Asset Forms

Page tree

Documentation for AssetForms app REST API v1.0


Configuration

To access AssetForms REST APIs you will need a token. Token can be generated via AssetForms app configuration

In "Manage apps" look for "AssetForms for Jira" and click "Configure" button

You will be presented with the configuration options available in AssetForms. Click on "API tokens" tab

Click on generate to generate new access token for the AssetForms REST API

Server URL is  https://app.assetforms.com

API prefix  /rest/api/v1


AssetForms REST API endpoints


MethodURL endpointRequest parametersErrorsExample
Get asset type by ID or keyGET

/assettype/get/{token}/{assetTypeIdOrKey}

  • {token} - REST API access token
  • {assetTypeIdOrKey} - asset type ID or key

400 - When "assetTypeId" is missing

404 - When asset type cannot be found by given ID

{
    "key": "ABC",
    "created": 1576498471883,
    "name": "My ABC asset",
    "id": "3b3d80c4-3980-4e5a-9f50-3db69103b193",
    "fields": [
      {
        "name": "mytestfield",
        "index": 1,
        "description": "Some description here",
        "label": "My test field",
        "type": "text",
        "required": true
      },
      {
        "name": "selectField",
        "options": {
          "1": "one",
          "2": "two",
          "3": "three"
        },
        "index": 2,
        "description": "",
        "label": "My super dropdown",
        "type": "select",
        "required": false
      }
    ]
  }
List asset typesGET

/assettype/list/{token}

  • {token} - REST API access token

Empty JSON array is returned when you don't have any asset type registered
[
{
    "key": "ABC",
    "created": 1576498471883,
    "name": "My ABC asset",
    "id": "3b3d80c4-3980-4e5a-9f50-3db69103b193",
    "fields": [
      {
        "name": "mytestfield",
        "index": 1,
        "description": "Some description here",
        "label": "My test field",
        "type": "text",
        "required": true
      },
      {
        "name": "selectField",
        "options": {
          "1": "one",
          "2": "two",
          "3": "three"
        },
        "index": 2,
        "description": "",
        "label": "My super dropdown",
        "type": "select",
        "required": false
      }
    ]
  },
]






Search assetsGET / POST

/asset/search/{token}/{assetTypeIdOrKey}

  • {token} - REST API access token
  • {assetTypeIdOrKey} - asset type ID or key

Supports optional parameters:

  • query - AssetForms Filters expected (empty means no filter and all records for this asset type are returned)
  • sort - Sorting in AssetForms
  • startAt - starts with 1 for first record if not specified. Must be a positive numeric value and larger than 0
  • limit - number of records to show per page. Maximum (and the default) number is 100 records per page
  • expandFields - comma separated list of field names to expand. This helps you to load referenced records via smart fields, or rich properties for "user" and "Jira" fields, as well as the data for web-service enabled fields

By default 100 assets loaded per page
Create or update assetPOST/asset/save/{token}/{assetTypeIdOrKey}

Expecting an input payload in JSON format that describes new Asset

Creates Asset

{
 "fields": {
   "name": "some name here",
   "mycheckboxfield": true,
   "textfield1": "",
   "multiuserfield": [
      "557058:49c2eeaf-b72c-4e4d-86a7-97c1a77b50b6", 
       "557058:dcece530-c784-4d86-a62d-25c2f2207210"
   ],
   "multijirafield": [
      "JTEST-203",
      "JTEST-141"
   ]
 }
}

Updates asset by "id"

{
 "fields": {
   "id": "e598a9c5-379c-4ed1-9f43-fd2b124411c8",
   "name": "some name here",
   "mycheckboxfield": true,
   "textfield1": "",
   "multiuserfield": [
      "557058:49c2eeaf-b72c-4e4d-86a7-97c1a77b50b6", 
      "557058:dcece530-c784-4d86-a62d-25c2f2207210"
   ],
   "multijirafield": [
       "JTEST-203",
       "JTEST-141"
   ]
 }
}





Get asset by ID or keyGET/asset/get/{token}/{assetTypeIdOrKey}/{assetIdOrKey}

Returns asset by key (or ID) of requested asset type

Supports (optional parameters)

  • expandFields - comma separated list of field names to expand. This helps you to load referenced records via smart fields, or rich properties for "user" and "Jira" fields, as well as the data for web-service enabled fields

Example


{
  "assetTypeId": "7f39c2ad-28aa-471b-bf50-ce929afbd249",
  "createdBy": "557058:49c2eeaf-b72c-4e4d-86a7-97c1a77b50b6",
  "created": 1584016196143,
  "name": "My super multi-select asset",
  "id": "e598a9c5-379c-4ed1-9f43-fd2b124411c8",
  "fields": {
    "description": "",
    "usermulti": "557058:49c2eeaf-b72c-4e4d-86a7-97c1a77b50b6,557058:dcece530-c784-4d86-a62d-25c2f2207210"
  },
  "key": "ABC-1"
}

Same asset, when expandFields=usermulti is given

{
  "assetTypeId": "7f39c2ad-28aa-471b-bf50-ce929afbd249",
  "createdBy": "557058:49c2eeaf-b72c-4e4d-86a7-97c1a77b50b6",
  "created": 1584016196143,
  "name": "My super multi-select asset",
  "id": "e598a9c5-379c-4ed1-9f43-fd2b124411c8",
  "fields": {
    "description": "",
    "usermulti": [
      {
        "accountId": "557058:49c2eeaf-b72c-4e4d-86a7-97c1a77b50b6",
        "fullName": "Sam Smith"
      },
      {
        "accountId": "557058:dcece530-c784-4d86-a62d-25c2f2207210",
        "fullName": "Johnny English"
      }
    ]
  },
  "key": "ABC-1"
}
Delete asset by ID or keyDELETE/asset/delete/{token}/{assetTypeIdOrKey}/{assetIdOrKey}Deletes asset by key (or ID) of requested asset type

Common errors / error codes

HTTP 401 is returned when "Authentication token is missing" or "Invalid or expired token" is provided