Working with Jira Assets Rest API in Python: A Comprehensive Tutorial
Assets (formerly Insight) is a feature within Jira Service Management that allows teams to track their assets, configuration items, and resources. This is used to understand and visualize the critical relationships between applications, and services. Asset functions as a repository that houses all your possessions, from hardware, software, office supplies, keyboards, licenses, and more. It can also accommodate any items you wish to store within it.
Working with the REST API enables users to perform various operations on their Assets data, such as retrieving, creating, updating, and deleting objects, schemas, and more. The Assets Cloud REST API documentation provides a comprehensive list of available APIs.
So, how can you get started with Assets Rest API? Follow the step-by-step process outlined below, which covers acquiring your access token, retrieving your workspace_id, creating Object Schemas, Types, and more.
Generate API Token
To authenticate and gain access to the Jira Insight REST API, we must generate an API Token from our account. Here are the steps to do so:
i)Go to https://id.atlassian.com/manage/api-tokens.
ii)Click on “Create API Token.”
iii)Set a Label and click “Create”.
iv)Save the Token to remember for future use.
Authenticate & Retrieve Workspace_Id
Now that we have our API_token, the Base64 encoding will be used to encode the combination of our Jira username and API token, creating an access token. The resulting access token will then be used to authenticate to Jira Asset.
To retrieve our Workspace_id, we’ll use the endpoint https://{domain}/rest/servicedeskapi/assets/workspace. Here, “domain” should be replaced with the hostname of your Jira Service Desk instance. For instance, if your Jira Service Desk is hosted at example.atlassian.net, the URL would be: https://example.atlassian.net/rest/servicedeskapi/assets/workspace
The code below shows how to authenticate and retrieve the workspace_id.
Creating Object Schema
Now that we’ve authenticated and retrieved our workspace_id, we can proceed to create our Object Schema in Assets. An Object Schema is very important as it helps to structure and organize our data. You can think of an Object Schema as a puzzle piece that connects everything. In the Jira world, we can think of it as a ‘project’.
We can create an Object Schema by sending a POST request to the endpoint https://api.atlassian.com/jsm/assets/workspace/{workspace_id}/v1/objectschema/create, where we substitute the workspace_id with the workspace_id. generated earlier.
This is what my interface looks like after creating the Object Schema.
Creating Object Type
An Object Type is used to group objects sharing similar characteristics. For example, when considering PCs, we can have Object Types such as Laptops, Hardware, Software, and more. Each PC you manage falls under one of these Object Types. The beauty of it is that you’re free to create as many distinct Object Types as you need, allowing you to neatly organize your objects within them.
Now, let’s create our Object Type. We send a POST request to the endpoint https://api.atlassian.com/jsm/assets/workspace/{workspace_id}/v1/objecttype/create
In the code snippet above, we must note that within the payload, we replace the ObjectSchemaId with the Id value generated when we created our Object Schema.
After running the code, this is what our interface looks like, which shows our object type has been created.
Adding Attributes to Object Types
Attributes are very important as they allow us to include essential information within our objects. These typically represent relevant fields that point to the data we want to add to our objects. When you create an attribute, you must specify its type, which determines the kind of information stored in the attribute. Also, an attribute can be inherited by all child objects. For more information, check the official Jira Assets documentation here.
Here is the endpoint for adding attributes: https://api.atlassian.com/jsm/assets/workspace/{workspace_id}/v1/objecttypeattribute/{objectTypeId}.
When using this endpoint, you should provide the Object TypeID generated in the JSON response after creating the Object Type.
This is what our interface looks like after running the code. All attributes we can see aside from the “Geolocation” we created was a default attribute in Asset.
Creating Objects
Here is where we send in the actual assets or data in our object container. This is similar to Jira issues or requests in Jira world. When creating these objects we must place each object in the appropriate object type.
For example, you wouldn’t classify vehicles under the ‘Furniture’ category, same here in Asset, it’s important not to put employees within a ‘Hardware’ object type.
We can use this endpoint for creating our object https://api.atlassian.com/jsm/assets/workspace/{workspace_id}/v1/object/create
In the code above, both objectTypeId and objectTypeAttributeId are IDs retrieved from JSON responses generated for Object Types and Object Attributes, respectively. This is what our interface looks like after running the code. We can see the Object card showing the ‘Geolocation’ information we passed in.
Also, note that we can add as many objects under our Object Type, this is just a simple guide to figure out how you can get started.
We have more endpoints we can access while working with the Jira Assets Rest APi. Check here for more.
Thanks for reading my article. I hope you have found this useful.
See you next time.
