filter Filter Blog

Jira Administration

Keep Your Lists Up-to-date with ProForma Data Lookups

by Jenny Choban on August 2, 2019

There are many add-ons in the Atlassian Marketplace that are dedicated to bringing third party data into Jira. We want to make that just one of ProForma’s many features.

Introducing Data Lookups

Today we are pleased to announce that you can now load live data into your ProForma forms. The new Data Lookup feature lets you link choice lists on your ProForma forms to external data sources.  These connections are live, so when the source data changes, your forms will automatically be updated to show the new options. When a user completes and submits a form that uses a data connection, their selected choice is saved in the ProForma field.

How Can I use Data Connections?

 

You can connect to any data source that has available API and returns JSON data. Use cases might include:

  • Directories  –  You can connect with your LDAP, allowing users who are completing forms to select any member of your directory, regardless of whether or not that person is a Jira users. 

  • Approved Purchasing Lists – Need an easier way to manage purchasing? Why not handle routine purchases in JSD? You can create a ProForma form that connects directly to your approved purchasing catalogue, making it easy to handle requests and approvals in one place.

  • Site Locations  If you’re using forms to manage repairs, deliveries and maintenance requests, then you can easily load a list of locations into your forms.  When you business expands, you can add new locations to the sources list and won’t have to worry about updating multiple forms.

How Do Data Lookups Work?

 

There are two parts to using data lookups with ProForma. First, a Jira Administrator must create the Data Connection.  Once the connection has been created, a Project Administrator can use is it when building or editing ProForma forms.

Creating a Data Connection

To create a data connection, go to Manage Add-on > ProForma > Connections. You will be prompted to enter the name, type, URL, authentication requirements and cacheing interval. A few things to keep in mind:

ProForma for Jira – Data Connection

  • Name – Use a short, descriptive name, as this is will be displayed in the form builder.
  • Type – ProForma uses REST APIs to connect to external sources. Alternatively, you you can create data connections to Jira properties. This gives you the option to store the needed data in Jira, rather than in a third party system.
  • Authentication – ProForma provides several authentication options. If you choose to enable authentication, you will only need to enter authentication credentials when the connection is created.
  • Cacheing – ProForma allows you to cache results of the data lookup in order to optimize performance.  Values are 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.

 

Note: Server and Data Center users will need to ensure that each connection is covered by one of their whitelist rules. See Atlassian documentation for more information on whitelisting.

 

The next screen will test the connection. You’ll be able to see the request that was made and a sample of the results returned.

 

ProForma for Jira – Data Connection

 

The Configure screen allows you to specify the fields that are included in the data connection.

ProForma will look for arrays that returns at least one suitable ID field and one suitable string fields. The results will be listed under Items. You may then select the field that will serve as the ID number, and the string fields that will populate the choice lists on the form.

 

ProForma for Jira – Data Connections

 

The Confirmation screen will show a sample of the results returned.

Using Data Lookups on ProForma Forms

Once the connection has been created, it can be accessed from the form builder. To use a data connection, simply create or edit a Choice question. Use the dropdown to select the indicated connection. Data from the connection will populate the choice list.

 

ProForma for Jira – Data Connections

 

Limitations

There are a few limitations to ProForma Data Lookups. Note that this is the first iteration and we will continue to enhance how ProForma integrates with other systems in the future.

  • Currently, you cannot have data connection and linked Jira field on same field.
  • Data lookups only work with Choice questions (Dropdown, single choice or multiple choice).
  • ProForma data lookups populate choice fields. They are not intended to serve as search fields.
  • Data connections are read-only. ProForma cannot write to an API.
  • ProForma data connections are designed to work with simple arrays of JSON data. We will continue developing integrations to work with specific apps. (Integration with Riada Insight will be developed later this year.)

Try It

 

Want to try it yourself? Use the sample data at https://jsonplaceholder.typicode.com/todos Then start adding data lookups to any ProForma form.