Jira Service Management (Assets)

Sync assets from vScope to Jira Service Management (JSM) Assets on a schedule. The import runs inside Jira and fetches CSV data through the vScope API, so no scripts or middleware are needed.

This guide uses Jira Assets’ documented web address import and import scheduling features for Jira Cloud.

Prerequisites

• Admin access to vScope.
• Assets schema manager or Assets app admin permission in Jira Cloud. See Assets roles and permissions.
• A vScope address that Jira can reach over public HTTPS.

---

Prepare the data in vScope

1. Create a user with the permission level Viewer and an API token for it, with an expiry date. See Export a saved table via API.
2. In Tables, select the asset type (for example Virtual Machines) and add the columns you want in Jira, such as Name, Operating System, CPU Total and RAM.
3. Add the column UUID. It is the stable identifier Jira will use to match later imports to existing objects.
4. Save the table and share it with the user from step 1 (Share > Collaborators).
5. Click Share > Copy link. The table ID is the last part of the URL, for example 1792055636942.
6. Build the CSV URL and open it in a browser to verify that it returns CSV data:

https://{VSCOPE_HOST}/v1/tables/{TABLE_ID}/data/csv?token={TOKEN}

The table controls what Jira can see

Jira can only fetch the rows and columns in the table, so add only what it needs.

Token in the URL

Jira Assets can only import from a public HTTPS address and cannot send custom headers, so the API token has to be part of the URL. We otherwise always recommend sending the token in the token header, because URLs are often stored in proxy and server logs. To limit the risk:

• Use a dedicated Viewer user, and share only the Jira table with that user.
• Set an expiry date on the token and renew it before it expires.
• To limit who can reach vScope from the internet, allow only the IP addresses published by Atlassian.

---

Create the object type and attributes in Jira

1. In Jira, open Assets and create an object schema (or open an existing one).
2. Create an object type for the assets, for example Virtual Machine.
3. Create attributes for the columns you want to import. At minimum, create a Text attribute for UUID and attributes for Name and the other vScope columns.

Create one table, one import and one object type for each asset type (for example virtual machines and hosts). This keeps each import’s identifier and missing-object behavior isolated. Web address imports are limited to 40 MB.

---

Create the import

1. In the object schema, open Schema settings and select the Import tab.
2. Click Create import and select CSV Import.
3. Enter a Name, select Import data from a web address and paste the CSV URL.
4. Disable Automatically create object types and attributes. This guide maps the CSV to the object type you created above.
5. Click Create.

For details about these options, see Atlassian’s guide to importing data from a web address.

---

Map the columns

1. On the import, select Edit mapping.
2. Select Create mapping and choose the object type you created above.
3. Configure how Jira should handle objects that disappear from the vScope table:
   • Ignore leaves the Jira object unchanged. This is the safest starting point.
   • Update changes an attribute, for example an In vScope attribute from Yes to No.
   • Remove deletes objects that are no longer in the source. Use a threshold to avoid deleting objects after a temporary incomplete export.
4. Save the object type mapping, then select Edit attributes mapping.
5. Map each vScope data source field to its destination attribute.

vScope column	Assets attribute	Type	Note
UUID	UUID	Text	Select as the import Identifier, and set the attribute to Unique to get warnings about duplicates.
Name	Name	Text	Human-readable asset name. Do not use as the identifier unless it is unique and never changes.
Operating System, CPU Total, RAM, …	Matching attributes	Text, Integer, etc.	As needed.

When the import runs again, a row with the same identifier updates the existing object; an identifier not already present creates a new object. UUID is therefore a better identifier than a potentially duplicated or renamed asset name. One identifier is enough for this import, but Assets allows more than one if you need it. See Create attributes and references from your data.

For all missing-object options and threshold behavior, see Create Assets objects from data using object type mapping.

Optional: link back to vScope

Jira converts a source value to a URL attribute when the complete value begins with http:// or https://. If your vScope table contains a column with the complete asset URL, map that column to a URL attribute in Assets.

Do not enter https://{VSCOPE_HOST}/ui/properties/${UUID} as an attribute mapping. Atlassian documents placeholders for AQL reference lookups, not as a general-purpose template for creating attribute values. If the CSV does not contain the complete URL, omit this attribute. See Prepare your data for importing into Assets and Using placeholders in AQL.

Enable the mappings

The import can’t run until every object type mapping is enabled. Right-click each mapping and select Enable.

---

Optional: add relations to other objects

The steps above import each vScope table into one object type, one to one. In Jira you often want objects connected to each other, for example a server that points to its operating system, or a laptop that points to its user. Assets does this with attributes that reference other objects or users.

Reference another object type

Example: each server references an Operating System object type that has its own import.

1. In vScope, create a table for the referenced objects (for example operating systems) and a table column on the server table that contains the same value, such as the operating system name.
2. Create the referenced object type and its import first, and run it, so the objects exist when the servers are imported.
3. On the server object type, create an attribute of type Object that references Operating System.
4. In the server import, open Edit attributes mapping, map the vScope column to that attribute, and set the Reference mapping to look up the object by its Label. The AQL lookup is Label = ${Operating System}, where Operating System is the name of the CSV column.
5. For several references in one cell, separate the values with || and use Label IN (${Operating System${0}}).

See Atlassian’s guide to creating attributes and references from your data.

Connect to a Jira user

Example: each laptop belongs to a person.

1. Include a column with the person’s email address in the vScope table.
2. On the laptop object type, create an attribute of type User.
3. Map the email column to that attribute. Assets matches Jira users by email address or Atlassian account ID, not by user name.

See Atlassian’s guide to preparing your data for import.

To connect to a User object type in Assets instead of a Jira user, use an Object attribute and a lookup on the attribute that holds the email address, as described above.

---

Run and schedule the import

1. Click Import data to run the import once.
2. Open the import history and confirm that objects were created without warnings.
3. Change a non-identifier value in the vScope table, run the import again and confirm that Jira updates the existing object instead of creating a duplicate.
4. Note the import configuration ID from the import history. You need it to schedule the import.

Schedule with Automation (recommended for production)

Use a Jira Automation rule to start the import on a schedule. Unlike the built-in schedule, the rule doesn’t depend on one person’s Assets permissions.

1. Create a dedicated Jira service account with permission to manage imports, and create an API token for it.
2. In Jira, go to Project settings > Automation > Create rule.
3. Set the trigger to Scheduled, for example daily.
4. Add a Send web request action:
   • URL: https://api.atlassian.com/jsm/assets/workspace/{WORKSPACE_ID}/v1/import/start/{IMPORT_CONFIGURATION_ID}
   • Method: POST
   • Headers: Authorization = Basic followed by the base64-encoded {email}:{API_TOKEN} of the service account, and Accept = application/json
   • Body: empty
5. Publish the rule, then check the import history after the scheduled time.

For how to find the workspace ID and more details, see Atlassian’s article Schedule Assets import using Automation.

New assets discovered by vScope are now added to Jira automatically, and existing objects are updated.

Alternative: built-in schedule

The built-in schedule is easy to set up and works well for testing:

1. In the Imports list, open More actions (•••) for the import and select Create schedule.
2. Choose Once, Daily, Weekly or Monthly, set the date and time, then save.

The schedule uses the time zone in your Atlassian profile and depends on the user who creates or last updates it. Jira disables the schedule if that user is removed or loses permission to manage imports, and the import then stops. See Schedule an Assets import.

Tip

Atlassian recommends testing an import manually before scheduling it.

---

Troubleshooting

• Jira can’t read the file: Confirm that the URL is public, uses HTTPS and has a valid certificate. To test it from Jira, create a scheduled Automation rule with a Send web request action to the CSV URL, followed by Log action steps that print {{webResponse.status}} and {{webResponse.body}}. The audit log then shows what Jira received. Delete the rule when you are done, since it contains the token.
• 401/403: The token is missing, wrong or expired. Create a new token and update the import URL.
• 404: The table ID is wrong, or the table isn’t shared with the user that owns the token.
• Nothing is imported: Enable all object type mappings.
• Duplicate objects: Confirm that UUID is mapped as the one import Identifier and that its values are present and unique.
• Objects remain after disappearing from vScope: Check the object type mapping’s Missing objects option and threshold.
• The built-in schedule stopped: Check that the schedule owner still has permission to manage imports, then open and save the schedule as an Assets schema manager or Assets app admin. To avoid this, schedule the import with Automation.
• The Automation rule fails: Check the rule’s audit log for the response status. 401/403 means the service account’s token or permissions are wrong, 404 means the workspace ID or import configuration ID is wrong.

For more help with API access, see Troubleshoot API access issues.