APM Asset API Version v1 Guide

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,

Select the type Basic Auth.
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:

https://www.predix.io/docs/?r=332184#X9M7hYj6

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:

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.
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.
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.
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

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.

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

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.

[]

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.

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

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.

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

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.

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

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.

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.

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.

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

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>

Escape Special chars while Querying

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

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,256` or `pwr_turbine\00'1,257` /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,256` or `pwr_turbine\00'1,257` 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`

/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

Unresolved directive in enterpriseTypes/enterprise-types-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/enterprise-types-documentation/create-enterprise-types/curl-request.adoc[]

Example HTTP Request

Request Structure

Example Response

Response Structure

Retrieving All Enterprise Types

Use this GET method to retrieve all enterprise types.

Example cURL Request

Example HTTP Request

Example Response

Response 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

Example HTTP Request

Request Parameters

Example Response

Response 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

Example HTTP Request

Path Parameters

Example Response

Response 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

Example HTTP Request

Request Structure

Request Params

Example Response

Response Structure

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

Example HTTP request

Request Structure

Example Response

Response 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

Example HTTP Request

Request Structure

Example Response

Deleting Enterprise Type

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

Example cURL request

Example HTTP request

Path

Response structure

SiteTypes

Creating Site Types

Use this POST method to create site types.

Example cURL Request

Unresolved directive in siteTypes/site-types-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/site-types-documentation/create-site-types/curl-request.adoc[]

Example HTTP Request

Request Structure

Example Response

Response Structure

Retireving All Site Types

Use this GET method to retrieve all site types.

Example cURL Request

Example HTTP Request

Example Response

Response Structure

Example 3. Json Structure for Attributes

"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

Example HTTP Request

Request Parameters

Example Response

Response 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

Example HTTP Request

Path Parameters

Example Response

Response 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

Example HTTP Request

Request Structure

Request Parameters

Example Response

Response Structure

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

Example HTTP Request

Request Structure

Example Response

Updating Site Types

Use this PATCH request to update the site type.

Example cURL Request

Example HTTP Request

Request Structure

Example Response

Deleting Site Type

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

Example cURL request

Example HTTP request

Path

Response structure

SegmentTypes

Creating Segment Types

Use this POST method to create segment types.

Example cURL Request

Unresolved directive in segmentTypes/segment-types-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/segment-types-documentation/create-segment-types/curl-request.adoc[]

Example HTTP Request

Request Structure

Example Response

Response Structure

Retrieving All Segment Types

Use this GET method to retrieve all segment types.

Example cURL Request

Example HTTP Request

Example Response

Response Structure

Example 4. Json Structure for Attributes

"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

Example HTTP request

Request parameters

Example response

Response 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

Example HTTP Request

Path Parameters

Example Response

Response 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

Example HTTP Request

Request Structure

Request Params

Example Response

Response Structure

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

Example HTTP Request

Request Structure

Example Response

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

Example HTTP Request

Request Structure

Example Response

Deleting Segment Type

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

Example cURL request

Example HTTP request

Path

Response structure

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

Unresolved directive in assetTypes/asset-types-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/asset-types-documentation/create-asset-types/curl-request.adoc[]

Example HTTP Request

Request Structure

Example Response

Response Structure

Retrieving All Asset Types

Use this GET method to retrieve all asset types.

Example cURL request

Example HTTP request

Example response

Response structure

Example 6. Json Structure for Attributes

"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

Example HTTP Request

Request Parameters

Example Response

Response 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

Example HTTP Request

Path Parameters

Example Response

Response Structure

Retrieving All Inherited Asset Types

Use this GET request to retrieve child asset types.

Example cURL Request

Example HTTP Request

Request Structure

Request Parameters

Example Response

Response Structure

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

Example HTTP Request

Request Structure

Example Response

Response 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

Example response

Response 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

Example HTTP Request

Request Structure

Example Response

Deleting Asset Type

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

Example cURL request

Example HTTP request

Path

Response structure

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

Unresolved directive in tagTypes/tag-types-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/tag-types-documentation/create-tag-types/curl-request.adoc[]

Example HTTP Request

Request Structure

Example Response

Response Structure

Getting All Tag Types

Use this GET method to retrieve all tag types.

Example cURL Request

Example HTTP Request

Example Response

Response Structure

Example 8. Json Structure for Attributes

"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

Example HTTP Request

Request Parameters

Example Response

Response 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

Example HTTP Request

Path Parameters

Example Response

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

Example response

Response 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

Example HTTP Request

Request Structure

Example Response

Deleting Tag Type

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

Example cURL request

Example HTTP request

Path

Response structure

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:

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

Unresolved directive in enterprises/enterprises-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/enterprises-documentation/create-enterprises/curl-request.adoc[]

Example HTTP Request

Example Response

Response Structure

Retrieving All Enterprises

Use this GET method to retrieve all enterprises.

Example cURL Request

Example HTTP Request

Example Response

Response Structure

Example 10. Json Structure for Attributes

"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

Example HTTP Request

Request Parameters

Example Response

Response Structure

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

Example HTTP Request

Path Parameters

Example Response

Response Structure

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

Example HTTP Request

Request Structure

Request Parameters

Example Response

Response Structure

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

Example HTTP Request

Request Structure

Request Parameters

Example Response

Response Structure

Updating Enterprise Details

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

Example cURL Request

Example HTTP Request

Request Structure

Example Response

Retrieving Tags for an Enterprise

Use this GET method to retrieve tags for an Enterprise.

Example cURL request

Example HTTP request

Path Params

Request Params

Example response

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

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

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.

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

Example HTTP request

Request Structure

Path Params

Example response

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

Example HTTP request

Path Params

Request Params

Example response

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

Unresolved directive in sites/sites-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/sites-documentation/create-sites/curl-request.adoc[]

Example HTTP Request

Example Response

Response Structure

Getting All Sites

Use this GET request to get all sites.

Example cURL Request

Example HTTP Request

Example Response

Response Structure

Example 12. Json Structure for Attributes

"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

Example HTTP request

Request parameters

Example response

Response structure

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

Example HTTP request

Path Params

Example response

Response structure

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

Example HTTP request

Request structure

Request Parameters

Example response

Response structure

Updating Sites

Use this PATCH request to update a site.

Example cURL request

Example HTTP request

Request structure

Example response

Retrieving Tags for a Site

Use this GET method to retrieve tags for a site.

Example cURL request

Example HTTP request

Path Params

Request Params

Example response

Response structure

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

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.

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.

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'.

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

Example HTTP request

Request Structure

Path Params

Example response

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

Example HTTP request

Path Params

Request Params

Example response

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

Unresolved directive in segments/segments-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/segments-documentation/create-segments/curl-request.adoc[]

Example HTTP Request

Example Response

Response Structure

Getting All Segments

Use this GET method to get all segments.

Example cURL Request

Example HTTP Request

Example Response

Response Structure

Example 14. Json Structure for Attributes

"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

Example HTTP Request

Request Parameters

Example Response

Response Structure

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

Example HTTP Request

Path Parameters

Example Response

Response Structure

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

Example HTTP Request

Request Structure

Request Parameters

Example Response

Response Structure

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

Example HTTP Request

Path Parameters

Example Response

Response Structure

Updating the Segment

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

Example CURL request

Example HTTP request

Request structure

Example response

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

Example HTTP request

Path Params

Request Params

Example response

Response structure

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

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.

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.

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'.

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

Example HTTP request

Request Structure

Path Params

Example response

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

Example HTTP request

Path Params

Request Params

Example response

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

Unresolved directive in assets/assets-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/assets-documentation/create-assets/curl-request.adoc[]

Example HTTP Request

Example Response

Response Structure

Getting All Assets

Use this GET method to get all assets.

Example cURL Request

Example HTTP Request

Example Response

Response Structure

Example 16. Json Structure for Attributes

"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

Example HTTP request

Request parameters

Example response

Response structure

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

Example HTTP Request

Path Parameters

Example response

Response structure

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

Example HTTP request

Request structure

Request Parameter

Example response

Response structure

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

Example HTTP request

Path Params

Example response

Response structure

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

Example response

Response structure

Updating the Asset

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

Example CURL request

Example HTTP request

Request structure

Example response

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

Example HTTP request

Path Params

Request Params

Example response

Response structure

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

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.

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.

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'.

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

Example HTTP request

Request Structure

Path Params

Example response

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

Example HTTP request

Path Params

Request Params

Example response

Deleting Asset

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

Example cURL request

Example HTTP request

Path

Response structure

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

Unresolved directive in tags/tags-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/tags-documentation/get-by-criteria/curl-request.adoc[]

Example HTTP request

Request parameters

Example response

Response structure

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

Example response

Response structure

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

Unresolved directive in assetObjects/asset-objects-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/asset-objects-documentation/cascade-delete/curl-request.adoc[]

Example HTTP request

Path

Request Params

Response structure

Asset Groups

Getting All Groups

A GET request is used to get all groups

Example CURL request

Unresolved directive in groups/groups-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/groups-documentation/get-groups/curl-request.adoc[]

Example HTTP request

Example response

Response structure

Example 18. Json Structure for Attributes

"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

Example HTTP request

Request parameters

Example response

Response structure

Get Group by Uri

A GET request is used to get group by uri

Example CURL request

Example HTTP request

Path Params

Example response

Response structure

Create Group

A POST request is used to create group.

Example CURL request

Example HTTP request

Example response

Response structure

Get Group members

A GET request is used to get Group members

Example CURL request

Example HTTP request

Path Parameters

Example response

Response structure

Associate Members to Group

A POST request is used to associate members to group

Example CURL request

Example HTTP request

Payload consists of sourceKeys of objects corresponding to the group category.

Example response

Disassociate Members from Group

A DELETE request is used to disassociate members from group

Example CURL request

Example HTTP request

Payload consists of sourceKeys of objects corresponding to the group category.

Example response

Update Group

A PATCH request is used to update group

Example CURL request

Example HTTP request

Request structure

Example response

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 3. 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 4. 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.

Parameter

Description

assetgroupuri

URI of asset group.

asseturi

URI of business functional hierarchy object.

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.

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:

Submitting the export request through the REST endpoint. Appropriate credentials are needed to request tenant classifications export. The customer administrator can provide the details.
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

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.

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 5. /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

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.

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

Unresolved directive in tenantConfig/alm-tenant-configuration-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/tenant-configuration-documentation/get-asset-status/curl-request.adoc[]