API

Asset Studio can be read/edited via API, to automate creation of pages.

Note: This is not available on Asset Studio (Dashboard gadget).

1 Steps to get started
2 Get Asset Studio configuration and IDs via API
- 2.1 Required parameters:
- 2.2 Response:
3 Update Asset Studio configuration via API
- 3.1 Required parameters:
- 3.2 Required post body:
- 3.3 Response:
4 Create Page with Asset Studio configuration via API
- 4.1 Required parameters:
- 4.2 Required post body:
- 4.3 Response:
5 Copy Page and update Asset Studio configuration via API
- 5.1 Required parameters:
- 5.2 Required post body:
- 5.3 Response:
6 Display As options

Steps to get started

Go to Manage Apps → Asset Studio → Configuration
Click the API tab.

To enable API access you need to generate an access token.

Click the Generate Access Token - button to generate one or more tokens.

By default the access token will be applicable for all spaces with Read and Write permissions.

Click the Edit link to edit token permissions

Get Asset Studio configuration and IDs via API

Make a HTTP GET request to the URL available on your API page.

Use this API when you need to retreive a Asset Studio configuration.

Method	URI	Query Params	Token Scope	Token Space(s)	Description

Method

URI

Query Params

Token Scope

Token Space(s)

Description

GET

api_url

^{found on API page of Macro Configuration}

pageId
token

READ

can be limited using space list or empty to allow all spaces.

Returns an array of Asset Studio configuration for a specific page using pageId query parameter.
Example;

GET {api_url}/macro?pageId=1234&token=xxx-yyyy

Required parameters:

token = the access token (scope must be READ and space must match page space)

pageId = the page to read macro configuration values from

Response:

200 OK (application/json) When request is valid

Response Body:

[
    {
        "id": "rxt-95ae25ba-0759-4b4e-a40f-edbdc7194067",
        "configuration": {
            "columns": [],
            "iql": "objectType=\"Jira Users\"",
            "displayAs": "AS_TABLE",
            "pageSize": 5,
            "schemaId": "4",
            "connectionId": "45157a8a-79ad-46f7-b920-c21211bf79ec",
            "tableOptions": {
                "linksEnabled": true,
                "downloadEnabled": false,
                "printEnabled": false
            }
        }
    }
]

400 BAD REQUEST When request is invald

Body:

Error message describing the problem

Note: Verify parameters to resolve this issue

401 UNAUTHORIZED When request is unauthorized.

Body:

Error message

Note: Verify access token permissions to resolve this issue

Update Asset Studio configuration via API

Make a HTTP PUT request to the URL available on your API page.

Use this API when you want to update Asset Studio configuration on a page.

You can read the current macro config using the GET api and then use those IDs to update the macro configuration using this endpoint.

Method	URI	Query Params	Token Scope	Token Space(s)	Description

Method

URI

Query Params

Token Scope

Token Space(s)

Description

PUT

api_url

^{found on API page of Macro Configuration}

pageId
token

WRITE

can be limited using space list or empty to allow all spaces.

Updates all Asset Studio configuration specified in the body for a specific page using pageId param. Macro to update matches on “id” property in body

Use GET on a page to fetch format of a macro configuration.

Example;

PUT {api_url}?pageId=1234&token=xxx-yyy
body:

[
  {
    "id": "rxt-95ae25ba-0759-4b4e-a40f-edbdc7194067",
    "configuration": {
        "columns": [],
        "iql": "objectType=\"Jira Users\"",
        "displayAs": "AS_TABLE",
        "pageSize": 5,
        "schemaId": "4",
        "connectionId": "45157a8a-79ad-46f7-b920-c21211bf79ec",
        "tableOptions": {
            "linksEnabled": true,
            "downloadEnabled": false,
            "printEnabled": false
        }
    }
  } 
]

Required parameters:

token = the access token (scope must be WRITE and space must match page space)

pageId = the page to store the macro config on values from

Required post body:

An array of macro configuration, use multiple configuration JSON objects to update multiple configurations on the page. Note: To update a single value this still has to be an array containing the single value entity.

[
     {
        "id": "rxt-95ae25ba-0759-4b4e-a40f-edbdc7194067",
        "configuration": {
            "columns": [],
            "iql": "objectType=\"Okta Policies\"",
            "displayAs": "AS_TABLE",
            "pageSize": 5,
            "schemaId": "4",
            "connectionId": "45157a8a-79ad-46f7-b920-c21211bf79ec",
            "tableOptions": {
                "linksEnabled": true,
                "downloadEnabled": false,
                "printEnabled": false
            }
        }
    }
]

Response:

200 OK When request is valid and value was updated

Body:

{
    "status": "SUCCESS",
    "message": "Macro for pageId 1979514881 has been updated!"
}

400 BAD REQUEST When request is invalid

Body:Bad Request

Note: Verify parameters to resolve this issue

401 UNAUTHORIZED When request is unauthorized.

Body: Unauthorized

Note: Verify access token permissions to resolve this issue

Create Page with Asset Studio configuration via API

Make a HTTP POST request to the URL available on your API page.

Use this when you want to programatically create a new page with the Asset Studio on it with pre-configured settings.

Method	URI	Query Params	Token Scope	Token Space(s)	Description

Method

URI

Query Params

Token Scope

Token Space(s)

Description

POST

api_url

^{found on API page of Macro Configuration}

spaceKey
token

WRITE

can be limited using space list or empty to allow all spaces.

Creates one or more new page(s) with Asset Studio added and pre-configured.

spaceKey determine what space to add the page in.

Body takes an array of pages title and parent with macro configuration.

Example;

Post {api_url}?spaceKey=ABC&token=xxx-yyy
body:

[
    {
        "title":"New page",
        "parentPageId":null,
        "macros":[
            {
                "id": "",
                "configuration": {
                    "columns": [],
                    "iql": "objectType=\"Jira Users\"",
                    "displayAs": "AS_ITEM",
                    "pageSize": 5,
                    "schemaId": "4",
                    "connectionId": "45157a8a-79ad-46f7-b920-c21211bf79ec",
                    "tableOptions": {
                        "linksEnabled": true,
                        "downloadEnabled": false,
                        "printEnabled": false
                    }
                }
            }
        ]
    }
]

Required parameters:

token = the access token (scope must be WRITE and space must match spaceKey)

spaceKey = the spaceKey to store the page with macro config on.

Required post body:

An array of pages with macro configuration. Note: To update a single value this still has to be an array containing the single value entity.

Each array object takes a title and optional parenPageId and the list of macros to add.

[
    {
        "title":"NY page",
        "parentPageId":1977778177,
        "macros":[
            {
                "id": "",
                "configuration": {
                    "columns": [],
                    "iql": "objectType=\"Jira Users\"",
                    "displayAs": "AS_ITEM",
                    "pageSize": 5,
                    "schemaId": "4",
                    "connectionId": "45157a8a-79ad-46f7-b920-c21211bf79ec",
                    "tableOptions": {
                        "linksEnabled": true,
                        "downloadEnabled": false,
                        "printEnabled": false
                    }
                }
            }
        ]
    }
]

Response:

200 OK When request is valid and value was updated

Body:

{
    "status": "SUCCESS",
    "message": "Page has been created with Macro for space fff, new page(s) are 1979514881",
    "newPages": [
        "1979514881"
    ]
}

400 BAD REQUEST When request is invalid

Body:Bad Request

Note: Verify parameters to resolve this issue

401 UNAUTHORIZED When request is unauthorized.

Body: Unauthorized

Note: Verify access token permissions to resolve this issue

Copy Page and update Asset Studio configuration via API

Make a HTTP PATCH request to the URL available on your API page.

Use this when you want your system to automatically make copies of a page that already has the Asset Studio on it. Each copy will have the macro already set up for a specific Work Item or Asset.

For example, if you have a template page and an automation rule detects a new Work Item or Asset, this feature will create a new page from that template and update the macro so it shows information about the new Work Item or Asset.

Method	URI	Query Params	Token Scope	Token Space(s)	Description

Method

URI

Query Params

Token Scope

Token Space(s)

Description

PATCH

api_url

^{found on API page of Macro Configuration}

pageId
spaceKey
token

WRITE

can be limited using space list or empty to allow all spaces.

Copies one page and creates one or more new page(s) with Asset Studio added and pre-configured.

spaceKey determine what space to add the page in.

pageId determine the page to copy.

Body takes an array of pages with macro configuration

Example;

PATCH {api_url}?spaceKey=ABC&spaceKey=SK&token=xxx-yyy
body:

[
  {
    "title":"Page title",
    "parentPageId":"id of parent page or null on root level",
    "macros":[
      {
            "id": "rxt-95ae25ba-0759-4b4e-a40f-edbdc7194067",
            "configuration": {
                "columns": [],
                "iql": "objectType=\"Jira Users\"",
                "displayAs": "AS_TABLE",
                "pageSize": 5,
                "schemaId": "4",
                "connectionId": "45157a8a-79ad-46f7-b920-c21211bf79ec",
                "tableOptions": {
                    "linksEnabled": true,
                    "downloadEnabled": false,
                    "printEnabled": false
                }
            }
      }
    ]
  }
]

Required parameters:

token = the access token (scope must be WRITE and spaces must match both spaceKey for destination space and page space)

spaceKey = the spaceKey to store the page with macro config on.

pageId = the page to read the macro config on values from

Required post body:

An array of pages with macro configuration. Note: To update a single value this still has to be an array containing the single value entity.

Each array object takes a title and optional parenPageId and the list of macros to add.

[
    {
        "title":"NY page",
        "parentPageId":1977778177,
        "macros":[
            {
                "id": "",
                "configuration": {
                    "columns": [],
                    "iql": "objectType=\"Jira Users\"",
                    "displayAs": "AS_ITEM",
                    "pageSize": 5,
                    "schemaId": "4",
                    "connectionId": "45157a8a-79ad-46f7-b920-c21211bf79ec",
                    "tableOptions": {
                        "linksEnabled": true,
                        "downloadEnabled": false,
                        "printEnabled": false
                    }
                }
            }
        ]
    }
]

Response:

200 OK When request is valid and value was updated

Body: OK

400 BAD REQUEST When request is invalid

Body:Bad Request

Note: Verify parameters to resolve this issue

401 UNAUTHORIZED When request is unauthorized.

Body: Unauthorized

Note: Verify access token permissions to resolve this issue

Display As options

Display types	Value

Display types	Value
As card	`AS_ITEM`
Horizontal table	`AS_TABLE`
Vertical Table	`AS_VERTICAL_TABLE`
Pie chart	`AS_PIE`
Bar chart	`AS_BAR`