Authorization

The APM Asset microservices use the Predix UAA service for user authentication and authorization. To use the service endpoints, you must first obtain an authorization token and pass this token in the request header when requesting resources through the REST endpoints.

POST /oauth/token?grant_type=password&username=<username>&password=<password>

To obtain the authorization token, make a HTTP or cURL POST request. In the request Authorization,

  1. Select the type Basic Auth.

  2. Enter the Username and Password.

The Authorization header is automatically generated with the value:
“Basic <Base64(client_username:client_password)>”

Where
<Base64(client_username:client_password)> is the Base64-encoded string containing the username:password.

Example cURL Request

$ curl -X POST -H "Authorization: Basic b29hcHA6b29hcHBzZWNyZXQ=" -H "Cache-Control: no-cache"  "https://92263bd8-7adf-4060-9c4e-b9316a85dae4.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token?grant_type=password&username=<username>&password=<password>"

Example Response

Status: 200: OK
Loading time: 1141 ms
Response headers (14)
Access-Control-Allow-Origin :*
Cache-Control :no-cache, no-store, max-age=0, must-revalidate, no-store
Content-Type :application/json;charset=UTF-8
Correlation-Id :3f40c5ad-babb-471a-a119-f4931e05415e
Date :Thu, 02 Jun 2016 14:45:16 GMT
Expires :0
Pragma :no-cache, no-cache
Server :Apache-Coyote/1.1
Strict-Transport-Security :max-age=31536000 ; includeSubDomains
Transfer-Encoding :chunked
X-Content-Type-Options :nosniff
X-Frame-Options :DENY
X-Vcap-Request-Id :84b392d2-aadb-4c74-4a3b-83b0f2534fae
X-Xss-Protection :1; mode=block

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI4YjE2NWQ4ZC1hZGUwLTQyMTQtODg1My1jZGZhOWY0ZDZiMDgiLCJzdWIiOiI2OWUwNTdmNC0zMWM2LTRhOTQtYWI2NC00OWVkODEyNWZiMWUiLCJzY29wZSI6WyJvcGVuaWQiXSwiY2xpZW50X2lkIjoib29odWJ1c3IiLCJjaWQiOiJvb2h1YnVzciIsImF6cCI6Im9vaHVidXNyIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjY5ZTA1N2Y0LTMxYzYtNGE5NC1hYjY0LTQ5ZWQ4MTI1ZmIxZSIsIm9yaWdpbiI6InVhYSIsInVzZXJfbmFtZSI6InNwaWRlcm1hbiIsImVtYWlsIjoic3BpZGVybWFuQG1hcnZlbC5jb20iLCJhdXRoX3RpbWUiOjE0NjQ4Nzg3MTYsInJldl9zaWciOiI2N2RjZDRkZCIsImlhdCI6MTQ2NDg3ODcxNiwiZXhwIjoxNDY0OTIxOTE2LCJpc3MiOiJodHRwczovL2Q5NzkzOGIxLWNhYTQtNDE4NS04OTIzLTAzNTUwNjBkOWE3Ni5wcmVkaXgtdWFhLnJ1bi5hc3YtcHIuaWNlLnByZWRpeC5pby9vYXV0aC90b2tlbiIsInppZCI6ImQ5NzkzOGIxLWNhYTQtNDE4NS04OTIzLTAzNTUwNjBkOWE3NiIsImF1ZCI6WyJvb2h1YnVzciIsIm9wZW5pZCJdfQ.A3osxGfK9COSKvdUHIj9fT-SFE_TlvlcqBLaIpt4hS5AWgEL_J2uyDmMndlBa-qjLfiAYksLf3W631lGW9yi8vy4plAugljIimdwr1HsDP6rMKMa9SSx26yZaIC0smgpYj5CgHlWC6d3FGRMrejlhHwxU_kMuIAAq1IL6ORluiJCTsMbMeivL7o6w9gzBJ0K3uhpWN5A45dz_cJwTwYVwk2sEYy_jBEOZ1taPF3aPBxLvcK8zrGfeMNVkEUZVc3LhnWA7hG6NuoJBak1K6piANzz-myVCvI9sHsiNATH-tJwg0Ih5pzD2ge_OqxsDQkqfrzSAb-ff8maSAe9KuuSYg",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIyODYyMmE4NC0xNzgxLTRkMDktYWRmZC1hYzdkYTdhOTY2NTAtciIsInN1YiI6IjY5ZTA1N2Y0LTMxYzYtNGE5NC1hYjY0LTQ5ZWQ4MTI1ZmIxZSIsInNjb3BlIjpbIm9wZW5pZCJdLCJpYXQiOjE0NjQ4Nzg3MTYsImV4cCI6MTQ2NzQ3MDcxNiwiY2lkIjoib29odWJ1c3IiLCJjbGllbnRfaWQiOiJvb2h1YnVzciIsImlzcyI6Imh0dHBzOi8vZDk3OTM4YjEtY2FhNC00MTg1LTg5MjMtMDM1NTA2MGQ5YTc2LnByZWRpeC11YWEucnVuLmFzdi1wci5pY2UucHJlZGl4LmlvL29hdXRoL3Rva2VuIiwiemlkIjoiZDk3OTM4YjEtY2FhNC00MTg1LTg5MjMtMDM1NTA2MGQ5YTc2IiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9uYW1lIjoic3BpZGVybWFuIiwib3JpZ2luIjoidWFhIiwidXNlcl9pZCI6IjY5ZTA1N2Y0LTMxYzYtNGE5NC1hYjY0LTQ5ZWQ4MTI1ZmIxZSIsInJldl9zaWciOiI2N2RjZDRkZCIsImF1ZCI6WyJvb2h1YnVzciIsIm9wZW5pZCJdfQ.FN7Spn8Zv22EOaaHpTmLIOsVZWYSAKVX0qoSwdLxv7Op1isgsDzxX_ctAeI2SnaaNW6hQiuHQZJ0GQ1CFF6lGrwHcQhGX8mrO9SmSH7gYX4m-8MbYV1w7fLcy2jbob1HiRqw2OC5P6juLGSVQDt_klweXsBahbsZpM-q2n3IQjtu76YKOYyb8uYMZPipHIVCipa8ASHEjk76bRVRgv9V6f2ECszLKSUOTO4INiFmJbErshjfUDJ0285N2WLAPlaIqP_L6dgR3LrXLk6eY-zvPGzAQezGkmxhboWAYcmN0NkkRNinbrbF5i3bHXDDD7hEPOMI3c0uJgDQFyJU_R6Fog",
  "expires_in": 43199,
  "scope": "openid",
  "jti": "8b165d8d-ade0-4214-8853-cdfa9f4d6b08"
}

For information on Predix UAA services, click the following link:

Asset Ingestion Endpoint

The asset ingestion microservice provides a POST method to upload your asset model and data. Before the data is ingested into the APM asset persistent data store in Predix, a copy of the ZIP file used for ingestion is retained in the Predix blobstore. The files are queued to be processed and eventually ingested into the persistent data store for retrival and processing. Each ingestion logs an ingestion task in the adaptor configuration for tracking the ingestion status.

About the Asset Model

An asset is a digital abstraction of something in the physical world. It can be an enterprise, organization, site, machine train, or equipment. Creating an asset model in APM enables an application built on APM consistently derive data for these common assets.

As you build your asset model, use the following process to understand the structure of an ingestion file and develop a script or utility to convert the customer asset data to asset-ingestion files.

  • Understand how APM asset provides the S95 adapter that uses four ccomclasses namely enterprise, site, segment, and asset to model all levels and assets as nodes in the asset hierarchy. As you create your asset model, match all nodes to one of these four ccomclasses.

  • Develop the classifications needed to model the nodes in your asset hierarchy. Each node represents a single classification instance. However, a single classification can have many instances (for example, COM167034664, COM167023409, COM167045789 are multiple instances of the same kind of centrifugal compressor 3MCL).

  • Determine the connections needed to build out the asset hierarchy. Use the parent connection, for example, to create a parent-child relationship between an asset instance and a segment instance.

  • Define the tags used in the customer asset hierarchy.

  • Determine each tag’s association with a node. You can apply the same tag to many nodes.

  • Create a JSON file to house your asset model, following the structure in the sample asset ingestion file. Examine the example classifications, instances, tags and tag associations from the sample file as patterns to create these objects in your file.

You can build a single JSON file with the complete asset model using all model elements (including asset classifications, instances, connections, tag classifications and tag associations), or you can save each model element as a separate JSON file.

Example asset models:

  • Enterprise > Site > Segment > Asset

  • Enterprise > Site > Asset

  • Enterprise > Site > Segment > Segment > Asset

  • Enterprise > Site > Site> Segment > Segment > Asset

Asset Ingestion Process

Typically, a system integrator or customer administrator performs the asset ingestion. The ingestion process includes the following actions:

  1. Creating an asset ingestion file. Asset ingestion files are JSON files that specify customer assets and their hierarchical structure or asset model. You can specify a complete set of assets and its asset model in a single JSON file within a ZIP file, or as discrete JSON files for each type, such as classifications, instances, connections, tag classifications, and tag associations within a single ZIP file.

  2. Submitting the ingestion file through the REST endpoint. Appropriate credentials are needed to submit an asset ingestion file. Ask the customer administrator to provide the asset ingestor user ID and password.

  3. Verifying the ingestion. After submitting an ingestion file, log into APM to verify that the asset model and assets were ingested correctly. Correct any errors in the ingestion file and resubmit as needed.

  4. Reingesting the data. If you re-ingest data with existing id, the new data replaces existing data. This applies to both classification and instances alike, with the exception of tags that are not updated this way. Any data with new id ingests as new records.

Asset Ingestion File

Determine how to extract asset hierarchy data and convert it to the JSON asset-ingestion file. Use the JSON asset-ingestion file to build an inventory of the assets and levels that make up the existing customer asset hierarchy. You also can use the file to develop an asset hierarchy for a new customer. Typically, the source of the hierarchy comes from a customer database. After building the asset model and data for ingestion, create a ZIP file containing JSON code for ingesting assets into APM.

The following applies to the asset ingestion JSON file(s):

  • It must conform to the specified JSON format with all the required elements. s95-sample to download the template JSON.Note: If clicking the link fails to initiate the file download, then, right-click on the link and select the option to save the file. Depending on the browser this option varies. For example, in Chrome, this option is Save as and in IE this option is Save target as. It gives you a way to save the file locally. After downloading the file, navigate to the saved folder and open the file in a text editor for viewing or editing.

  • The values in the JSON must not contain the following characters $ < > : | ( ) , = ! ? & \. The following code example illustrates invalid use of characters:

    {
       "classifications":[
       {
             "id":"<Sample-ASSET-ENTERPRISE>",
             "name":"Sample & Co, Inc",
             "description":"This is a sample enterprise!",
             "ccomClass":"ENTERPRISE_TYPE",
             "parent":null
          },
          {
             "id":"Sample-ASSET-SITE",
             "name":"North|South America Region",
             "description":"Represents Northern & Southern regions",
             "ccomClass":"SITE_TYPE",
             "parent":null
          }
    ]}
  • It may be split into individual JSON files each for classifications, instances, connections, tagClassifications and tagAssociations.

  • It may be combined into a single ZIP file or can be ingested as separate ZIP files.

  • Single ZIP file with multiple JSON must contain files in the following order:

    1. your_classifications.json

    2. your_instances.json

    3. your_connections.json

    4. your_tagClassifications.json

    5. your_tagAssociations.json

  • Make sure you use a compression utility that produces ZIP files without introducing the control character (CTRL-CHAR). You can use one of the following that applies to you:

    • In Mac OS, compress the JSON into a ZIP file using command line compression utility.

      zip -r archive_name.zip your_classifications.json your_instances.json your_connections.json your_tagClassifications.json your_tagAssociations.json
    • In Windows, use utilities such as 7-Zip or WinZip to create the ZIP file. Make sure to add the JSON files in the order specified above.

Starting An Ingestion Task

Use the POST method to create an asset resource to be ingested into the Predix Asset store. After submitting the request, the ingestion happens asynchronously, which means that your request is queued for the server to process it. An ingestion task is created. You can check the ingestion progress through HTTP GET to make sure if ingestion was successful. Save the uuid from the JSON response for tracking purposes.

Example CURL Request
$ curl 'https://apm-asset-adapter-svc-rc.int-app.aws-usw02-pr.predix.io/v1/asset/upload' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Content-Type: multipart/form-data' -H 'Accept: application/json' -F 'file=<file>'
Example HTTP Request
POST /v1/asset/upload HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Content-Type: multipart/form-data
Accept: application/json
Host: apm-asset-adapter-svc-rc.int-app.aws-usw02-pr.predix.io
Example JSON File
{
  "classifications" : [ {
    "id" : "Demo_enterprise_supertype",
    "name" : "Demo_enterprise_supertype",
    "description" : "This is the type of parent enterprise type",
    "ccomClass" : "ENTERPRISE_TYPE",
    "parent" : null
  }, {
    "id" : "Demo_enterprise_type",
    "name" : "Demo_enterprise_type",
    "description" : "This is the type of enterprise",
    "ccomClass" : "ENTERPRISE_TYPE",
    "properties" : [ {
      "id" : "Demo Enterprise Asset Type",
      "value" : [ "Demo Enterprise Asset Type" ],
      "type" : "string"
    } ],
    "parent" : "Demo_enterprise_supertype"
  }, {
    "id" : "Demo_enterprise_subtype",
    "name" : "Demo_enterprise_subtype",
    "description" : "This is the type of child enterprise type",
    "ccomClass" : "ENTERPRISE_TYPE",
    "parent" : "Demo_enterprise_type"
  }, {
    "id" : "Demo_site_supertype",
    "name" : "Demo_site_supertype",
    "description" : "This is the type of parent site type",
    "ccomClass" : "SITE_TYPE",
    "parent" : null
  }, {
    "id" : "Demo_site_type",
    "name" : "Demo_site_type",
    "description" : "This is the type of site type",
    "ccomClass" : "SITE_TYPE",
    "properties" : [ {
      "id" : "Demo Site Asset Type",
      "value" : [ "Demo Site Asset Type" ],
      "type" : "string"
    } ],
    "parent" : "Demo_site_supertype"
  }, {
    "id" : "Demo_site_subtype",
    "name" : "Demo_site_subtype",
    "description" : "This is the type of site type ",
    "ccomClass" : "SITE_TYPE",
    "parent" : "Demo_site_type"
  }, {
    "id" : "Demo_segment_supertype",
    "name" : "Demo_segment_supertype",
    "description" : "This is the super type of segment",
    "ccomClass" : "SEGMENT_TYPE",
    "parent" : null
  }, {
    "id" : "Demo_segment_type",
    "name" : "Demo_segment_type",
    "description" : "This is the segment type",
    "ccomClass" : "SEGMENT_TYPE",
    "properties" : [ {
      "id" : "Demo Segment Asset Type",
      "value" : [ "Demo Segment Asset Type" ],
      "type" : "string"
    } ],
    "parent" : "Demo_segment_supertype"
  }, {
    "id" : "Demo_segment_subtype",
    "name" : "Demo_segment_subtype",
    "description" : "This is the segment type children",
    "ccomClass" : "SEGMENT_TYPE",
    "parent" : "Demo_segment_type"
  }, {
    "id" : "Demo_asset_grand_supertype",
    "name" : "Demo_asset_grand_supertype",
    "description" : "This is the parent of parent asset type",
    "ccomClass" : "ASSET_TYPE",
    "parent" : null
  }, {
    "id" : "Demo_asset_supertype",
    "name" : "Demo_asset_supertype",
    "description" : "This is the parent of asset type",
    "ccomClass" : "ASSET_TYPE",
    "parent" : "Demo_asset_grand_supertype"
  }, {
    "id" : "Demo_asset_type",
    "name" : "Demo_asset_type",
    "description" : "This is the type 2 of asset",
    "properties" : [ {
      "id" : "ActualAssetType",
      "value" : [ "ActualAssetType" ],
      "type" : "string"
    } ],
    "reservedProperties" : {
      "familyType" : "",
      "equipmentType" : "",
      "make" : "GE",
      "model" : "GTX-50",
      "series" : "GTX",
      "serialNumber" : null,
      "maintenanceCriticalityRiskScore" : 7,
      "faultMode" : [ "1", "2" ]
    },
    "ccomClass" : "ASSET_TYPE",
    "parent" : "Demo_asset_supertype"
  }, {
    "id" : "Demo_asset_subtype",
    "name" : "Demo_asset_subtype",
    "description" : "This is the child of asset type",
    "properties" : [ {
      "id" : "child",
      "value" : [ "childAssetType" ],
      "type" : "string"
    } ],
    "ccomClass" : "ASSET_TYPE",
    "parent" : "Demo_asset_type"
  }, {
    "id" : "Demo_asset_type_reserved",
    "name" : "Demo_asset_type_reserved",
    "description" : "This is the parent of parent asset type",
    "reservedProperties" : {
      "familyType" : "",
      "equipmentType" : "",
      "make" : "GE",
      "model" : "GTX-50",
      "series" : "GTX",
      "serialNumber" : null,
      "maintenanceCriticalityRiskScore" : 7,
      "faultMode" : [ "1" ]
    },
    "properties" : [ {
      "id" : "ch_attr_min",
      "type" : "Character",
      "value" : [ "A" ]
    }, {
      "id" : "ch_attr_max",
      "type" : "Character",
      "value" : [ "Z" ]
    }, {
      "id" : "ch_attr_array",
      "type" : "Character",
      "value" : [ "Z", "a", "v", "N", "q", "i" ]
    }, {
      "id" : "sh_attr_min",
      "type" : "Short",
      "value" : [ -32768 ]
    }, {
      "id" : "sh_attr_max",
      "type" : "Short",
      "value" : [ 32767 ]
    }, {
      "id" : "sh_attr_array",
      "type" : "Short",
      "value" : [ 32767, 300, 600, 90, 158, -32768 ]
    }, {
      "id" : "int_attr_min",
      "type" : "Integer",
      "value" : [ -2147483648 ]
    }, {
      "id" : "int_attr_max",
      "type" : "Integer",
      "value" : [ 2147483647 ]
    }, {
      "id" : "int_attr_array",
      "type" : "Integer",
      "value" : [ 2147483647, 200, -500, 600, 99999, -1452895 ]
    }, {
      "id" : "fl_attr_min",
      "type" : "Float",
      "value" : [ -3.4E38 ]
    }, {
      "id" : "fl_attr_max",
      "type" : "Float",
      "value" : [ 3.4E38 ]
    }, {
      "id" : "fl_attr_array",
      "type" : "Float",
      "value" : [ 3.4E38, 3.2E38, 3.1E38 ]
    }, {
      "id" : "dbl_attr_min",
      "type" : "Double",
      "value" : [ -1.7E308 ]
    }, {
      "id" : "dbl_attr_max",
      "type" : "Double",
      "value" : [ 1.7E308 ]
    }, {
      "id" : "dbl_attr_array",
      "type" : "Double",
      "value" : [ 1.7E308, 1.6E302, 1.4E302, 1.1E38 ]
    }, {
      "id" : "bool_attr_true",
      "type" : "Boolean",
      "value" : [ true ]
    }, {
      "id" : "bool_attr_fal",
      "type" : "Boolean",
      "value" : [ false ]
    }, {
      "id" : "ts_attr",
      "type" : "Timestamp",
      "value" : [ "07/15/2016 04:45:30" ]
    }, {
      "id" : "ts_attr_array",
      "type" : "Timestamp",
      "value" : [ "07/15/2016 04:45:30", "07/16/2016 04:45:30", "08/20/2016 04:45:30", "09/21/2016 04:45:30" ]
    }, {
      "id" : "str_attr_min",
      "type" : "String",
      "value" : [ "H" ]
    }, {
      "id" : "str_attr_max",
      "type" : "String",
      "value" : [ "This is a string " ]
    }, {
      "id" : "str_attr_array",
      "type" : "String",
      "value" : [ "First", "Second", "Third", "Fourt" ]
    } ],
    "ccomClass" : "ASSET_TYPE",
    "parent" : null
  }, {
    "id" : "Demo_asset_type_attributes",
    "name" : "Demo_asset_type_attributes",
    "description" : "This is the parent of parent asset type",
    "reservedProperties" : {
      "familyType" : "",
      "equipmentType" : "",
      "make" : "GE",
      "model" : "GTX-50",
      "series" : "GTX",
      "serialNumber" : null,
      "maintenanceCriticalityRiskScore" : 7,
      "faultMode" : [ "1", "2" ]
    },
    "properties" : [ {
      "id" : "Custom Attribute",
      "type" : "String",
      "value" : [ "Test" ]
    } ],
    "ccomClass" : "ASSET_TYPE",
    "parent" : null
  } ],
  "instances" : [ {
    "id" : "Demo_enterprise",
    "name" : "Demo_enterprise",
    "description" : "Demo asset entierprise for test description",
    "properties" : [ {
      "id" : "Location",
      "value" : [ "Bay Area" ],
      "type" : "string"
    } ],
    "classification" : "Demo_enterprise_type",
    "ccomClass" : "ENTERPRISE"
  }, {
    "id" : "Demo_site1",
    "name" : "Demo_site1",
    "description" : "Demo CA north site description",
    "properties" : [ {
      "id" : "Demo_CA_address",
      "value" : [ "Bay Area" ],
      "type" : "string"
    } ],
    "classification" : "Demo_site_type",
    "ccomClass" : "SITE"
  }, {
    "id" : "Demo_site2",
    "name" : "Demo_site2",
    "description" : "Demo CA north site description",
    "properties" : [ {
      "id" : "Demo_CA_address",
      "value" : [ "Bay Area" ],
      "type" : "string"
    } ],
    "classification" : "Demo_site_type",
    "ccomClass" : "SITE"
  }, {
    "id" : "Demo_segment1",
    "name" : "Demo_segment1",
    "description" : "Demo ca segment id description",
    "properties" : [ {
      "id" : "Demo_model_number",
      "value" : [ "Demo ca segment id description" ],
      "type" : "string"
    } ],
    "classification" : "Demo_segment_type",
    "ccomClass" : "SEGMENT"
  }, {
    "id" : "Demo_segment2",
    "name" : "Demo_segment2",
    "description" : "Demo ca segment id description",
    "properties" : [ {
      "id" : "Demo_model_number",
      "value" : [ "Demo ca segment id description" ],
      "type" : "string"
    } ],
    "classification" : "Demo_segment_type",
    "ccomClass" : "SEGMENT"
  }, {
    "id" : "Demo_asset1",
    "name" : "Demo_asset1",
    "description" : "",
    "classification" : "Demo_asset_type",
    "ccomClass" : "ASSET",
    "properties" : [ {
      "id" : "alias",
      "type" : "string",
      "value" : [ "Demo CA Asset Alias" ]
    }, {
      "id" : "ch_attr_min",
      "type" : "Character",
      "value" : [ "A" ]
    }, {
      "id" : "ch_attr_max",
      "type" : "Character",
      "value" : [ "Z" ]
    }, {
      "id" : "ch_attr_array",
      "type" : "Character",
      "value" : [ "Z", "a", "v", "N", "q", "i" ]
    }, {
      "id" : "sh_attr_min",
      "type" : "Short",
      "value" : [ -32768 ]
    }, {
      "id" : "sh_attr_max",
      "type" : "Short",
      "value" : [ 32767 ]
    }, {
      "id" : "sh_attr_array",
      "type" : "Short",
      "value" : [ 32767, 300, 600, 90, 158, -32768 ]
    }, {
      "id" : "int_attr_min",
      "type" : "Integer",
      "value" : [ -2147483648 ]
    }, {
      "id" : "int_attr_max",
      "type" : "Integer",
      "value" : [ 2147483647 ]
    }, {
      "id" : "int_attr_array",
      "type" : "Integer",
      "value" : [ 2147483647, 200, -500, 600, 99999, -1452895 ]
    }, {
      "id" : "fl_attr_min",
      "type" : "Float",
      "value" : [ -3.4E38 ]
    }, {
      "id" : "fl_attr_max",
      "type" : "Float",
      "value" : [ 3.4E38 ]
    }, {
      "id" : "fl_attr_array",
      "type" : "Float",
      "value" : [ 3.4E38, 3.2E38, 3.1E38 ]
    }, {
      "id" : "dbl_attr_min",
      "type" : "Double",
      "value" : [ -1.7E308 ]
    }, {
      "id" : "dbl_attr_max",
      "type" : "Double",
      "value" : [ 1.7E308 ]
    }, {
      "id" : "dbl_attr_array",
      "type" : "Double",
      "value" : [ 1.7E308, 1.6E302, 1.4E302, 1.1E38 ]
    }, {
      "id" : "bool_attr_true",
      "type" : "Boolean",
      "value" : [ true ]
    }, {
      "id" : "bool_attr_fal",
      "type" : "Boolean",
      "value" : [ false ]
    }, {
      "id" : "ts_attr",
      "type" : "Timestamp",
      "value" : [ "07/15/2016 04:45:30" ]
    }, {
      "id" : "ts_attr_array",
      "type" : "Timestamp",
      "value" : [ "07/15/2016 04:45:30", "07/16/2016 04:45:30", "08/20/2016 04:45:30", "09/21/2016 04:45:30" ]
    }, {
      "id" : "str_attr_min",
      "type" : "String",
      "value" : [ "H" ]
    }, {
      "id" : "str_attr_max",
      "type" : "String",
      "value" : [ "This is a string" ]
    }, {
      "id" : "str_attr_array",
      "type" : "String",
      "value" : [ "First", "Second", "Third", "Fourt" ]
    } ]
  }, {
    "id" : "Demo_asset2",
    "name" : "Demo_asset2",
    "description" : "",
    "classification" : "Demo_asset_type",
    "ccomClass" : "ASSET",
    "properties" : [ {
      "id" : "alias",
      "type" : "string",
      "value" : [ "Demo CA Asset Alias" ]
    }, {
      "id" : "ch_attr_min",
      "type" : "Character",
      "value" : [ "A" ]
    }, {
      "id" : "ch_attr_max",
      "type" : "Character",
      "value" : [ "Z" ]
    }, {
      "id" : "ch_attr_array",
      "type" : "Character",
      "value" : [ "Z", "a", "v", "N", "q", "i" ]
    }, {
      "id" : "sh_attr_min",
      "type" : "Short",
      "value" : [ -32768 ]
    }, {
      "id" : "sh_attr_max",
      "type" : "Short",
      "value" : [ 32767 ]
    }, {
      "id" : "sh_attr_array",
      "type" : "Short",
      "value" : [ 32767, 300, 600, 90, 158, -32768 ]
    }, {
      "id" : "int_attr_min",
      "type" : "Integer",
      "value" : [ -2147483648 ]
    }, {
      "id" : "int_attr_max",
      "type" : "Integer",
      "value" : [ 2147483647 ]
    }, {
      "id" : "int_attr_array",
      "type" : "Integer",
      "value" : [ 2147483647, 200, -500, 600, 99999, -1452895 ]
    }, {
      "id" : "fl_attr_min",
      "type" : "Float",
      "value" : [ -3.4E38 ]
    }, {
      "id" : "fl_attr_max",
      "type" : "Float",
      "value" : [ 3.4E38 ]
    }, {
      "id" : "fl_attr_array",
      "type" : "Float",
      "value" : [ 3.4E38, 3.2E38, 3.1E38 ]
    }, {
      "id" : "dbl_attr_min",
      "type" : "Double",
      "value" : [ -1.7E308 ]
    }, {
      "id" : "dbl_attr_max",
      "type" : "Double",
      "value" : [ 1.7E308 ]
    }, {
      "id" : "dbl_attr_array",
      "type" : "Double",
      "value" : [ 1.7E308, 1.6E302, 1.4E302, 1.1E38 ]
    }, {
      "id" : "bool_attr_true",
      "type" : "Boolean",
      "value" : [ true ]
    }, {
      "id" : "bool_attr_fal",
      "type" : "Boolean",
      "value" : [ false ]
    }, {
      "id" : "ts_attr",
      "type" : "Timestamp",
      "value" : [ "07/15/2016 04:45:30" ]
    }, {
      "id" : "ts_attr_array",
      "type" : "Timestamp",
      "value" : [ "07/15/2016 04:45:30", "07/16/2016 04:45:30", "08/20/2016 04:45:30", "09/21/2016 04:45:30" ]
    }, {
      "id" : "str_attr_min",
      "type" : "String",
      "value" : [ "H" ]
    }, {
      "id" : "str_attr_max",
      "type" : "String",
      "value" : [ "This is a string " ]
    }, {
      "id" : "str_attr_array",
      "type" : "String",
      "value" : [ "First", "Second", "Third", "Fourt" ]
    } ]
  } ],
  "connections" : [ {
    "from" : {
      "id" : "Demo_site1",
      "ccomClass" : "SITE"
    },
    "to" : [ {
      "type" : "parent",
      "id" : "Demo_enterprise",
      "ccomClass" : "ENTERPRISE"
    } ]
  }, {
    "from" : {
      "id" : "Demo_site2",
      "ccomClass" : "SITE"
    },
    "to" : [ {
      "type" : "parent",
      "id" : "Demo_enterprise",
      "ccomClass" : "ENTERPRISE"
    } ]
  }, {
    "from" : {
      "id" : "Demo_segment1",
      "ccomClass" : "SEGMENT"
    },
    "to" : [ {
      "type" : "parent",
      "id" : "Demo_site1",
      "ccomClass" : "SITE"
    } ]
  }, {
    "from" : {
      "id" : "Demo_segment2",
      "ccomClass" : "SEGMENT"
    },
    "to" : [ {
      "type" : "parent",
      "id" : "Demo_site2",
      "ccomClass" : "SITE"
    } ]
  }, {
    "from" : {
      "id" : "Demo_asset1",
      "ccomClass" : "ASSET"
    },
    "to" : [ {
      "type" : "parent",
      "id" : "Demo_segment1",
      "ccomClass" : "SEGMENT"
    } ]
  }, {
    "from" : {
      "id" : "Demo_asset2",
      "ccomClass" : "ASSET"
    },
    "to" : [ {
      "type" : "parent",
      "id" : "Demo_segment2",
      "ccomClass" : "SEGMENT"
    } ]
  } ],
  "tagClassifications" : [ {
    "id" : "Demo_tag_type",
    "name" : "Demo_tag_type",
    "description" : "This is tag Pressure Classification description",
    "unitGroup" : "pressure",
    "properties" : [ {
      "id" : "compressor",
      "value" : [ 190 ],
      "type" : "int"
    } ]
  } ],
  "tagAssociations" : [ {
    "monitoredEntity" : {
      "id" : "Demo_enterprise",
      "ccomClass" : "ENTERPRISE"
    },
    "tags" : [ {
      "name" : "Demo_enterprise_tag",
      "id" : "Demo_enterprise_tag",
      "description" : "Enterprise Tag Descrpition",
      "classification" : "Demo_tag_type",
      "aliases" : [ "Demo Enterprise Tag Alias" ]
    } ]
  }, {
    "monitoredEntity" : {
      "id" : "Demo_site1",
      "ccomClass" : "SITE"
    },
    "tags" : [ {
      "name" : "Demo_site_tag",
      "id" : "Demo_site_tag",
      "description" : "Site Tag Pressure Descrpition",
      "classification" : "Demo_tag_type",
      "aliases" : [ "Demo Site Tag Pressure Alias" ]
    } ]
  }, {
    "monitoredEntity" : {
      "id" : "Demo_segment1",
      "ccomClass" : "SEGMENT"
    },
    "tags" : [ {
      "name" : "Demo_segment_tag",
      "id" : "Demo_segment_tag",
      "description" : "Segment Tag Pressure Descrpition",
      "classification" : "Demo_tag_type",
      "aliases" : [ "Demo Tag Segment Alias 1" ]
    } ]
  }, {
    "monitoredEntity" : {
      "id" : "Demo_asset1",
      "ccomClass" : "ASSET"
    },
    "tags" : [ {
      "name" : "Demo_asset_tag1",
      "id" : "Demo_asset_tag1",
      "description" : "Asset Tag Pressure Descrpition",
      "classification" : "Demo_tag_type",
      "properties" : [ {
        "id" : "ch_attr_min",
        "type" : "Character",
        "value" : [ "A" ]
      }, {
        "id" : "ch_attr_max",
        "type" : "Character",
        "value" : [ "Z" ]
      }, {
        "id" : "ch_attr_array",
        "type" : "Character",
        "value" : [ "Z", "a", "v", "N", "q", "i" ]
      }, {
        "id" : "sh_attr_min",
        "type" : "Short",
        "value" : [ -32768 ]
      }, {
        "id" : "sh_attr_max",
        "type" : "Short",
        "value" : [ 32767 ]
      }, {
        "id" : "sh_attr_array",
        "type" : "Short",
        "value" : [ 32767, 300, 600, 90, 158, -32768 ]
      }, {
        "id" : "int_attr_min",
        "type" : "Integer",
        "value" : [ -2147483648 ]
      }, {
        "id" : "int_attr_max",
        "type" : "Integer",
        "value" : [ 2147483647 ]
      }, {
        "id" : "int_attr_array",
        "type" : "Integer",
        "value" : [ 2147483647, 200, -500, 600, 99999, -1452895 ]
      }, {
        "id" : "fl_attr_min",
        "type" : "Float",
        "value" : [ -3.4E38 ]
      }, {
        "id" : "fl_attr_max",
        "type" : "Float",
        "value" : [ 3.4E38 ]
      }, {
        "id" : "fl_attr_array",
        "type" : "Float",
        "value" : [ 3.4E38, 3.2E38, 3.1E38 ]
      }, {
        "id" : "dbl_attr_min",
        "type" : "Double",
        "value" : [ -1.7E308 ]
      }, {
        "id" : "dbl_attr_max",
        "type" : "Double",
        "value" : [ 1.7E308 ]
      }, {
        "id" : "dbl_attr_array",
        "type" : "Double",
        "value" : [ 1.7E308, 1.6E302, 1.4E302, 1.1E38 ]
      }, {
        "id" : "bool_attr_true",
        "type" : "Boolean",
        "value" : [ true ]
      }, {
        "id" : "bool_attr_fal",
        "type" : "Boolean",
        "value" : [ false ]
      }, {
        "id" : "ts_attr",
        "type" : "Timestamp",
        "value" : [ "07/15/2016 04:45:30" ]
      }, {
        "id" : "ts_attr_array",
        "type" : "Timestamp",
        "value" : [ "07/15/2016 04:45:30", "07/16/2016 04:45:30", "08/20/2016 04:45:30", "09/21/2016 04:45:30" ]
      }, {
        "id" : "str_attr_min",
        "type" : "String",
        "value" : [ "H" ]
      }, {
        "id" : "str_attr_max",
        "type" : "String",
        "value" : [ "This is a string" ]
      }, {
        "id" : "str_attr_array",
        "type" : "String",
        "value" : [ "First", "Second", "Third", "Fourt" ]
      } ],
      "reservedProperties" : {
        "status" : "01",
        "uom" : "psi",
        "dataType" : "Double",
        "resolution" : ""
      },
      "aliases" : [ "Demo Tag Pressure Alias" ]
    }, {
      "name" : "Demo_asset_tag2",
      "id" : "Demo_asset_tag2",
      "description" : "Asset Tag Temperature Descrpition",
      "classification" : "Demo_tag_type",
      "aliases" : [ "Demo Tag Temperature Alias" ],
      "nextRelatedTag" : {
        "id" : "Demo_asset_tag1"
      }
    } ]
  } ],
  "groups" : [ {
    "id" : "Demo_asset_group",
    "name" : "Demo_asset_group",
    "description" : "Demo Asset Group Description",
    "ccomClass" : "GROUP",
    "associatedEntityCcomClass" : "ASSET",
    "properties" : [ {
      "id" : "Demo_Asset_Group_attribute",
      "value" : [ "Demo Asset Group Attribute Description" ],
      "type" : "string"
    } ],
    "associatedEntityIds" : [ "Demo_asset1", "Demo_asset2" ],
    "mappedInstances" : [ {
      "ccomClass" : "ASSET",
      "id" : "Demo_asset1"
    }, {
      "ccomClass" : "SEGMENT",
      "id" : "Demo_segment1"
    }, {
      "ccomClass" : "SITE",
      "id" : "Demo_site1"
    }, {
      "ccomClass" : "ENTERPRISE",
      "id" : "Demo_enterprise"
    } ]
  } ]
}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 293

{
  "description": "Upload S95 assets from zip file: newE2EAsset.zip, size: 1927 bytes",
  "status": "QUEUED",
  "uuid": "2408ba25-77d2-42b2-9a8f-88b01875a86b",
  "startTime": "05-02-2017 13:43:30.899"
}
Response Structure
Path Type Description

description

String

A message that describes the scope of the task. This normally contains the ZIP file name and file size.

status

String

The status of ingestion in the log. It can be one of the following:

QUEUED - The file has been queued to be processed.

IN PROGRESS -The ingestion into the application asset store is currently in progress. Ingested assets will be available in the application after the ingestion completes.

COMPLETED- The ingestion completed successfully.

ERROR - The ingestion did not complete successfully. There has been an error uploading the file. You must correct the errors and re-ingest the file.

uuid

String

The unique ID for the task. This value is needed to track the ingestion progress.

startTime

String

The value represents the timezone at which the ingestion task was logged for the first time.


Asset Ingestion Tracking Endpoints

Tracking the Ingestion Status

After submitting an asset ingestion file, a task is created for each ingestion request. Tasks may have child tasks. You can use the following GET methods to retrieve these tasks for tracking the asset ingestion status. The Adaptor Configuration microservice reconciles multiple submissions of the same file and prevents duplicate instances of the same asset.

Getting All Tasks

Use this GET method to get a list of all tasks currently logged for a specific tenant.

Example CURL request
$ curl 'https://apm-asset-adapter-svc-domain/v1/tasks' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Content-Type: application/json' -H 'Accept: application/json'
Example HTTP request
GET /v1/tasks HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Content-Type: application/json
Accept: application/json
Host: apm-asset-adapter-svc-domain
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 904

[
   {
        "uuid": "38106f3b-e20b-4f67-9610-ad1e97b674ec",
        "description": "US80340_Ingestion_RestoreDefaultConnections.zip",
        "size": "502 bytes",
        "status": "COMPLETED",
        "startTime": "05-27-2020 05:18:49.857",
        "endTime": "05-27-2020 05:18:53.727",
        "totalCount": 3,
        "completedCount": 3
    },
    {
        "uuid": "827c00cc-b2d2-49c4-9a27-69aeeaee5079",
        "description": "ingestion_updateTagInstanceReservedAttribute.zip",
        "size": "582 bytes",
        "status": "COMPLETED",
        "startTime": "05-27-2020 05:18:47.101",
        "endTime": "05-27-2020 05:18:51.514",
        "totalCount": 1,
        "completedCount": 1
    },
    {
        "uuid": "51df7b15-d368-4698-b4ea-c307dc910d9a",
        "description": "US80340_Ingestion_UpdatePreant.zip",
        "size": "419 bytes",
        "status": "COMPLETED",
        "startTime": "05-27-2020 05:18:37.152",
        "endTime": "05-27-2020 05:18:40.974",
        "totalCount": 1,
        "completedCount": 1
    },
    {
        "uuid": "09790e38-7d03-4740-9085-d1a3c672bd50",
        "description": "US6488-classification.zip",
        "size": "751 bytes",
        "status": "COMPLETED",
        "startTime": "05-27-2020 05:18:33.581",
        "endTime": "05-27-2020 05:18:38.787",
        "totalCount": 1,
        "completedCount": 1
    },
    {
        "uuid": "f919cae9-27b5-416f-a299-fe833357375c",
        "description": "US80340_Ingestion_UpdatePreant.zip",
        "size": "392 bytes",
        "status": "COMPLETED",
        "startTime": "05-27-2020 05:18:23.674",
        "endTime": "05-27-2020 05:18:28.171",
        "totalCount": 1,
        "completedCount": 1
    }
]
Response structure
Path Type Description

[]

Object

A list of Task

[].description

String

A message that describes the scope of the task. This normally contains the ZIP file name and file size.

[].status

String

The status of ingestion in the log. It can be one of the following:

QUEUED - The file has been queued to be processed.

IN PROGRESS -The ingestion into the application asset store is currently in progress. Ingested assets will be available in the application after the ingestion completes.

COMPLETED- The ingestion completed successfully.

ERROR - The ingestion did not complete successfully. There has been an error uploading the file. You must correct the errors and re-ingest the file.

[].uuid

String

The unique ID for the task. This value is needed to track the ingestion progress.

[].startTime

String

The value represents the timezone at which the ingestion task was logged for the first time.

[].endTime

String

The value represents the timezone at which the ingestion task was last updated.


Getting a Specific Task

Use one of the two GET methods to check the asset ingestion status for a specific task. You must pass the task uuid using the path parameter. Both methods return See the usage example requests below.

Example CURL Request for Ingestion Logs
$ curl 'https://apm-asset-adapter-svc-domain/v1/ingestionlogs/004066e0-d480-4908-b82d-15af1e4122ab' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Content-Type: application/json' -H 'Accept: application/json'
Example HTTP Request for Ingestion Logs
GET /v1/ingestionlogs/004066e0-d480-4908-b82d-15af1e4122ab HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Content-Type: application/json
Accept: application/json
Host: apm-asset-adapter-svc-domain
Path Parameters for Ingestion Logs
Table 1. /v1/ingestionlogs/{uuid}
Parameter Description

uuid

The unique identifier for the Ingestion Log

Example Response for Ingestion Logs
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1225

{
    "uuid": "30507eb4-b568-44d5-9b17-96ccb28acb89",
    "name": "Location_Grid_Groups.zip",
    "size": "5155 bytes",
    "status": "COMPLETED",
    "createdOn": 1577839018799,
    "updatedOn": 1577839022652,
    "totalCount": 60,
    "completedCount": 60,
    "children": [
        {
            "uuid": "d3b30889-9bfa-3c44-b74b-ce69a28f6192",
            "name": "/jenkins/workspace/04-AWS-RC/01-Asset/Backend Regression/SmokeV3/src/main/resources/files/Asset/F10589_IngestionFiles/Location_Grid_Groups.json",
            "size": "5155 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839021603,
            "updatedOn": 1577839022627,
            "totalCount": 0,
            "completedCount": 0,
            "taskType": "/jenkins/workspace/04-AWS-RC/01-Asset/Backend Regression/SmokeV3/src/main/resources/files/Asset/F10589_IngestionFiles/Location_Grid_Groups.json"
        }
    ]
}
Response Structure for Ingestion Logs
Path Type Description

uuid

String

The unique identifier for the ingestion log

name

String

The name of the ingestion log

size

String

The size of the ingestion log

status

String

The state of the ingestion log. Can be 'QUEUED', 'IN PROGRESS', 'COMPLETED', or 'ERROR'

createdOn

Number

A timestamp equal to the time the ingestion log was created

updatedOn

Number

A timestamp equal to the most recent time the ingestion log status was updated

children

Array

A list of child ingestion logs

messages

Array

List of ingestion messages

totalCount

Integer

The total number of objects being ingested for this task.

completedCount

Integer

The number of objects successfully ingested for this task.

taskType

String

The type of object being ingested.

Example CURL Request for Tasks
$ curl 'https://apm-asset-adapter-svc-domain/v1/tasks/004066e0-d480-4908-b82d-15af1e4122ab' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Content-Type: application/json' -H 'Accept: application/json'
Example HTTP Request for Tasks
GET /v1/tasks/004066e0-d480-4908-b82d-15af1e4122ab HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Content-Type: application/json
Accept: application/json
Host: apm-asset-adapter-svc-domain
Path Parameters for Tasks
Table 2. /v1/tasks/{uuid}
Parameter Description

uuid

The unique identifier for the Task

Example Response for Tasks
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 296

{
    "uuid": "71d754f9-88b4-4d1b-b613-ae6158c2c87f",
    "description": "Upload S95 assets from zip file: US6491_createTagInstanceWithAttributesHavingAdditionalDataTypes.zip, size: 990 bytes.",
    "status": "COMPLETED",
    "startTime": "05-27-2020 05:22:32.927",
    "endTime": "05-27-2020 05:22:36.108",
    "children": [
        {
            "uuid": "5446202d-34f9-4d35-bb42-bc74cf55a628",
            "description": "Process S95 assets file: /tmp/json/US6491_createTagInstanceWithAttributesHavingAdditionalDataTypes15905569524882396543258117911134.json",
            "status": "COMPLETED",
            "startTime": "05-27-2020 05:22:34.860",
            "endTime": "05-27-2020 05:22:36.108",
            "totalCount": 3,
            "completedCount": 3,
            "taskType": "/tmp/json/US6491_createTagInstanceWithAttributesHavingAdditionalDataTypes15905569524882396543258117911134.json"
        }
    ],
    "totalCount": 3,
    "completedCount": 3,
    "taskResponse": {
        "responseUri": {
            "url1": "https://bucket-b981e35b-3556-4906-9895-d2afea5d76ba.s3-us-west-2.amazonaws.com/71d754f9-88b4-4d1b-b613-ae6158c2c87f_US6491_createTagInstanceWithAttributesHavingAdditionalDataTypes.zip"
        }
    }
}
Response Structure for Tasks
Path Type Description

description

String

A message that describes the scope of the task. This normally contains the ZIP file name and file size.

status

String

The status of ingestion in the log. It can be one of the following:

QUEUED - The file has been queued to be processed.

IN PROGRESS -The ingestion into the application asset store is currently in progress. Ingested assets will be available in the application after the ingestion completes.

COMPLETED- The ingestion completed successfully.

ERROR - The ingestion did not complete successfully. There has been an error uploading the file. You must correct the errors and re-ingest the file.

uuid

String

The unique ID for the task. This value is needed to track the ingestion progress.

isActive

boolean

The value is true if the task is currently active.

startTime

String

The value represents the timezone at which the ingestion task was logged for the first time.

endTime

String

The value represents the timezone at which the ingestion task was last updated.

children

Array

A list of child ingestion logs

totalCount

Integer

The total number of objects being ingested for this task.

completedCount

Integer

The number of objects successfully ingested for this task.

taskType

String

The type of object being ingested.


Get Tasks for the User Interface

Use this GET method to get all ingestion tasks for showing in the user interface. Provide the query parameters to filter the ingestion logs. If you do not provide any query parameter, all ingestion tasks are returned.

Example CURL request
$ curl 'https://apm-asset-adapter-svc-domain/v1/ingestionlogs?currentPage=0&sortOrder=ASC&searchField=status&searchValue=COMPLETED&sortBy=createdOn&pageValue=10' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Content-Type: application/json' -H 'Accept: application/json'
Example HTTP request
GET /v1/ingestionlogs?currentPage=0&sortOrder=ASC&searchField=status&searchValue=COMPLETED&sortBy=createdOn&pageValue=10 HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Content-Type: application/json
Accept: application/json
Host: apm-asset-adapter-svc-domain
Request Params
Parameter Description

currentPage

The page number of the results to retrieve. If unspecified, the first page is retrieved by default.

sortOrder

The sort order for the sortBy field. Possible values: ASC, DESC. The default sort order is ASC.

searchField

The field to search. Allowed values: uuid, createdOn, updatedOn and status.

searchValue

The search text as string (for example, .zip). The search text is case-insensitive and returns only those rows that contain the search text.

sortBy

The field to sort the results. Sorts results by the specified sortBy. Allowed values: createdOn, updatedOn and status. Default is 'createdOn'.

pageValue

The number of results to show per page. Default is 10.

Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1308

{
    "currentPage": 1,
    "totalItems": 4070,
    "itemsOnPage": 10,
    "totalPages": 408,
    "dtoList": [
        {
            "uuid": "30507eb4-b568-44d5-9b17-96ccb28acb89",
            "name": "Location_Grid_Groups.zip",
            "size": "5155 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839018799,
            "updatedOn": 1577839022652,
            "totalCount": 60,
            "completedCount": 60
        },
        {
            "uuid": "daa4d887-d701-44a8-aaac-4505a04f2167",
            "name": "TemplateE2E_Classifications.zip",
            "size": "1538 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839055863,
            "updatedOn": 1577839058478,
            "totalCount": 37,
            "completedCount": 37
        },
        {
            "uuid": "1c105f7e-5955-4c1e-8ae5-76f9f84edaeb",
            "name": "TemplateE2E_02000.zip",
            "size": "1191 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839076009,
            "updatedOn": 1577839092148,
            "totalCount": 1,
            "completedCount": 1
        },
        {
            "uuid": "781f8e86-509d-4239-8b3f-08303e93fba5",
            "name": "TemplateE2E.zip",
            "size": "1328 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839095675,
            "updatedOn": 1577839199150,
            "totalCount": 1,
            "completedCount": 1
        },
        {
            "uuid": "57bf6243-a5e8-41ff-bb0f-328837bcd100",
            "name": "Location_Grid_Groups.zip",
            "size": "5141 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839103206,
            "updatedOn": 1577839105597,
            "totalCount": 60,
            "completedCount": 60
        },
        {
            "uuid": "51b62f3c-3d74-4b9a-a1a8-83967ee27809",
            "name": "TemplateE2E_Classifications.zip",
            "size": "1542 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839138422,
            "updatedOn": 1577839140347,
            "totalCount": 37,
            "completedCount": 37
        },
        {
            "uuid": "7035f87b-9c7c-478b-8a8e-61e6cbdcb1b4",
            "name": "TemplateE2E_02000.zip",
            "size": "1175 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839157996,
            "updatedOn": 1577839191803,
            "totalCount": 1,
            "completedCount": 1
        },
        {
            "uuid": "6c98d9e2-e75e-4522-aefe-f32a3291e38f",
            "name": "TemplateE2E.zip",
            "size": "1332 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839209340,
            "updatedOn": 1577839262013,
            "totalCount": 1,
            "completedCount": 1
        },
        {
            "uuid": "d222b78e-cff2-4195-931d-8b682c3e67dc",
            "name": "TemplateE2E_03000.zip",
            "size": "938 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839211712,
            "updatedOn": 1577839229221,
            "totalCount": 1,
            "completedCount": 1
        },
        {
            "uuid": "01f98103-7ecb-4265-b188-dc04ca58a850",
            "name": "TemplateE2E_03001.zip",
            "size": "1026 bytes",
            "status": "COMPLETED",
            "createdOn": 1577839231218,
            "updatedOn": 1577839260266,
            "totalCount": 1,
            "completedCount": 1
        }
    ]
}
Response structure
Path Type Description

currentPage

Integer

Index of current page

totalItems

Integer

Total number of tasks.

itemsOnPage

Integer

No. of items per page.

totalPages

Integer

Total number of pages.

dtoList

Array

A list of tasks.

[].tenantUuid

String

The unique ID for the tenant.

[].uuid

String

The unique ID for the task. This value is needed to track the ingestion progress.

[].name

String

The name of the task.

[].size

String

The size of the uploaded ZIP file in bytes.

[].status

String

The status of ingestion in the log. It can be one of the following:

QUEUED - The file has been queued to be processed.

IN PROGRESS -The ingestion into the application asset store is currently in progress. Ingested assets will be available in the application after the ingestion completes.

COMPLETED- The ingestion completed successfully.

ERROR - The ingestion did not complete successfully. There has been an error uploading the file. You must correct the errors and re-ingest the file.

[].createdOn

Number

The UNIX epoch timestamp at which the ingestion task was logged for the first time.

[].updatedOn

Number

The UNIX epoch timestamp of when the ingestion task status was last updated.

[].children

Array

A list of any child tasks. This is true if multiple JSON files are present within a single ZIP file.

totalCount

Integer

The total number of objects being ingested for this task.

completedCount

Integer

The number of objects successfully ingested for this task.

taskType

String

The type of object being ingested.


Asset Resource Endpoints

Components

These endpoints (such as CRUD, Hierarchy, Criteria and Source Key that return an object or an array of objects) accept an optional query parameter called components.

The parameter values allowed are: BASIC, PARENT, TYPE, ATTRIBUTES, TAGS, FULL, and DETAILED. Pass one or more of these options to specify the amount of information to return for each object.

Component option Description

BASIC

Returns only basic fields such as URI, sourceKey, name, description, label, reservedAttributes (where applicable), parent, type (type URI, if applicable), location (if applicable), and category (applicable only to groups).

PARENT

Returns the immediate parent object (with PARENT components) of the requested resource and its basic fields. It also returns grandparents up to the root node.

TYPE

Returns the type object of the requested resource and its basic fields. This component is not applicable to types/classifications.

ATTRIBUTES

Returns the attributes of the requested resource and its basic fields.

TAGS

Return the basic fields and the tags(default maximum of 250) associated with the object. This component is not applicable to types/classifications.

FULL

Returns parents, object type, attributes, tags and basic fields of the requested resource. It is the same as specifying 'PARENT,TYPE,ATTRIBUTES,TAGS'.

DETAILED

Returns FULL, and also returns FULL components of parents.

Usage example, /v1/assets?components=BASIC. If not specified, the default is BASIC.
When querying for instances(Enterprise, Site, Segment & Asset) with components as TAGS, the service will return maximum of 250(default limit) tags. If intention is to get more tags, then example usage is /v1/assets/{uuid}/tags.
sortBy param only supported for tag instances of single asset.

Advanced Search Supported Query Params

Below are the supported query params for advanced search on various endpoints

Resource Endpoint Supported Query Params Example

Instances - Enterprises, Sites & Segments

uri
name
sourcekey
description
attributes
reservedattributes
type
parent

* v1/assets/query?q=uri=/assets/<uuid>
* v1/sites/query?q=attributes.Sample_CA_address.value=Bay
* v1/segments/query?q=name=Sample

Assets

uri
name
sourcekey
description
attributes
reservedattributes
type
parent

* v1/assets/query?q=reservedAttributes.state.key=06
* v1/assets/query?q=parent=/segments/<uuid>

Asset Types & Tag Types

uri
name
sourcekey
description
attributes
reservedattributes
parent

* v1/segments/query?q=type=/segmentTypes/<uuid>

Tags

uri
name
sourcekey
description
attributes
reservedattributes
type
monitoredentityuri
monitoredentityname
monitoredentitysourcekey

* v1/tags/query?q=monitoredentitysourcekey=Sample_Asset& sortBy=reservedAttributes.uom.desc

Asset Groups

uri
name
sourcekey
description
attributes
reservedattributes
category

* v1/assetgroups/query?q=category=Tag

List of Special characters

Backslash

\

Single Quote

'

Asterisk

*

Comma

,

Colon

:

Pipe

|

Equals

=

To use above special characters in the query, one should escape using backslash ( \ ). Below table shows usage of Query APIs with Special Characters Example.

Query APIs with Special Characters Example

EndPoints Special Chars to escape Example

/assets/query
/segments/query
/sites/query
/enterprises/query

/assets/<uuid>/tags/download
/segments/<uuid>/tags/download
/sites/<uuid>/tags/download
/enterprises/<uuid>/tags/download

/tags/query

Backslash ( \ )
Single Quote ( ' )
Asterisk ( * )

Escape below chars only if value are unquoted

Colon ( : )
Pipe ( | )
Equals ( =)

/assets/query?q=name='E2EAVD-ASSET-\\-\*-\'-1'
+ Above example will show how to query for an asset has Single Quote, Asterisk, Backslash.
Result set will conatain assets has name E2EAVD-ASSET-\-*-'-1

/assets/query?q=name=E2EAVD-ASSET-\:-|-\=-2'
+ Above example will show how to query for an asset has Colon, Pipe, Equals unquoted Result set will conatain assets has name E2EAVD-ASSET-:-|-=-2

/tags?sourceKeys=<sourceKey1>
/tags?sourceKeys=<sourceKey1>,<sourceKey2>

Backslash ( \ )
Single Quote ( ' )
Asterisk ( * )

Escape below chars only if value are unquoted

Comma ( , )

/tags/sourceKeys='pwr_turbine\\00\'1,25\*6','pwr_turbine\\00\'1,25\*7'
+ Above example will show how to query for an tag contains Single Quote, Asterisk, Comma, Backslash in sourceKey.
Result set will conatain tags has sourceKey pwr_turbine\00'1,25*6 or pwr_turbine\00'1,25*7


/tags/sourceKeys=pwr_turbine\\00\'1\,25\*6,pwr_turbine\\00\'1\,25\*7

Above example will show how to query for an tag contains Single Quote, Asterisk, Comma, Backslash in sourceKey.
Result set will conatain tags has sourceKey pwr_turbine\00'1,25*6 or pwr_turbine\00'1,25*7
Note that Comma is escaped using backslash.

/assets?sourceKey=<value>
/assets?name=<value>
/assets/search?sourceKey=<value>
/assets/search?name=<value>
/assets/search?sourceKey=<sourceKey>&name=<name>
/assets/bySourceKey?sourceKey=<value>
/tags/bySourceKey?sourceKey=<sourceKey1>
/assets/<uuid>/tags?sourceKey=<value>
/assets/<uuid>/tags?name=<value>

Backslash ( \ )
Single Quote ( ' )
Asterisk ( * )

/assets/sourceKey='pwr_turbine\\00\'1-25\*6'
+ Above example will show how to query for an asset contains Single Quote, Asterisk, Backslash in sourceKey.
Result set will conatain tags has sourceKey pwr_turbine\00'1,25*6

Classification Types

An asset is a digital abstraction of something in the physical world. It can be an enterprise, organization, site, machine train, or equipment.

A classification is a reusable definition of a specific entity in your business-object hierarchy. You can also represent multiple entities that are essentially the same and define them as a single classification. For example, you can create a classification machine to identify machinery with common attributes and properties. You can create sub-classifications such as turbines, compressors, and shafts from the parent machine class. Sub-classifications inherit properties from the parents and can have be assigned their own custom properties.

Classification types are more like a blueprint or definition. They do not represent a physical entity.

The Asset microservice provides the following endpoints to create, update and fetch resources for the supported classification types.

EnterpriseTypes


Creating Enterprise Types

Use this POST method to create enterprise types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterpriseTypes' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Enterprise Type",
  "description" : "Sample Enterprise Type",
  "attributes" : { }
} ]'
Example HTTP Request
POST /v1/enterpriseTypes HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 144

[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Enterprise Type",
  "description" : "Sample Enterprise Type",
  "attributes" : { }
} ]
Request Structure
Path Type Description

[]

Array

A list of EnterpriseTypes

[].uri

String

The uniform resource identifier (URI) of EnterpriseType

[].objectId

String

The object id of the EnterpriseType as represented in the source system.

[].tenantId

String

The tenant id of the EnterpriseType as represented in the source system.

[].rootTypeName

String

The CCOM type of the EnterpriseType as represented in the source system.

[].sourceKey

String

The unique identifier of the EnterpriseType as represented in the source system. Must be unique per EnterpriseType defined.

[].name

String

The name of the EnterpriseType.

[].label

String

Hierarchical name of the EnterpriseType.

[].description

String

The general description for the EnterpriseType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the EnterpriseTypes parent

[].location

Object

Please refer Location Json Structure

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 358

[ {
  "objectId" : "4ae36fd8-25d2-3895-924e-b2aa5d408cdd",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterpriseTypes/4ae36fd8-25d2-3895-924e-b2aa5d408cdd",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Enterprise Type",
  "description" : "Sample Enterprise Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of EnterpriseTypes

[].uri

String

The uniform resource identifier (URI) of EnterpriseType

[].objectId

String

The object id of the EnterpriseType as represented in the source system.

[].tenantId

String

The tenant id of the EnterpriseType as represented in the source system.

[].rootTypeName

String

The CCOM type of the EnterpriseType as represented in the source system.

[].sourceKey

String

The unique identifier of the EnterpriseType as represented in the source system. Must be unique per EnterpriseType defined.

[].name

String

The name of the EnterpriseType.

[].label

String

Hierarchical name of the EnterpriseType.

[].description

String

The general description for the EnterpriseType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the EnterpriseTypes parent

[].location

Object

Please refer Location Json Structure


Retrieving All Enterprise Types

Use this GET method to retrieve all enterprise types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterpriseTypes?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterpriseTypes?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 323

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Enterprise Type",
  "description" : "Sample Enterprise Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of EnterpriseTypes

[].uri

String

The uniform resource identifier (URI) of EnterpriseType

[].objectId

String

The object id of the EnterpriseType as represented in the source system.

[].tenantId

String

The tenant id of the EnterpriseType as represented in the source system.

[].rootTypeName

String

The CCOM type of the EnterpriseType as represented in the source system.

[].sourceKey

String

The unique identifier of the EnterpriseType as represented in the source system. Must be unique per EnterpriseType defined.

[].name

String

The name of the EnterpriseType.

[].label

String

Hierarchical name of the EnterpriseType.

[].description

String

The general description for the EnterpriseType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the EnterpriseTypes parent

[].location

Object

Please refer Location Json Structure

Example 1. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.
Example 2. Json Structure for Location

Possible properties for Location attribute

"location": {
      "geoPoints": [
            {
                "order" : 1,
                "name" : "point1",
                "latitude" : -21.29,
                "longitude" : 13.112,
                "altitude" : 112.356
            } ],
            "timezone" : "Pacific/Samoa"
            }

Retrieving Enterprise Types by Criteria

Use this GET method to retrieve enterprise types matching a specific criterion or criteria passed as the request query parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterpriseTypes?sourceKey=DEMO-ASSET-ENTERPRISE&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterpriseTypes?sourceKey=DEMO-ASSET-ENTERPRISE&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Parameters
Parameter Description

sourceKey

The source key of the EnterpriseType to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to EnterpriseTypes to be returned.

attributes

The attributes filter for the EnterpriseTypes. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to EnterpriseTypes to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the EnterpriseTypes returned.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 371

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-ENTERPRISE",
  "name" : "DEMO ASSET ENTERPRISE",
  "description" : "This is the type of enterprise",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of EnterpriseTypes

[].uri

String

The uniform resource identifier (URI) of EnterpriseType

[].objectId

String

The object id of the EnterpriseType as represented in the source system.

[].tenantId

String

The tenant id of the EnterpriseType as represented in the source system.

[].rootTypeName

String

The CCOM type of the EnterpriseType as represented in the source system.

[].sourceKey

String

The unique identifier of the EnterpriseType as represented in the source system. Must be unique per EnterpriseType defined.

[].name

String

The name of the EnterpriseType.

[].label

String

Hierarchical name of the EnterpriseType.

[].description

String

The general description for the EnterpriseType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the EnterpriseTypes parent

[].location

Object

Please refer Location Json Structure


Getting the Enterprise Type by URI

Use this GET method to retrieve the enterprise type by its resource URI. You must pass the URI using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 3. /v1/enterpriseTypes/{uuid}
Parameter Description

uuid

The unique identifier for the EnterpriseType. Must be unique per EnterpriseType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 319

{
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Enterprise Type",
  "description" : "Sample Enterprise Type",
  "attributes" : { }
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of EnterpriseType

objectId

String

The object id of the EnterpriseType as represented in the source system.

tenantId

String

The tenant id of the EnterpriseType as represented in the source system.

rootTypeName

String

The CCOM type of the EnterpriseType as represented in the source system.

sourceKey

String

The unique identifier of the EnterpriseType as represented in the source system. Must be unique per EnterpriseType defined.

name

String

The name of the EnterpriseType.

label

String

Hierarchical name of the EnterpriseType.

description

String

The general description for the EnterpriseType

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the EnterpriseTypes parent

location

Object

Please refer Location Json Structure


Retrieving All Inherited Enterprise Types

Use this GET method to retrieve all child classifications derived from a specific enterprise type. You must pass the UUID of the requested resource using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterpriseTypes/24925eea-a9af-4a90-87f0-2bbc7570865e/children?name=Sample*&components=BASIC&deepSearch=true' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterpriseTypes/24925eea-a9af-4a90-87f0-2bbc7570865e/children?name=Sample*&components=BASIC&deepSearch=true HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 4. /v1/enterpriseTypes/{uuid}/children
Parameter Description

uuid

The unique identifier for the EnterpriseType. Must be unique per EnterpriseType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

name

The name filter to apply to EnterpriseTypes to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 323

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Enterprise Type",
  "description" : "Sample Enterprise Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of EnterpriseTypes

[].uri

String

The uniform resource identifier (URI) of EnterpriseType

[].objectId

String

The object id of the EnterpriseType as represented in the source system.

[].tenantId

String

The tenant id of the EnterpriseType as represented in the source system.

[].rootTypeName

String

The CCOM type of the EnterpriseType as represented in the source system.

[].sourceKey

String

The unique identifier of the EnterpriseType as represented in the source system. Must be unique per EnterpriseType defined.

[].name

String

The name of the EnterpriseType.

[].label

String

Hierarchical name of the EnterpriseType.

[].description

String

The general description for the EnterpriseType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the EnterpriseTypes parent

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of EnterpriseType


Retrieving the Parent of an Enterprise Type

Use this GET method to retrieve the parent URI of a specific enterprise type. You must pass the UUID of the requested resource using the path parameter.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/enterpriseTypes/e6e83f70-5171-464f-9e5e-c9a6970a7381/parent?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/enterpriseTypes/e6e83f70-5171-464f-9e5e-c9a6970a7381/parent?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 5. /v1/enterpriseTypes/{uuid}/parent
Parameter Description

uuid

The unique identifier for the EnterpriseType. Must be unique per EnterpriseType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 555

{
  "objectId" : "fc9161d7-e273-369e-a6a0-5be1156e9e79",
  "tenantId" : "8d663b3d-faf9-43d8-9aa1-62ac70f7a3eb",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterpriseTypes/fc9161d7-e273-369e-a6a0-5be1156e9e79",
  "sourceKey" : "IngestionlogRetryClassificationReverse-asset-enterprise-type-parent1527594048695",
  "name" : "IngestionlogRetryClassificationReverse asset enterprise-parent1527594048695",
  "description" : "This is the type of parent enterprise classification type",
  "parent" : "/enterpriseTypes/2e50b9b9-2368-31a3-890f-c307caf37532"
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of EnterpriseType

objectId

String

The object id of the EnterpriseType as represented in the source system.

tenantId

String

The tenant id of the EnterpriseType as represented in the source system.

rootTypeName

String

The CCOM type of the EnterpriseType as represented in the source system.

sourceKey

String

The unique identifier of the EnterpriseType as represented in the source system. Must be unique per EnterpriseType defined.

name

String

The name of the EnterpriseType.

label

String

Hierarchical name of the EnterpriseType.

description

String

The general description for the EnterpriseType

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the EnterpriseTypes parent

location

Object

Please refer Location Json Structure


Updating an Enterprise Type

Use this PATCH method to replace or update current information for a specific enterprise type. You must pass the UUID of the enterprise type to update as the path parameter. Depending on the operation specified in the request body, the property values are added or replaced.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
} ]'
Example HTTP Request
PATCH /v1/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 200

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
} ]
Request Structure
Table 6. /v1/enterpriseTypes/{uuid}
Parameter Description

uuid

The unique identifier for the EnterpriseType. Must be unique per EnterpriseType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 204 No Content

Deleting Enterprise Type

Use the DELETE method to delete a specific enterprise type by UUID.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/enterpriseTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/enterpriseTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 7. /v1/enterpriseTypes/{uuid}
Parameter Description

uuid

The unique identifier for the EnterpriseType. Must be unique per EnterpriseType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Response structure
HTTP/1.1 200 OK

SiteTypes


Creating Site Types

Use this POST method to create site types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/siteTypes' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Site Type",
  "description" : "Sample Site Type",
  "attributes" : { }
} ]'
Example HTTP Request
POST /v1/siteTypes HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 132

[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Site Type",
  "description" : "Sample Site Type",
  "attributes" : { }
} ]
Request Structure
Path Type Description

[]

Array

A list of SiteTypes

[].uri

String

The uniform resource identifier (URI) of SiteType

[].objectId

String

The object id of the SiteType as represented in the source system.

[].tenantId

String

The tenant id of the SiteType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SiteType as represented in the source system.

[].sourceKey

String

The unique identifier of the SiteType as represented in the source system. Must be unique per SiteType defined.

[].name

String

The name of the SiteType.

[].label

String

Hierarchical name of the SiteType.

[].description

String

The general description for the SiteType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SiteTypes parent

[].location

Object

Please refer Location Json Structure

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 346

[ {
  "objectId" : "d6c72959-1812-3124-8b26-6cd18729fdda",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/siteTypes/d6c72959-1812-3124-8b26-6cd18729fdda",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Enterprise Type",
  "description" : "Sample Enterprise Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of SiteTypes

[].uri

String

The uniform resource identifier (URI) of SiteType

[].objectId

String

The object id of the SiteType as represented in the source system.

[].tenantId

String

The tenant id of the SiteType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SiteType as represented in the source system.

[].sourceKey

String

The unique identifier of the SiteType as represented in the source system. Must be unique per SiteType defined.

[].name

String

The name of the SiteType.

[].label

String

Hierarchical name of the SiteType.

[].description

String

The general description for the SiteType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SiteTypes parent

[].location

Object

Please refer Location Json Structure


Retireving All Site Types

Use this GET method to retrieve all site types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/siteTypes?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/siteTypes?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 360

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/siteTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "UUIDTest-ASSET-SITE-TYPEtest1500361377089",
  "name" : "Sample Site Type",
  "description" : "Sample Site Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of SiteTypes

[].uri

String

The uniform resource identifier (URI) of SiteType

[].objectId

String

The object id of the SiteType as represented in the source system.

[].tenantId

String

The tenant id of the SiteType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SiteType as represented in the source system.

[].sourceKey

String

The unique identifier of the SiteType as represented in the source system. Must be unique per SiteType defined.

[].name

String

The name of the SiteType.

[].label

String

Hierarchical name of the SiteType.

[].description

String

The general description for the SiteType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SiteTypes parent

[].location

Object

Please refer Location Json Structure

Example 3. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Retrieving Site Types by Criteria

Use this GET method to retrieve site types matching a specific criterion or criteria passed as the request query parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/siteTypes?sourceKey=DEMO-ASSET-SITE&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/siteTypes?sourceKey=DEMO-ASSET-SITE&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Parameters
Parameter Description

sourceKey

The source key of the SiteType to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to SiteTypes to be returned.

attributes

The attributes filter for the SiteTypes. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to SiteTypes to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the SiteTypes returned.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 360

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/siteTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "UUIDTest-ASSET-SITE-TYPEtest1500361377089",
  "name" : "Sample Site Type",
  "description" : "Sample Site Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of SiteTypes

[].uri

String

The uniform resource identifier (URI) of SiteType

[].objectId

String

The object id of the SiteType as represented in the source system.

[].tenantId

String

The tenant id of the SiteType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SiteType as represented in the source system.

[].sourceKey

String

The unique identifier of the SiteType as represented in the source system. Must be unique per SiteType defined.

[].name

String

The name of the SiteType.

[].label

String

Hierarchical name of the SiteType.

[].description

String

The general description for the SiteType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SiteTypes parent

[].location

Object

Please refer Location Json Structure


Retrieving Site Type by URI

Use this GET method to retrieve a site type by its resource URI. You must pass the URI using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/siteTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/siteTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 8. /v1/siteTypes/{uuid}
Parameter Description

uuid

The unique identifier for the SiteType. Must be unique per SiteType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 356

{
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/siteTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "UUIDTest-ASSET-SITE-TYPEtest1500361377089",
  "name" : "Sample Site Type",
  "description" : "Sample Site Type",
  "attributes" : { }
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of SiteType

objectId

String

The object id of the SiteType as represented in the source system.

tenantId

String

The tenant id of the SiteType as represented in the source system.

rootTypeName

String

The CCOM type of the SiteType as represented in the source system.

sourceKey

String

The unique identifier of the SiteType as represented in the source system. Must be unique per SiteType defined.

name

String

The name of the SiteType.

label

String

Hierarchical name of the SiteType.

description

String

The general description for the SiteType

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the SiteTypes parent

location

Object

Please refer Location Json Structure


Retrieving All Inherited Site Types

Use this GET method to retrieve all child classifications derived from a specific site type. You must pass the UUID of the requested resource using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/siteTypes/ed47322d-8cf5-404d-8be1-8077fddda277/children?name=Sample*&components=BASIC&deepSearch=true' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/siteTypes/ed47322d-8cf5-404d-8be1-8077fddda277/children?name=Sample*&components=BASIC&deepSearch=true HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 9. /v1/siteTypes/{uuid}/children
Parameter Description

uuid

The unique identifier for the SiteType. Must be unique per SiteType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Parameters
Parameter Description

name

The name filter to apply to SiteTypes to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 299

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/siteTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Site Type",
  "description" : "Sample Site Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of SiteTypes

[].uri

String

The uniform resource identifier (URI) of SiteType

[].objectId

String

The object id of the SiteType as represented in the source system.

[].tenantId

String

The tenant id of the SiteType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SiteType as represented in the source system.

[].sourceKey

String

The unique identifier of the SiteType as represented in the source system. Must be unique per SiteType defined.

[].name

String

The name of the SiteType.

[].label

String

Hierarchical name of the SiteType.

[].description

String

The general description for the SiteType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SiteTypes parent

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of SiteType


Retrieving the Parent of a Site Type

Use this GET method to retrieve the parent URI of a specific site type. You must pass the UUID of the requested resource using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/siteTypes/11a04100-41fd-4a9f-9e60-a3ff728fff03/parent?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/siteTypes/11a04100-41fd-4a9f-9e60-a3ff728fff03/parent?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 10. /v1/siteTypes/{uuid}/parent
Parameter Description

uuid

The unique identifier for the SiteType. Must be unique per SiteType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 359

{
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/siteTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Site Type",
  "description" : "Sample Site Type",
  "attributes" : { },
  "parent" : "/siteTypes/ed47322d-8cf5-404d-8be1-8077fddda277"
}

Updating Site Types

Use this PATCH request to update the site type.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/siteTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
} ]'
Example HTTP Request
PATCH /v1/siteTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 200

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
} ]
Request Structure
Path Type Description

[]

Array

A list of patch operations

[].op

String

The operation name for the patch operation

[].path

String

The '/' separated path for the property being updated.

[].from

String

The old value of the property being updated.

[].value

Varies

The new value of the property to update.

Example Response
HTTP/1.1 204 No Content

Deleting Site Type

Use the DELETE method to delete a specific site type by UUID.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/siteTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/siteTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 11. /v1/siteTypes/{uuid}
Parameter Description

uuid

The unique identifier for the SiteType. Must be unique per SiteType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Response structure
HTTP/1.1 200 OK

SegmentTypes


Creating Segment Types

Use this POST method to create segment types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segmentTypes' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment Type",
  "description" : "Sample Segment Type",
  "attributes" : { }
} ]'
Example HTTP Request
POST /v1/segmentTypes HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 138

[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment Type",
  "description" : "Sample Segment Type",
  "attributes" : { }
} ]
Request Structure
Path Type Description

[]

Array

A list of SegmentTypes

[].uri

String

The uniform resource identifier (URI) of SegmentType

[].objectId

String

The object id of the SegmentType as represented in the source system.

[].tenantId

String

The tenant id of the SegmentType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SegmentType as represented in the source system.

[].sourceKey

String

The unique identifier of the SegmentType as represented in the source system. Must be unique per SegmentType defined.

[].name

String

The name of the SegmentType.

[].label

String

Hierarchical name of the SegmentType.

[].description

String

The general description for the SegmentType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SegmentTypes parent

[].location

Object

Please refer Location Json Structure

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 346

[ {
  "objectId" : "21561838-2b23-3201-bdef-30525ff15ced",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segmentTypes/21561838-2b23-3201-bdef-30525ff15ced",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment Type",
  "description" : "Sample Segment Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of SegmentTypes

[].uri

String

The uniform resource identifier (URI) of SegmentType

[].objectId

String

The object id of the SegmentType as represented in the source system.

[].tenantId

String

The tenant id of the SegmentType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SegmentType as represented in the source system.

[].sourceKey

String

The unique identifier of the SegmentType as represented in the source system. Must be unique per SegmentType defined.

[].name

String

The name of the SegmentType.

[].label

String

Hierarchical name of the SegmentType.

[].description

String

The general description for the SegmentType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SegmentTypes parent

[].location

Object

Please refer Location Json Structure

Retrieving All Segment Types

Use this GET method to retrieve all segment types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segmentTypes?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segmentTypes?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 346

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segmentTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment Type",
  "description" : "Sample Segment Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of SegmentTypes

[].uri

String

The uniform resource identifier (URI) of SegmentType

[].objectId

String

The object id of the SegmentType as represented in the source system.

[].tenantId

String

The tenant id of the SegmentType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SegmentType as represented in the source system.

[].sourceKey

String

The unique identifier of the SegmentType as represented in the source system. Must be unique per SegmentType defined.

[].name

String

The name of the SegmentType.

[].label

String

Hierarchical name of the SegmentType.

[].description

String

The general description for the SegmentType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SegmentTypes parent

[].location

Object

Please refer Location Json Structure

Example 4. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Retrieving Segment Types by Criteria

Use this GET method to retrieve segment types matching a specific criterion or criteria passed as the request query parameter.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/segmentTypes?sourceKey=DEMO-ASSET-SEGMENT-TYPE&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/segmentTypes?sourceKey=DEMO-ASSET-SEGMENT-TYPE&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request parameters
Parameter Description

sourceKey

The source key of the SegmentType to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to SegmentTypes to be returned.

attributes

The attributes filter for the SegmentTypes. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to SegmentTypes to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the SegmentTypes returned.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 346

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segmentTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment Type",
  "description" : "Sample Segment Type",
  "attributes" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of SegmentTypes

[].uri

String

The uniform resource identifier (URI) of SegmentType

[].objectId

String

The object id of the SegmentType as represented in the source system.

[].tenantId

String

The tenant id of the SegmentType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SegmentType as represented in the source system.

[].sourceKey

String

The unique identifier of the SegmentType as represented in the source system. Must be unique per SegmentType defined.

[].name

String

The name of the SegmentType.

[].label

String

Hierarchical name of the SegmentType.

[].description

String

The general description for the SegmentType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SegmentTypes parent

[].location

Object

Please refer Location Json Structure


Retrieving the Segment Type by URI

Use this GET method to retrieve the segment type by its resource URI. You must pass the URI using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segmentTypes/80ca97a2-c622-4538-ae9c-64d33f51a61e?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segmentTypes/80ca97a2-c622-4538-ae9c-64d33f51a61e?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 12. /v1/segmentTypes/{uuid}
Parameter Description

uuid

The unique identifier for the SegmentType. Must be unique per SegmentType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 342

{
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segmentTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment Type",
  "description" : "Sample Segment Type",
  "attributes" : { }
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of SegmentType

objectId

String

The object id of the SegmentType as represented in the source system.

tenantId

String

The tenant id of the SegmentType as represented in the source system.

rootTypeName

String

The CCOM type of the SegmentType as represented in the source system.

sourceKey

String

The unique identifier of the SegmentType as represented in the source system. Must be unique per SegmentType defined.

name

String

The name of the SegmentType.

label

String

Hierarchical name of the SegmentType.

description

String

The general description for the SegmentType

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the SegmentTypes parent

location

Object

Please refer Location Json Structure


Retrieving All Inherited Segment Types

Use this GET method to retrieve all child classifications derived from a specific segment type. You must pass the UUID of the requested resource using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segmentTypes/56d4c914-174e-4741-ab40-eb85d9b8006b/children?name=Sample*&components=BASIC&deepSearch=true' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segmentTypes/56d4c914-174e-4741-ab40-eb85d9b8006b/children?name=Sample*&components=BASIC&deepSearch=true HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 13. /v1/segmentTypes/{uuid}/children
Parameter Description

uuid

The unique identifier for the SegmentType. Must be unique per SegmentType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

name

The name filter to apply to SegmentTypes to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 346

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segmentTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment Type",
  "description" : "Sample Segment Type",
  "attributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of SegmentTypes

[].uri

String

The uniform resource identifier (URI) of SegmentType

[].objectId

String

The object id of the SegmentType as represented in the source system.

[].tenantId

String

The tenant id of the SegmentType as represented in the source system.

[].rootTypeName

String

The CCOM type of the SegmentType as represented in the source system.

[].sourceKey

String

The unique identifier of the SegmentType as represented in the source system. Must be unique per SegmentType defined.

[].name

String

The name of the SegmentType.

[].label

String

Hierarchical name of the SegmentType.

[].description

String

The general description for the SegmentType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the SegmentTypes parent

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of SegmentType


Retrieving the Parent of a Segment Type

Use this GET method to retrieve the parent URI of a specific segment type. You must pass the UUID of the requested resource using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segmentTypes/bce3200a-790b-47cd-980d-fca339fa8024/parent?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segmentTypes/bce3200a-790b-47cd-980d-fca339fa8024/parent?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 14. /v1/segmentTypes/{uuid}/parent
Parameter Description

uuid

The unique identifier for the SegmentType. Must be unique per SegmentType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 409

{
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segmentTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment Type",
  "description" : "Sample Segment Type",
  "attributes" : { },
  "parent" : "/segmentTypes/56d4c914-174e-4741-ab40-eb85d9b8006b"
}

Updating the Segment Type

Use this PATCH method to replace or update current information for a specific segment type. You must pass the UUID of the segment type as the path parameter. Depending on the operation specified in the request body, the property values are added or replaced.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segmentTypes/80ca97a2-c622-4538-ae9c-64d33f51a61e' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
} ]'
Example HTTP Request
PATCH /v1/segmentTypes/80ca97a2-c622-4538-ae9c-64d33f51a61e HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 200

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
} ]
Request Structure
Path Type Description

[]

Array

A list of patch operations

[].op

String

The operation name for the patch operation

[].path

String

The '/' separated path for the property being updated.

[].from

String

The old value of the property being updated.

[].value

Varies

The new value of the property to update.

Example Response
HTTP/1.1 204 No Content

Deleting Segment Type

Use the DELETE method to delete a specific segment type by UUID.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/segmentTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/segmentTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 15. /v1/segmentTypes/{uuid}
Parameter Description

uuid

The unique identifier for the SegmentType. Must be unique per SegmentType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Response structure
HTTP/1.1 200 OK

AssetTypes

Reserved Attributes
Example 5. Reserved Attributes config for AssetType

Below json provides the possible reserved attributes and corresponding metadata.

{
  "familyType": {
    "name": "familyType",
    "displayName": "Family Type",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "equipmentType": {
    "name": "equipmentType",
    "displayName": "Equipment Type",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "make": {
    "name": "make",
    "displayName": "Make",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "model": {
    "name": "model",
    "displayName": "Model",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "series": {
    "name": "series",
    "displayName": "Series",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "serialNumber": {
    "name": "serialNumber",
    "displayName": "Serial Number",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "maintenanceCriticalityRiskScore": {
    "name": "maintenanceCriticalityRiskScore",
    "displayName": "Maintenance Criticality Risk Score",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "faultMode": {
    "name": "faultMode",
    "displayName": "Fault Mode",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "ONE_DIMENSIONAL",
    "instanceApplicability": {
      "arrayType": "ONE_DIMENSIONAL",
      "overwrite": true
    }
  }
}

Creating Asset Types

Use this POST method to create asset types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assetTypes' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleAssetType",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { }
} ]'
Example HTTP Request
POST /v1/assetTypes HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 164

[ {
  "sourceKey" : "SampleAssetType",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Request Structure
Path Type Description

[]

Array

A list of AssetTypes

[].uri

String

The uniform resource identifier (URI) of AssetType

[].objectId

String

The object id of the AssetType as represented in the source system.

[].tenantId

String

The tenant id of the AssetType as represented in the source system.

[].rootTypeName

String

The CCOM type of the AssetType as represented in the source system.

[].sourceKey

String

The unique identifier of the AssetType as represented in the source system. Must be unique per AssetType defined.

[].name

String

The name of the AssetType.

[].label

String

Hierarchical name of the AssetType.

[].description

String

The general description for the AssetType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the AssetTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for AssetType for possible reserved attribute values for asset type.

[].location

Object

Please refer Location Json Structure

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 368

[ {
  "objectId" : "08316f1f-2220-3543-9524-791e08e7c509",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assetTypes/08316f1f-2220-3543-9524-791e08e7c509",
  "sourceKey" : "SampleAssetType",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of AssetTypes

[].uri

String

The uniform resource identifier (URI) of AssetType

[].objectId

String

The object id of the AssetType as represented in the source system.

[].tenantId

String

The tenant id of the AssetType as represented in the source system.

[].rootTypeName

String

The CCOM type of the AssetType as represented in the source system.

[].sourceKey

String

The unique identifier of the AssetType as represented in the source system. Must be unique per AssetType defined.

[].name

String

The name of the AssetType.

[].label

String

Hierarchical name of the AssetType.

[].description

String

The general description for the AssetType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the AssetTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for AssetType for possible reserved attribute values for asset type.

[].location

Object

Please refer Location Json Structure


Retrieving All Asset Types

Use this GET method to retrieve all asset types.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetTypes?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assetTypes?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 333

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of AssetTypes

[].uri

String

The uniform resource identifier (URI) of AssetType

[].objectId

String

The object id of the AssetType as represented in the source system.

[].tenantId

String

The tenant id of the AssetType as represented in the source system.

[].rootTypeName

String

The CCOM type of the AssetType as represented in the source system.

[].sourceKey

String

The unique identifier of the AssetType as represented in the source system. Must be unique per AssetType defined.

[].name

String

The name of the AssetType.

[].label

String

Hierarchical name of the AssetType.

[].description

String

The general description for the AssetType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the AssetTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for AssetType for possible reserved attribute values for asset type.

[].location

Object

Please refer Location Json Structure

Example 6. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Retrieving Asset Types by Criteria

Use this GET method to retrieve asset types matching a specific criterion or criteria passed as the request query parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assetTypes?sourceKey=DEMO-ASSET-TYPE&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/assetTypes?sourceKey=DEMO-ASSET-TYPE&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Parameters
Parameter Description

sourceKey

The source key of the AssetType to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to AssetTypes to be returned.

attributes

The attributes filter for the AssetTypes. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to AssetTypes to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the AssetTypes returned.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 370

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SAMPLE_ASSET_TYPE",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of AssetTypes

[].uri

String

The uniform resource identifier (URI) of AssetType

[].objectId

String

The object id of the AssetType as represented in the source system.

[].tenantId

String

The tenant id of the AssetType as represented in the source system.

[].rootTypeName

String

The CCOM type of the AssetType as represented in the source system.

[].sourceKey

String

The unique identifier of the AssetType as represented in the source system. Must be unique per AssetType defined.

[].name

String

The name of the AssetType.

[].label

String

Hierarchical name of the AssetType.

[].description

String

The general description for the AssetType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the AssetTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for AssetType for possible reserved attribute values for asset type.

[].location

Object

Please refer Location Json Structure


Retrieving the Asset Type by URI

Use this GET method to retrieve the asset type by its resource URI. Pass the URI using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assetTypes/114d4d69-6861-4cf7-a6bb-5d22e405f65c?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/assetTypes/114d4d69-6861-4cf7-a6bb-5d22e405f65c?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 16. /v1/assetTypes/{uuid}
Parameter Description

uuid

The unique identifier for the AssetType. Must be unique per AssetType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 329

{
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { }
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of AssetType

objectId

String

The object id of the AssetType as represented in the source system.

tenantId

String

The tenant id of the AssetType as represented in the source system.

rootTypeName

String

The CCOM type of the AssetType as represented in the source system.

sourceKey

String

The unique identifier of the AssetType as represented in the source system. Must be unique per AssetType defined.

name

String

The name of the AssetType.

label

String

Hierarchical name of the AssetType.

description

String

The general description for the AssetType

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the AssetTypes parent

reservedAttributes

Object

Please refer Reserved Attributes config for AssetType for possible reserved attribute values for asset type.

location

Object

Please refer Location Json Structure


Retrieving All Inherited Asset Types

Use this GET request to retrieve child asset types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assetTypes/196cb578-1940-4897-8c3e-437c6a3a3227/children?name=Sample*&components=BASIC&deepSearch=true' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/assetTypes/196cb578-1940-4897-8c3e-437c6a3a3227/children?name=Sample*&components=BASIC&deepSearch=true HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 17. /v1/assetTypes/{uuid}/children
Parameter Description

uuid

The unique identifier for the AssetType. Must be unique per AssetType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Parameters
Parameter Description

name

The name filter to apply to AssetTypes to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 333

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of AssetTypes

[].uri

String

The uniform resource identifier (URI) of AssetType

[].objectId

String

The object id of the AssetType as represented in the source system.

[].tenantId

String

The tenant id of the AssetType as represented in the source system.

[].rootTypeName

String

The CCOM type of the AssetType as represented in the source system.

[].sourceKey

String

The unique identifier of the AssetType as represented in the source system. Must be unique per AssetType defined.

[].name

String

The name of the AssetType.

[].label

String

Hierarchical name of the AssetType.

[].description

String

The general description for the AssetType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the AssetTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for AssetType for possible reserved attribute values for asset type.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of AssetType


Retrieving the Parent of an Asset Type

Use this GET method to retrieve the parent URI of a specific asset type. Pass the UUID of the requested resource using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assetTypes/33624a8f-0945-4302-9d8c-af1f9baf8145/parent?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/assetTypes/33624a8f-0945-4302-9d8c-af1f9baf8145/parent?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 18. /v1/assetTypes/{uuid}/parent
Parameter Description

uuid

The unique identifier for the AssetType. Must be unique per AssetType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 394

{
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { },
  "parent" : "/assetTypes/33624a8f-0945-4302-9d8c-af1f9baf8145"
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of AssetType

objectId

String

The object id of the AssetType as represented in the source system.

tenantId

String

The tenant id of the AssetType as represented in the source system.

rootTypeName

String

The CCOM type of the AssetType as represented in the source system.

sourceKey

String

The unique identifier of the AssetType as represented in the source system. Must be unique per AssetType defined.

name

String

The name of the AssetType.

label

String

Hierarchical name of the AssetType.

description

String

The general description for the AssetType

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the AssetTypes parent

reservedAttributes

Object

Please refer Reserved Attributes config for AssetType for possible reserved attribute values for asset type.

location

Object

Please refer Location Json Structure


Advanced Asset Type search

Use this GET method to get asset types by advanced search criteria. Any field in the response structure can be used in the query string. Fields in the response structure for the "parent" object can also be used in the query string. Search strings can include wildcard characters to perform starts with, ends with, contains, and similar searches.

Example cURL request
$ curl 'https://www.predixapis.com/v1/assetTypes/query?components=&pageSize=&q=name=Sample*' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json'
Example HTTP request
GET /v1/assetTypes/query?components=&pageSize=&q=name=Sample* HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Request Params
Parameter Description

components

Refer to section Components for more information.

pageSize

Page size to apply to the AssetTypes returned.

q

This field is required. Refer to section Advanced Search Supported Query Params for supported params. The query string to use for searching AssetTypes.

To search for AssetTypes by a field, use a query such as q=description=ObjectDescription.

To search for AssetTypes by a field within the "attributes" or "reservedAttributes" objects, use a query such as q=attributes.manufacturer.value=GE.

To search for AssetTypes by a field on a resource which a AssetType refers to, use a query such as q=type->name=AssetTypeTypeName. You can search up to two levels deep. For example, q=parent->parent->sourceKey=grandparentSourceKey will return all AssetTypes whose parent’s parent has the given sourceKey.

For fields which contain an array of values, a query such as q=attributes.modelNumbers.value=GT100 will match all AssetTypes which have a modelNumbers attribute with an array that contains a value of 'GT100'.

Use '*' to specify a wildcard search. For example, a query such as q=name=*Temperature* will return all AssetTypes with a name that contains the word 'Temperature'.

You can specify multiple filters in the query. Use the ':' and '|' characters to connect filters with 'AND' and 'OR' operators, respectively. The 'OR' operator takes precedence over the 'AND' operator. For example, q=name=Gas*|description=Gas*:attributes.modelNumbers.value=GT100|sourceKey=Gas* will return all AssetTypes for which match both of the following conditions:

1. name or description starts with 'Gas'

2. modelNumbers attribute with an array that contains a value of 'GT100' or sourceKey of the AssetType starts with 'Gas'.

q=_name=GE*:sourceKey=GEEngine717*|description=Gas*:attributes.modelNumbers.value=GT100|reservedAttributes.state.key=06 will return all AssetTypes for which match following conditions:

1. name starts with 'GE'

2. sourceKey of the AssetType starts with 'GEEngine717' or description of the AssetType starts with 'Gas'

3. modelNumbers attribute with an array that contains a value of 'GT100' or state reservedAttributes key contains of '06'.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 370

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SAMPLE_ASSET_TYPE",
  "name" : "Sample Asset Type",
  "description" : "Sample Asset Type",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of AssetTypes

[].uri

String

The uniform resource identifier (URI) of AssetType

[].objectId

String

The object id of the AssetType as represented in the source system.

[].tenantId

String

The tenant id of the AssetType as represented in the source system.

[].rootTypeName

String

The CCOM type of the AssetType as represented in the source system.

[].sourceKey

String

The unique identifier of the AssetType as represented in the source system. Must be unique per AssetType defined.

[].name

String

The name of the AssetType.

[].label

String

Hierarchical name of the AssetType.

[].description

String

The general description for the AssetType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the AssetTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for AssetType for possible reserved attribute values for asset type.

[].location

Object

Please refer Location Json Structure


Updating Asset Types

Use this PATCH method to replace or update current information for a specific asset type. You must pass the UUID of the asset type to update as the path parameter. Depending on the operation specified in the request body, the properties values are added or replaced.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assetTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "replace",
  "path" : "/attributes/Manufacturer"
} ]'
Example HTTP Request
PATCH /v1/assetTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 201

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "replace",
  "path" : "/attributes/Manufacturer"
} ]
Request Structure
Path Type Description

[]

Array

A list of patch operations

[].op

String

The operation name for the patch operation

[].path

String

The '/' separated path for the property being updated.

[].from

String

The old value of the property being updated.

[].value

Varies

Please refer Json Structure for Attributes for more information.

Example Response
HTTP/1.1 204 No Content

Deleting Asset Type

Use the DELETE method to delete a specific asset type by UUID.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/assetTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 19. /v1/assetTypes/{uuid}
Parameter Description

uuid

The unique identifier for the AssetType. Must be unique per AssetType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Response structure
HTTP/1.1 200 OK

TagTypes

Reserved Attributes
Example 7. Reserved Attributes config for TagType

Below json provides the possible reserved attributes and corresponding metadata. The possible values for the attribute 'uom' will be dynamically populated with tenant specific unit of measurements.

{
  "uom": {
    "name": "uom",
    "displayName": "Source Unit Of Measure",
    "type": "UnitOfMeasure",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": false
    }
  },
  "uomGroup": {
    "name": "uomGroup",
    "displayName": "Source Unit Of Measure Group",
    "type": "UnitOfMeasureGroup",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": false
    }
  },
  "dataType": {
    "name": "dataType",
    "displayName": "Data Type",
    "type": "String",
    "possibleValues": [
      "Double",
      "Float",
      "String"
    ],
    "defaultValue": "String",
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": false
    }
  },
  "resolution": {
    "name": "resolution",
    "displayName": "Resolution",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "shiLowThreshold": {
    "name": "shiLowThreshold",
    "displayName": "Sensor Health Index Low Threshold",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "shiHighThreshold": {
    "name": "shiHighThreshold",
    "displayName": "Sensor Health Index High Threshold",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 1,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "shiFlatLineNumber": {
    "name": "shiFlatLineNumber",
    "displayName": "Sensor Health Index Flat Line Number",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": 720,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "shiFlatLineEpsilon": {
    "name": "shiFlatLineEpsilon",
    "displayName": "Sensor Health Index Flat Line Epsilon",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "badObservationPersistent": {
    "name": "badObservationPersistent",
    "displayName": "Bad Observation Persistent / Penalty Window",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": 2880,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "falseAlarmProbability": {
    "name": "falseAlarmProbability",
    "displayName": "False Alarm Probability",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0.001,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "missedAlarmProbability": {
    "name": "missedAlarmProbability",
    "displayName": "Missed Alarm Probability",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0.001,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "sampleFailureMagnitudesMean": {
    "name": "sampleFailureMagnitudesMean",
    "displayName": "Sample Failure Magnitudes Mean",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": 10,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "sampleFailureMagnitudesVariance": {
    "name": "sampleFailureMagnitudesVariance",
    "displayName": "Sample Failure Magnitudes Variance",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": 40,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "nullHypothesisVariance": {
    "name": "nullHypothesisVariance",
    "displayName": "Null Hypothesis Variance",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0.0025,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "nanTestWeight": {
    "name": "nanTestWeight",
    "displayName": "NaN Test Weight",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 1,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "outlierTestWeight": {
    "name": "outlierTestWeight",
    "displayName": "Outlier Test Weight",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 1,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "flatTestWeight": {
    "name": "flatTestWeight",
    "displayName": "Flat Test Weight",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 1,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "category": {
    "name": "category",
    "displayName": "Category",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "maxOperatingValue": {
    "name": "maxOperatingValue",
    "displayName": "Maximum Operating Value",
    "type": "Double",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "instanceApplicability" : {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "minOperatingValue": {
    "name": "minOperatingValue",
    "displayName": "Minimum Operating Value",
    "type": "Double",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "instanceApplicability" : {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "highestThresholdValue": {
    "name": "highestThresholdValue",
    "displayName": "Highest Threshold Value",
    "type": "Double",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "instanceApplicability" : {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "lowestThresholdValue": {
    "name": "lowestThresholdValue",
    "displayName": "Lowest Threshold Value",
    "type": "Double",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "instanceApplicability" : {
      "arrayType": "NA",
      "overwrite": true
    }
  }
}

Sample Values

            "nullHypothesisVariance": 0.0025,
            "outlierTestWeight": 1,
            "shiFlatLineEpsilon": 0.000000010,
            "maxOperatingValue": null,
            "sampleFailureMagnitudesVariance": 40,
            "dataType": "String",
            "falseAlarmProbability": 0.001,
            "highestThresholdValue": null,
            "resolution": null,
            "shiLowThreshold": 0,
            "minOperatingValue": null,
            "missedAlarmProbability": 0.001,
            "nanTestWeight": 1,
            "uom": null,
            "shiHighThreshold": 1,
            "badObservationPersistent": 2880,
            "shiFlatLineNumber": 720,
            "uomGroup": null,
            "lowestThresholdValue": null,
            "sampleFailureMagnitudesMean": 10,
            "category": null,
            "flatTestWeight": 1,
            "isRestricted": false

Creating Tag Types

Use this POST method to create tag types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/tagTypes' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Measurement Tag",
  "description" : "Sample Measurement Tag",
  "attributes" : { },
  "reservedAttributes" : { }
} ]'
Example HTTP Request
POST /v1/tagTypes HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 174

[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Measurement Tag",
  "description" : "Sample Measurement Tag",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Request Structure
Path Type Description

[]

Array

A list of TagTypes

[].uri

String

The uniform resource identifier (URI) of TagType

[].objectId

String

The object id of the TagType as represented in the source system.

[].tenantId

String

The tenant id of the TagType as represented in the source system.

[].rootTypeName

String

The CCOM type of the TagType as represented in the source system.

[].sourceKey

String

The unique identifier of the TagType as represented in the source system. Must be unique per TagType defined.

[].name

String

The name of the TagType.

[].label

String

Hierarchical name of the TagType.

[].description

String

The general description for the TagType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the TagTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for TagType for possible reserved attribute values for tag type.

[].location

Object

Please refer Location Json Structure

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 374

[ {
  "objectId" : "01082cee-086f-3a85-b5d0-7c7254a95072",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tagTypes/01082cee-086f-3a85-b5d0-7c7254a95072",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Measurement Tag",
  "description" : "Sample Measurement Tag",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of TagTypes

[].uri

String

The uniform resource identifier (URI) of TagType

[].objectId

String

The object id of the TagType as represented in the source system.

[].tenantId

String

The tenant id of the TagType as represented in the source system.

[].rootTypeName

String

The CCOM type of the TagType as represented in the source system.

[].sourceKey

String

The unique identifier of the TagType as represented in the source system. Must be unique per TagType defined.

[].name

String

The name of the TagType.

[].label

String

Hierarchical name of the TagType.

[].description

String

The general description for the TagType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the TagTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for TagType for possible reserved attribute values for tag type.

[].location

Object

Please refer Location Json Structure


Getting All Tag Types

Use this GET method to retrieve all tag types.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/tagTypes?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/tagTypes?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 339

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Measurement Tag",
  "description" : "Sample Measurement Tag",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of TagTypes

[].uri

String

The uniform resource identifier (URI) of TagType

[].objectId

String

The object id of the TagType as represented in the source system.

[].tenantId

String

The tenant id of the TagType as represented in the source system.

[].rootTypeName

String

The CCOM type of the TagType as represented in the source system.

[].sourceKey

String

The unique identifier of the TagType as represented in the source system. Must be unique per TagType defined.

[].name

String

The name of the TagType.

[].label

String

Hierarchical name of the TagType.

[].description

String

The general description for the TagType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the TagTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for TagType for possible reserved attribute values for tag type.

[].location

Object

Please refer Location Json Structure

Example 8. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Getting Tag Types by Criteria

Use this GET method to retrieve tag types matching a specific criterion or criteria passed as the request query parameter.

Example CURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/tagTypes?sourceKey=Tag_Temperature_1992&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/tagTypes?sourceKey=Tag_Temperature_1992&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Parameters
Parameter Description

sourceKey

The source key of the TagType to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to TagTypes to be returned.

attributes

The attributes filter for the TagTypes. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to TagTypes to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the TagTypes returned.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 339

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Measurement Tag",
  "description" : "Sample Measurement Tag",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of TagTypes

[].uri

String

The uniform resource identifier (URI) of TagType

[].objectId

String

The object id of the TagType as represented in the source system.

[].tenantId

String

The tenant id of the TagType as represented in the source system.

[].rootTypeName

String

The CCOM type of the TagType as represented in the source system.

[].sourceKey

String

The unique identifier of the TagType as represented in the source system. Must be unique per TagType defined.

[].name

String

The name of the TagType.

[].label

String

Hierarchical name of the TagType.

[].description

String

The general description for the TagType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the TagTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for TagType for possible reserved attribute values for tag type.

[].location

Object

Please refer Location Json Structure


Retrieving the Tag Type by URI

Use this GET method to retrieve the tag type by its resource URI. You must pass the URI using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/tagTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/tagTypes/f72aa434-e801-45a9-a997-6375a3e5a0d8?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 20. /v1/tagTypes/{uuid}
Parameter Description

uuid

The unique identifier for the TagType. Must be unique per TagType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 335

{
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Measurement Tag",
  "description" : "Sample Measurement Tag",
  "attributes" : { },
  "reservedAttributes" : { }
}

Advanced Tag Type search

Use this GET method to get tag types by advanced search criteria. Any field in the response structure can be used in the query string. Fields in the response structure for the "parent" object can also be used in the query string. Search strings can include wildcard characters to perform starts with, ends with, contains, and similar searches.

Example cURL request
$ curl 'https://www.predixapis.com/v1/tagTypes/query?components=&pageSize=&q=name=Sample*' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json'
Example HTTP request
GET /v1/tagTypes/query?components=&pageSize=&q=name=Sample* HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Request Params
Parameter Description

components

Refer to section Components for more information.

pageSize

Page size to apply to the TagTypes returned.

q

This field is required. Refer to section Advanced Search Supported Query Params for supported params. The query string to use for searching TagTypes.

To search for TagTypes by a field, use a query such as q=description=ObjectDescription.

To search for TagTypes by a field within the "attributes" or "reservedAttributes" objects, use a query such as q=attributes.manufacturer.value=GE.

To search for TagTypes by a field on a resource which a TagType refers to, use a query such as q=type->name=TagTypeTypeName. You can search up to two levels deep. For example, q=parent->parent->sourceKey=grandparentSourceKey will return all TagTypes whose parent’s parent has the given sourceKey.

For fields which contain an array of values, a query such as q=attributes.modelNumbers.value=GT100 will match all TagTypes which have a modelNumbers attribute with an array that contains a value of 'GT100'.

Use '*' to specify a wildcard search. For example, a query such as q=name=*Temperature* will return all TagTypes with a name that contains the word 'Temperature'.

You can specify multiple filters in the query. Use the ':' and '|' characters to connect filters with 'AND' and 'OR' operators, respectively. The 'OR' operator takes precedence over the 'AND' operator. For example, q=name=Gas*|description=Gas*:attributes.modelNumbers.value=GT100|sourceKey=Gas* will return all TagTypes for which match both of the following conditions:

1. name or description starts with 'Gas'

2. modelNumbers attribute with an array that contains a value of 'GT100' or sourceKey of the TagType starts with 'Gas'.

q=_name=GE*:sourceKey=GEEngine717*|description=Gas*:attributes.modelNumbers.value=GT100|reservedAttributes.state.key=06 will return all TagTypes for which match following conditions:

1. name starts with 'GE'

2. sourceKey of the TagType starts with 'GEEngine717' or description of the TagType starts with 'Gas'

3. modelNumbers attribute with an array that contains a value of 'GT100' or state reservedAttributes key contains of '06'.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 339

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "name" : "Sample Measurement Tag",
  "description" : "Sample Measurement Tag",
  "attributes" : { },
  "reservedAttributes" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of TagTypes

[].uri

String

The uniform resource identifier (URI) of TagType

[].objectId

String

The object id of the TagType as represented in the source system.

[].tenantId

String

The tenant id of the TagType as represented in the source system.

[].rootTypeName

String

The CCOM type of the TagType as represented in the source system.

[].sourceKey

String

The unique identifier of the TagType as represented in the source system. Must be unique per TagType defined.

[].name

String

The name of the TagType.

[].label

String

Hierarchical name of the TagType.

[].description

String

The general description for the TagType

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the TagTypes parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for TagType for possible reserved attribute values for tag type.

[].location

Object

Please refer Location Json Structure


Updating a Tag Type

Use this PATCH method to replace or update current information for a specific tag type. You must pass the UUID of the tag type to update as the path parameter. Depending on the operation specified in the request body, the properties values are added or replaced.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/tagTypes/00700f60-f53b-4de2-9307-4fbd27826b51' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
} ]'
Example HTTP Request
PATCH /v1/tagTypes/00700f60-f53b-4de2-9307-4fbd27826b51 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 200

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
} ]
Request Structure
Path Type Description

[]

Array

A list of patch operations

[].op

String

The operation name for the patch operation

[].path

String

The '/' separated path for the property being updated.

[].from

String

The old value of the property being updated.

[].value

Varies

The new value of the property to update.

Example Response
HTTP/1.1 204 No Content

Deleting Tag Type

Use the DELETE method to delete a specific tag type by UUID.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/tagTypes/00700f60-f53b-4de2-9307-4fbd27826b51' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/tagTypes/00700f60-f53b-4de2-9307-4fbd27826b51 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 21. /v1/tagTypes/{uuid}
Parameter Description

uuid

The unique identifier for the TagType. Must be unique per TagType and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Response structure
HTTP/1.1 200 OK

Instances

An asset instance can be any capital, separately maintainable and uniquely trackable item. A physical entity such as the generator GN9999 located in North Plant of Acme Inc is an instance of a generator class. The general structure of this asset model is provided by the following example:

Instance Example

You can use the following CRUD operations for instances.


Enterprise


Reserved Attributes
Example 9. Reserved Attributes config for Enterprise

Below json provides the possible reserved attributes and corresponding metadata.

{
  "state": {
    "name": "state",
    "displayName": "State",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Plan"
      },
      {
        "key": "02",
        "value": "Design"
      },
      {
        "key": "03",
        "value": "Procure"
      },
      {
        "key": "04",
        "value": "Build"
      },
      {
        "key": "05",
        "value": "Commission"
      },
      {
        "key": "06",
        "value": "Operate"
      },
      {
        "key": "07",
        "value": "Maintain"
      },
      {
        "key": "08",
        "value": "Monitor"
      },
      {
        "key": "09",
        "value": "Upgrade"
      },
      {
        "key": "10",
        "value": "Decommission"
      },
      {
        "key": "11",
        "value": "Replace"
      },
      {
        "key": "12",
        "value": "Dispose"
      }
    ],
    "defaultValue": {
      "key": "06",
      "value": "Operate"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  },
  "status": {
    "name": "status",
    "displayName": "Status",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Failure"
      },
      {
        "key": "02",
        "value": "Warning"
      },
      {
        "key": "03",
        "value": "Normal"
      },
      {
        "key": "04",
        "value": "External Help Request"
      },
      {
        "key": "05",
        "value": "User-Defined Condition"
      }
    ],
    "defaultValue": {
      "key": "03",
      "value": "Normal"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  }
 }
Creating Enterprises

Use this POST method to create enterprises.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Enterprise",
  "description" : "Sample Enterprise",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/enterpriseTypes/bb571726-c1a3-4610-99de-435ab7f74000"
} ]'
Example HTTP Request
POST /v1/enterprises HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 232

[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Enterprise",
  "description" : "Sample Enterprise",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/enterpriseTypes/bb571726-c1a3-4610-99de-435ab7f74000"
} ]
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 517

[ {
  "objectId" : "799ec2ce-ca94-33c5-84a0-1b24dab611ac",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterprises/799ec2ce-ca94-33c5-84a0-1b24dab611ac",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Enterprise",
  "description" : "Sample Enterprise",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/enterpriseTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Enterprises

[].uri

String

The uniform resource identifier (URI) of Enterprise

[].objectId

String

The object id of the Enterprise as represented in the source system.

[].tenantId

String

The tenant id of the Enterprise as represented in the source system.

[].rootTypeName

String

The CCOM type of the Enterprise as represented in the source system.

[].sourceKey

String

The unique identifier of the Enterprise as represented in the source system. Must be unique per Enterprise defined.

[].name

String

The name of the Enterprise.

[].label

String

Hierarchical name of the Enterprise.

[].description

String

The general description for the Enterprise

[].attributes

Object

Please refer Json Structure for Attributes

[].reservedAttributes

Object

Please refer Reserved Attributes config for Enterprise for possible reserved attribute values for enterprise.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Enterprise

[].enterpriseType

Object

The Enterprise Type of Enterprise


Retrieving All Enterprises

Use this GET method to retrieve all enterprises.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterprises?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 482

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterprises/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample enterprise",
  "description" : "Sample enterprise",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Enterprises

[].uri

String

The uniform resource identifier (URI) of Enterprise

[].objectId

String

The object id of the Enterprise as represented in the source system.

[].tenantId

String

The tenant id of the Enterprise as represented in the source system.

[].rootTypeName

String

The CCOM type of the Enterprise as represented in the source system.

[].sourceKey

String

The unique identifier of the Enterprise as represented in the source system. Must be unique per Enterprise defined.

[].name

String

The name of the Enterprise.

[].label

String

Hierarchical name of the Enterprise.

[].description

String

The general description for the Enterprise

[].attributes

Object

Please refer Json Structure for Attributes

[].reservedAttributes

Object

Please refer Reserved Attributes config for Enterprise for possible reserved attribute values for enterprise.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Enterprise

[].enterpriseType

Object

The Enterprise Type of Enterprise

Example 10. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Retrieving Enterprises by Criteria

Use this GET method to retrieve enterprises matching a specific criterion or criteria passed as the request query parameter. Refer to Handle special characters section for more information.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterprises?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Parameters
Parameter Description

sourceKey

The source key of the Enterprise to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Enterprises to be returned.

attributes

The attributes filter for the Enterprises. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to Enterprises to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the Enterprises returned.

type

The type filter to apply to Enterprises to be returned.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 532

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterprises/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-ENTERPRISE",
  "name" : "DEMO ASSET ENTERPRISE",
  "description" : "This is the enterprise",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Enterprises

[].uri

String

The uniform resource identifier (URI) of Enterprise

[].objectId

String

The object id of the Enterprise as represented in the source system.

[].tenantId

String

The tenant id of the Enterprise as represented in the source system.

[].rootTypeName

String

The CCOM type of the Enterprise as represented in the source system.

[].sourceKey

String

The unique identifier of the Enterprise as represented in the source system. Must be unique per Enterprise defined.

[].name

String

The name of the Enterprise.

[].label

String

Hierarchical name of the Enterprise.

[].description

String

The general description for the Enterprise

[].attributes

Object

Please refer Json Structure for Attributes

[].reservedAttributes

Object

Please refer Reserved Attributes config for Enterprise for possible reserved attribute values for enterprise.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Enterprise

[].enterpriseType

Object

The Enterprise Type of Enterprise


Retrieving the Enterprise by URI

Use this GET method to retrieve a specific enterprise by its resource URI. You must pass the URI using the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterprises/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 22. /v1/enterprises/{uuid}
Parameter Description

uuid

The unique identifier for the Enterprise. Must be unique per Enterprise and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 528

{
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/enterprises/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-ENTERPRISE",
  "name" : "DEMO ASSET ENTERPRISE",
  "description" : "This is the enterprise",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/enterpriseTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of Enterprise

objectId

String

The object id of the Enterprise as represented in the source system.

tenantId

String

The tenant id of the Enterprise as represented in the source system.

rootTypeName

String

The CCOM type of the Enterprise as represented in the source system.

sourceKey

String

The unique identifier of the Enterprise as represented in the source system. Must be unique per Enterprise defined.

name

String

The name of the Enterprise.

label

String

Hierarchical name of the Enterprise.

description

String

The general description for the Enterprise

attributes

Object

Please refer Json Structure for Attributes

reservedAttributes

Object

Please refer Reserved Attributes config for Enterprise for possible reserved attribute values for enterprise.

location

Object

Please refer Location Json Structure

type

String

Type uri of Enterprise

enterpriseType

Object

The Enterprise Type of Enterprise


Getting the Child Nodes linked to an Enterprise

Use this GET method to get all children nodes (enterprises or sites) that are directly linked to a specific enterprise. You must pass the enterprise UUID in the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises/004066e0-d480-4908-b82d-15af1e4122ab/children?name=*Turbine*&components=BASIC&childPrefix=&deepSearch=&childPrefix=&deepSearch=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterprises/004066e0-d480-4908-b82d-15af1e4122ab/children?name=*Turbine*&components=BASIC&childPrefix=&deepSearch=&childPrefix=&deepSearch= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 23. /v1/enterprises/{uuid}/children
Parameter Description

uuid

The unique identifier for the Enterprise. Must be unique per Enterprise and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Parameters
Parameter Description

name

The name filter to apply to Enterprises to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

childPrefix

Single type of children.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 458

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/sites/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Site",
  "description" : "Sample Site",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/siteTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Enterprises

[].uri

String

The uniform resource identifier (URI) of Enterprise

[].objectId

String

The object id of the Enterprise as represented in the source system.

[].tenantId

String

The tenant id of the Enterprise as represented in the source system.

[].rootTypeName

String

The CCOM type of the Enterprise as represented in the source system.

[].sourceKey

String

The unique identifier of the Enterprise as represented in the source system. Must be unique per Enterprise defined.

[].name

String

The name of the Enterprise.

[].label

String

Hierarchical name of the Enterprise.

[].description

String

The general description for the Enterprise

[].attributes

Object

Please refer Json Structure for Attributes

[].reservedAttributes

Object

Please refer Reserved Attributes config for Enterprise for possible reserved attribute values for enterprise.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Enterprise


Retrieving All Sites Linked to an Enterprise

Use this GET method to retrieve all sites linked to a specific enterprise. You must pass the enterprise UUID in the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises/004066e0-d480-4908-b82d-15af1e4122ab/sites?name=*Turbine*&components=BASIC&deepSearch=false' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/enterprises/004066e0-d480-4908-b82d-15af1e4122ab/sites?name=*Turbine*&components=BASIC&deepSearch=false HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 24. /v1/enterprises/{uuid}/sites
Parameter Description

uuid

The unique identifier for the Enterprise. Must be unique per Enterprise and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Parameters
Parameter Description

name

The name filter to apply to Enterprises to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 458

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "EnterpriseType",
  "uri" : "/sites/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Site",
  "description" : "Sample Site",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/siteTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Enterprises

[].uri

String

The uniform resource identifier (URI) of Enterprise

[].objectId

String

The object id of the Enterprise as represented in the source system.

[].tenantId

String

The tenant id of the Enterprise as represented in the source system.

[].rootTypeName

String

The CCOM type of the Enterprise as represented in the source system.

[].sourceKey

String

The unique identifier of the Enterprise as represented in the source system. Must be unique per Enterprise defined.

[].name

String

The name of the Enterprise.

[].label

String

Hierarchical name of the Enterprise.

[].description

String

The general description for the Enterprise

[].attributes

Object

Please refer Json Structure for Attributes

[].reservedAttributes

Object

Please refer Reserved Attributes config for Enterprise for possible reserved attribute values for enterprise.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Enterprise


Updating Enterprise Details

Use this PATCH request to update the details of a specific enterprise.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises/004066e0-d480-4908-b82d-15af1e4122ab' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
}, {
  "op" : "replace",
  "path" : "/reservedAttributes/status",
  "value" : "02"
} ]'
Example HTTP Request
PATCH /v1/enterprises/004066e0-d480-4908-b82d-15af1e4122ab HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 283

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
}, {
  "op" : "replace",
  "path" : "/reservedAttributes/status",
  "value" : "02"
} ]
Request Structure
Table 25. /v1/enterprises/{uuid}
Parameter Description

uuid

The unique identifier for the Enterprise. Must be unique per Enterprise and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 204 No Content

Retrieving Tags for an Enterprise

Use this GET method to retrieve tags for an Enterprise.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression&tagUri=&includeCorrelatedTags&sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression=&tagUri=&includeCorrelatedTags=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/enterprises/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression&tagUri=&includeCorrelatedTags&sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression=&tagUri=&includeCorrelatedTags= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 26. /v1/enterprises/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Enterprise. Must be unique per Enterprise and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

sourceKey

The source key of the Enterprise to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Enterprises to be returned.

alias

Alias filter to apply to Enterprises to be returned.

description

The description filter to apply to Enterprises to be returned.

pageSize

Page size to apply to the Enterprises returned.

deepSearch

Search within the scope of all descendant nodes.

expression

Expression

tagUri

The tag uri filter to apply to the Enterprise to be returned

includeCorrelatedTags

If this is set to true, the Tag will be returned with all of the Tags in its correlation.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 541

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tags/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "Tag1",
  "name" : "Tag_1",
  "description" : "This is Tag_1",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/enterprises/bb571726-c1a3-4610-99de-435ab7f74000",
  "monitoredEntitySourceKey" : "SampleSite"
} ]
If deepSearch flag is 'true' then it will return specified pageSize tags without nextPageLink (HTTP status ok). e.g. If Enterprise 'GE power' has 100 sites (each site has 1 tag), 100 segments (each segment has 1 tag) and 100 assets (each asset has 2 tag) then tags of 'GE power' API (with pageSize 250) returns first matching 250 tags without nextPageLink (Http status ok).
Response structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification


Download Tags for an Enterprise

Use this GET method to download all tags for an enterprise instance in a CSV file.

Example cURL Request
$ curl 'https://www.predixapis.com/v1/enterprises/0008acd7-983d-4b72-a600-1990fdda4aeb/tags/download?q=name=Sample*&sortBy=name.asc&fields=name,sourceKey,reservedAttributes.uom&fieldHeaders=Name,SourceID,Units' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/enterprises/0008acd7-983d-4b72-a600-1990fdda4aeb/tags/download?q=name=Sample*&sortBy=name.asc&fields=name,sourceKey,reservedAttributes.uom&fieldHeaders=Name,SourceID,Units HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: www.predixapis.com
Request parameters
Parameter Description

q

This field is required. Refer to section Advanced Search Supported Query Params for supported params. The query string to use for searching Assets.

To search for Assets by a field, use a query such as q=description=ObjectDescription.

To search for Assets by a field within the "attributes" or "reservedAttributes" objects, use a query such as q=attributes.manufacturer.value=GE.

To search for Assets by a field on a resource which a Asset refers to, use a query such as q=type->name=AssetTypeName. You can search up to two levels deep. For example, q=parent->parent->sourceKey=grandparentSourceKey will return all Assets whose parent’s parent has the given sourceKey.

For fields which contain an array of values, a query such as q=attributes.modelNumbers.value=GT100 will match all Assets which have a modelNumbers attribute with an array that contains a value of 'GT100'.

Use '*' to specify a wildcard search. For example, a query such as q=name=*Temperature* will return all Assets with a name that contains the word 'Temperature'.

You can specify multiple filters in the query. Use the ':' and '|' characters to connect filters with 'AND' and 'OR' operators, respectively. The 'OR' operator takes precedence over the 'AND' operator. For example, q=name=Gas*|description=Gas*:attributes.modelNumbers.value=GT100|sourceKey=Gas* will return all Assets for which match both of the following conditions:

1. name or description starts with 'Gas'

2. modelNumbers attribute with an array that contains a value of 'GT100' or sourceKey of the Asset starts with 'Gas'.

q=_name=GE*:sourceKey=GEEngine717*|description=Gas*:attributes.modelNumbers.value=GT100|reservedAttributes.state.key=06 will return all Assets for which match following conditions:

1. name starts with 'GE'

2. sourceKey of the Asset starts with 'GEEngine717' or description of the Asset starts with 'Gas'

3. modelNumbers attribute with an array that contains a value of 'GT100' or state reservedAttributes key contains of '06'.

sortBy

Sort Tag instances ascending/descending based on sortBy param value

fields

Tag instance attributes to be included in csv file

fieldHeaders

Column headers to be included in csv file. This is an optional param, if it’s not provided field names will be returned as column headers.


Mapping Tags to an Enterprise

Use this POST method to link tags to a specific enterprise.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises/0008acd7-983d-4b72-a600-1990fdda4aeb/tags' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb",
  "sourceKey" : "Tag1",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/enterprises/bb571726-c1a3-4610-99de-435ab7f74000"
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aec",
  "sourceKey" : "Tag2",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/enterprises/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ],
  "nextRelatedTag" : {
    "tagUri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb"
  }
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aed",
  "sourceKey" : "Tag3",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/enterprises/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ]
} ]'
Example HTTP request
POST /v1/enterprises/0008acd7-983d-4b72-a600-1990fdda4aeb/tags HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 907

[ {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb",
  "sourceKey" : "Tag1",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/enterprises/bb571726-c1a3-4610-99de-435ab7f74000"
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aec",
  "sourceKey" : "Tag2",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/enterprises/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ],
  "nextRelatedTag" : {
    "tagUri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb"
  }
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aed",
  "sourceKey" : "Tag3",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/enterprises/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ]
} ]
Request Structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification

Path Params
Table 27. /v1/enterprises/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Enterprise. Must be unique per Enterprise and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK

Deleting / Disassociating Tags from an Enterprise

Use the DELETE method to remove the tag-enterprise mapping. Removing the mapping will make the tags orphaned until you link them back.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/enterprises/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?uris=/tags/bb571726-c1a3-4610-99de-435ab7f74000' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/enterprises/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?uris=/tags/bb571726-c1a3-4610-99de-435ab7f74000 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 28. /v1/enterprises/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Enterprise. Must be unique per Enterprise and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

uris

URIs of tags to delete

Example response
HTTP/1.1 200 OK

Site


Reserved Attributes
Example 11. Reserved Attributes config for Site

Below json provides the possible reserved attributes and corresponding metadata.

{
  "state": {
    "name": "state",
    "displayName": "State",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Plan"
      },
      {
        "key": "02",
        "value": "Design"
      },
      {
        "key": "03",
        "value": "Procure"
      },
      {
        "key": "04",
        "value": "Build"
      },
      {
        "key": "05",
        "value": "Commission"
      },
      {
        "key": "06",
        "value": "Operate"
      },
      {
        "key": "07",
        "value": "Maintain"
      },
      {
        "key": "08",
        "value": "Monitor"
      },
      {
        "key": "09",
        "value": "Upgrade"
      },
      {
        "key": "10",
        "value": "Decommission"
      },
      {
        "key": "11",
        "value": "Replace"
      },
      {
        "key": "12",
        "value": "Dispose"
      }
    ],
    "defaultValue": {
      "key": "06",
      "value": "Operate"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  },
  "status": {
    "name": "status",
    "displayName": "Status",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Failure"
      },
      {
        "key": "02",
        "value": "Warning"
      },
      {
        "key": "03",
        "value": "Normal"
      },
      {
        "key": "04",
        "value": "External Help Request"
      },
      {
        "key": "05",
        "value": "User-Defined Condition"
      }
    ],
    "defaultValue": {
      "key": "03",
      "value": "Normal"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  }
 }
Creating Sites

Use this POST method to create sites.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/sites' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Site",
  "description" : "Sample Site",
  "attributes" : {
    "State" : {
      "type" : "String",
      "value" : [ "California" ]
    }
  },
  "reservedAttributes" : {
    "status" : {
      "key" : "01"
    },
    "state" : {
      "key" : "01"
    }
  },
  "type" : "/siteTypes/bb571726-c1a3-4610-99de-435ab7f74000"
} ]'
Example HTTP Request
POST /v1/sites HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 382

[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Site",
  "description" : "Sample Site",
  "attributes" : {
    "State" : {
      "type" : "String",
      "value" : [ "California" ]
    }
  },
  "reservedAttributes" : {
    "status" : {
      "key" : "01"
    },
    "state" : {
      "key" : "01"
    }
  },
  "type" : "/siteTypes/bb571726-c1a3-4610-99de-435ab7f74000"
} ]
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 487

[ {
  "objectId" : "87918610-f975-387a-9a91-02171faac85e",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/sites/87918610-f975-387a-9a91-02171faac85e",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Site",
  "description" : "Sample Site",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/siteTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Sites

[].uri

String

The uniform resource identifier (URI) of Site

[].objectId

String

The object id of the Site as represented in the source system.

[].tenantId

String

The tenant id of the Site as represented in the source system.

[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

[].sourceKey

String

The unique identifier of the Site as represented in the source system. Must be unique per Site defined.

[].name

String

The name of the Site.

[].label

String

Hierarchical name of the Site.

[].description

String

The general description for the Site

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Sites parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Site for possible reserved attribute values for site.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Site

[].measurementTags

Array

Tags which monitor this Site

[].measurementTags.[].objectId

String

The object id of the Site as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Site as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

[].siteType

Object

Site Type of Site

[].enterprise

Object

Parent of Site


Getting All Sites

Use this GET request to get all sites.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/sites?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/sites?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 452

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/sites/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Site",
  "description" : "Sample Site",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/siteTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Sites

[].uri

String

The uniform resource identifier (URI) of Site

[].objectId

String

The object id of the Site as represented in the source system.

[].tenantId

String

The tenant id of the Site as represented in the source system.

[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

[].sourceKey

String

The unique identifier of the Site as represented in the source system. Must be unique per Site defined.

[].name

String

The name of the Site.

[].label

String

Hierarchical name of the Site.

[].description

String

The general description for the Site

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Sites parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Site for possible reserved attribute values for site.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Site

[].measurementTags

Array

Tags which monitor this Site

[].measurementTags.[].objectId

String

The object id of the Site as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Site as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

[].siteType

Object

Site Type of Site

[].enterprise

Object

Parent of Site

Example 12. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Getting Sites by Criteria

Use this GET method to get sites matching a specific criterian or criteria passed as the request query parameter. Refer to Handle special characters section for more information.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/sites?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/sites?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request parameters
Parameter Description

sourceKey

The source key of the Site to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Sites to be returned.

attributes

The attributes filter for the Sites. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to Sites to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the Sites returned.

type

The type filter to apply to Sites to be returned.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 496

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/sites/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-site",
  "name" : "DEMO ASSET site",
  "description" : "This is the site",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/siteTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of Sites

[].uri

String

The uniform resource identifier (URI) of Site

[].objectId

String

The object id of the Site as represented in the source system.

[].tenantId

String

The tenant id of the Site as represented in the source system.

[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

[].sourceKey

String

The unique identifier of the Site as represented in the source system. Must be unique per Site defined.

[].name

String

The name of the Site.

[].label

String

Hierarchical name of the Site.

[].description

String

The general description for the Site

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Sites parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Site for possible reserved attribute values for site.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Site

[].measurementTags

Array

Tags which monitor this Site

[].measurementTags.[].objectId

String

The object id of the Site as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Site as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

[].siteType

Object

Site Type of Site

[].enterprise

Object

Parent of Site


Getting the Sites by URI

Use this GET method to a specific site by the resource URI. You would pass the URI using the path parameter. See the usage example requests below

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/sites/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/sites/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 29. /v1/sites/{uuid}
Parameter Description

uuid

The unique identifier for the Site. Must be unique per Site and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 492

{
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/sites/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-site",
  "name" : "DEMO ASSET site",
  "description" : "This is the site",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/siteTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
}
Response structure
Path Type Description

uri

String

The uniform resource identifier (URI) of Site

objectId

String

The object id of the Site as represented in the source system.

tenantId

String

The tenant id of the Site as represented in the source system.

rootTypeName

String

The CCOM type of the Site as represented in the source system.

sourceKey

String

The unique identifier of the Site as represented in the source system. Must be unique per Site defined.

name

String

The name of the Site.

label

String

Hierarchical name of the Site.

description

String

The general description for the Site

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the Sites parent

reservedAttributes

Object

Please refer Reserved Attributes config for Site for possible reserved attribute values for site.

location

Object

Please refer Location Json Structure

type

String

Type uri of Site

measurementTags

Array

Tags which monitor this Site

measurementTags.[].objectId

String

The object id of the Site as represented in the source system.

measurementTags.[].tenantId

String

The tenant id of the Site as represented in the source system.

measurementTags.[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

siteType

Object

Site Type of Site

enterprise

Object

Parent of Site


Getting the Child Nodes linked to a Site

Use this GET method to get all children nodes (segments or assets) that are directly linked to a specific segment. You must pass the site UUID in the path parameter.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/children?name=*Turbine*&components=BASIC&childPrefix=&deepSearch=&childPrefix=&deepSearch=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/children?name=*Turbine*&components=BASIC&childPrefix=&deepSearch=&childPrefix=&deepSearch= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request structure
Table 30. /v1/sites/{uuid}/children
Parameter Description

uuid

The unique identifier for the Site. Must be unique per Site and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Parameters
Parameter Description

name

The name filter to apply to Sites to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

childPrefix

Single type of children.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 467

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segments/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Segment",
  "description" : "Sample Segment",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/segmentTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of Sites

[].uri

String

The uniform resource identifier (URI) of Site

[].objectId

String

The object id of the Site as represented in the source system.

[].tenantId

String

The tenant id of the Site as represented in the source system.

[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

[].sourceKey

String

The unique identifier of the Site as represented in the source system. Must be unique per Site defined.

[].name

String

The name of the Site.

[].label

String

Hierarchical name of the Site.

[].description

String

The general description for the Site

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Sites parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Site for possible reserved attribute values for site.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Site


Updating Sites

Use this PATCH request to update a site.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/sites/004066e0-d480-4908-b82d-15af1e4122ab' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
}, {
  "op" : "replace",
  "path" : "/reservedAttributes/status",
  "value" : "02"
} ]'
Example HTTP request
PATCH /v1/sites/004066e0-d480-4908-b82d-15af1e4122ab HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 283

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
}, {
  "op" : "replace",
  "path" : "/reservedAttributes/status",
  "value" : "02"
} ]
Request structure
Table 31. /v1/sites/{uuid}
Parameter Description

uuid

The unique identifier for the Site. Must be unique per Site and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 204 No Content

Retrieving Tags for a Site

Use this GET method to retrieve tags for a site.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression&tagUri=&includeCorrelatedTags&sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression=&tagUri=&includeCorrelatedTags=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression&tagUri=&includeCorrelatedTags&sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression=&tagUri=&includeCorrelatedTags= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 32. /v1/sites/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Site. Must be unique per Site and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

sourceKey

The source key of the Site to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Sites to be returned.

alias

Alias filter to apply to Sites to be returned.

description

The description filter to apply to Sites to be returned.

pageSize

Page size to apply to the Sites returned.

deepSearch

Search within the scope of all descendant nodes.

expression

Expression

tagUri

The tag uri filter to apply to the Site to be returned

includeCorrelatedTags

If this is set to true, the Tag will be returned with all of the Tags in its correlation.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 505

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tags/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "Tag1",
  "name" : "Tag_1",
  "description" : "This is Tag_1",
  "attributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/sites/bb571726-c1a3-4610-99de-435ab7f74000",
  "monitoredEntitySourceKey" : "SampleSite"
} ]
If deepSearch flag is 'true' then it will return specified pageSize tags without nextPageLink (HTTP status ok). e.g. If Enterprise 'GE power' has 100 sites (each site has 1 tag), 100 segments (each segment has 1 tag) and 100 assets (each asset has 2 tag) then tags of 'GE power' API (with pageSize 250) returns first matching 250 tags without nextPageLink (Http status ok).
Response structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification


Download Tags for a Site

Use this GET method to download all tags for a Site instance in a CSV file.

Example cURL Request
$ curl 'https://www.predixapis.com/v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/tags/download?q=name=Sample*&sortBy=name.asc&fields=name,sourceKey,reservedAttributes.uom&fieldHeaders=Name,SourceID,Units' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/tags/download?q=name=Sample*&sortBy=name.asc&fields=name,sourceKey,reservedAttributes.uom&fieldHeaders=Name,SourceID,Units HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: www.predixapis.com
Request parameters
Parameter Description

q

This field is required. Refer to section Advanced Search Supported Query Params for supported params. The query string to use for searching Assets.

To search for Assets by a field, use a query such as q=description=ObjectDescription.

To search for Assets by a field within the "attributes" or "reservedAttributes" objects, use a query such as q=attributes.manufacturer.value=GE.

To search for Assets by a field on a resource which a Asset refers to, use a query such as q=type->name=AssetTypeName. You can search up to two levels deep. For example, q=parent->parent->sourceKey=grandparentSourceKey will return all Assets whose parent’s parent has the given sourceKey.

For fields which contain an array of values, a query such as q=attributes.modelNumbers.value=GT100 will match all Assets which have a modelNumbers attribute with an array that contains a value of 'GT100'.

Use '*' to specify a wildcard search. For example, a query such as q=name=*Temperature* will return all Assets with a name that contains the word 'Temperature'.

You can specify multiple filters in the query. Use the ':' and '|' characters to connect filters with 'AND' and 'OR' operators, respectively. The 'OR' operator takes precedence over the 'AND' operator. For example, q=name=Gas*|description=Gas*:attributes.modelNumbers.value=GT100|sourceKey=Gas* will return all Assets for which match both of the following conditions:

1. name or description starts with 'Gas'

2. modelNumbers attribute with an array that contains a value of 'GT100' or sourceKey of the Asset starts with 'Gas'.

q=_name=GE*:sourceKey=GEEngine717*|description=Gas*:attributes.modelNumbers.value=GT100|reservedAttributes.state.key=06 will return all Assets for which match following conditions:

1. name starts with 'GE'

2. sourceKey of the Asset starts with 'GEEngine717' or description of the Asset starts with 'Gas'

3. modelNumbers attribute with an array that contains a value of 'GT100' or state reservedAttributes key contains of '06'.

sortBy

Sort Tag instances ascending/descending based on sortBy param value

fields

Tag instance attributes to be included in csv file

fieldHeaders

Column headers to be included in csv file. This is an optional param, if it’s not provided field names will be returned as column headers.


Mapping Tags to a Site

Use this POST method to link tags to a specific site.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/tags' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb",
  "sourceKey" : "Tag1",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/sites/bb571726-c1a3-4610-99de-435ab7f74000"
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aec",
  "sourceKey" : "Tag2",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/sites/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ],
  "nextRelatedTag" : {
    "tagUri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb"
  }
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aed",
  "sourceKey" : "Tag3",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/sites/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ]
} ]'
Example HTTP request
POST /v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/tags HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 889

[ {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb",
  "sourceKey" : "Tag1",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/sites/bb571726-c1a3-4610-99de-435ab7f74000"
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aec",
  "sourceKey" : "Tag2",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/sites/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ],
  "nextRelatedTag" : {
    "tagUri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb"
  }
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aed",
  "sourceKey" : "Tag3",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/sites/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ]
} ]
Request Structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification

Path Params
Table 33. /v1/sites/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Site. Must be unique per Site and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK

Deleting / Disassociating Tags from a Site

Use the DELETE method to remove the tag-site mapping. Removing the mapping will make the tags orphaned until you link them back.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?uris=/tags/bb571726-c1a3-4610-99de-435ab7f74000' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/sites/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?uris=/tags/bb571726-c1a3-4610-99de-435ab7f74000 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 34. /v1/sites/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Site. Must be unique per Site and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

uris

URIs of tags to delete

Example response
HTTP/1.1 200 OK

Segment


Reserved Attributes
Example 13. Reserved Attributes config for Segment

Below json provides the possible reserved attributes and corresponding metadata.

{
  "state": {
    "name": "state",
    "displayName": "State",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Plan"
      },
      {
        "key": "02",
        "value": "Design"
      },
      {
        "key": "03",
        "value": "Procure"
      },
      {
        "key": "04",
        "value": "Build"
      },
      {
        "key": "05",
        "value": "Commission"
      },
      {
        "key": "06",
        "value": "Operate"
      },
      {
        "key": "07",
        "value": "Maintain"
      },
      {
        "key": "08",
        "value": "Monitor"
      },
      {
        "key": "09",
        "value": "Upgrade"
      },
      {
        "key": "10",
        "value": "Decommission"
      },
      {
        "key": "11",
        "value": "Replace"
      },
      {
        "key": "12",
        "value": "Dispose"
      }
    ],
    "defaultValue": {
      "key": "06",
      "value": "Operate"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  },
  "status": {
    "name": "status",
    "displayName": "Status",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Failure"
      },
      {
        "key": "02",
        "value": "Warning"
      },
      {
        "key": "03",
        "value": "Normal"
      },
      {
        "key": "04",
        "value": "External Help Request"
      },
      {
        "key": "05",
        "value": "User-Defined Condition"
      }
    ],
    "defaultValue": {
      "key": "03",
      "value": "Normal"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  }
 }
Creating Segments

Use this POST method to create segments.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segments' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment",
  "description" : "Sample Segment",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/segmentTypes/bb571726-c1a3-4610-99de-435ab7f74000"
} ]'
Example HTTP Request
POST /v1/segments HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 223

[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment",
  "description" : "Sample Segment",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/segmentTypes/bb571726-c1a3-4610-99de-435ab7f74000"
} ]
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 502

[ {
  "objectId" : "aada30fa-3b65-3b21-925b-ee8526f9a553",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segments/aada30fa-3b65-3b21-925b-ee8526f9a553",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Segment",
  "description" : "Sample Segment",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/segmentTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Segments

[].uri

String

The uniform resource identifier (URI) of Segment

[].objectId

String

The object id of the Segment as represented in the source system.

[].tenantId

String

The tenant id of the Segment as represented in the source system.

[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

[].sourceKey

String

The unique identifier of the Segment as represented in the source system. Must be unique per Segment defined.

[].name

String

The name of the Segment.

[].label

String

Hierarchical name of the Segment.

[].description

String

The general description for the Segment

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Segments parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Segment for possible reserved attribute values for segment.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Segment

[].measurementTags

Array

Tags which monitor this Segment

[].measurementTags.[].objectId

String

The object id of the Segment as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Segment as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

[].segmentType

Object

Segment Type of Segment

[].site

Object

Parent of Segment

[].segment

Object

Parent of Segment


Getting All Segments

Use this GET method to get all segments.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segments?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segments?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 467

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segments/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Segment",
  "description" : "Sample Segment",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/segmentTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Segments

[].uri

String

The uniform resource identifier (URI) of Segment

[].objectId

String

The object id of the Segment as represented in the source system.

[].tenantId

String

The tenant id of the Segment as represented in the source system.

[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

[].sourceKey

String

The unique identifier of the Segment as represented in the source system. Must be unique per Segment defined.

[].name

String

The name of the Segment.

[].label

String

Hierarchical name of the Segment.

[].description

String

The general description for the Segment

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Segments parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Segment for possible reserved attribute values for segment.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Segment

[].measurementTags

Array

Tags which monitor this Segment

[].measurementTags.[].objectId

String

The object id of the Segment as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Segment as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

[].segmentType

Object

Segment Type of Segment

[].site

Object

Parent of Segment

[].segment

Object

Parent of Segment

Example 14. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Getting Segments by Criteria

Use this GET method to get segments matching a specific criterian or criteria passed as the request query parameter. Refer to Handle special characters section for more information.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segments?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segments?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Parameters
Parameter Description

sourceKey

The source key of the Segment to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Segments to be returned.

attributes

The attributes filter for the Segments. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to Segments to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the Segments returned.

type

The type filter to apply to Segments to be returned.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 514

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segments/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-segment",
  "name" : "DEMO ASSET segment",
  "description" : "This is the segment",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/segmentTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Segments

[].uri

String

The uniform resource identifier (URI) of Segment

[].objectId

String

The object id of the Segment as represented in the source system.

[].tenantId

String

The tenant id of the Segment as represented in the source system.

[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

[].sourceKey

String

The unique identifier of the Segment as represented in the source system. Must be unique per Segment defined.

[].name

String

The name of the Segment.

[].label

String

Hierarchical name of the Segment.

[].description

String

The general description for the Segment

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Segments parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Segment for possible reserved attribute values for segment.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Segment

[].measurementTags

Array

Tags which monitor this Segment

[].measurementTags.[].objectId

String

The object id of the Segment as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Segment as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

[].segmentType

Object

Segment Type of Segment

[].site

Object

Parent of Segment

[].segment

Object

Parent of Segment


Getting the Segment by URI

Use this GET method to a specific segment by the resource URI. You would pass the URI using the path parameter. See the usage example requests below

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segments/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segments/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 35. /v1/segments/{uuid}
Parameter Description

uuid

The unique identifier for the Segment. Must be unique per Segment and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 570

{
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segments/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-segment",
  "name" : "DEMO ASSET segment",
  "description" : "This is the segment",
  "label" : "name_entInstance_SourceKey1570068996024",
  "attributes" : { },
  "reservedAttributes" : { },
  "parent" : "/sites/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "type" : "/segmentTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of Segment

objectId

String

The object id of the Segment as represented in the source system.

tenantId

String

The tenant id of the Segment as represented in the source system.

rootTypeName

String

The CCOM type of the Segment as represented in the source system.

sourceKey

String

The unique identifier of the Segment as represented in the source system. Must be unique per Segment defined.

name

String

The name of the Segment.

label

String

Hierarchical name of the Segment.

description

String

The general description for the Segment

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the Segments parent

reservedAttributes

Object

Please refer Reserved Attributes config for Segment for possible reserved attribute values for segment.

location

Object

Please refer Location Json Structure

type

String

Type uri of Segment

measurementTags

Array

Tags which monitor this Segment

measurementTags.[].objectId

String

The object id of the Segment as represented in the source system.

measurementTags.[].tenantId

String

The tenant id of the Segment as represented in the source system.

measurementTags.[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

segmentType

Object

Segment Type of Segment

site

Object

Parent of Segment

segment

Object

Parent of Segment


Getting All Child Nodes Linked to a Segment

Use this GET method to get all children nodes (segments or assets) that are directly linked to a specific segment. You must pass the site UUID in the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/children?name=*Turbine*&components=BASIC&childPrefix=&deepSearch=&childPrefix=&deepSearch=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/children?name=*Turbine*&components=BASIC&childPrefix=&deepSearch=&childPrefix=&deepSearch= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request Structure
Table 36. /v1/segments/{uuid}/children
Parameter Description

uuid

The unique identifier for the Segment. Must be unique per Segment and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Parameters
Parameter Description

name

The name filter to apply to Segments to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

childPrefix

Single type of children.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 392

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segments/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Segment",
  "description" : "Sample Segment",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/segmentTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae"
} ]
Response Structure
Path Type Description

[]

Array

A list of Segments

[].uri

String

The uniform resource identifier (URI) of Segment

[].objectId

String

The object id of the Segment as represented in the source system.

[].tenantId

String

The tenant id of the Segment as represented in the source system.

[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

[].sourceKey

String

The unique identifier of the Segment as represented in the source system. Must be unique per Segment defined.

[].name

String

The name of the Segment.

[].label

String

Hierarchical name of the Segment.

[].description

String

The general description for the Segment

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Segments parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Segment for possible reserved attribute values for segment.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Segment


Getting the Parent of a Segment

Use this GET method to get the parent node (segment or site) directly linked to the specific segment. You must pass the site UUID in the path parameter.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/segments/006924e8-7a16-49cc-a142-1a7dab36f615/parent?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/segments/006924e8-7a16-49cc-a142-1a7dab36f615/parent?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 37. /v1/segments/{uuid}/parent
Parameter Description

uuid

The unique identifier for the Segment. Must be unique per Segment and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 448

{
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SiteType",
  "uri" : "/sites/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-site",
  "name" : "DEMO ASSET site",
  "description" : "This is the site",
  "label" : "DEMO ASSET site",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/siteTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae"
}
Response Structure
Path Type Description

uri

String

The uniform resource identifier (URI) of Site

objectId

String

The object id of the Site as represented in the source system.

tenantId

String

The tenant id of the Site as represented in the source system.

rootTypeName

String

The CCOM type of the Site as represented in the source system.

sourceKey

String

The unique identifier of the Site as represented in the source system. Must be unique per Site defined.

name

String

The name of the Site.

label

String

Hierarchical name of the Site.

description

String

The general description for the Site

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the Sites parent

reservedAttributes

Object

Please refer Reserved Attributes config for Site for possible reserved attribute values for site.

location

Object

Please refer Location Json Structure

type

String

Type uri of Site

measurementTags

Array

Tags which monitor this Site

measurementTags.[].objectId

String

The object id of the Site as represented in the source system.

measurementTags.[].tenantId

String

The tenant id of the Site as represented in the source system.

measurementTags.[].rootTypeName

String

The CCOM type of the Site as represented in the source system.

siteType

Object

Site Type of Site

enterprise

Object

Parent of Site


Updating the Segment

Use the PATCH method to update the details of a specific segment.

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/segments/004066e0-d480-4908-b82d-15af1e4122ab' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
}, {
  "op" : "replace",
  "path" : "/reservedAttributes/status",
  "value" : "02"
} ]'
Example HTTP request
PATCH /v1/segments/004066e0-d480-4908-b82d-15af1e4122ab HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 283

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "New Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "remove",
  "path" : "/attributes/Manufacturer"
}, {
  "op" : "replace",
  "path" : "/reservedAttributes/status",
  "value" : "02"
} ]
Request structure
Table 38. /v1/segments/{uuid}
Parameter Description

uuid

The unique identifier for the Segment. Must be unique per Segment and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 204 No Content

Getting Tags for a Segment

Use this GET method to get all tags that are directly linked to a specific segment. You must pass the site UUID in the path parameter.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression&tagUri=&includeCorrelatedTags&sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression=&tagUri=&includeCorrelatedTags=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression&tagUri=&includeCorrelatedTags&sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression=&tagUri=&includeCorrelatedTags= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 39. /v1/segments/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Segment. Must be unique per Segment and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

sourceKey

The source key of the Segment to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Segments to be returned.

alias

Alias filter to apply to Segments to be returned.

description

The description filter to apply to Segments to be returned.

pageSize

Page size to apply to the Segments returned.

deepSearch

Search within the scope of all descendant nodes.

expression

Expression

tagUri

The tag uri filter to apply to the Segment to be returned

includeCorrelatedTags

If this is set to true, the Tag will be returned with all of the Tags in its correlation.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 511

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tags/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "Tag1",
  "name" : "Tag_1",
  "description" : "This is Tag_1",
  "attributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000",
  "monitoredEntitySourceKey" : "SampleSegment"
} ]
If deepSearch flag is 'true' then it will return specified pageSize tags without nextPageLink (HTTP status ok). e.g. If Enterprise 'GE power' has 100 sites (each site has 1 tag), 100 segments (each segment has 1 tag) and 100 assets (each asset has 2 tag) then tags of 'GE power' API (with pageSize 250) returns first matching 250 tags without nextPageLink (Http status ok).
Response structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification


Download Tags for a Segment

Use this GET method to download all tags for a Segment instance in a CSV file.

Example cURL Request
$ curl 'https://www.predixapis.com/v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/tags/download?q=name=Sample*&sortBy=name.asc&fields=name,sourceKey,reservedAttributes.uom&fieldHeaders=Name,SourceID,Units' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/tags/download?q=name=Sample*&sortBy=name.asc&fields=name,sourceKey,reservedAttributes.uom&fieldHeaders=Name,SourceID,Units HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: www.predixapis.com
Request parameters
Parameter Description

q

This field is required. Refer to section Advanced Search Supported Query Params for supported params. The query string to use for searching Assets.

To search for Assets by a field, use a query such as q=description=ObjectDescription.

To search for Assets by a field within the "attributes" or "reservedAttributes" objects, use a query such as q=attributes.manufacturer.value=GE.

To search for Assets by a field on a resource which a Asset refers to, use a query such as q=type->name=AssetTypeName. You can search up to two levels deep. For example, q=parent->parent->sourceKey=grandparentSourceKey will return all Assets whose parent’s parent has the given sourceKey.

For fields which contain an array of values, a query such as q=attributes.modelNumbers.value=GT100 will match all Assets which have a modelNumbers attribute with an array that contains a value of 'GT100'.

Use '*' to specify a wildcard search. For example, a query such as q=name=*Temperature* will return all Assets with a name that contains the word 'Temperature'.

You can specify multiple filters in the query. Use the ':' and '|' characters to connect filters with 'AND' and 'OR' operators, respectively. The 'OR' operator takes precedence over the 'AND' operator. For example, q=name=Gas*|description=Gas*:attributes.modelNumbers.value=GT100|sourceKey=Gas* will return all Assets for which match both of the following conditions:

1. name or description starts with 'Gas'

2. modelNumbers attribute with an array that contains a value of 'GT100' or sourceKey of the Asset starts with 'Gas'.

q=_name=GE*:sourceKey=GEEngine717*|description=Gas*:attributes.modelNumbers.value=GT100|reservedAttributes.state.key=06 will return all Assets for which match following conditions:

1. name starts with 'GE'

2. sourceKey of the Asset starts with 'GEEngine717' or description of the Asset starts with 'Gas'

3. modelNumbers attribute with an array that contains a value of 'GT100' or state reservedAttributes key contains of '06'.

sortBy

Sort Tag instances ascending/descending based on sortBy param value

fields

Tag instance attributes to be included in csv file

fieldHeaders

Column headers to be included in csv file. This is an optional param, if it’s not provided field names will be returned as column headers.


Mapping Tags to a Segment

Use the POST method to link tags to a specific segment.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/tags' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb",
  "sourceKey" : "Tag1",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000"
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aec",
  "sourceKey" : "Tag2",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ],
  "nextRelatedTag" : {
    "tagUri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb"
  }
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aed",
  "sourceKey" : "Tag3",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ]
} ]'
Example HTTP request
POST /v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/tags HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 898

[ {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb",
  "sourceKey" : "Tag1",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000"
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aec",
  "sourceKey" : "Tag2",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ],
  "nextRelatedTag" : {
    "tagUri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb"
  }
}, {
  "uri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aed",
  "sourceKey" : "Tag3",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ]
} ]
Request Structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification

Path Params
Table 40. /v1/segments/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Segment. Must be unique per Segment and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK

Deleting / Disassociating Tags from a Segment

Use the DELETE method to remove the tag-segment mapping. Removing the mapping will make the tags orphaned until you link them back.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?uris=/tags/bb571726-c1a3-4610-99de-435ab7f74000' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/segments/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?uris=/tags/bb571726-c1a3-4610-99de-435ab7f74000 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 41. /v1/segments/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Segment. Must be unique per Segment and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

uris

URIs of tags to delete

Example response
HTTP/1.1 200 OK

Asset


Reserved Attributes
Example 15. Reserved Attributes config for Asset

Below json provides the possible reserved attributes and corresponding metadata. This meta data includes metadata of asset classification reserved attributes.

{
  "state": {
    "name": "state",
    "displayName": "State",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Plan"
      },
      {
        "key": "02",
        "value": "Design"
      },
      {
        "key": "03",
        "value": "Procure"
      },
      {
        "key": "04",
        "value": "Build"
      },
      {
        "key": "05",
        "value": "Commission"
      },
      {
        "key": "06",
        "value": "Operate"
      },
      {
        "key": "07",
        "value": "Maintain"
      },
      {
        "key": "08",
        "value": "Monitor"
      },
      {
        "key": "09",
        "value": "Upgrade"
      },
      {
        "key": "10",
        "value": "Decommission"
      },
      {
        "key": "11",
        "value": "Replace"
      },
      {
        "key": "12",
        "value": "Dispose"
      }
    ],
    "defaultValue": {
      "key": "06",
      "value": "Operate"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  },
  "status": {
    "name": "status",
    "displayName": "Status",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Failure"
      },
      {
        "key": "02",
        "value": "Warning"
      },
      {
        "key": "03",
        "value": "Normal"
      },
      {
        "key": "04",
        "value": "External Help Request"
      },
      {
        "key": "05",
        "value": "User-Defined Condition"
      }
    ],
    "defaultValue": {
      "key": "03",
      "value": "Normal"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  },
  "familyType": {
    "name": "familyType",
    "displayName": "Family Type",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "equipmentType": {
    "name": "equipmentType",
    "displayName": "Equipment Type",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "make": {
    "name": "make",
    "displayName": "Make",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "model": {
    "name": "model",
    "displayName": "Model",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "series": {
    "name": "series",
    "displayName": "Series",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "serialNumber": {
    "name": "serialNumber",
    "displayName": "Serial Number",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "maintenanceCriticalityRiskScore": {
    "name": "maintenanceCriticalityRiskScore",
    "displayName": "Maintenance Criticality Risk Score",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "faultMode": {
    "name": "faultMode",
    "displayName": "Fault Mode",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "ONE_DIMENSIONAL",
    "instanceApplicability": {
      "arrayType": "ONE_DIMENSIONAL",
      "overwrite": true
    }
  }
}

Creating Assets

Use this POST method to create assets.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assets' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Asset",
  "description" : "Sample Asset",
  "attributes" : {
    "State" : {
      "type" : "String",
      "value" : [ "California" ]
    }
  },
  "reservedAttributes" : { },
  "type" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "location" : { }
} ]'
Example HTTP Request
POST /v1/assets HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 319

[ {
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Asset",
  "description" : "Sample Asset",
  "attributes" : {
    "State" : {
      "type" : "String",
      "value" : [ "California" ]
    }
  },
  "reservedAttributes" : { },
  "type" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "location" : { }
} ]
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 437

[ {
  "objectId" : "d1667ee4-95ba-3178-ae66-8c24228e2ba3",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assets/d1667ee4-95ba-3178-ae66-8c24228e2ba3",
  "sourceKey" : "SampleSourceKey",
  "name" : "Sample Asset",
  "description" : "Sample Asset",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/assetTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Assets

[].uri

String

The uniform resource identifier (URI) of Asset

[].objectId

String

The object id of the Asset as represented in the source system.

[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].sourceKey

String

The unique identifier of the Asset as represented in the source system. Must be unique per Asset defined.

[].name

String

The name of the Asset.

[].label

String

Hierarchical name of the Asset.

[].description

String

The general description for the Asset

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Assets parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Asset for possible reserved attribute values for asset.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Asset

[].measurementTags

Array

Tags which monitor this Asset

[].measurementTags.[].objectId

String

The object id of the Asset as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].assetType

Object

Classification or Type to which the Asset belongs.

[].site

Object

Parent of the Asset

[].segment

Object

Parent of the Asset

[].asset

Object

Parent of the Asset

[].location

Object

Location of the Asset

[].reservedAttributes

Object

Reserved attributes associated to Asset or inherited from classification


Getting All Assets

Use this GET method to get all assets.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assets?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/assets?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 402

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assets/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Asset",
  "description" : "Sample Asset",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/assetTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response Structure
Path Type Description

[]

Array

A list of Assets

[].uri

String

The uniform resource identifier (URI) of Asset

[].objectId

String

The object id of the Asset as represented in the source system.

[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].sourceKey

String

The unique identifier of the Asset as represented in the source system. Must be unique per Asset defined.

[].name

String

The name of the Asset.

[].label

String

Hierarchical name of the Asset.

[].description

String

The general description for the Asset

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Assets parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Asset for possible reserved attribute values for asset.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Asset

[].measurementTags

Array

Tags which monitor this Asset

[].measurementTags.[].objectId

String

The object id of the Asset as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].assetType

Object

Classification or Type to which the Asset belongs.

[].site

Object

Parent of the Asset

[].segment

Object

Parent of the Asset

[].asset

Object

Parent of the Asset

[].location

Object

Location of the Asset

[].reservedAttributes

Object

Reserved attributes associated to Asset or inherited from classification

Example 16. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Getting Assets by Criteria

This GET method is used to get assets matching a specific criterian or criteria passed as the request query parameter. Refer to Handle special characters section for more information.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assets?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assets?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request parameters
Parameter Description

sourceKey

The source key of the Asset to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Assets to be returned.

attributes

The attributes filter for the Assets. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to Assets to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the Assets returned.

type

The type filter to apply to Assets to be returned.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 447

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assets/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-asset",
  "name" : "DEMO ASSET asset",
  "description" : "This is the asset",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/assetTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of Assets

[].uri

String

The uniform resource identifier (URI) of Asset

[].objectId

String

The object id of the Asset as represented in the source system.

[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].sourceKey

String

The unique identifier of the Asset as represented in the source system. Must be unique per Asset defined.

[].name

String

The name of the Asset.

[].label

String

Hierarchical name of the Asset.

[].description

String

The general description for the Asset

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Assets parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Asset for possible reserved attribute values for asset.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Asset

[].measurementTags

Array

Tags which monitor this Asset

[].measurementTags.[].objectId

String

The object id of the Asset as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].assetType

Object

Classification or Type to which the Asset belongs.

[].site

Object

Parent of the Asset

[].segment

Object

Parent of the Asset

[].asset

Object

Parent of the Asset

[].location

Object

Location of the Asset

[].reservedAttributes

Object

Reserved attributes associated to Asset or inherited from classification


Getting the Asset by URI

Use this GET method to a specific asset by the resource URI. You would pass the URI using the path parameter. See the usage example requests below

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/assets/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/assets/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 42. /v1/assets/{uuid}
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 601

{
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assets/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-asset",
  "name" : "DEMO ASSET asset",
  "description" : "This is the asset",
  "label" : "DEMO ASSET ENTERPRISE > DEMO ASSET site > DEMO ASSET segment > DEMO ASSET asset",
  "attributes" : { },
  "reservedAttributes" : { },
  "parent" : "/segments/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "type" : "/assetTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
}
Response structure
Path Type Description

uri

String

The uniform resource identifier (URI) of Asset

objectId

String

The object id of the Asset as represented in the source system.

tenantId

String

The tenant id of the Asset as represented in the source system.

rootTypeName

String

The CCOM type of the Asset as represented in the source system.

sourceKey

String

The unique identifier of the Asset as represented in the source system. Must be unique per Asset defined.

name

String

The name of the Asset.

label

String

Hierarchical name of the Asset.

description

String

The general description for the Asset

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the Assets parent

reservedAttributes

Object

Please refer Reserved Attributes config for Asset for possible reserved attribute values for asset.

location

Object

Please refer Location Json Structure

type

String

Type uri of Asset

measurementTags

Array

Tags which monitor this Asset

measurementTags.[].objectId

String

The object id of the Asset as represented in the source system.

measurementTags.[].tenantId

String

The tenant id of the Asset as represented in the source system.

measurementTags.[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

assetType

Object

Classification or Type to which the Asset belongs.

site

Object

Parent of the Asset

segment

Object

Parent of the Asset

asset

Object

Parent of the Asset

location

Object

Location of the Asset

reservedAttributes

Object

Reserved attributes associated to Asset or inherited from classification


Getting All Child Nodes Linked to an Asset

Use this GET method to get all children nodes (other assets) that are directed linked to a specific asset. You must pass the site UUID in the path parameter.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/children?name=*Turbine*&components=BASIC&deepSearch=&deepSearch=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/children?name=*Turbine*&components=BASIC&deepSearch=&deepSearch= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request structure
Table 43. /v1/assets/{uuid}/children
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Parameter
Parameter Description

name

The name filter to apply to Assets to be returned.

components

Refer to section Components for more information.

deepSearch

Search within the scope of all descendant nodes.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 402

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assets/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Asset",
  "description" : "Sample Asset",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/assetTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of Assets

[].uri

String

The uniform resource identifier (URI) of Asset

[].objectId

String

The object id of the Asset as represented in the source system.

[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].sourceKey

String

The unique identifier of the Asset as represented in the source system. Must be unique per Asset defined.

[].name

String

The name of the Asset.

[].label

String

Hierarchical name of the Asset.

[].description

String

The general description for the Asset

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Assets parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Asset for possible reserved attribute values for asset.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Asset


Getting the Parent of an Asset

Use this GET method to get the parent node (segment, site, or asset) directly linked to the specific asset. You must pass the site UUID in the path parameter.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assets/006924e8-7a16-49cc-a142-1a7dab36f615/parent?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assets/006924e8-7a16-49cc-a142-1a7dab36f615/parent?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 44. /v1/assets/{uuid}/parent
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 469

{
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "SegmentType",
  "uri" : "/segments/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-segment",
  "name" : "DEMO ASSET segment",
  "description" : "This is the segment",
  "label" : "DEMO ASSET segment",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/segmentTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae"
}
Response structure
Path Type Description

uri

String

The uniform resource identifier (URI) of Segment

objectId

String

The object id of the Segment as represented in the source system.

tenantId

String

The tenant id of the Segment as represented in the source system.

rootTypeName

String

The CCOM type of the Segment as represented in the source system.

sourceKey

String

The unique identifier of the Segment as represented in the source system. Must be unique per Segment defined.

name

String

The name of the Segment.

label

String

Hierarchical name of the Segment.

description

String

The general description for the Segment

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the Segments parent

reservedAttributes

Object

Please refer Reserved Attributes config for Segment for possible reserved attribute values for segment.

location

Object

Please refer Location Json Structure

type

String

Type uri of Segment

measurementTags

Array

Tags which monitor this Segment

measurementTags.[].objectId

String

The object id of the Segment as represented in the source system.

measurementTags.[].tenantId

String

The tenant id of the Segment as represented in the source system.

measurementTags.[].rootTypeName

String

The CCOM type of the Segment as represented in the source system.

segmentType

Object

Segment Type of Segment

site

Object

Parent of Segment

segment

Object

Parent of Segment


Advanced Asset search

Use this GET method to get assets by advanced search criteria. Any field in the response structure can be used in the query string. Fields in the response structure for the "type" and "parent" objects can also be used in the query string. Search strings can include wildcard characters to perform starts with, ends with, contains, and similar searches.

Example cURL request
$ curl 'https://www.predixapis.com/v1/assets/query?components=&pageSize=&q=name=Sample*' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json'
Example HTTP request
GET /v1/assets/query?components=&pageSize=&q=name=Sample* HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Request Params
Parameter Description

components

Refer to section Components for more information.

pageSize

Page size to apply to the Assets returned.

q

This field is required. Refer to section Advanced Search Supported Query Params for supported params. The query string to use for searching Assets.

To search for Assets by a field, use a query such as q=description=ObjectDescription.

To search for Assets by a field within the "attributes" or "reservedAttributes" objects, use a query such as q=attributes.manufacturer.value=GE.

To search for Assets by a field on a resource which a Asset refers to, use a query such as q=type->name=AssetTypeName. You can search up to two levels deep. For example, q=parent->parent->sourceKey=grandparentSourceKey will return all Assets whose parent’s parent has the given sourceKey.

For fields which contain an array of values, a query such as q=attributes.modelNumbers.value=GT100 will match all Assets which have a modelNumbers attribute with an array that contains a value of 'GT100'.

Use '*' to specify a wildcard search. For example, a query such as q=name=*Temperature* will return all Assets with a name that contains the word 'Temperature'.

You can specify multiple filters in the query. Use the ':' and '|' characters to connect filters with 'AND' and 'OR' operators, respectively. The 'OR' operator takes precedence over the 'AND' operator. For example, q=name=Gas*|description=Gas*:attributes.modelNumbers.value=GT100|sourceKey=Gas* will return all Assets for which match both of the following conditions:

1. name or description starts with 'Gas'

2. modelNumbers attribute with an array that contains a value of 'GT100' or sourceKey of the Asset starts with 'Gas'.

q=_name=GE*:sourceKey=GEEngine717*|description=Gas*:attributes.modelNumbers.value=GT100|reservedAttributes.state.key=06 will return all Assets for which match following conditions:

1. name starts with 'GE'

2. sourceKey of the Asset starts with 'GEEngine717' or description of the Asset starts with 'Gas'

3. modelNumbers attribute with an array that contains a value of 'GT100' or state reservedAttributes key contains of '06'.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 402

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "AssetType",
  "uri" : "/assets/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "name" : "Sample Asset",
  "description" : "Sample Asset",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/assetTypes/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "location" : { }
} ]
Response structure
Path Type Description

[]

Array

A list of Assets

[].uri

String

The uniform resource identifier (URI) of Asset

[].objectId

String

The object id of the Asset as represented in the source system.

[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].sourceKey

String

The unique identifier of the Asset as represented in the source system. Must be unique per Asset defined.

[].name

String

The name of the Asset.

[].label

String

Hierarchical name of the Asset.

[].description

String

The general description for the Asset

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Assets parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Asset for possible reserved attribute values for asset.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Asset

[].measurementTags

Array

Tags which monitor this Asset

[].measurementTags.[].objectId

String

The object id of the Asset as represented in the source system.

[].measurementTags.[].tenantId

String

The tenant id of the Asset as represented in the source system.

[].measurementTags.[].rootTypeName

String

The CCOM type of the Asset as represented in the source system.

[].assetType

Object

Classification or Type to which the Asset belongs.

[].site

Object

Parent of the Asset

[].segment

Object

Parent of the Asset

[].asset

Object

Parent of the Asset

[].location

Object

Location of the Asset

[].reservedAttributes

Object

Reserved attributes associated to Asset or inherited from classification


Updating the Asset

Use the PATCH method to update the details of a specific asset.

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assets/004066e0-d480-4908-b82d-15af1e4122ab' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "Test Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "add",
  "path" : "/location/geoPoints",
  "value" : [ ]
}, {
  "op" : "add",
  "path" : "/location/timezone",
  "value" : "Pacific/Samoa"
} ]'
Example HTTP request
PATCH /v1/assets/004066e0-d480-4908-b82d-15af1e4122ab HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 292

[ {
  "op" : "replace",
  "path" : "/name",
  "value" : "Test Name"
}, {
  "op" : "add",
  "path" : "/attributes/City",
  "value" : { }
}, {
  "op" : "add",
  "path" : "/location/geoPoints",
  "value" : [ ]
}, {
  "op" : "add",
  "path" : "/location/timezone",
  "value" : "Pacific/Samoa"
} ]
Request structure
Table 45. /v1/assets/{uuid}
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 204 No Content
Asset Decommissioning/Commissioning

Decommissioning/commissioning is a life-cycle event for an asset. In the asset model, reserved attribute: 'state' contains all of the life-cycle states. A reserved attribute 'state' with a value of '10' means 'Decommissioned'; any other value is considered as 'Commissioned'. Existing 'commissioned' asset can be 'decommissioned' by changing the 'state' reserved attribute, using a PATCH operation.

[
    {
        "op" : "replace",
        "path" : "/reservedAttributes/state/key",
        "value" : "10"
    }
]

OR

[
    {
        "op" : "replace",
        "path" : "/reservedAttributes/state",
        "value" : {
            "key" : "10"
        }
    }
]
When a user decommissions/commissions an asset using a PATCH operation, the payload should not contain any other operation except state change. This is a change in behavior.

Getting Tags for an Asset

Use this GET method to get all tags that are directly linked to a specific aasset. You must pass the site UUID in the path parameter.

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression&tagUri=&includeCorrelatedTags&sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression=&tagUri=&includeCorrelatedTags=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression&tagUri=&includeCorrelatedTags&sourceKey=&name=&alias=&description=&pageSize=&deepSearch=&expression=&tagUri=&includeCorrelatedTags= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 46. /v1/assets/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

sourceKey

The source key of the Asset to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Assets to be returned.

alias

Alias filter to apply to Assets to be returned.

description

The description filter to apply to Assets to be returned.

pageSize

Page size to apply to the Assets returned.

deepSearch

Search within the scope of all descendant nodes.

expression

Expression

tagUri

The tag uri filter to apply to the Asset to be returned

includeCorrelatedTags

If this is set to true, the Tag will be returned with all of the Tags in its correlation.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1155

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tags/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "Tag1",
  "name" : "Tag_1123",
  "description" : "This is Tag_1",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000",
  "monitoredEntitySourceKey" : "SampleAsset",
  "tagCorrelationUri" : "/tagcorrelations/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagCorrelations" : [ {
    "uri" : "/tags/bb571726-c1a3-4610-99de-435ab7f74001",
    "sourceKey" : "Tag2",
    "name" : "Tag_2",
    "description" : "This is Tag_2",
    "attributes" : { },
    "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74001",
    "tagType" : "SENSOR",
    "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000",
    "monitoredEntitySourceKey" : "SampleAsset",
    "aliases" : [ "AliasX", "AliasY" ],
    "tagCorrelationUri" : "/tagcorrelations/bb571726-c1a3-4610-99de-435ab7f74000"
  } ]
} ]
Response structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification


Download Tags for an Asset

Use this GET method to download all tags for an Asset instance in a CSV file.

Example cURL Request
$ curl 'https://www.predixapis.com/v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/tags/download?q=name=Sample*&sortBy=name.asc&fields=name,sourceKey,reservedAttributes.uom&fieldHeaders=Name,SourceID,Units' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/tags/download?q=name=Sample*&sortBy=name.asc&fields=name,sourceKey,reservedAttributes.uom&fieldHeaders=Name,SourceID,Units HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: www.predixapis.com
Request parameters
Parameter Description

q

This field is required. Refer to section Advanced Search Supported Query Params for supported params. The query string to use for searching Assets.

To search for Assets by a field, use a query such as q=description=ObjectDescription.

To search for Assets by a field within the "attributes" or "reservedAttributes" objects, use a query such as q=attributes.manufacturer.value=GE.

To search for Assets by a field on a resource which a Asset refers to, use a query such as q=type->name=AssetTypeName. You can search up to two levels deep. For example, q=parent->parent->sourceKey=grandparentSourceKey will return all Assets whose parent’s parent has the given sourceKey.

For fields which contain an array of values, a query such as q=attributes.modelNumbers.value=GT100 will match all Assets which have a modelNumbers attribute with an array that contains a value of 'GT100'.

Use '*' to specify a wildcard search. For example, a query such as q=name=*Temperature* will return all Assets with a name that contains the word 'Temperature'.

You can specify multiple filters in the query. Use the ':' and '|' characters to connect filters with 'AND' and 'OR' operators, respectively. The 'OR' operator takes precedence over the 'AND' operator. For example, q=name=Gas*|description=Gas*:attributes.modelNumbers.value=GT100|sourceKey=Gas* will return all Assets for which match both of the following conditions:

1. name or description starts with 'Gas'

2. modelNumbers attribute with an array that contains a value of 'GT100' or sourceKey of the Asset starts with 'Gas'.

q=_name=GE*:sourceKey=GEEngine717*|description=Gas*:attributes.modelNumbers.value=GT100|reservedAttributes.state.key=06 will return all Assets for which match following conditions:

1. name starts with 'GE'

2. sourceKey of the Asset starts with 'GEEngine717' or description of the Asset starts with 'Gas'

3. modelNumbers attribute with an array that contains a value of 'GT100' or state reservedAttributes key contains of '06'.

sortBy

Sort Tag instances ascending/descending based on sortBy param value

fields

Tag instance attributes to be included in csv file

fieldHeaders

Column headers to be included in csv file. This is an optional param, if it’s not provided field names will be returned as column headers.


Associating Tags to an Asset

A POST request is used to associate tags to an asset

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/tags' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "sourceKey" : "Tag1",
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000"
}, {
  "sourceKey" : "Tag2",
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ],
  "nextRelatedTag" : {
    "tagUri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb"
  }
}, {
  "sourceKey" : "Tag3",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ]
} ]'
Example HTTP request
POST /v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/tags HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 784

[ {
  "sourceKey" : "Tag1",
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000"
}, {
  "sourceKey" : "Tag2",
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ],
  "nextRelatedTag" : {
    "tagUri" : "/tags/0008acd7-983d-4b72-a600-1990fdda4aeb"
  }
}, {
  "sourceKey" : "Tag3",
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000",
  "aliases" : [ "AliasX", "AliasY" ]
} ]
Request Structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification

Path Params
Table 47. /v1/assets/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK

Deleting / Disassociating Tags from an Asset

Use the DELETE method to remove the tag-asset mapping. Removing the mapping will make the tags orphaned until you link them back.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?uris=/tags/bb571726-c1a3-4610-99de-435ab7f74000' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/assets/0008acd7-983d-4b72-a600-1990fdda4aeb/tags?uris=/tags/bb571726-c1a3-4610-99de-435ab7f74000 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 48. /v1/assets/{uuid}/tags
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

uris

URIs of tags to delete

Example response
HTTP/1.1 200 OK

Deleting Asset

Use the DELETE method to delete a specific asset by UUID.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assets/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/assets/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 49. /v1/assets/{uuid}
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Response structure
HTTP/1.1 200 OK

Tag

Reserved Attributes
Example 17. Reserved Attributes config for Tags

Below json provides the possible reserved attributes and corresponding metadata. The possible values for the attribute 'uom' will be dynamically populated with tenant specific unit of measurements.

{
  "status": {
    "name": "status",
    "displayName": "Status",
    "type": "KeyValue",
    "possibleValues": [
      {
        "key": "01",
        "value": "Unknown"
      },
      {
        "key": "02",
        "value": "Active"
      },
      {
        "key": "03",
        "value": "Inactive"
      }
    ],
    "defaultValue": {
      "key": "01",
      "value": "Unknown"
    },
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA"
  },
  "timeseriesLink": {
    "name": "timeseriesLink",
    "displayName": "Timeseries Link",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA"
  },
  "shiOutlierLimitsLow": {
    "name": "shiOutlierLimitsLow",
    "displayName": "Sensor Health Index Outlier Limits Low",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA"
  },
  "shiOutlierLimitsHigh": {
    "name": "shiOutlierLimitsHigh",
    "displayName": "Sensor Health Index Outlier Limits High",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA"
  },
  "sensorHealthIndex": {
    "name": "sensorHealthIndex",
    "displayName": "Sensor Health Index",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA"
  },
  "sensorHealthStatus": {
    "name": "sensorHealthStatus",
    "displayName": "Sensor Health Status",
    "type": "Boolean",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA"
  },
  "standardUom": {
    "name": "standardUom",
    "displayName": "Standard Unit Of Measure",
    "type": "UnitOfMeasure",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA"
  },
   "standardUomGroup": {
    "name": "standardUomGroup",
    "displayName": "Standard Unit Of Measure Group",
    "type": "UnitOfMeasureGroup",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA"
  },
  "paintBrushingTestWeight": {
    "name": "paintBrushingTestWeight",
    "displayName": "Paint Brushing Test Weight",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA"
  },
  "timeseriesDataSource": {
    "name": "timeseriesDataSource",
    "displayName": "Timeseries Data Source Identifier",
    "type": "String",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true
  },
  "uom": {
    "name": "uom",
    "displayName": "Source Unit Of Measure",
    "type": "UnitOfMeasure",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": false
    }
  },
  "uomGroup": {
    "name": "uomGroup",
    "displayName": "Source Unit Of Measure Group",
    "type": "UnitOfMeasureGroup",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": false
    }
  },
  "dataType": {
    "name": "dataType",
    "displayName": "Data Type",
    "type": "String",
    "possibleValues": [
      "Double",
      "Float",
      "String"
    ],
    "defaultValue": "String",
    "tenant": null,
    "overwrite": false,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": false
    }
  },
  "resolution": {
    "name": "resolution",
    "displayName": "Resolution",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "shiLowThreshold": {
    "name": "shiLowThreshold",
    "displayName": "Sensor Health Index Low Threshold",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "shiHighThreshold": {
    "name": "shiHighThreshold",
    "displayName": "Sensor Health Index High Threshold",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 1,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "shiFlatLineNumber": {
    "name": "shiFlatLineNumber",
    "displayName": "Sensor Health Index Flat Line Number",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": 720,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "shiFlatLineEpsilon": {
    "name": "shiFlatLineEpsilon",
    "displayName": "Sensor Health Index Flat Line Epsilon",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "badObservationPersistent": {
    "name": "badObservationPersistent",
    "displayName": "Bad Observation Persistent / Penalty Window",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": 2880,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "falseAlarmProbability": {
    "name": "falseAlarmProbability",
    "displayName": "False Alarm Probability",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0.001,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "missedAlarmProbability": {
    "name": "missedAlarmProbability",
    "displayName": "Missed Alarm Probability",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0.001,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "sampleFailureMagnitudesMean": {
    "name": "sampleFailureMagnitudesMean",
    "displayName": "Sample Failure Magnitudes Mean",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": 10,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "sampleFailureMagnitudesVariance": {
    "name": "sampleFailureMagnitudesVariance",
    "displayName": "Sample Failure Magnitudes Variance",
    "type": "Integer",
    "possibleValues": [],
    "defaultValue": 40,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "nullHypothesisVariance": {
    "name": "nullHypothesisVariance",
    "displayName": "Null Hypothesis Variance",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 0.0025,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "nanTestWeight": {
    "name": "nanTestWeight",
    "displayName": "NaN Test Weight",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 1,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "outlierTestWeight": {
    "name": "outlierTestWeight",
    "displayName": "Outlier Test Weight",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 1,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "flatTestWeight": {
    "name": "flatTestWeight",
    "displayName": "Flat Test Weight",
    "type": "Double",
    "possibleValues": [],
    "defaultValue": 1,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "category": {
    "name": "category",
    "displayName": "Category",
    "type": "String",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "arrayType": "NA",
    "instanceApplicability": {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "maxOperatingValue": {
    "name": "maxOperatingValue",
    "displayName": "Maximum Operating Value",
    "type": "Double",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "instanceApplicability" : {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "minOperatingValue": {
    "name": "minOperatingValue",
    "displayName": "Minimum Operating Value",
    "type": "Double",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "instanceApplicability" : {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "highestThresholdValue": {
    "name": "highestThresholdValue",
    "displayName": "Highest Threshold Value",
    "type": "Double",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "instanceApplicability" : {
      "arrayType": "NA",
      "overwrite": true
    }
  },
  "lowestThresholdValue": {
    "name": "lowestThresholdValue",
    "displayName": "Lowest Threshold Value",
    "type": "Double",
    "valueRegex": "NA",
    "arrayType" : "NA",
    "possibleValues": [],
    "defaultValue": null,
    "tenant": null,
    "overwrite": true,
    "instanceApplicability" : {
      "arrayType": "NA",
      "overwrite": true
    }
  }
}

Sample Values

            "status": {
                "key": "02"
            },
            "category": null,
            "dataType": "String",
            "resolution": null,
            "isRestricted": false,
            "nanTestWeight": 1.0,
            "flatTestWeight": 1.0,
            "shiLowThreshold": 0.0,
            "shiHighThreshold": 1.0,
            "maxOperatingValue": null,
            "minOperatingValue": null,
            "outlierTestWeight": 1.0,
            "sensorHealthIndex": null,
            "shiFlatLineNumber": 720,
            "sensorHealthStatus": null,
            "shiFlatLineEpsilon": 1.0E-8,
            "shiOutlierLimitsLow": null,
            "lowestThresholdValue": null,
            "shiOutlierLimitsHigh": null,
            "timeseriesDataSource": null,
            "falseAlarmProbability": 0.001,
            "highestThresholdValue": null,
            "missedAlarmProbability": 0.001,
            "nullHypothesisVariance": 0.0025,
            "paintBrushingTestWeight": null,
            "badObservationPersistent": 2880,
            "sampleFailureMagnitudesMean": 10,
            "sampleFailureMagnitudesVariance": 40,
            "uom": null,
            "uomGroup": null,
            "standardUom": null,
            "standardUomGroup": null,
            "timeseriesLink": "test@#"

Get Tags by Criteria

Use this GET request to get tag details either by comma-separated tag source keys or by group source key. One of the parameters are required. The response contains a list of tag objects for which the user has access to. Refer to Handle special characters section for more information.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/tags?sourceKeys=TEST&groupSourceKey=&groupSourceKey=' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/tags?sourceKeys=TEST&groupSourceKey=&groupSourceKey= HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request parameters
Parameter Description

sourceKeys

Comma separated tag source keys..eg: TAG1,TAG2

groupSourceKey

Group source key

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 530

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tags/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SampleSourceKey",
  "name" : "Tag_1",
  "description" : "This is Tag_1",
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000",
  "monitoredEntitySourceKey" : "SampleSegment"
} ]
Response structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification

Advanced Tag search

Use this GET method to get tags by advanced search criteria. Any field in the response structure can be used in the query string. Fields in the response structure for the "type", "monitoredEntity", and "nextRelatedTag" objects can also be used in the query string. Search strings can include wildcard characters to perform starts with, ends with, contains, and similar searches.

Example cURL request
$ curl 'https://www.predixapis.com/v1/tags/query?components=&pageSize=&q=name=Sample*' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json'
Example HTTP request
GET /v1/tags/query?components=&pageSize=&q=name=Sample* HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Request Params
Parameter Description

components

Refer to section Components for more information.

pageSize

Page size to apply to the Tags returned.

q

This field is required. Refer to section Advanced Search Supported Query Params for supported params. The query string to use for searching Tags.

To search for Tags by a field, use a query such as q=description=ObjectDescription.

To search for Tags by a field within the "attributes" or "reservedAttributes" objects, use a query such as q=attributes.manufacturer.value=GE.

To search for Tags by a field on a resource which a Tag refers to, use a query such as q=type->name=TagTypeName. You can search up to two levels deep. For example, q=parent->parent->sourceKey=grandparentSourceKey will return all Tags whose parent’s parent has the given sourceKey.

For fields which contain an array of values, a query such as q=attributes.modelNumbers.value=GT100 will match all Tags which have a modelNumbers attribute with an array that contains a value of 'GT100'.

Use '*' to specify a wildcard search. For example, a query such as q=name=*Temperature* will return all Tags with a name that contains the word 'Temperature'.

You can specify multiple filters in the query. Use the ':' and '|' characters to connect filters with 'AND' and 'OR' operators, respectively. The 'OR' operator takes precedence over the 'AND' operator. For example, q=name=Gas*|description=Gas*:attributes.modelNumbers.value=GT100|sourceKey=Gas* will return all Tags for which match both of the following conditions:

1. name or description starts with 'Gas'

2. modelNumbers attribute with an array that contains a value of 'GT100' or sourceKey of the Tag starts with 'Gas'.

q=_name=GE*:sourceKey=GEEngine717*|description=Gas*:attributes.modelNumbers.value=GT100|reservedAttributes.state.key=06 will return all Tags for which match following conditions:

1. name starts with 'GE'

2. sourceKey of the Tag starts with 'GEEngine717' or description of the Tag starts with 'Gas'

3. modelNumbers attribute with an array that contains a value of 'GT100' or state reservedAttributes key contains of '06'.

sortBy

Sort Tag instances ascending/descending based on sortBy param value. Sorting will only be supported for Tag instances of single asset.

monitoredEntityUri is mandatory if 'sortBy' param present. monitoredEntitySourceKey/monitoredEntityName/wildcard('\*') in monitoredEntityUri are not supported with 'sortBy' param

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 530

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tags/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "SampleSourceKey",
  "name" : "Tag_1",
  "description" : "This is Tag_1",
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/segments/bb571726-c1a3-4610-99de-435ab7f74000",
  "monitoredEntitySourceKey" : "SampleSegment"
} ]
Response structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification


Cascade Deletion

The cascade delete APIs permanently deletes all the objects and their associations with other objects. Data cannot be recovered after this operation.

Cascade deleting Asset object

Use the DELETE method to recursive delete a specific asset object (enterprise | site | segment| asset) by UUID.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetobjects/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae?recursive=true&deletionReason=APIDocTest' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/assetobjects/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae?recursive=true&deletionReason=APIDocTest HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 50. /v1/assetobjects/{uuid}
Parameter Description

uuid

The unique identifier for the Asset. Must be unique per Asset and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Request Params
Parameter Description

recursive

Flag to indicate if the deletion is for one object or all objects undeneath the asset object.

If false, only the asset object identified by UUID is deleted.

If true, all the objects under asset object by UUID, including the passed object are removed.

deletionReason

This field is required, if recursive is true.

Reason for deletion of structure underneath the asset object identified by UUID.

Response structure
HTTP/1.1 200 OK

Asset Groups


Getting All Groups

A GET request is used to get all groups

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetGroups?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assetGroups?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 321

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "uri" : "/assetGroups/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "TagGroup",
  "name" : "Sample group getAll 1",
  "description" : "Sample group",
  "attributes" : { },
  "category" : "TAG"
} ]
Response structure
Path Type Description

[]

Array

A list of Groups

[].uri

String

The uniform resource identifier (URI) of Group

[].objectId

String

The object id of the Group as represented in the source system.

[].tenantId

String

The tenant id of the Group as represented in the source system.

[].rootTypeName

String

The CCOM type of the Group as represented in the source system.

[].sourceKey

String

The unique identifier of the Group as represented in the source system. Must be unique per Group defined.

[].name

String

The name of the Group.

[].label

String

Hierarchical name of the Group.

[].description

String

The general description for the Group

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Groups parent

[].location

Object

Please refer Location Json Structure

[].category

String

Group Category Group

Example 18. Json Structure for Attributes

Define attributes in key-value pairs. Each key is of type String and 'value' is an object with variables type, and value(array of values). You cannot define the attribute key with special character such as !@#$%^&*?().

"attributes": {
      "Latitude": {  (1)
        "type": "String", (2)
        "value": [
          "37.7749° N" (3)
        ]
      },
      "Longitude": { (1)
        "type": "String", (2)
        "value": [
          "122.4194° W" (3)
        ]
      },
      "Contacts": { (1)
        "type": "String", (2)
        "value": [
          "925-123-4444", "925-123-5555" (3)
        ]
      },
      "Code": { (1)
        "type": "Character", (2)
        "value": [
          "B" (3)
        ]
      },
      "Frequency": { (1)
        "type": "Integer", (2)
        "value": [
          44100 (3)
        ]
      },
      "No. of Assets": { (1)
        "type": "Short", (2)
        "value": [
          2500 (3)
        ]
      },
      "Mean Temperature": { (1)
        "type": "Double", (2)
        "value": [
          71.4 (3)
        ]
      },
      "Temperature range": { (1)
        "type": "Float", (2)
        "value": [
          60.0, 80.0 (3)
        ]
      },
      "Is_active": { (1)
        "type": "Boolean", (2)
        "value": [
          true (3)
        ]
      },
      "Date created": { (1)
        "type": "Timestamp", (2)
        "value": [
          "12/31/2015 11:30:22" (3)
        ]
      },
      "Health Zone": { (1)
        "type": "Grid", (2)
        "value": [ (3)
          {
            "Name": "Very Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": -1,
            "Value From": 85,
            "Value To": 100,
            "Color": "0064cd",
            "Severity": 0
          },
          {
            "Name": "Good",
            "Description": "-",
            "Recommended Actions": "DEFAULT",
            "Alert Level": 0,
            "Value From": 70,
            "Value To": 84,
            "Color": "ffffff",
            "Severity": 0
          },
          {
            "Name": "Fair",
            "Description": "-",
            "Recommended Actions": "A1",
            "Alert Level": 1,
            "Value From": 50,
            "Value To": 69,
            "Color": "cccccc",
            "Severity": 1
          }
         ],
         "metaInfo": [ (4)
           {
              "id": "Name",
              "type": "string"
           },
           {
              "id": "Description",
              "type": "string"
           },
           {
              "id": "Recommended Actions",
              "type": "string"
           },
           {
              "id": "Alert Level",
              "type": "integer"
           },
           {
              "id": "Value From",
              "type": "integer"
           },
           {
              "id": "Value To",
              "type": "integer"
           },
           {
              "id": "Color",
              "type": "string"
           },
           {
               "id": "Severity",
               "type": "integer"
           }
         ]
      }
    }
1 The attribute keys.
2 The data type of the values. The nine supported types are shown above.
3 The array of values for the defined type. Values are validated against the type.
4 Attribute key - metaInfo defines type of each column of the Grid. This attribute is added to support validation of column values (json objects) of the Grid.

Getting Groups by criteria

A GET request is used to get groups

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetGroups?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assetGroups?sourceKey=source-key&components=BASIC&name=SampleValue&description=SampleValue&pageSize=1&attributes=%7B%7D&type=SampleValue HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Request parameters
Parameter Description

sourceKey

The source key of the Group to be returned. NOTE: If you filter by sourceKey all other criteria will be ignored.

name

The name filter to apply to Groups to be returned.

attributes

The attributes filter for the Groups. Filter on multiple attributes by using a colon ':' as an AND separator, such as 'key1=value1:key2=value2'. 'OR' operation is not supported

description

The description filter to apply to Groups to be returned.

components

Refer to section Components for more information.

pageSize

Page size to apply to the Groups returned.

type

The type filter to apply to Groups to be returned.

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 340

[ {
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "uri" : "/assetGroups/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-GROUP",
  "name" : "ASSET GROUP GET BY Criteria",
  "description" : "This is the group",
  "attributes" : { },
  "category" : "TAG"
} ]
Response structure
Path Type Description

[]

Array

A list of Groups

[].uri

String

The uniform resource identifier (URI) of Group

[].objectId

String

The object id of the Group as represented in the source system.

[].tenantId

String

The tenant id of the Group as represented in the source system.

[].rootTypeName

String

The CCOM type of the Group as represented in the source system.

[].sourceKey

String

The unique identifier of the Group as represented in the source system. Must be unique per Group defined.

[].name

String

The name of the Group.

[].label

String

Hierarchical name of the Group.

[].description

String

The general description for the Group

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Groups parent

[].location

Object

Please refer Location Json Structure

[].category

String

Group Category Group


Get Group by Uri

A GET request is used to get group by uri

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ab?components=%7B%7D HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Params
Table 51. /v1/assetGroups/{uuid}
Parameter Description

uuid

The unique identifier for the Group. Must be unique per Group and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 331

{
  "objectId" : "fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "uri" : "/assetGroups/fdc601b9-c745-43ab-a7c8-a7f6be31f6ae",
  "sourceKey" : "DEMO-ASSET-GROUP",
  "name" : "ASSET GROUP GET BY URI",
  "description" : "This is the group",
  "attributes" : { },
  "category" : "TAG"
}
Response structure
Path Type Description

uri

String

The uniform resource identifier (URI) of Group

objectId

String

The object id of the Group as represented in the source system.

tenantId

String

The tenant id of the Group as represented in the source system.

rootTypeName

String

The CCOM type of the Group as represented in the source system.

sourceKey

String

The unique identifier of the Group as represented in the source system. Must be unique per Group defined.

name

String

The name of the Group.

label

String

Hierarchical name of the Group.

description

String

The general description for the Group

attributes

Object

Please refer Json Structure for Attributes

parent

String

The unique identifier of the Groups parent

location

Object

Please refer Location Json Structure

category

String

Group Category Group


Create Group

A POST request is used to create group.

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetGroups' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "uri" : "",
  "sourceKey" : "TagGroupType2_instance1",
  "name" : "TagGroupType2_instance1",
  "description" : "TagGroupType2_instance1",
  "category" : "TAG"
} ]'
Example HTTP request
POST /v1/assetGroups HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 168

[ {
  "uri" : "",
  "sourceKey" : "TagGroupType2_instance1",
  "name" : "TagGroupType2_instance1",
  "description" : "TagGroupType2_instance1",
  "category" : "TAG"
} ]
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 349

[ {
  "objectId" : "85e79b32-8fe6-3dc6-8f03-c234b6415dd2",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "uri" : "/assetGroups/85e79b32-8fe6-3dc6-8f03-c234b6415dd2",
  "sourceKey" : "TagGroupType2_instance1",
  "name" : "TagGroupType2_instance1",
  "description" : "TagGroupType2_instance1",
  "attributes" : { },
  "category" : "TAG"
} ]
Response structure
Path Type Description

[]

Array

A list of Groups

[].uri

String

The uniform resource identifier (URI) of Group

[].objectId

String

The object id of the Group as represented in the source system.

[].tenantId

String

The tenant id of the Group as represented in the source system.

[].rootTypeName

String

The CCOM type of the Group as represented in the source system.

[].sourceKey

String

The unique identifier of the Group as represented in the source system. Must be unique per Group defined.

[].name

String

The name of the Group.

[].label

String

Hierarchical name of the Group.

[].description

String

The general description for the Group

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Groups parent

[].location

Object

Please refer Location Json Structure

[].category

String

Group Category Group


Get Group members

A GET request is used to get Group members

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ab/members' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
GET /v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ab/members HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path Parameters
Table 52. /v1/assetGroups/{uuid}/members
Parameter Description

uuid

The unique identifier for the Group. Must be unique per Group and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 540

[ {
  "objectId" : "bb571726-c1a3-4610-99de-435ab7f74000",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "rootTypeName" : "TagType",
  "uri" : "/tags/bb571726-c1a3-4610-99de-435ab7f74000",
  "sourceKey" : "TEST",
  "name" : "Tag_1123",
  "description" : "This is Tag_1",
  "attributes" : { },
  "reservedAttributes" : { },
  "type" : "/tagTypes/bb571726-c1a3-4610-99de-435ab7f74000",
  "tagType" : "SENSOR",
  "monitoredEntityUri" : "/assets/bb571726-c1a3-4610-99de-435ab7f74000",
  "monitoredEntitySourceKey" : "SampleAsset"
} ]
Response structure
Path Type Description

[]

Array

A list of Tags

[].uri

String

The uniform resource identifier (URI) of Tag

[].objectId

String

The object id of the Tag as represented in the source system.

[].tenantId

String

The tenant id of the Tag as represented in the source system.

[].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].name

String

The name of the Tag.

[].label

String

Hierarchical name of the Tag.

[].description

String

The general description for the Tag

[].attributes

Object

Please refer Json Structure for Attributes

[].parent

String

The unique identifier of the Tags parent

[].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagCorrelations[0].tagType

String

The tag type of this Tag

[].tagCorrelations[0].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].tagCorrelations[0].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].tagCorrelations[0].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations[0].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].tagCorrelations[0].type

String

Type uri of Tag

[]

Array

A list of Tags

[].tagCorrelations[0].uri

String

The uniform resource identifier (URI) of Tag

[].tagCorrelations[0].objectId

String

The object id of the Tag as represented in the source system.

[].tagCorrelations[0].tenantId

String

The tenant id of the Tag as represented in the source system.

[].tagCorrelations[0].rootTypeName

String

The CCOM type of the Tag as represented in the source system.

[].tagCorrelations[0].sourceKey

String

The unique identifier of the Tag as represented in the source system. Must be unique per Tag defined.

[].tagCorrelations[0].name

String

The name of the Tag.

[].tagCorrelations[0].label

String

Hierarchical name of the Tag.

[].tagCorrelations[0].description

String

The general description for the Tag

[].tagCorrelations[0].attributes

Object

Please refer Json Structure for Attributes

[].tagCorrelations[0].parent

String

The unique identifier of the Tags parent

[].tagCorrelations[0].reservedAttributes

Object

Please refer Reserved Attributes config for Tags for possible reserved attribute values for tag.

[].tagCorrelations[0].location

Object

Please refer Location Json Structure

[].type

String

Type uri of Tag

[].tagType

String

The tag type of this Tag

[].monitoredEntityUri

String

The URI of the entity linked to this Tag

[].monitoredEntitySourceKey

String

The source key id of the entity linked to this Tag. If this Tag is link

[].aliases

Array

Possible alias names for this Tag as a string array.

[].tagCorrelations

Array

Possible tag correlations for this Tag as a string array. A tag correlation is a different but closely associated tag. For example, an output tag from a device can correlate to an input tag on a second device which consumes data from that output tag.

[].monitoredEntityName

String

The name of the entity linked to this Tag.

[].monitoredEntityAlias

String

The alias name of the entity linked to this Tag

[].tagCorrelationUri

String

Identifier to get the tag correlation information of this tag

[].nextRelatedTag

Object

An object representing the tag which this tag correlates to. Provide a tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].nextRelatedTag.tagUri

String

tagUri to correlate this tag to another tag, or set nextRelatedTag.tagUri as null to remove a correlation. A tag can only correlate to a tag which monitors the same Tag.

[].reservedAttributes

Object

Reserved attributes associated to Tag or inherited from classification


Associate Members to Group

A POST request is used to associate members to group

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ab/members' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ "Tag_1" ]'
Example HTTP request
POST /v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ab/members HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 11

[ "Tag_1" ]
Payload consists of sourceKeys of objects corresponding to the group category.
Example response
HTTP/1.1 200 OK

Disassociate Members from Group

A DELETE request is used to disassociate members from group

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ba/members' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ "TEST" ]'
Example HTTP request
DELETE /v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ba/members HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 10

[ "TEST" ]
Payload consists of sourceKeys of objects corresponding to the group category.
Example response
HTTP/1.1 200 OK

Update Group

A PATCH request is used to update group

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ab' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "add",
  "path" : "/name",
  "value" : "Test Name"
}, {
  "op" : "add",
  "path" : "/description",
  "value" : "Test Description"
} ]'
Example HTTP request
PATCH /v1/assetGroups/004066e0-d480-4908-b82d-15af1e4122ab HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 146

[ {
  "op" : "add",
  "path" : "/name",
  "value" : "Test Name"
}, {
  "op" : "add",
  "path" : "/description",
  "value" : "Test Description"
} ]
Request structure
Table 53. /v1/assetGroups/{uuid}
Parameter Description

uuid

The unique identifier for the Group. Must be unique per Group and can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-) and periods (.).

Example response
HTTP/1.1 204 No Content

Asset Group Association


Create Asset Group Associations

A POST request is used to create association between asset group and business functional hierarchy objects(enterprise, site, segment & asset).

This API will allow two way association;
  • associate single asset group to multiple business functional hierarchy objects

  • associate single business functional hierarchy object to multiple groups

Example CURL request
Associate single asset group to multiple business functional hierarchy objects
$ curl 'https://www.predixapis.com/v1/assetgroupassociations' -i -X POST -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '
{
  "assetUri": "/sites/df54d427-0a58-3d09-a8a7-300c4cdbe4e6",
  "assetGroups": {
    "sourceKeys": [
      "AssetGroups_20170713_100_101"
    ],
    "uris": [
      "/assetGroups/a367c355-f175-3571-b75a-c2c4da770ec7"
    ]
  }
}
'
Associate single business functional hierarchy object to multiple groups
$ curl 'https://www.predixapis.com/v1/assetgroupassociations' -i -X POST -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '
{
  "assetGroupUri": "/assetGroups/group1",
  "assets": {
    "sourceKeys": [
      {
        "type": "/sites",
        "sourceKeys": [
          "siteKey1",
          "siteKey2"
        ]
      },
      {
        "type": "/assets",
        "sourceKeys": [
          "assetKey1",
          "assetKey2"
        ]
      }
    ],
    "uris": [
      "/assets/1234",
      "/assets/abcd"
    ]
  }
}
'
Example HTTP request
Associate single asset group to multiple business functional hierarchy objects
POST /v1/assetgroupassociations HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Content-Length: 244

{
  "assetGroupUri": "/assetGroups/df54d427-0a58-3d09-a8a7-300c4cdbe4e6",
  "assets": {
    "sourceKeys": [
      {
        "type": "/sites",
        "sourceKeys": [
          "siteKey1",
          "siteKey2"
        ]
      },
      {
        "type": "/assets",
        "sourceKeys": [
          "assetKey1",
          "assetKey2"
        ]
      }
    ],
    "uris": [
      "/assets/df54d427-0a58-3d09-a8a7-300c4cdbe4e6",
      "/sites/df54d427-0a58-3d09-a8a7-300c4cdbe4e6"
    ]
  }
}
Associate single business functional hierarchy object to multiple groups
POST /v1/assetgroupassociations HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Content-Length: 244

{
  "assetUri": "/sites/df54d427-0a58-3d09-a8a7-300c4cdbe4e6",
  "assetGroups": {
    "sourceKeys": [
      "AssetGroups_20170713_100_101"
    ],
    "uris": [
      "/assetGroups/a367c355-f175-3571-b75a-c2c4da770ec7"
    ]
  }
}
Example response
Associate single asset group to multiple business functional hierarchy objects
HTTP/1.1 201 CREATED
Location: /v1/assetgroupassociations?assetgroupuri=/assetGroups/{uuid}
Associate single business functional hierarchy object to multiple groups
HTTP/1.1 201 CREATED
Location: /v1/assetgroupassociations?asseturi=/sites/{uuid}
Response structure
Table 54. Associate single asset group to multiple business functional hierarchy objects
Path Type Description

assetGroupUri

String

The uniform resource identifier (URI) of Asset Group

assets.sourceKeys.[].sourceKeys

String

List of source keys of enterprises, sites, segments & assets to which the asset group is getting associated.

assets.sourceKeys.[].type

String

As above field 'sourceKeys' doesn’t tell which type business functional hierarchy object it is, we need to specify whether sourceKey is of type enterprise, site, segment OR asset. Possible values for the field are: /enterprises, /sites, /segments, /assets

assets.uris

String

List of business functional hierarchy object uris.

If the pay load has values populated for fields 'assets.sourceKeys' & 'assets.uris', then we consolidate and unique business functional hierarchy objects will identified, and finally get associated to the asset group.
Table 55. Associate single business functional hierarchy object to multiple groups
Path Type Description

assetUri

String

The uniform resource identifier (URI) of business functional hierarchy object

assetGroups.sourceKeys

String

List of asset group source keys.

assetGroups.uris

String

List of asset group uris.

If the pay load has values populated for fields 'assetGroups.sourceKeys' & 'assetGroups.uris', then we consolidate and unique asset groups will identified, and finally get associated to the business functional hierarchy object.

Get Asset Group Associations

Asset group associations can be queried by either assetGroup URI or business functional hierarchy object(enterprise, site, segment & asset) URI.

Example CURL request
Get business functional hierarchy objects associated to an asset group
$ curl 'https://www.predixapis.com/v1/assetgroupassociations?assetgroupuri=/assetGroups/{uuid}' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json'
Get groups, filtered by category, that are associated to business functional hierarchy objects
$ curl 'https://www.predixapis.com/v1/assetgroupassociations?asseturi=/assets/{uuid}&category=' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json'
Example HTTP request
Get business functional hierarchy objects associated to an asset group
GET /v1/assetgroupassociations?assetgroupuri=/assetGroups/{uuid} HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Get groups, filtered by category, that are associated to business functional hierarchy objects
GET /v1/assetgroupassociations?asseturi=/assets/{uuid}&category= HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Example response
Get business functional hierarchy objects associated to an asset group
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "tenantId": "567bb641-78b5-4a18-b1b7-fde29788db38",
    "objectId": "bb571726-c1a3-4610-99de-435ab7f74000",
    "rootTypeName": "AssetType",
    "uri": "/assets/bb571726-c1a3-4610-99de-435ab7f74000",
    "sourceKey": "SAMPLE_ASSET",
    "name": "Sample Asset",
    "description": "Sample Asset",
    "attributes": {
      "City": {
        "value": [
          "San Ramon"
        ]
      }
    },
    "reservedAttributes": {}
  },
  {
    "tenantId": "567bb641-78b5-4a18-b1b7-fde29788db38",
    "objectId": "bb571726-c1a3-4610-99de-435ab7f74001",
    "rootTypeName": "SiteType",
    "uri": "/sites/bb571726-c1a3-4610-99de-435ab7f74001",
    "sourceKey": "SAMPLE_SITE",
    "name": "Sample Site",
    "description": "Sample Site",
    "attributes": {
      "City": {
        "value": [
          "San Ramon"
        ]
      }
    },
    "reservedAttributes": {}
  }
]
Get groups, filtered by category, that are associated to business functional hierarchy objects
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "tenantId": "567bb641-78b5-4a18-b1b7-fde29788db38",
    "objectId": "a367c355-f175-3571-b75a-c2c4da770ec7",

    "uri": "/assetGroups/a367c355-f175-3571-b75a-c2c4da770ec7",
    "sourceKey": "AssetGroups_20170713_100_101",
    "name": "AssetGroups_20170713_100_101",
    "description": "AssetGroups_20170713_100_101",
    "attributes": {},
    "category": "ASSET"
  },
  {
    "tenantId": "567bb641-78b5-4a18-b1b7-fde29788db38",
    "objectId": "a367c355-f175-3571-b75a-c2c4da770ec7",

    "uri": "/assetGroups/26aeca43-2111-3e9c-82c4-74388c924f68",
    "sourceKey": "AssetGroups_20170713_100_102",
    "name": "AssetGroups_20170713_100_102",
    "description": "AssetGroups_20170713_100_102",
    "attributes": {},
    "category": "ASSET"
  }
]
Request structure
Parameter Description

assetgroupuri

URI of asset group.

asseturi

URI of business functional hierarchy object.

category

Category of groups to retrieve. It is applicable only when 'asseturi' parameter is provided. It is an optional parameter, with possible values of ENTERPRISE, SITE, SEGMENT, ASSET, TAG.

'assetgroupuri' or combination of 'asseturi' & 'category' are applicable for this request; not both.
Response structure
Response is based on which query parameters are being passed. When 'assetgroupuri' is passed, it returns collection of business functional hierarchy objects(enterprises, sites, segments and/or assets). When 'asseturi' is passed, it returns all groups associated to to the given business functional hierarchy object uri('asseturi).

Delete Asset Group Associations

This API is used to remove associations of asset groups with business functional hierarchy objects(enterprise, site, segment & asset)

Example CURL request
$ curl 'https://www.predixapis.com/v1/assetgroupassociations?assetgroupuri=/assetGroups/f72aa434-e801-45a9-a997-6375a3e5a0d8&asseturi=/sites/f72aa434-e801-45a9-a997-6375a3e5a0d8' -i -X DELETE -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Accept: application/json' -H 'Content-Type: application/json'
Example HTTP request
DELETE /v1/assetgroupassociations?assetgroupuri=/assetGroups/f72aa434-e801-45a9-a997-6375a3e5a0d8&asseturi=/sites/f72aa434-e801-45a9-a997-6375a3e5a0d8 HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Host: www.predixapis.com
Example response
HTTP/1.1 200 OK
Request structure
Parameter Description

assetgroupuri

URI of asset group.

asseturi

URI of business functional hierarchy object.

Behavior of parameter combination:
  • When only 'assetgroupuri' is passed as paramter, then API will remove all business functional hierarchy object associations with this group.

  • When only 'asseturi' is passed as paramter, then API will remove all group associations with this asset.

  • When both parameters are passed, then API will remove association which matches these two uris.


ALM Tenant Configuration

This feature allows the user with appropriate permission to perform tenant level ALM application specific configurations using APIs. The changes made using APIs are applicable to the entire tenant.

Export Tenant Data

Export Tenant Classifications

The asset microservice provides a GET method to download tenant classifications. The data is retrieved from the persistent data store and the resultant json file is streamed into multiple ZIP files depending on the size of the data. A zip file can hold thousand classifications, which is a configurable value. The ZIP files are stored in the APM blobstore. Each export logs a task in the persistent store for tracking the export status. Once the export is completed, the blob url is provided to the user as part of the task response.

Tenant Classifications Export Process

The export process includes the following actions:

  1. Submitting the export request through the REST endpoint. Appropriate credentials are needed to request tenant classifications export. The customer administrator can provide the details.

  2. Checking the status of the export task using the UUID provided by the previous action.

Starting an Export Task

Use the GET method to export tenant classifications from the persistent store. After submitting the request, the export happens asynchronously, which means that your request is queued for the server to process it. An export task is created. You can check the export progress through HTTP GET to make sure if export was successful. Save the uuid from the JSON response for tracking purposes.

Example CURL Request
$ curl 'https://apm-asset-adapter-svc-domain/v1/asset/download' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>'  -H 'Accept: application/json'
Example HTTP Request
GET /v1/asset/download HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-adapter-svc-domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 293

{
    "tenantId": "567bb641-78b5-4a18-b1b7-fde29788db38",
    "objectId": "1fac1a66-1de0-41ed-a4ba-bc01351c65bd",
    "uuid": "1fac1a66-1de0-41ed-a4ba-bc01351c65bd",
    "description": "Download tenant classifications to zip file",
    "status": "IN PROGRESS...",
    "startTime": "11-02-2017 20:48:42.971"
}
Response Structure
Path Type Description

tenantId

String

The tenant id of the as represented in the source system.

objectId

String

The object id of the as represented in the source system.

uuid

String

The unique ID for the task. This value is needed to track the export progress.

description

String

A message that describes the scope of the task.

status

String

The status of export. It can be one of the following:

IN PROGRESS -The export of the classification from the asset store is currently in progress. The BLOB urls are available in the task response once the export completes.

COMPLETED- The export completed successfully.

ERROR - The export did not complete successfully. There has been an error exporting the file. You may try re-exporting the file.

startTime

String

The value represents the timezone at which the export task was logged for the first time.

Example ZIP file content - JSON file
{
  "classifications": [
    {
      "id": "Sample-ASSET-ENTERPRISE",
      "name": "Sample ASSET ENTERPRISE",
      "description": "This is the type of enterprise",
      "ccomClass": "ENTERPRISE_TYPE",
      "parent": null
    },
    {
      "id": "Sample-ASSET-SITE",
      "name": "Sample ASSET SITE",
      "description": "This is the type of site ",
      "ccomClass": "SITE_TYPE",
      "parent": null
    },
    {
      "name": "Sample ASSET SEGMENT TYPE",
      "id": "Sample-ASSET-SEGMENT-TYPE",
      "description": "This is the type 1 of segment",
      "ccomClass": "SEGMENT_TYPE",
      "parent": null
    },
    {
      "id": "Sample-ASSET-TYPE",
      "name": "Sample ASSET TYPE",
      "description": "This is the type 2 of asset",
      "ccomClass": "ASSET_TYPE",
      "parent": null,
      "reservedProperties": {
        "familyType": "",
        "equipmentType": "",
        "make": "GE",
        "model": "MODELX",
        "series": "GET",
        "serialNumber": null,
        "maintenanceCriticalityRiskScore": 7,
        "faultMode": ""
      }
    },
    {
      "id": "Sample-ASSET-TYPE-PART-01",
      "name": "Sample ASSET TYPE PART 01",
      "description": "This is the type 2 of asset(part01)",
      "ccomClass": "ASSET_TYPE",
      "reservedProperties": {
        "familyType": "",
        "equipmentType": "",
        "make": "GE",
        "model": "MODELX",
        "series": "GET",
        "serialNumber": null,
        "maintenanceCriticalityRiskScore": 7,
        "faultMode": ""
      }
    },
    {
      "id": "PN01",
      "name": "Sample ASSET TYPE PN01",
      "description": "This is the type 2 of asset(PN01)",
      "ccomClass": "ASSET_TYPE",
      "reservedProperties": {
        "familyType": "",
        "equipmentType": "",
        "make": "GE",
        "model": "MODELX",
        "series": "GET",
        "serialNumber": null,
        "maintenanceCriticalityRiskScore": 7,
        "faultMode": ""
      }
    },
    {
      "id": "PN02",
      "name": "Sample ASSET TYPE PN02",
      "description": "This is the type 2 of asset(PN02)",
      "ccomClass": "ASSET_TYPE",
      "reservedProperties": {
        "familyType": "",
        "equipmentType": "",
        "make": "GE",
        "model": "MODELX",
        "series": "GET",
        "serialNumber": null,
        "maintenanceCriticalityRiskScore": 7,
        "faultMode": ""
      }
    },
    {
      "id": "PN05",
      "name": "Sample ASSET TYPE PN05",
      "description": "This is the type 2 of asset(PN05)",
      "ccomClass": "ASSET_TYPE",
      "reservedProperties": {
        "familyType": "",
        "equipmentType": "",
        "make": "GE",
        "model": "MODELX",
        "series": "GET",
        "serialNumber": null,
        "maintenanceCriticalityRiskScore": 7,
        "faultMode": ""
      }
    },
    {
      "id": "PN06",
      "name": "Sample ASSET TYPE PN06",
      "description": "This is the type 2 of asset(PN06)",
      "ccomClass": "ASSET_TYPE",
      "reservedProperties": {
        "familyType": "",
        "equipmentType": "",
        "make": "GE",
        "model": "MODELX",
        "series": "GET",
        "serialNumber": null,
        "maintenanceCriticalityRiskScore": 7,
        "faultMode": ""
      }
    }
  ]
}
Checking Export Status

Use the GET method to find the status of the export task using the uuid received from the export action.

Example CURL Request for Tasks
$ curl 'https://apm-asset-adapter-svc-domain/v1/tasks/004066e0-d480-4908-b82d-15af1e4122ab' -i -H 'Authorization: <Authorization>' -H 'tenant: <tenant>' -H 'Content-Type: application/json' -H 'Accept: application/json'
Example HTTP Request for Tasks
GET /v1/tasks/004066e0-d480-4908-b82d-15af1e4122ab HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Content-Type: application/json
Accept: application/json
Host: apm-asset-adapter-svc-domain
Path Parameters for Tasks
Table 56. /v1/tasks/{uuid}
Parameter Description

uuid

The unique identifier for the Task

Example Response for Tasks
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 296

{
    "tenantId": "567bb641-78b5-4a18-b1b7-fde29788db38",
    "objectId": "a8b073ff-3fd7-42b2-8c57-244819e44dcf",
    "uuid": "a8b073ff-3fd7-42b2-8c57-244819e44dcf",
    "description": "Download tenant classifications to zip file",
    "status": "COMPLETED",
    "startTime": "11-02-2017 22:56:07.695",
    "endTime": "11-02-2017 22:56:29.796",
    "totalCount": 0,
    "completedCount": 0,
    "taskType": "Download",
    "taskResponse": {
        "responseUri": {
            "url1": "https://blob.example.com/v3/attachments/887e5ad8-dd2a-4b98-a90a-c5987db75133/download",
            "url2": "https://blob.example.com/v3/attachments/1cbe8dcf-53ac-4763-8bc5-ad22a73bca18/download",
            "url3": "https://blob.example.com/v3/attachments/b7eb58c1-ce77-46e7-9f3a-f13cf8339908/download",
            "url4": "https://blob.example.com/v3/attachments/33c37361-6465-4411-ba04-ff32ff5e0316/download",
            "url5": "https://blob.example.com/v3/attachments/518ac3fb-410d-4619-ac18-1ac973bbffed/download",
            "url6": "https://blob.example.com/v3/attachments/f70bcd31-99be-4b34-9692-33f5ebf4389f/download",
            "url7": "https://blob.example.com/v3/attachments/f84582c2-c601-4230-b239-de5250da8825/download",
            "url8": "https://blob.example.com/v3/attachments/ebb8c086-adeb-45c9-978a-c46b8ff9d03f/download"
        }
    }
}
Response Structure
Path Type Description

tenantId

String

The tenant id of the as represented in the source system.

objectId

String

The object id of the as represented in the source system.

description

String

A message that describes the scope of the task.

status

String

The status of export in the log. It can be one of the following:

IN PROGRESS -The export from the application asset store is currently in progress.

COMPLETED- The export completed successfully.

ERROR - The export did not complete successfully. There has been an error exporting the file.

uuid

String

The unique ID for the task. This value is needed to track the export progress.

startTime

String

The value represents the timezone at which the export task was logged for the first time.

endTime

String

The value represents the timezone at which the export task was last updated.

totalCount

Integer

This property is only applicable for Upload.

completedCount

Integer

This property is only applicable for Upload.

taskType

String

The type of the task being performed which is 'Download'

taskResponse

Object

A ordered key value Map, where key is the string "url" followed by ordered number starting from 1 and value being the BLOB url for the zip file. The order suggests the sequence of the JSON files(in Zip file) to be considered for the ingestion.


Supported Configurations

Reserved Attribute configuration contexts

The tenant specific reserved attribute configurations are:

  • asset-status

  • asset-state

  • tag-status

  • tag-state

  • enterprise-status

  • enterprise-state

  • site-status

  • site-state

  • segment-status

  • segment-state

In addition, user can enable or disable various ui flags.

Other ALM configurations

  • asset_status_ui_edit

  • asset_state_ui_edit

  • tag_status_ui_edit

  • enterprise_state_ui_edit

  • enterprise_status_ui_edit

  • site_state_ui_edit

  • site_status_ui_edit

  • segment_state_ui_edit

  • segment_status_ui_edit


Get Context Configuration

Use this GET method to get configuration values.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/contextConfig/asset-status' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/contextConfig/asset-status HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 57. /v1/contextConfig/{context}
Parameter Description

context

Supported Configurations

Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 207

[ {
  "context" : "asset-status",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "code" : "01",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "Failure",
  "description" : "RED"
} ]
Response structure
Path Type Description

[].context

String

Supported Configurations

[].tenantId

String

The tenant id of the {0} as represented in the source system.

[].code

String

ALM system internal code (001 to 100 is system reserved).

[].displayName

String

Display Name for the configurable reserved attribute value.

[].description

String

Description of the reserved attribute value.

[].isActive

Boolean

Flag to either display or hide the configurable reserved attribute value in the user interface.

[].isDefault

Boolean

Flag to configure reserved attribute value as default.

[].semanticName

String

ALM default name for the reserved attribute value. This is used when the displayName value is not provided.


Get All Configurations

Use this GET method to get all configurations.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/contextConfig' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/contextConfig HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 247

[ {
  "context" : "asset-status",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "code" : "1",
  "displayName" : "Actively Running",
  "isActive" : true,
  "isDefault" : true,
  "semanticName" : "Running",
  "description" : "Running"
} ]
Response structure
Path Type Description

[].context

String

Supported Configurations

[].tenantId

String

The tenant id of the {0} as represented in the source system.

[].code

String

ALM system internal code (001 to 100 is system reserved).

[].displayName

String

Display Name for the configurable reserved attribute value.

[].description

String

Description of the reserved attribute value.

[].isActive

Boolean

Flag to either display or hide the configurable reserved attribute value in the user interface.

[].isDefault

Boolean

Flag to configure reserved attribute value as default.

[].semanticName

String

ALM default name for the reserved attribute value. This is used when the displayName value is not provided.

[].value

String

Configurable string value for the context.


Get Configuration By Filter

Use this GET method to get context configuration based on filter criteria.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/contextConfig?context=asset-status&code=01&isActive=true&semanticName=Running&displayName=Active' -i \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP Request
GET /v1/contextConfig?context=asset-status&code=01&isActive=true&semanticName=Running&displayName=Active HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Example Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 238

[ {
  "context" : "asset-status",
  "tenantId" : "567bb641-78b5-4a18-b1b7-fde29788db38",
  "code" : "01",
  "displayName" : "Active",
  "isActive" : true,
  "isDefault" : true,
  "semanticName" : "Running",
  "description" : "Running"
} ]
Response structure
Path Type Description

[].context

String

Supported Configurations

[].tenantId

String

The tenant id of the {0} as represented in the source system.

[].code

String

ALM system internal code (001 to 100 is system reserved).

[].displayName

String

Display Name for the configurable reserved attribute value.

[].description

String

Description of the reserved attribute value.

[].isActive

Boolean

Flag to either display or hide the configurable reserved attribute value in the user interface.

[].isDefault

Boolean

Flag to configure reserved attribute value as default.

[].semanticName

String

ALM default name for the reserved attribute value. This is used when the displayName value is not provided.

Reserved Attribute Configuration


Create Multiple Context Configurations

Use this POST method to create tenant specific values for supported reserved attribute configuration.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/contextConfig' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "context" : "tag-status",
  "code" : "102",
  "displayName" : "Running ",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "Running",
  "description" : "Running Tag Status Description"
}, {
  "context" : "asset-status",
  "code" : "102",
  "displayName" : "Operating",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "Operating",
  "description" : "Operating Asset Status Description"
}, {
  "context" : "asset-state",
  "code" : "102",
  "displayName" : "Active",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "Active",
  "description" : "ActiveAsset State Description"
} ]'
Example HTTP Request
POST /v1/contextConfig HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 626

[ {
  "context" : "tag-status",
  "code" : "102",
  "displayName" : "Running ",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "Running",
  "description" : "Running Tag Status Description"
}, {
  "context" : "asset-status",
  "code" : "102",
  "displayName" : "Operating",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "Operating",
  "description" : "Operating Asset Status Description"
}, {
  "context" : "asset-state",
  "code" : "102",
  "displayName" : "Active",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "Active",
  "description" : "ActiveAsset State Description"
} ]
Request structure
Path Type Description

[].context

String

ALM Supported Reserved Attribute tenant context. Configure possible values for the specified tenant configuration.

[].code

String

ALM system internal code (001 to 100 is system reserved).

[].displayName

String

Display Name for the configurable reserved attribute value.

[].description

String

Description of the reserved attribute value.

[].isActive

Boolean

Flag to either display or hide the configurable reserved attribute value in the user interface.

[].isDefault

Boolean

Flag to configure reserved attribute value as default.

[].semanticName

String

ALM default name for the reserved attribute value. This is used when the displayName value is not provided.

Example Response
HTTP/1.1 200 OK

Create Context Configuration

Use this POST method to create tenant specific values for supported reserved attribute configuration.

Example cURL Request
$ curl 'https://apm-asset-svc-env.domain/v1/contextConfig/asset-status' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '{
  "code" : "101",
  "displayName" : "SampleStatus",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "SampleStatus",
  "description" : "Sample Status Description"
}'
Example HTTP Request
POST /v1/contextConfig/asset-status HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 180

{
  "code" : "101",
  "displayName" : "SampleStatus",
  "isActive" : true,
  "isDefault" : false,
  "semanticName" : "SampleStatus",
  "description" : "Sample Status Description"
}
Path
Table 58. /v1/contextConfig/{context}
Parameter Description

context

ALM Supported Reserved Attribute tenant context. Configure possible values for the specified tenant configuration.

Request structure
Path Type Description

code

String

ALM system internal code (001 to 100 is system reserved).

displayName

String

Display Name for the configurable reserved attribute value.

description

String

Description of the reserved attribute value.

isActive

Boolean

Flag to either display or hide the configurable reserved attribute value in the user interface.

isDefault

Boolean

Flag to configure reserved attribute value as default.

semanticName

String

ALM default name for the reserved attribute value. This is used when the displayName value is not provided.

Example Response
HTTP/1.1 200 OK

Update Context Configuration

Use the PATCH method to update the tenant specific value for supported reserved attribute configuration.

Example CURL request
$ curl 'https://apm-asset-svc-env.domain/v1/contextConfig/asset-status/1011' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json' \
    -d '[ {
  "op" : "replace",
  "path" : "/",
  "value" : { }
} ]'
Example HTTP request
PATCH /v1/contextConfig/asset-status/1011 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Content-Length: 59

[ {
  "op" : "replace",
  "path" : "/",
  "value" : { }
} ]
Path
Table 59. /v1/contextConfig/{context}/{code}
Parameter Description

context

ALM Supported Reserved Attribute tenant context. Configure possible values for the specified tenant configuration.

code

ALM system internal code (001 to 100 is system reserved)

Request structure
Path Type Description

[]

Array

A list of patch operations

[].op

String

The operation name for the patch operation

[].path

String

The '/' separated path for the property being updated.

[].value

Object

The new value of the property to update.

Example response
HTTP/1.1 200 OK

Delete Context Configuration

Use the DELETE method to delete reserved attribute tenant configuration value.

Example cURL request
$ curl 'https://apm-asset-svc-env.domain/v1/contextConfig/asset-status/1012' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <Authorization>' \
    -H 'tenant: <tenant>' \
    -H 'Accept: application/json'
Example HTTP request
DELETE /v1/contextConfig/asset-status/1012 HTTP/1.1
Content-Type: application/json
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Host: apm-asset-svc-env.domain
Path
Table 60. /v1/contextConfig/{context}/{code}
Parameter Description

code

ALM system internal code (001 to 100 is system reserved)

context

ALM Supported Reserved Attribute tenant context. Configure possible values for the specified tenant configuration.

Response structure
HTTP/1.1 204 No Content