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
Click here to see a tutorial. You can change the language for the video by clicking on the Language icon in the upper right corner.
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.
The JSON data must be a single array of objects. ProForma cannot use data in nested arrays.
User Information JSON
Other examples: https://jsonplaceholder.typicode.com
Object List JSON
Connection Type and Options
The following options are supported for data connections:
This name is displayed in the form builder; it is not displayed to a user filling out a form.
This is the standard form of retrieving external data values for a choice list.
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.
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.
ProForma supports the following forms of authentication:
Custom (e.g. a JWT token)
You do not need to re-enter authentication details when you edit a connection.
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.
Values are first cached when the the form builder is loaded, or when a user views or fills out a form that uses a data connection.
ProForma doesn't support a forced refresh of choice lists. However, you can set the Cache setting of the connection to None. This will clear and reload the list.
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.
After deleting a connection, if a submitted form is reopened then all of the choice values will be removed from the form.
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.
Unlinking a Connection
If the choice question in a form template is unlinked from a data connection, all of the choice values in the form builder will be cleared. However, forms that already use the data connection and are attached to Jira issues/requests will remain unchanged and will continue to use the Data Connection.
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:
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.