USM Connector for Jira: Object Select Documentation 📝

Welcome to USM Connector for Jira: Object Select - User Documentation

Let us introduce you this powerful integration between Jira and your USM system. This app enhances your Jira experience by providing a custom field type that enables you to seamlessly connect, select, and manage objects from your USM system, all within Jira

Do not hesitate to contact us on 🤙

Your Sykora IT.

Getting Started

To make it happen, simply install USM Connector for Jira: Object Select on your Atlassian platform by following these simple steps:

  • Search for application USM Connector for Jira: Object Select in the Atlassian Marketplace.

  • Install USM Connector for Jira: Object Select into your Jira Software Cloud environment.


First steps after installation

  • Configure the USM Connector for Jira: Object Select App

    • Data source configuration

    • USM Object Select List custom field configuration



Data source configuration

A REST API data source allows you to fetch data from an external source of data (your USM system) and populate the custom field options with this data. This step is crucial for the following setup of the USM Object Select List custom field.


  1. Access the global administration page for USM Connector for Jira: Object Select

  2. Click on the 'Create a data source' button

  3. Provide a name and input all the necessary connection parameters, including authorization and service details, for this new data source.

  4. Finally, click on the 'Create' button to complete the data source configuration."


Data source administration page
Data source configuration settings

After successfully creating a data source, you will find a list displayed on this page, showing all the data sources currently available in your Jira instance.

Data source list


USM Object Select List custom field configuration

This application provides a fully integrated Jira Forge custom field that utilizes data sources created in the preceding step.

It provides a select list (retrieving data from configured external data sources) that can be used in your projects. Please note that, due to Atlassian's constraints, it is compatible only with Jira company-managed projects.


Initial steps:

After configuring the data source, proceed to create a new custom field in the Jira System settings.

  1. Select > Issues

  2. Under FIELDS, select Custom fields and click on the Create custom field button

  3. Select the type of field → USM Object Select List

  4. Add the details for your field and select Create

  5. Associate the new custom field with one or multiple screens by ticking the corresponding boxes


Following steps:

Once the custom field is created, it must be configured to function as intended.

  1. Select > Issues

  2. Under FIELDS, select Custom fields and find the custom field you have just created

  3. Under the custom field’s settings options select Contexts and default value and click on the Edit custom field config button.

Within the custom field configuration, you will set up a query to retrieve relevant results (selecting the appropriate data source and specifying your unique condition), and subsequently apply a template to each row of the retrieved result set.

Fetch data from API

To successfully retrieve data from the API, you must first select the desired data source for connection; without this step, saving the configuration will not be possible.

Then set up the condition parameter. The condition parameter tells the system what data (in what format) should be received.

Within the condition parameter smart values can be used. Smart values allow you to easily access issue data within Jira. For now, only the {{project.key}} that returns the issue project's key is supported in terms of retrieving issue data.

Another very useful smart value can be {{inputValue}} that corresponds to the value that user types in to the select for the purpose of retrieving (filtering) select options.

Fetch data from API configuration

Demo condition parameter values :

{ "types":[ { "type":"System", "condition": { "buildCondition":"manual", "parts":[ { "field":"name", "value":"{{inputValue}}", "operator":"startswith" } ]}, "sortedBy":[ "datchg descending" ], "fields":[ { "name":"name" }, { "name":"status" }, { "name":"systemname" }, { "name":"systype" }, { "name":"validfrom" }, { "name":"validto" }, { "name":"datchg" } ], "seekRead":{ "pageRequest":"first", "pageSize":"1000" } } ] }


Look and feel

Here's how straightforward it is: You have the option to choose between the select list custom field as either Single Choice or Multiple Choice, allowing users to make a single selection or multiple selections (values) simultaneously.

Next, you'll proceed to apply a template to each row of the retrieved result set. This template language is quite straightforward; it extracts values (fields) from the result set and matches them with the corresponding placeholders in the template. This makes it incredibly easy to combine your fields in the format of your preference.

The Label template determines how the options appear in the select list, while the Value template defines the format and structure of the values saved in the background, ensuring a unique identification of the given object.

It follows these two basic principles:

  • {{your_system_field_name}} → the field name must be enclosed between two curly braces on both sides

  • your field has to be included in the condition parametr → can not really take a field if it is not a part of the result set

Look and feel configuration

Demo “Look and feel” values:

Label option template:

{{name}} - {{systype}} ({{systemname}})

Example result:
DemoSystem - WorkNet (SELF8484)


Value option template:


Example result:


Optimizing Performance
  • To ensure optimal performance, it's advisable to retrieve a maximum of the first 1,000 rows from a result set and using the combination of the {{inputValue}} smart value and the 'startswith' operator.

    • In this scenario, select a system field (in the condition parameter) to serve as the basis for querying data. Typically, the 'name' field type is usually widely recognized and used by system users.

Don't forget to include this field in the label template, so that users can see the name they type as part of the select options.

  • A non-configurable cache for retrieved options exists. Identical queries will fetch the retrieved items values directly in the cache.

Configuration complete

After saving your configuration, you can start using your newly created and configured custom field. You should now observe the custom field functioning as expected. Keep in mind that to retrieve any options, you'll need to input at least 3 characters.

On-Issue Create Dialog
On-Issue Screen

Security: Forge App IP Address Ranges

Atlassian has updated their published IP addresses and domains for Atlassian cloud products to include IP address ranges for outbound connection for Forge apps.

You can use these IP address ranges to allow Forge apps to make connections through firewalls or integrate with software that has a managed IP allowlist.

Important Note:

  • The IP address range for outgoing connections is shared by all Forge apps. Allowing connections from this range permits connections from any Forge app.

Current IP Address Ranges for Outbound Connections:









Stay Updated:

If you plan to use these IP address ranges, it's essential to monitor Atlassian's documentation for any changes. A JSON file containing this information is published at, which may be helpful for automation.


It is essential to confirm that the USM system is both active and accessible. Currently, there is no method to pre-check the connection's proper configuration in advance.

Feedback and Support

Your invaluable feedback fuels the evolution of USM Connector for Jira: Object Select. Share your insights, and together, we'll cultivate a more refined and impactful user experience! 📊🌱

Our channels are always open to hear from you! If you encounter any challenges or have questions about USM Connector for Jira: Object Select, don't hesitate to reach out to us at our email: or via a ticket on our portal: 📧