Data connections

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 

Tutorial

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.

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 that be a number or a string. The ID is not 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

User information

Object list

[
  {
    "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"
    }
  }
]

Source: https://jsonplaceholder.typicode.com/users

Other examples: https://jsonplaceholder.typicode.com

[
  {
    "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.

  • 接続タイプ

    • 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.

  • URL
    The URL of the Rest API. This URL must allow connections from the Jira instance. It is likely that you will need to add the URL to the Jira Allowlist, so that Jira is permitted to make the connection to an external data source.

  • Authentication
    ProForma supports the following forms of authentication:

    • なし

    • Basic (基本)

    • Digest

    • Custom (e.g. a JWT token)

tip/resting Created with Sketch.

You do not need to re-enter authentication details when you edit a connection.

  • Caching
    Each node will maintain its own cache in memory.

tip/resting Created with Sketch.

Caching
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.

Forced Refresh
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: The object must contain an ID value that be a number or a 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.

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

tip/resting Created with Sketch.

Reopening a Form
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.

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:

  • Viewing an open form: 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 Forms - All choice values, including any selected choice(s) are preserved.

最終更新日 2024 年 6 月 18 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.