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.
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 will allow you to fetch data from an external source of data (your USM system) and populate the custom field options with this data. You will need this for the further configuration of the USM Object Select List custom field.
Access the USM Connector for Jira: Object Select global administration page
Click on the Create a data source button
Enter name and all needed connection parameters (authorization, service) for this new data source. Click on Create.
After a successful creating a list appears on this page including all the data sources currently available in your Jira instance.
USM Object Select List custom field configuration
This application offers fully integrated Jira Forge custom field, using data sources created in the step above.
It provides a select list (retrieving data from configured external data sources) that can be used in your projects. Due to Atlassian limitation it can only be used in Jira company-managed projects.
First steps:
Once the data source is configured, please 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 box
Next steps:
Once the custom field is created, to make the custom field work as expected it needs to be configured first
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.
In the custom field configuration you first configure a query which will fetch relevant results (choosing the fitting data source and entering your specific condition) and then apply a template on each row of the fetched result set.
Fetch data from API
To successfully fetch data from API, please select a data source you would like to connect to. Without it you will not be able to save this configuration.
Then set up the condition parameter. The condition parameter tells the system what data (in what format) should be received.
In the condition parametr 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
As simple as that you can easily choose between the select list custom field being Single Choice or Multiple Choice allowing user to pick only one, respective several options (values) at once.
Then you finally get to applying a template on each row of the fetched result set. It is a simple templating langue like that gets values (fields) from the result set and finds for it the corresponding match in the template. So it gets super easy to concatenate your fields together in the format of your choice.
Label template defines how you will see the options in the select list. Value template defines the format and structure of the values that will be saved on the background → should uniquely identify 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
Performance
For performance purposes, it is recommended to get maximally the first 1,000 rows of a result set with the combination of the {{inputValue}} smart value and the operator startswith.
In this case, choose a system field (in the condition parameter) which will be used to query the data → generally it is the “name” type of field that is usually very well known among users in the system
Do not forget to add this field in to the label template, so users actually see the name they type as a part of select options
A non-configurable cache for retrieved options exists. Identical queries will fetch the retrieved items values directly in the cache.
Configuration done
Once the configuration is saved, you can start to use your new created and configured custom field. Now you should be able to see the custom field working as expected. To see any results (to retrieve any options) you need to type at least 3 characters.
Troubleshooting
Ensure that the USM system is active and available. Currently there is no way to find out if the connection is set properly 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. 📧
Add Comment