Data lookup: REST APIs and Jira properties

ProForma can retrieve JSON data from Rest APIs and use this data to populate choice lists on forms. In order to use external data within a form, a connection must first be configured. Data Connections are created in Jira Admin > Apps > ProForma : Connections 

Data Requirements 

In order for ProForma to use external data, the following conditions must be met:

• Data Format: Valid JSON data

• List/Array of Objects: The JSON data must provide a list or array of objects.

• Object ID: The object must contain an ID value which can be a number or a string. The ID will not be displayed on the form. 

• Object Value: Any individual string field within the object can be selected as the value to be displayed to users on the form. 

• Size limitation: The API endpoint must return no more than 10MB of data.

JSON Examples

[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874",
      "geo": {
        "lat": "-37.3159",
        "lng": "81.1496"
      }
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org",
    "company": {
      "name": "Romaguera-Crona",
      "catchPhrase": "Multi-layered client-server neural-net",
      "bs": "harness real-time e-markets"
    }
  },
  {
    "id": 2,
    "name": "Ervin Howell",
    "username": "Antonette",
    "email": "Shanna@melissa.tv",
    "address": {
      "street": "Victor Plains",
      "suite": "Suite 879",
      "city": "Wisokyburgh",
      "zipcode": "90566-7771",
      "geo": {
        "lat": "-43.9509",
        "lng": "-34.4618"
      }
    },
    "phone": "010-692-6593 x09125",
    "website": "anastasia.net",
    "company": {
      "name": "Deckow-Crist",
      "catchPhrase": "Proactive didactic contingency",
      "bs": "synergize scalable supply-chains"
    }
  }
]

[
  {
    "object": "1",
    "name": "Apples",
    "location": "South Farm",
  },
  {
    "object": "2",
    "name": "Oranges",
    "location": "South Farm",
  },
  {
    "object": "3",
    "name": "Pears",
    "location": "North Farm",
  },
  {
    "object": "4",
    "name": "Nails",
    "location": "Warehouse",
  }
]

Connection Type and Options

The following options are supported for data connections:

• Name
  This name is displayed in the form builder; it is not displayed to a user filling out a form.
  
  

• Connection Type

  • REST API

    • This is the standard form of retrieving external data values for a choice list.
      
      

  • Jira Property

    • Use this setting to retrieve JSON data that have been stored as either an Application or Project property within Jira.
      Note: In Jira Cloud application properties are not accessible via ProForma.
      
      

• URL
  The URL of the Rest API. 

  • For Server & Data Center – This URL must allow connections from the Jira instance. It is likely that you will need to add the URL to the allowlist so that Jira is permitted to make the connection to an external data source.

  • No changes to the allowlist are needed for Cloud Premium.

• Authentication
  ProForma supports the following forms of authentication:

  • None

  • Basic

  • Digest

  • Custom (e.g. a JWT token)

• Caching 

  • Server: The cache will be maintained in memory on the local instance.

  • Data Center: Each node will maintain its own cache in memory.

  • Cloud: The cache is maintained in memory on the ProForma AWS servers.

Testing a Connection

When a new connection is created ProForma will test the URL as part of creating the connection. 

To test an already existing connection, go to the connection and click Edit. Clicking Next on the first Connect screen will test the connection again.

Configuring a Connection

The following items need to be specified for a data connection

Items: The list or array of objects within the JSON data set that contains the required data. 

ID: A number or string. The ID is not displayed on the form. 

Label: Any individual string field within the object. This is the field that will be displayed to users on the form. 

Clicking Next on the from Configure screen will show the Confirmation screen and a sample list of items with their respective IDs and Labels. 

Deleting / Restoring a Connection

Given the potential severe impact on the data contained within forms that use a data connection, a data connection is never permanently deleted. Instead, when a connection is Deleted it is placed in a deleted state and all authentication information is removed. The connection itself remains in place and can be restored if the connection is re-configured with new authentication details. 

The impact of deleting a data connection depends on the status of the forms that use that connection:

• OPEN Forms - All choice list values, including any selected choice(s), are removed from the form.

• SUBMITTED or LOCKED Forms - All choice list values, including any selected choice(s) are preserved.

Using a Data Connection

To use a data connection in a form, go to the form builder and select or create a choice question. Use the Data Connection property to link the question to the desired connection. 

Connection Unavailable 

While there are still cache values for a data connection, these values will be displayed on a form, even if the connection is not available.  If the cache expires however, then no choices will be displayed when viewing or editing form. Depending on the actions of the user the following outcomes could happen:

• OPEN Forms

  • Viewing the form only: No choices will be displayed. However, if the connection is restored, the selected choice will be retained.

  • Editing and saving a form: No choices will be displayed and the selected choice will be cleared. 

• SUBMITTED or LOCKED Forms - All choice values, including any selected choice(s) are preserved.