14.0 Consolidation APIs

WAS THIS PAGE HELPFUL? Leave Feedback

14.0 Consolidation APIs

14.1 Query Consolidations

Retrieve consolidations by query. There are two kinds of queries supported:

  1. Retrieve a single consolidation. Retrieves exactly one consolidation wrapped XML <consolidation> element
  2. Retrieve one or more consolidations . Retrieves 1..n consolidation objects wrapped by an XML <consolidations> collection
14.1.1 Method: GET Consolidations

GET /api/consolidations?query=(query criteria see below)

14.1.2 Method: GET a single Consolidation by unique consolidation name

GET /api/consolidations/{consolidationName}

14.1.3 HTTP Query and Path Parameters
Field Type Description Required
query Query An encoded query string (where clause) no **
first Query Paging. First record to start from no
count Query Paging. Number of records to include when paging no
consolidationName Path the unique name of the consolidation criteria no **
depth Query The depth of the response data. Either ‘shallow’ or ‘deep’. Defaults to shallow no

Note: **If neither a consolidationName path parameter or query query parameter is not provided, all consolidations will be retrieved.

14.1.4 HTTP Headers
Header Valid Values Required
Content-Type application/xml or application/json True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
14.1.5 Query Fields
Field Description Alias
id Consolidation integer id consolidationId
name The consolidation primary unique name  
criteria Semi-colon separated list of consolidation criteria  

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.
***The fields entity

14.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

  1. query for all consolidations
    GET /api/consolidations
  2. query for all consolidations, order by name descending
    GET /api/consolidations?query=order by name desc
  3. query for a single consolidation named 'SYSTEM'
    GET /api/consolidations/SYSTEM
  4. a like query to find all consolidations in list
    GET /api/consolidations?query=like 'SY%'

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a consolidation name in the path parameter is always wrapped with a single <consolidation> entity element. Here is an XML example of the result of a query finding one consolidation. All fields are displayed as attributes.

<consolidation id="4" name="SYSLOG"
       criteria="OperationStatus;Device;MonitorStatus;ipaddress;ErrorType;SubComponent"/>

Result of queries are always wrapped in a <propertyTypes> collection element, with one or more <propertyType> subelements.

<consolidations>
  <consolidation id="2" name="NAGIOSEVENT"
  criteria="Device;MonitorStatus;OperationStatus;SubComponent;ErrorType" />
  <consolidation id="3" name="SNMPTRAP" criteria="OperationStatus;Device;ipaddress;MonitorStatus;Event_OID_numeric;Event_Name;Category;Variable_Bindings" />
  <consolidation id="4" name="SYSLOG"
  criteria="OperationStatus;Device;MonitorStatus;ipaddress;ErrorType;SubComponent" />
  <consolidation id="1" name="SYSTEM"
  criteria="OperationStatus;Device;MonitorStatus;ApplicationType;TextMessage" />
</consolidations>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Response Data - XML - JSON

14.2 Create or Update Consolidations

Persist a batch (1..n) of consolidations in foundation database. Consolidation records will be created if they do not exist. If a consolidation exists, it will be updated.

If one or more consolidation creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Consolidation creation/update operation is returned back in the resultset described below with a status of success or failure.

14.2.1 Method: POST

POST /api/consolidations

14.2.2 HTTP Headers
Header Valid Values Required
Content-Type application/xml or application/json True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME y our application name True
14.2.3 Post Data Attributes and Elements
Field Description Required Type
name The unique consolidation name Yes Attribute
criteria Semi-colon separated list of consolidation criteria Yes Attribute
14.2.4 XML POST Data Example
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<consolidations>
   <consolidation name='VEMA' criteria='MonitorStatus;ApplicationType'/>
   <consolidation name='BMS' criteria='Device;ApplicationType'/>
</consolidations>

More Post Data Examples: XML - JSON

14.2.5 HTTP Status Codes

200 - Zero or more consolidations were created without any internal server errors
500 - An internal server error occurred

14.2.6 Example Response

In this example, we use the POST data above. Two consolidations were successfully created.

Note that the results collection also returns the location of the created or updated consolidation which can be directly used by the GET operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="Consolidation"
             operation="Update" warning="0" count="2">
  <result>
    <entity>VEMA</entity>
    <location>http://localhost/api/consolidations/VEMA</location>
    <status>success</status>
  </result>
  <result>
    <entity>BMS</entity>
    <location>http://localhost/api/consolidations/BMS</location>
    <status>success</status>
  </result>
</results>
14.3 Delete Consolidations

Deletes one or more consolidations from the Collage database.

14.3.1 Method: DELETE

DELETE /api/consolidations/name1

where name1 is the name of the consolidation to delete

DELETE /api/consolidations/name1,name2 ...
A comma-separated list of two consolidation names (or more) are provided. Note that no-spaces are allowed in this HTTP path segment.

14.3.2 HTTP Headers
Header Valid Values Required
Content-Type application/xml or application/json True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
14.3.3 HTTP Status Codes

200 - Consolidation records were deleted successfully
500 - An internal server error occurred

14.3.4 Example Response
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="Consolidation"
             operation="Delete" warning="0" count="2">
  <result>
    <entity>name1</entity>
    <message>Consolidation deleted</message>
    <status>success</status>
  </result>
  <result>
    <entity>name2</entity>
    <message>Consolidation deleted</message>
    <status>success</status>
  </result>
</results>