APM Asset API Version v3 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 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	* v3/assets/query?q=uri=/assets/<uuid> * v3/sites/query?q=attributes.Sample_CA_address.value=Bay * v3/segments/query?q=name=Sample
Assets	uri name sourcekey description attributes reservedattributes type parent	* v3/assets/query?q=reservedAttributes.state.key=06 * v3/assets/query?q=parent=/segments/<uuid>
Asset Types & Tag Types	uri name sourcekey description attributes reservedattributes parent	* v3/segments/query?q=type=/segmentTypes/<uuid>
Tags	uri name sourcekey description attributes reservedattributes type monitoredentityuri monitoredentityname monitoredentitysourcekey	* v3/tags/query?q=monitoredentitysourcekey=Sample_Asset& sortBy=reservedAttributes.uom.desc
Asset Groups	uri name sourcekey description attributes reservedattributes category	* v3/assetgroups/query?q=category=Tag

Resource Endpoint

Supported Query Params

Example

Instances - Enterprises, Sites & Segments

uri
name
sourcekey
description
attributes
reservedattributes
type
parent

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

Assets

uri
name
sourcekey
description
attributes
reservedattributes
type
parent

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

Asset Types & Tag Types

uri
name
sourcekey
description
attributes
reservedattributes
parent

* v3/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 v3/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-v3/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 v3/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-v3/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 v3/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-v3/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 v3/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-v3/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/v3/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 /v3/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 v3/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-v3/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/v3/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 /v3/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 v3/enterprises/enterprises-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/enterprises-documentation-v3/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/v3/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 /v3/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 v3/sites/sites-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/sites-documentation-v3/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/v3/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 /v3/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 v3/segments/segments-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/segments-documentation-v3/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/v3/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 /v3/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 v3/assets/assets-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/assets-documentation-v3/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

Use 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/v3/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 /v3/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

Unresolved directive in v3/assets/assets-index.adoc - include::v3/decommission-commission-asset.adoc[]

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/v3/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 /v3/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 v3/tags/tags-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/tags-documentation-v3/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.

It also supports 'sortBy' param that sorts all return Tag instances ascending/descending based on sortBy param value.

Example cURL request

$ curl 'https://www.predixapis.com/v3/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 /v3/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 v3/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-v3/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 v3/groups/groups-index.adoc - include::/home/jenkins/agent/workspace/lican_apm-geda-apidoc-svc_master/apm-asset-restdoc/target/generated-snippets/groups-documentation-v3/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/v3/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": [
      "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/assetGroups/a367c355-f175-3571-b75a-c2c4da770ec7"
    ]
  }
}
'

Associate single business functional hierarchy object to multiple groups

$ curl 'https://www.predixapis.com/v3/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": [
      "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/assets/1234",
      "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/assets/abcd"
    ]
  }
}
'

Example HTTP request

Associate single asset group to multiple business functional hierarchy objects

POST /v3/assetgroupassociations HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Content-Length: 244

{
  "assetGroupUri": "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/assetGroups/df54d427-0a58-3d09-a8a7-300c4cdbe4e6",
  "assets": {
    "sourceKeys": [
      {
        "type": "/sites",
        "sourceKeys": [
          "siteKey1",
          "siteKey2"
        ]
      },
      {
        "type": "/assets",
        "sourceKeys": [
          "assetKey1",
          "assetKey2"
        ]
      }
    ],
    "uris": [
      "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/assets/df54d427-0a58-3d09-a8a7-300c4cdbe4e6",
      "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/sites/df54d427-0a58-3d09-a8a7-300c4cdbe4e6"
    ]
  }
}

Associate single business functional hierarchy object to multiple groups

POST /v3/assetgroupassociations HTTP/1.1
Authorization: <Authorization>
tenant: <tenant>
Accept: application/json
Content-Type: application/json
Host: www.predixapis.com
Content-Length: 244

{
  "assetUri": "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/sites/df54d427-0a58-3d09-a8a7-300c4cdbe4e6",
  "assetGroups": {
    "sourceKeys": [
      "AssetGroups_20170713_100_101"
    ],
    "uris": [
      "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/assetGroups/a367c355-f175-3571-b75a-c2c4da770ec7"
    ]
  }
}

Example response

Associate single asset group to multiple business functional hierarchy objects

HTTP/1.1 201 CREATED
Location: /v3/assetgroupassociations?assetgroupuri=/assetGroups/{uuid}

Associate single business functional hierarchy object to multiple groups

HTTP/1.1 201 CREATED
Location: /v3/assetgroupassociations?asseturi=/sites/{uuid}

Response structure

Table 1. 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 2. 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/v3/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/v3/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 /v3/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 /v3/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": "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/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": "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/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": "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/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": "/tenants/259dd121-fd2c-43e0-aa5c-c9ebf0cb724c/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/v3/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 /v3/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.

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 v3/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-v3/get-asset-status/curl-request.adoc[]