Develop > Developer Reference > Using APIs > Universal CMDB REST API > Reference > Execute Query By Definition

Execute Query By Definition

This call executes a TQL query defined by the payload.

URL

/topologyQuery

Method

POST

Headers

Required: 

Authorization: Bearer <token>

Note <token> is the token that is returned by the Authentication call.

Example: 

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njc5ODQ5MTcsImN1c3RvbWVyIjoxLCJ1c2VybmFtZSI6InN5c2FkbWluIn0.Ph8WHtzvpvfuH1j0CtwHqyBhX1uLlfhr0eQQ7m0_gT0

Request type

JSON

Response type

JSON

URL Parameters

Required: None

Optional: 

chunkSize=<chunkSize>

<chunkSize> - integer value that represents the chunk size of the result.

Payload 

{
  nodes: [
    queryIdentifier: [temp_id],
    type: [ucmdb_cit],
    visible: [boolean],
    includeSubtypes: [boolean],
    layout: list of [ucmdb_cit_prop],
    attributeConditions: [
       {
         attribute: [ucmdb_cit_prop],
         operator: [operator] @optional,
         value: [ucmdb_cit_prop_value],
         not: [boolean] @optional default=false
       },
       {
         logicalOperator: [logic_operator] @optional default=and,
         conditions: list of [attributeConditions]
       },
       …
    ],
    ids: list of [ucmdb_id],
    linkConditions: [
       {
          linkIdentifier: [temp_id],
          minCardinality: [cardinality],
          maxCardinality: [cardinality]
       },
      
       {
         logicalOperator: [logic_operator] @optional default=and,
         conditions: list of [linkCondition]
       },
       …
    ]
   },
   …
  ],
  relations: [
    {
    queryIdentifier: [temp_id],
    type: [ucmdb_cit],
    visible: [boolean],
    includeSubtypes: [boolean],
    layout: list of [ucmdb_cit_prop],
    attributeCondtitions: list of [attributeCondition],
    from: [temp_id],
    to: [temp_id]
    },
    …
  ]
}

Data Types:

[temp_id]

The string that represents a temporary ID of the objects. This temporary object ID can be used for referring to the object inside this payload. For example, you can specify the two ends of a relationship, or use the relationship temp ID inside the link conditions.

[ucmdb_cit]

The string that represents the name of a valid CI Type from the UCMDB. You have to use the name of the CI Type, not the display name. The name of the CI Type can be found inside the CI Type Manager.

<ucmdb_cit_prop>

This represents the valid property name of the CI Type. You can get the name and the list of all properties of a CI Type from the CI Type Manager.

[operator]

One of the following strings: isNull, equals, isNotEqualTo, like, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, in, containsAny, contains. If this is unspecified, the default value is equals.

[ucmdb_cit_prop_value]

The property value, which can be integer, string, Boolean, long, double, ISO8601 date, or a list of values depending on the CIT property data type and the operator. For example, the contains operator expects a list of valid values.

[logic_operator]

The string that represents a logic operator, which can be "and" or "or".

[cardinality]

The string that represents the cardinality of a relationship end, which can be a number, *, or UNBOUNDED.

Note  

  • The …(three dots) denotes that there can be 0 or more values.
  • The visible attribute above specifies whether to return this node in the results or not.
  • The includeSubtypes attribute specifies whether to include the subtypes of this node type or not.
  • The layout attribute specifies which attributes of the objects will be returned (default: none).
  • The attributeConditions attribute specifies conditions on the properties of the objects or relationships. You can use simple attributes (name, operator, or value) or complex attributes (a logical operator and a list of attributes that are joined by that logical operator).
  • The linkConditions attribute specifies conditions on the links that the object participates into. You need to specify the link’s temporary ID and the cardinality. You can also use complex conditions that are made of a logical operator and a list of conditions.
  • The not property on the conditions specifies whether to negate the condition. If this property is unspecified, the default value is false.

Example:

See the output of GET /sampleToplogyQuery.

Success Response

Response: 200

Content:

  • Case 1: Result size <= chunk size

    {
  cis: [
    {
      ucmdbId: [ucmdb_id],
      type: [ucmdb_cit],
      properties: {
        <ucmdb_cit_prop>: [ucmdb_cit_prop_value],
        …
      }
    },
    …
  ],
  relations: [
    {
      ucmdbId: [ucmdb_id],
      type: [ucmdb_cit],
      end1Id: [ucmdb_id],
      end2Id: [ucmdb_id],
      properties: {
        <ucmdb_cit_prop>: [ucmdb_cit_prop_value],
        …
      }
    },
    …
  ]
}

  • Case 2: resultSize > chunkSize

    {
  "queryResultId": [resultIdToken],
  "numberOfChunks": [integer],
  "cis": null,
  "relations": null
}

Note The …(three dots) denotes that there can be 0 or more values.

Data Types:

[ucmdb_id]

The string that represents the ID of an object.

[ucmdb_cit]

The string that represents the name of a valid CI Type from the UCMDB. The name of the CI Type can be found inside the CI Type Manager.

[ucmdb_cit_prop_value]

The property value, which can be integer, string, Boolean, long, double, ISO8601 date, or a list of values depending on the CIT property data type.

[resultIdToken]

The string that represents a token that identifies this resultId, used to retrieve individual chunks.

Custom fields:

<ucmdb_cit_prop>

The valid property name of the CI Type. You can get the name and the list of all properties of a CI Type from the CI Type Manager. You have to use the name of the property, not its display name.

Error Response

Code: 400

Content: 

{
  error: [string]
}

Example:

Code: 400

Content: 

{
   error: The following error has occurred: Class "nodeo" is not defined in the class model. Please consult logs for more details
}

Notes

The user that the token belongs to must have the required permissions for executing TQL queries by definition through the SDK.

Send Help Center feedback