This page includes release notes and updates for app developers working against the Assets API. Use this page to keep track of upcoming changes, deprecation notices, new features, and feature updates from Assets.
Go to our developer community to ask questions. You may also be interested in the What's New blog for Atlassian Cloud where details of major changes that affect all developers are announced.
"id" fields in the various entities of the REST API for Assets in Jira Service Management cloud are of type string. Despite being a string, many of these contain a numeric value (for example "1245"). Please note that after the 30th of September 2024 some Asset entities will begin to be assigned a UUID value (for example "11ace219-a427-405c-bbb5-61d4f958e3fa") instead of a purely numeric one. If you have already treating these values as strings as per the API specification then you will not be effected by this change. If you have been assuming a numeric value within "id" fields, please make the appropriate adjustments to accomodate UUID’s before 30th of September 2024.
Note: despite all Asset entities being assigned a new UUID for the "id" field, the numeric values will continue to work as they do today when querying existing data via the publicly documented REST API’s. There is no need to update any id’s you might have previously stored in order to query particular data. This will be a backwards compatible change.
If you have already treating these values as strings as per the API specification then you will not be effected by this change. If you have been assuming a numeric value within "id" fields, please make the appropriate adjustments to accomodate UUID’s before 30th of September 2024. Id’s on existing entities will continue to be queryable via their numeric id to maintain backwards compatibility.
AQL in Assets for Jira Service Management cloud supports queries on Status attributes using the Name of the Status. For example Status = ACTIVE
An undocumented feature also allows the same query using the ID of the Status as opposed to its Name. For example Status = 1. However as all Status Names are guaranteed to be unique within Assets, there is no benefit to using the ID.
We will be removing this undocumented feature after the 30th of September 2024.
If you are using Status ID’s in your AQL queries, please adjust these to use the Status Name instead before the 30th of September 2024.
Assets now supports JWT authentication. See https://developer.atlassian.com/cloud/assets/imports-rest-api-guide/authorization/#connect-apps for more details.
We have some important updates to share regarding AQL in Assets for Jira Service Management in cloud. A number of features are being deprecated or changed in order to allow us to greatly increase the scalability, performance and reliability we can offer our customers. These changes will apply to any of our public API endpoints that accept AQL as a parameter. Please see below for more details or join the discussion on our Atlassian Developer Community post https://community.developer.atlassian.com/t/upcoming-changes-to-aql-in-assets-for-jira-service-management-cloud/80409.
All changes listed come into effect on or after 30 Sept 2024.
The CIDR function allows filtering over IP ranges, for example"IP Address" IN CIDR("192.0.0.0/8")
If this is a form of search you require, as an alternative we suggest trying LIKE to search for IP addresses in a particular range, e.g."IP Address" LIKE "192.0.0"
However, we do understand in many cases this will not be a suitable workaround.
Not to be confused with Text attributes which will continue to be searchable as they are today. If you have information contained with a TextArea attribute that you need to search on, we recommend moving it into one or more Text attributes.
Ordering via the Assets user experience or by using an AQL ORDER BY will no longer have the same behaviour for attributes of type User, Group, Project, Bitbucket repository and Opsgenie team. Ordering will be based on the underlying ID of the attribute value as opposed to the visible name. We understand this will likely not be the behaviour most of you expect in this situation. For most customers the new behaviour will appear as “grouping” as opposed to “ordering” as the underlying ID is not visible but values with the same ID will appear together after ordering. Ordering by all other attribute types will continue to work as they do today.
Ordering via the Assets user experience or by using an AQL ORDER BY will no longer be supported for attributes with a maximum cardinality configured as greater than 1. Currently very few customers use ordering on attributes of this kind and the behaviour often does not match what our customers expect. Ordering will continue to be supported on all attributes with a maximum cardinality of 1.
Today it is possible to use the >,>=,<,<= operators on attribute types where this is typically not required. Use of these operators will be limited to Integer, Float, Date and Date time where the use case and expected behaviour is clear.
The connectedTickets() function will not be usable when nested within the inboundReferences() or outboundReferences() functions. This means an AQL query such asobject HAVING connectedTickets(labels is empty)
(i.e. objects connected to issues where the label field is empty) will continue to behave as it does today. However,object HAVING inboundReferences(object having connectedTickets(labels is empty))
(i.e. objects with an inbound reference from other objects which are connected to issues where the label field is empty) will not be valid AQL.
Use of the dot operator(.) will not be possible when using AQL as a part of mapping source data to an object in an import configuration. This restriction will apply only to the use of AQL in the import mapping section of the Assets import experience as well as the import endpoints in our public REST API. In all other locations the the dot operator(.) will continue to function as it always has.
We are making changes to the /object/aql and /object/navlist/aql endpoints within the REST API’s for Assets in Jira Service Management cloud.
We will be removing the total attribute from the response payload of the /object/aql endpoint. If you require this, instead use the /object/aql/totalcount endpoint which will provide a total count for any AQL query.
We will be removing /object/navlist/aql from our list of supported public endpoints and it should now be considered deprecated. Instead we recommend you migrate to the /object/aql endpoint.
These changes will be made on or after 30 Sept 2024.
We are making changes to the responses of a number of endpoints within the REST API’s for Assets in Jira Service Management cloud. These endpoints include in their response body the ID for an object attribute value. This ID is now deprecated and will be removed (see https://community.developer.atlassian.com/t/object-attribute-value-id-will-be-removed-from-all-assets-rest-apis/79259 for details of all effected publicly documented endpoints).
This change will be made on or after 30 Sept 2024 for our publicly documented API endpoints. For any undocumented API endpoints that include this ID in their response body the change will be made sooner, on or after 1 Jul 2024.
The Jira Service Management Assets REST API endpoint GET /aql/objects is now deprecated and will be removed after the 18th of September 2024. For querying Assets objects please move to the API endpoint POST /object/aql.
You should now use the endpoint POST /object/aql for all AQL queries to Assets in Jira Service Management.
We are deprecating the Assets AQL anyAttribute function and it will be retired on 31st March 2024. For further details see https://community.atlassian.com/t5/Jira-Service-Management-articles/UPDATED-DATE-Upcoming-change-Assets-AQL-function-anyAttribute-to/ba-p/2586178.
Added externalIds functionality to object schemas, object types and object type attributes. externalIds allows users to assign an Id to an object schema, object type, and object type attribute for future modifications, and as a unique reference in update and mapping requests.
https://developer.atlassian.com/cloud/assets/imports-rest-api-guide/schema-and-mapping/
https://developer.atlassian.com/cloud/assets/rest/api-group-importsource/#api-group-importsource
Added extra fields to support:
uniqueness
cardinality
status
externalId
Added a new endpoint which retrieves the JSON provided in the mapping endpoint:
Get /schemaAndMapping
We will be making changes to Assets ObjectSchema REST API. In March 2024 we will be removing idAsInt property from the ObjectSchema API response payload. We have updated the examples in our documentation to reflect the future state of the response payload, without the idAsInt property.
Currently, our identifiers (id or <entity>Id) are strings representing integers, but they may change to UUID or other string representations in the near future.
We have updated type information for selected properties across the Assets API documentation, to indicate that they are Strings. These properties were previously documented incorrectly as Integers. See the More details section for the specific properties.
We also updated the response payload of object/aql endpoint to reflect the actual API response. See the More details section for payload details.
The following properties' type information has been updated
attributesToDisplay
referenceObjectTypeId
Id of ObjectHistory
objectId of ObjectHistory
parentObjectTypeId
objectTypeAttributeId
An example response of object/aql endpoint
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"startAt": ,
"maxResults": 25,
"total": 1,
//Objects
"values": [
{
"workspaceId": "f1668d0c-828c-470c-b7d1-8c4f48cd345a",
"globalId": "f1668d0c-828c-470c-b7d1-8c4f48cd345a:88",
"id": "88",
"label": "SYD-1",
"objectKey": "ITSM-88",
"avatar": {..},
"objectType" : {..},
"created": "2023-09-12T07:04:55.588Z",
"updated": "2023-09-12T07:42:29.807Z",
"hasAvatar": false,
"timestamp": 1694504549807,
"attributes": [..],
"_links": {
"self": "https://api.atlassian.com/jsm/insight/workspace/f1668d0c-828c-470c-b7d1-8c4f48cd345a/v1/object/34"
},
"name": "SYD-1"
}
],
"objectTypeAttributes": [..],
"last": true,
"isLast": true
}We’ve added a template for surfacing Forge UI Kit elements when integrating your app with Jira Service Management assets. This template includes extension points for useful import actions, including:
creating and deleting import structures
starting and stopping imports
returning import progress
Refer to the following pages for additional details:
In Jira Service Management, ‘Insight' has now changed its name to 'Assets'.
URLs with **/insight/** are now **/assets/**
URLs with **/iql/** are now **/aql/**
There’s no action required - no functionality has changed, and the change is backward-compatible.
An improvement will be made in the coming days to allow customers (site admins) to turn off (or back on) end-user installation capabilities for OAuth 2.0 (3LO) apps. If you are a developer of OAuth 2.0 (3LO) apps, you do not need to take any action as a result of this change, as this message is only to communicate the impact to the customer.
Previously, controls were not in place for an admin to block their users from installing 3LO apps. Adding the ability for an admin to prohibit users from installing 3LO apps now aligns more closely to how a user would install any other, non-3LO apps on the Marketplace. This functionality was requested by several Atlassian enterprise customers to gain increased control over where their data is shared and which apps have access to their instance. By allowing admins to control end-user app installs, we are making it possible for more enterprise customers to move to cloud. Once in cloud, these companies will not be blocked from installing 3LO apps, because admins will retain the ability to vet and install the apps at their discretion.
Figure (a) below demonstrates the section of the customer’s admin console where they will now be able to block their users from installing 3LO apps. Figure (b) below shows the new experience when a customer tries to install a 3LO app after their admin has disabled this function.
If a customer attempts to install a 3LO app after their admin has disabled this function, the following error message will appear:
App is blocked by an admin
An admin has not allowed [App Name] to access data from [Your Atlassian Instance] . Select another site to authorize access to or contact your admin for more information.
(a)
(b)
External imports can now define and use their own set of icons.
Rate this page: