Assets Search
- Gia Jgarkava
Table of Contents
Assets search gives the possibility of enhanced search, visibility, and selection of Asset objects in Assets custom fields from the Customer Portal. After configuration, the Asset search field will be added to the customer portal on the request creation page. See Asset search configuration and Assets search on the Customer Portal below for the user guide.
Before configuring the Asset search field, you need to establish a connection with Assets.
You need to have a Jira Service Management Premium or Enterprise license to use this feature!
Connection to Assets
When you navigate to the Asset search in the app configuration page after the installation of the app, you will see the notification that the connection with Assets is not established:
Go to “General Settings / Assets search” to configure connection with Assets:
Click the “Configure now” button and fill in the Email and API Token fields:
Email
Enter the email address of the user who has permission to access Assets. This user should have valid JSM Agent License.
API Token
Enter the API Token of the user selected above. You can create a Token through the following link.
When fill both fields in, the “Save Configuration“ button will be enabled and if the credentials are correct, you will see the success message:
You can refresh the connection status by clicking the “Refresh status“ button.
If the credentials are incorrect, you will see the corresponding notification:
When the connection is successful, you can go to the “Assets Search” in the left sidebar to configure the Asset search field.
You can also delete the connection by clicking the “Delete configuration” button after clicking the “Edit Configuration” and by confirming the deletion in the confirmation popup:
Asset search configuration
The Better Search in Customer Portal does not create Assets custom field and it should be created and configured with JSM native functionality to be displayed on the Customer Portal. In the Jira custom field configuration, you need to select the object schema, where the search field will search the objects and the attributes that need to be searched and displayed. See the following link for the instructions: Set up the Assets objects custom field | Jira Service Management Cloud.
To configure the Asset search field, you initially need to connect to Assets. If the connection is not configured (for example after the initial installation of the app), you will see the corresponding notification:
To configure the connection with assets, see the instructions above.
After the connection is successful, you can start configuring the Asset search field by clicking “+Add Asset search field“ button and defining the parameters.
The corresponding Assets custom field should be initially created and configured in Jira!
Asset Search Parameters & Scope
Active/Inactive (toggle)
Switch this toggle to show or hide the search field on the Customer Portal.
Name (mandatory)
Choose a name for your Asset search field. The name will be visible above the search field on the Customer Portal.
Project (mandatory)
Select the project, in the requests of which the Asset search field should be visible.
Issue Types (mandatory)
Select the Issue Type(s), where the Asset search field should be visible. The list of the Issue Types is defined by the selected project above.
If you remove a project from the configuration, the corresponding Issue Types will be cleared.
Request Types
Select the Request Type(s), in which the Asset search field should be visible. The list of the Request Types is defined by the selected Projects and Issue Types above.
If you remove a project or issue type from the configuration, the corresponding Request Types will be cleared.
If the Assets field is added to any Request Type in the Jira configuration, you cannot add such a field into the configuration of the app. If you need to use the field from the app, please remove it from the selected Request Type in Jira.
You can configure only one Asset search field with the same request type. If the Request Type is selected in the configuration of one Asset search field, if you try to configure another field with the same request type, you will see the corresponding error message upon saving the configuration and the field configuration will not be saved:
Assets Display Settings
Display Name
Choose a name for your Asset search field. The name will be visible above the search field on the Customer Portal.
Description
Add a description for your Asset search field. This description will be visible under the search field on the Customer Portal.
Linked Jira Asset Field (mandatory)
Choose the Asset custom field that should be shown on the Customer portal and where the searched object will be selected after the creation of the request. The dropdown will show all the Asset fields in the JSM. The Asset field must be associated with the create and edit issue screens of the selected projects' corresponding issue type(s).
Display and search across these attributes in the custom field
Select the attributes that should be displayed on the Customer Portal in the Asset Info Sheet for the searched object. The list shows the attributes selected in "Allow search filtering by these attributes" in the Assets custom field configuration in Jira.
When you click in the field for the first time it might take few seconds until all the attributes are loaded.
Even if not selected, the Label attribute and the object key will always be visible on the Customer portal.
Fields display ordering
Here you can arrange the order of the attributes that were selected in the field above (“Display and search across these attributes in the custom field”).
Field can store multiple objects (toggle)
Select this toggle only if the “Field can store multiple objects“ option in the Asset field configuration is selected.
If the toggle is not activated, it will be possible to select only one Asset object in the field (radio button):
Default Response
Select the attributes that should be displayed on the Customer Portal in the Asset Info Sheet for the searched object. The list shows the attributes selected in "Allow search filtering by these attributes" in the Assets custom field configuration in Jira.
Use Default response and hide from portal (toggle)
Hide this field from the request form. It will be visible in the issue view, and pre-field with the value you field here.
Required (toggle)
Make this field mandatory for requests in the Customer Portal.
+ Add another field
You can add more than one Asset search field (up to 20). If you try to add more than 20 files, the “+ Add another field“ button will be disabled and you will see the corresponding notification:
You can also add dependent (cascading) fields, using filter scope (AQL) in the Jira custom field configuration.
After all the mandatory fields are filled, you can add another Assets field by clicking the “+Add another field“ button or click the enabled “Save Configuration“ button to save the field:
If you decide to add another field, a new section will appear with the same fields (if the mandatory fields are not filled, the section will be red):
Clicking anywhere on the field box will expand the fields that need to be filled.
You can rearrange the order of the fields either by drag and drop or by the arrows on the left side of the section:
To delete the section, use the “delete“ icon on the right side of the section. You will see the confirmation popup:
You can add up to 20 Asset fields (i.e. sections) in one Asset search field!
Cascading Assets fields
Using the application and the Assets custom field configuration, you can create Cascading Assets search fields, with the ability to be hidden or have a default object selected.
Let’s assume you have an object schema “Global” with countries (Object Type: “Country“) and corresponding cities (Object Type: “City“). The City Object Type has a reference attribute to the Object Type Country.
Let’s say you have various Request Types dedicated to certain countries and you need that when the customer opens a ticket of a certain Request Type, only cities in that country be shown in the Cities field.
To achieve this, you need to:
Create an Assets custom field “Country“ with the following Filter Scope (AQL):
obectType = Country
Create an Assets custom field “City“ with the following Filter Scope (AQL) and Filter issue scope (AQL):
Filter Scope (AQL): objectType = CityFilter issue scope (AQL): object HAVING outboundReferences(objecttype = Country AND objectId IN (${customfield_10182${0}}))where
customfield_10182is the ID of the Country custom field
Create Request Types for countries (e.g. “Request for USA offices“)
Go to the Better Search app, create an Asset search field, and define the Project and the Request Type for a certain country.
In the Assets Display Settings, add 2 fields:
For Country
Fill the mandatory and optional fields (if needed): Display name, Placeholder, and Description.
Select the “Country” custom field in the Linked Jira Asset Field.
Select an attribute in the “Display and search across these attributes in the custom field” (e.g. Label)
Select the default response for the Request Type (e.g. USA)
Toggle the “use Default response and hide from portal“ on.
For City
Fill in the mandatory and optional fields (if needed): Display name, Placeholder, and Description.
Select the “City” custom field in the Linked Jira Asset Field.
Select an attribute in the “Display and search across these attributes in the custom field” (e.g. Label)
Leave the default response empty.
Leave the “use Default response and hide from portal“ toggle off.
Toggle “Required“ if needed.
Save configuration.
See the following Atlassian instructions for the Using Assets Query Language (AQL) syntax.
As a result, while creating a request in the “Request for USA offices” request Type, the customer will see only one Asset field (City) with the cities related to the USA Object Type:
You can add up to 20 cascading fields with various relations between each other.
When the field is added, you can see it in the list under “Assets search” from the left menu:
From here you can view the name and status of the field and the user who created it. You can go to the configuration of the field by clicking the “Edit“ button, or delete the field by clicking the “Delete“ button. You will see the confirmation popup and the notification in the bottom left corner of the screen when the field is successfully deleted:
Assets search on the Customer Portal
The Better Search in Customer Portal does not create Assets custom field and it should be created and configured with JSM native functionality to be displayed on the Customer Portal. In the Jira custom field configuration, you need to select object schema, where the search field will search the objects and the attributes that need to be searched and displayed. See the following link for the instructions: Set up the Assets objects custom field | Jira Service Management Cloud.
When the Asset search field is configured, you will see the field in the request create page and can search and view object details according to the configuration:
Even if not selected in the configuration, the Label attribute and the object key will always be visible in the Assets Info Sheet.
For the customer users, the object icons cannot be visible due to the permission limitations. The customer users will see the default object icons:
By checking the checkbox, you can select the object(s) in the field:
After creating the request, the Asset field will be filled with the selected objects.
If the “Field can store multiple objects“ toggle is NOT on in the configuration, you will be able to select only one object (you will see radio buttons instead of checkboxes):
If the object attribute name is too long, you will see the full name while hovering the name with the mouse.
If you select the “Required“ checkbox in the configuration, you will not be able to create a request without filling in the field. You will see the corresponding message:
After the successful creation of the request, the Asset custom field will be filled with the selected Assets object(s). You can view the selected Assets objects in the registered request and also view the details of the selected object by clicking the downward arrow along the object:
If the “Copy to Summary” option was selected, upon creating the request, the selected object names will be copied into the Summary, separated with commas:
To remove the view of the objects in the ticket, please delete the corresponding Linked Jira Asset Field from the app configuration (see the “Assets Display Settings” above). Unless the linked Jira Asset field is removed from the configuration, the selected object(s) will be visible in the request even if the field is removed from the corresponding screen in the Jira configuration.
You can also enable reselecting the Assets objects from the customer portal. To do so, go to the issue view of the corresponding issue and click the “Better Search for Customer Portal” section in the sidebar:
Here, you will see the “Open customer edits on this form“ toggle, by turning of which on will make the Assets objects reselectable in corresponding request on the Customer Portal:
Once you reselect the object, the fields will be closed for edit until they are opened again with the abovementioned method.