WAS THIS PAGE HELPFUL? {html}<a href="mailto:training@gwos.com?subject=Consolidation APIs">Leave Feedback</a>{html}
h4. 14.0 Consolidation APIs
h5. 14.1 Query Consolidations
Retrieve consolidations by query. There are two kinds of queries supported:
# Retrieve a single consolidation. Retrieves exactly one consolidation wrapped XML {{<consolidation>}} element
# Retrieve one or more consolidations . Retrieves 1..n consolidation objects wrapped by an XML {{<consolidations>}} collection
h6. 14.1.1 Method: GET Consolidations
{color:#4a86e8}GET /api/consolidations?query=(query criteria see below){color}
h6. 14.1.2 Method: GET a single Consolidation by unique consolidation name
{color:#4a86e8}GET /api/consolidations/{color}{html}{consolidationName}{html}
h6. 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._
h6. 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 |
h6. 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
h6. 14.1.6 Example Queries
_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# _query for all consolidations_
{color:#4a86e8}GET /api/consolidations{color}
# _query for all consolidations, order by name descending_
{color:#4a86e8}GET /api/consolidations?query=order by name desc{color}
# _query for a single consolidation named 'SYSTEM'_
{color:#4a86e8}GET /api/consolidations/SYSTEM{color}
# _a like query to find all consolidations in list_
{color:#4a86e8}GET /api/consolidations?query=like 'SY%'{color}
*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.
{code}<consolidation id="4" name="SYSLOG"
criteria="OperationStatus;Device;MonitorStatus;ipaddress;ErrorType;SubComponent"/>{code}
Result of queries are always wrapped in a {{<propertyTypes>}} collection element, with one or more {{<propertyType>}} subelements.
{code}<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>{code}
See [Appendix A|1.0 Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|2.0 Appendix B XML Example Data] and [Appendix C|3.0 Appendix C JSON Example Data] for example query data in both XML and JSON:
Response Data - [XML|2.0 Appendix B XML Example Data#Consolidation Query Response Data XML] \- [JSON|3.0 Appendix C JSON Example Data#Consolidation Query Response Data JSON]
h5. 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.
h6. 14.2.1 Method: POST
{color:#4a86e8}POST /api/consolidations{color}
h6. 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 |
h6. 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 |
h6. 14.2.4 XML POST Data Example
{code}<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<consolidations>
<consolidation name='VEMA' criteria='MonitorStatus;ApplicationType'/>
<consolidation name='BMS' criteria='Device;ApplicationType'/>
</consolidations>{code}
More Post Data Examples: [XML|2.0 Appendix B XML Example Data#Consolidation Post Data Data XML] \- [JSON|3.0 Appendix C JSON Example Data#Consolidation Post Data Data JSON]
h6. 14.2.5 HTTP Status Codes
200 - Zero or more consolidations were created without any internal server errors
500 - An internal server error occurred
h6. 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.
{code}<?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>{code}
h5. 14.3 Delete Consolidations
Deletes one or more consolidations from the Collage database.
h6. 14.3.1 Method: DELETE
{color:#4a86e8}DELETE /api/consolidations/name1{color}
where _name1_ is the name of the consolidation to delete
{color:#4a86e8}DELETE /api/consolidations/name1,name2 ...{color}
A comma-separated list of two consolidation names (or more) are provided. Note that no-spaces are allowed in this HTTP path segment.
h6. 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 |
h6. 14.3.3 HTTP Status Codes
200 - Consolidation records were deleted successfully
500 - An internal server error occurred
h6. 14.3.4 Example Response
{code}<?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>{code}
h4. 14.0 Consolidation APIs
h5. 14.1 Query Consolidations
Retrieve consolidations by query. There are two kinds of queries supported:
# Retrieve a single consolidation. Retrieves exactly one consolidation wrapped XML {{<consolidation>}} element
# Retrieve one or more consolidations . Retrieves 1..n consolidation objects wrapped by an XML {{<consolidations>}} collection
h6. 14.1.1 Method: GET Consolidations
{color:#4a86e8}GET /api/consolidations?query=(query criteria see below){color}
h6. 14.1.2 Method: GET a single Consolidation by unique consolidation name
{color:#4a86e8}GET /api/consolidations/{color}{html}{consolidationName}{html}
h6. 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._
h6. 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 |
h6. 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
h6. 14.1.6 Example Queries
_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# _query for all consolidations_
{color:#4a86e8}GET /api/consolidations{color}
# _query for all consolidations, order by name descending_
{color:#4a86e8}GET /api/consolidations?query=order by name desc{color}
# _query for a single consolidation named 'SYSTEM'_
{color:#4a86e8}GET /api/consolidations/SYSTEM{color}
# _a like query to find all consolidations in list_
{color:#4a86e8}GET /api/consolidations?query=like 'SY%'{color}
*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.
{code}<consolidation id="4" name="SYSLOG"
criteria="OperationStatus;Device;MonitorStatus;ipaddress;ErrorType;SubComponent"/>{code}
Result of queries are always wrapped in a {{<propertyTypes>}} collection element, with one or more {{<propertyType>}} subelements.
{code}<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>{code}
See [Appendix A|1.0 Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|2.0 Appendix B XML Example Data] and [Appendix C|3.0 Appendix C JSON Example Data] for example query data in both XML and JSON:
Response Data - [XML|2.0 Appendix B XML Example Data#Consolidation Query Response Data XML] \- [JSON|3.0 Appendix C JSON Example Data#Consolidation Query Response Data JSON]
h5. 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.
h6. 14.2.1 Method: POST
{color:#4a86e8}POST /api/consolidations{color}
h6. 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 |
h6. 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 |
h6. 14.2.4 XML POST Data Example
{code}<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<consolidations>
<consolidation name='VEMA' criteria='MonitorStatus;ApplicationType'/>
<consolidation name='BMS' criteria='Device;ApplicationType'/>
</consolidations>{code}
More Post Data Examples: [XML|2.0 Appendix B XML Example Data#Consolidation Post Data Data XML] \- [JSON|3.0 Appendix C JSON Example Data#Consolidation Post Data Data JSON]
h6. 14.2.5 HTTP Status Codes
200 - Zero or more consolidations were created without any internal server errors
500 - An internal server error occurred
h6. 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.
{code}<?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>{code}
h5. 14.3 Delete Consolidations
Deletes one or more consolidations from the Collage database.
h6. 14.3.1 Method: DELETE
{color:#4a86e8}DELETE /api/consolidations/name1{color}
where _name1_ is the name of the consolidation to delete
{color:#4a86e8}DELETE /api/consolidations/name1,name2 ...{color}
A comma-separated list of two consolidation names (or more) are provided. Note that no-spaces are allowed in this HTTP path segment.
h6. 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 |
h6. 14.3.3 HTTP Status Codes
200 - Consolidation records were deleted successfully
500 - An internal server error occurred
h6. 14.3.4 Example Response
{code}<?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>{code}