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 support@sykorait.com. 🤙

Your Sykora IT.

1 Getting Started
- 1.1 First steps after installation
2 Configuration
- 2.1 Data source configuration
- 2.2 USM Object Select List custom field configuration
  - 2.2.1 Fetch data from API
  - 2.2.2 Look and feel
  - 2.2.3 Optimizing Performance
  - 2.2.4 Configuration complete
3 Security: Forge App IP Address Ranges
4 Data Residency
5 Troubleshooting
6 Feedback and Support

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

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.

Access the global administration page for USM Connector for Jira (Object Select)
Click on the 'Create a data source' button
Provide a name and input all the necessary connection parameters, including authorization and service details, for this new data source.
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.

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.

Select > Issues
Under FIELDS, select Custom fields and click on the Create custom field button
Select the type of field → USM Object Select List
Add the details for your field and select Create
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.

Select > Issues
Under FIELDS, select Custom fields and find the custom field you have just created
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.

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

Demo “Look and feel” values:

Label option template:

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

Example result:
DemoSystem - WorkNet (SELF8484)

Value option template:

{{name}}

Example result:
DemoSystem

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.

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: https://support.atlassian.com/organization-administration/docs/ip-addresses-and-domains-for-atlassian-cloud-products/#Outgoing-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 https://ip-ranges.atlassian.com/, which may be helpful for automation.

Data Residency

USM Connector for Jira (Object Select), built on the Forge platform, offers you the advantage of data residency control. With the latest Forge capabilities integrated, you can securely store your USM connection data with confidence. This empowers you to align with your organization's data governance policies and ensures compliance with regional regulations. Your data remains safe and accessible, giving you peace of mind while using our app.

Troubleshooting

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: support@sykorait.com or via a ticket on our portal: https://support.sykorait.com. 📧