WAS THIS PAGE HELPFUL? {html}<a href="mailto:training@gwos.com?subject=Custom Group APIs">Leave Feedback</a>{html}
h4. 22.0 Custom Group APIs
h5. 22.1 Query Custom Groups
Retrieve custom groups by query. There are two kinds of queries supported:
# Retrieving a single custom group. Retrieves exactly one custom group by name.
# Retrieving one or more custom groups. Retrieves 1..n custom group objects wrapped by an XML {{<customGroups>}} collection or a JSON object with a {{customGroups}} array member.
h6. 22.1.1 Method: GET a Single Custom Group by Unique Name
{color:#4a86e8}GET /api/customgroups/\{customGroupName\}{color}
h6. 22.1.2 HTTP Query and Path Parameters
|| Field || Type || Description || Required ||
| customGroupName | Path | the unique name of the custom group | yes |
h6. 22.1.3 Method: GET Custom Groups
{color:#4a86e8}GET /api/customgroups?query=(query criteria see below){color}
h6. 22.1.4 HTTP Query and Path Parameters
|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no \*\* |
| first | Query | Paging for query. First record to start from | no |
| count | Query | Paging for query. Number of records to include when paging | no |
| appType | Query | Application type name filter for custom groups | no |
| agentId | Query | Agent id filter for custom groups | no |
_\**Note: If a query parameter is not provided, all custom groups will be retrieved._
h6. 22.1.5 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. 22.1.6 Query Fields
Because custom groups are implemented as categories, supported query fields are identical. However, entityType shortcuts and fully qualified fields are hardcoded for custom groups and should not be used in a query.
|| Field || Description || Alias ||
| id | Custom group integer id | categoryId |
| name | The custom group primary unique name | |
| description | The description of this custom group | |
| root | Boolean flag indicating a root custom group of a hierarchy | |
| categoryEntities | A prefix for the host or service groups associated with this custom group. Valid sub-fields are: \\
categoryEntities.categoryEntityID \\
categoryEntities.objectID \\
categoryEntities.entityType.name \\
categoryEntities.entityType.entityTypeId \\
categoryEntities.entityType.description \\
categoryEntities.entityType.LogicalEntity \\
categoryEntities.entityType.applicationTypeSupported | |
| ancestors | A prefix for the ancestor parent custom groups. Valid sub-fields include all query fields recursively | |
| parents | A prefix for the parent custom groups. Valid sub-fields include all query fields recursively | |
| children | A prefix for the child custom groups. Valid sub-fields include all query fields recursively | |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._
h6. 22.1.7 Example Queries
_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# _query for all custom groups_
{color:#4a86e8}GET /api/customgroups{color}
# _query for all custom groups order by name descending_
{color:#4a86e8}GET /api/customgroups?query=order by name desc{color}
# _query for a single custom group named 'TEST-CUSTOM-GROUP-0'_
{color:#4a86e8}GET /api/customgroups/TEST-CUSTOM-GROUP-0{color}
# _a like query to find all custom groups starting with 'TEST-'_
{color:#4a86e8}GET /api/customgroups?query=name like 'TEST-%'{color}
# _query for one or more custom group names using IN query syntax_
{color:#4a86e8}GET /api/customgroups?query=name in ('CALL-CENTER','DATA-CENTER'){color}
# _query for all custom groups with application type 'VEMA'_
{color:#4a86e8}GET /api/customgroups/?appType=VEMA{color}
# _query for custom groups with a specific host group entity_
{color:#4a86e8}GET /api/customgroups/?query=categoryEntities.objectID = 512 and categoryEntities.entityType.name = 'HOST_GROUP'{color}
# _query for custom groups with a specific service group entity and agent id '007'_
{color:#4a86e8}GET /api/customgroups/?query=categoryEntities.objectID = 1024 and categoryEntities.entityType.name = 'SERVICE_GROUP'&agentId=007{color}
h6. 22.1.8 HTTP Status Codes
200 - One or more query results returned
404 - No query results found
500 - An internal server error occurred
h6. 22.1.9 Example Responses
Results of requesting a single entity is always wrapped with a single {{<customGroup>}} XML element. Here is an XML example of the result of a query finding one custom group. All simple fields are displayed as attributes. Collections of host and service groups appear as subelements.
{code: language=html/xml}
<customGroup id="82" name="TEST-CUSTOM-GROUP-0" description="TEST-CUSTOM-GROUP-0" appType="NAGIOS" agentId="TEST-AGENT" root="true">
<hostGroups>
<hostGroup id="20" name="TEST-HOST-GROUP-0" alias="TEST-HOST-GROUP-0" appType="NAGIOS"/>
</hostGroups>
</customGroup>
{code}
Result of queries are always wrapped in a {{<customGroups>}} XML collection element, with one or more {{<customGroup>}} subelements.
{code: language=html/xml}
<customGroups>
<customGroup id="82" name="TEST-CUSTOM-GROUP-0" description="TEST-CUSTOM-GROUP-0" appType="NAGIOS" agentId="TEST-AGENT" root="true">
<hostGroups>
<hostGroup id="20" name="TEST-HOST-GROUP-0" alias="TEST-HOST-GROUP-0" appType="NAGIOS"/>
</hostGroups>
</customGroup>
<customGroup id="83" name="TEST-CUSTOM-GROUP-1" agentId="TEST-AGENT" root="true">
<serviceGroups>
<serviceGroup id="77" name="TEST-SERVICE-GROUP-0"/>
</serviceGroups>
</customGroup>
<customGroup id="84" name="TEST-CUSTOM-GROUP-2" appType="NAGIOS" root="true"/>
<customGroup id="85" name="TEST-CUSTOM-GROUP-3" root="true"/>
</customGroups>
{code}
Here is a JSON example of the result of a query finding one custom group.
{code: language=javascript}
{
"id" : 78,
"name" : "TEST-CUSTOM-GROUP-0",
"description" : "TEST-CUSTOM-GROUP-0",
"appType" : "NAGIOS",
"agentId" : "TEST-AGENT",
"root" : true,
"hostGroups" : [ {
"id" : 20,
"name" : "TEST-HOST-GROUP-0",
"alias" : "TEST-HOST-GROUP-0",
"appType" : "NAGIOS"
} ]
}
{code}
The array results of queries are always wrapped in an object with a field named {{customGroups}}.
{code: language=javascript}
{
"customGroups" : [ {
"id" : 78,
"name" : "TEST-CUSTOM-GROUP-0",
"description" : "TEST-CUSTOM-GROUP-0",
"appType" : "NAGIOS",
"agentId" : "TEST-AGENT",
"root" : true,
"hostGroups" : [ {
"id" : 20,
"name" : "TEST-HOST-GROUP-0",
"alias" : "TEST-HOST-GROUP-0",
"appType" : "NAGIOS"
} ]
}, {
"id" : 79,
"name" : "TEST-CUSTOM-GROUP-1",
"agentId" : "TEST-AGENT",
"root" : true,
"serviceGroups" : [ {
"id" : 77,
"name" : "TEST-SERVICE-GROUP-0"
} ]
}, {
"id" : 80,
"name" : "TEST-CUSTOM-GROUP-2",
"appType" : "NAGIOS",
"root" : true
}, {
"id" : 81,
"name" : "TEST-CUSTOM-GROUP-3",
"root" : true
} ]
}
{code}
h5. 22.2 Create or Update Custom Groups
Persist a batch (1..n) of custom groups in foundation database. Custom groups will be created if they do not exist. If a custom group exists, it will be updated. You can also specify one or more host or service groups to be associated with the custom groups. Specified host or service groups will replace existing groups.
If one or more custom group creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual creation/update operation is returned back in the resultset described below with a status of success or failure.
h6. 22.2.1 Method: POST
{color:#4a86e8}POST /api/customgroups{color}
h6. 22.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 | your application name | True |
h6. 22.2.3 Post Data Attributes and Elements
|| Field || Description || Required || Type ||
| name | The unique custom group name | Yes | Attribute/Field |
| description | The description of this custom group | No | Attribute/Field |
| appType | Application type name of this custom group | No | Attribute/Field |
| agentId | Agent id of this custom group | No | Attribute/Field |
| hostGroupNames | Host group names to be associated with this custom group | No | Elements/Array Field |
| serviceGroupNames | Service group names to be associated with this custom group | No | Elements/Array Field |
h6. 22.2.4 Example Post Data
As with the results of queries, custom groups are always wrapped in a {{<customGroups>}} XML collection element, with one or more {{<customGroup>}} subelements. For JSON, custom groups are always wrapped in an object with a field named {{customGroups}}.
{code: language=html/xml}
<customGroups>
<customGroup name="TEST-CUSTOM-GROUP-0" description="TEST-CUSTOM-GROUP-0" appType="NAGIOS" agentId="TEST-AGENT">
<hostGroupNames>
<hostGroupName>TEST-HOST-GROUP-0</hostGroupName>
</hostGroupNames>
</customGroup>
<customGroup name="TEST-CUSTOM-GROUP-1" agentId="TEST-AGENT">
<serviceGroupNames>
<serviceGroupName>TEST-SERVICE-GROUP-0</serviceGroupName>
</serviceGroupNames>
</customGroup>
<customGroup name="TEST-CUSTOM-GROUP-2" appType="NAGIOS"/>
<customGroup name="TEST-CUSTOM-GROUP-3"/>
</customGroups>
{code}
{code: language=javascript}
{
"customGroups" : [ {
"name" : "TEST-CUSTOM-GROUP-0",
"description" : "TEST-CUSTOM-GROUP-0",
"appType" : "NAGIOS",
"agentId" : "TEST-AGENT",
"hostGroupNames" : [ "TEST-HOST-GROUP-0" ]
}, {
"name" : "TEST-CUSTOM-GROUP-1",
"agentId" : "TEST-AGENT",
"serviceGroupNames" : [ "TEST-SERVICE-GROUP-0" ]
}, {
"name" : "TEST-CUSTOM-GROUP-2",
"appType" : "NAGIOS"
}, {
"name" : "TEST-CUSTOM-GROUP-3"
} ]
}
{code}
h6. 22.2.5 HTTP Status Codes
200 - Zero or more custom groups were created without any internal server errors
500 - An internal server error occurred
h6. 22.2.6 Example Responses
In this example, we use the POST data above: four custom groups were successfully created.
Note that the results collection also returns the location of the created or updated custom group which can be directly used by the GET operation.
{code: language=html/xml}
<results successful="4" failed="0" entityType="CustomGroup" operation="Update" warning="0" count="4">
<result>
<entity>TEST-CUSTOM-GROUP-0</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-0</location>
<status>success</status>
</result>
<result>
<entity>TEST-CUSTOM-GROUP-1</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-1</location>
<status>success</status>
</result>
<result>
<entity>TEST-CUSTOM-GROUP-2</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-2</location>
<status>success</status>
</result>
<result>
<entity>TEST-CUSTOM-GROUP-3</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-3</location>
<status>success</status>
</result>
</results>
{code}
{code: language=javascript}
{
"successful" : 4,
"failed" : 0,
"entityType" : "CustomGroup",
"operation" : "Update",
"warning" : 0,
"results" : [ {
"entity" : "TEST-CUSTOM-GROUP-0",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-0"
}, {
"entity" : "TEST-CUSTOM-GROUP-1",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-1"
}, {
"entity" : "TEST-CUSTOM-GROUP-2",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-2"
}, {
"entity" : "TEST-CUSTOM-GROUP-3",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-3"
} ],
"count" : 4
}
{code}
h5. 22.3 Add or Delete Custom Group Members
Host and service groups are associated with custom groups and can be manipulated via these PUT operations.
h6. 22.3.1 Method: PUT adding members with POST Data
{color:#4a86e8}PUT /api/customgroups/addmembers{color}
h6. 22.3.2 Method: PUT deleting members with POST Data
{color:#4a86e8}PUT /api/customgroups/deletemembers{color}
h6. 22.3.3 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. 22.3.4 Post Data Attributes and Elements
|| Field || Description || Required || Type ||
| name | The unique custom group name | Yes | Attribute/Field |
| hostGroupNames | Host group names to be added to or removed from the custom group | No | Elements/Array Field |
| serviceGroupNames | Service group names to be added to or removed from the custom group | No | Elements/Array Field |
h6. 22.3.5 Example POST Data
{code: language=html/xml}
<customGroup name="TEST-CUSTOM-GROUP-0">
<hostGroupNames>
<hostGroupName>TEST-HOST-GROUP-1</hostGroupName>
</hostGroupNames>
</customGroup>
{code}
{code: language=javascript}
{
"name" : "TEST-CUSTOM-GROUP-0",
"hostGroupNames" : [ "TEST-HOST-GROUP-1" ]
}
{code}
h6. 22.3.6 HTTP Status Codes
200 - Custom groups were updated without any internal server errors
500 - An internal server error occurred
h6. 22.3.7 Example Responses
Note that the results collection also returns the location of the updated custom group which can be directly used by the GET operation.
{code: language=html/xml}
<results successful="1" failed="0" entityType="CustomGroup" operation="Update" warning="0" count="1">
<result>
<entity>TEST-CUSTOM-GROUP-0</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-0</location>
<status>success</status>
</result>
</results>
{code}
{code: language=javascript}
{
"successful" : 1,
"failed" : 0,
"entityType" : "CustomGroup",
"operation" : "Update",
"warning" : 0,
"results" : [ {
"entity" : "TEST-CUSTOM-GROUP-0",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-0"
} ],
"count" : 1
}
{code}
h5. 22.4 Delete Custom Groups
Deletes one or more custom groups from the Collage database. Deletes are specified with POST data, passing in custom group names.
Note that while deleting hierarchical custom groups is supported for backward compatibility, this is not recommended. Hierarchical custom group delete operations should be carried out using the hierarchy-specific APIs for categories.
h6. 22.4.1 Method: DELETE with POST Data
{color:#4a86e8}DELETE /api/customgroups{color}
h6. 22.4.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. 22.4.3 Post Data Attributes and Elements
|| Field || Description || Required || Type ||
| name | The unique custom group name | Yes | Attribute/Field |
h6. 22.4.4 Example POST Data
The post data should be formatted like a POST payload, but the only required field is the custom group name.
{code: language=html/xml}
<customGroups>
<customGroup name="TEST-CUSTOM-GROUP-1"/>
<customGroup name="TEST-CUSTOM-GROUP-2"/>
</customGroups>
{code}
{code: language=javascript}
{
"customGroups" : [ {
"name" : "TEST-CUSTOM-GROUP-1"
}, {
"name" : "TEST-CUSTOM-GROUP-2"
} ]
}
{code}
h6. 22.4.5 HTTP Status Codes
200 - Custom groups were deleted successfully
500 - An internal server error occurred
h6. 22.4.6 Example Responses
{code: language=html/xml}
<results successful="2" failed="0" entityType="CustomGroup" operation="Delete" warning="0" count="2">
<result>
<entity>TEST-CUSTOM-GROUP-1</entity>
<message>Custom Group TEST-CUSTOM-GROUP-1 deleted.</message>
<status>success</status>
</result>
<result>
<entity>TEST-CUSTOM-GROUP-2</entity>
<message>Custom Group TEST-CUSTOM-GROUP-2 deleted.</message>
<status>success</status>
</result>
</results>
{code}
{code: language=javascript}
{
"successful" : 2,
"failed" : 0,
"entityType" : "CustomGroup",
"operation" : "Delete",
"warning" : 0,
"results" : [ {
"entity" : "TEST-CUSTOM-GROUP-1",
"status" : "success",
"message" : "Custom Group TEST-CUSTOM-GROUP-1 deleted."
}, {
"entity" : "TEST-CUSTOM-GROUP-2",
"status" : "success",
"message" : "Custom Group TEST-CUSTOM-GROUP-2 deleted."
} ],
"count" : 2
}
{code}
h5. 22.5 Custom Group Name Autocomplete
Get limited number of sorted existing Custom Group names that match a specified prefix. Matching and sorting is done in a case-insensitive fashion. The special wildcard prefix '*' matches all names. Autocomplete names are updated asynchronously when Custom Group names are modified.
h6. 22.5.1 Method: GET Custom Group Name Autocomplete
{color:#4a86e8}GET /api/customgroups/autocomplete/\{prefix\}{color}
h6. 22.5.2 Path Parameters
|| Field || Type || Description || Required ||
| prefix | Path | Encoded Custom Group name prefix to match | yes |
h6. 22.5.3 HTTP Headers
|| Header || Valid Values || Required ||
| Accept | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. 22.5.4 HTTP Status Codes
|| Code || Description ||
| 200 | Autocomplete names for prefix returned |
| 404 | No autocomplete names for prefix |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while processing autocomplete prefix |
h6. 22.5.5 Example Responses
Here is an XML example of the autocomplete names returned.
XML results are always wrapped in an {{<names>}} collection element, with one or more {{<name>}} subelements.
{code: language=html/xml}
<names>
<name>CG1</name>
<name>CG2</name>
</names>
{code}
Here is a JSON example of the autocomplete names returned.
JSON results are always wrapped in an object with a {{names}} array member, with one or more name strings.
{code: language=javascript}
{
"names" : [ "CG1", "CG2" ]
}
{code}
h4. 22.0 Custom Group APIs
h5. 22.1 Query Custom Groups
Retrieve custom groups by query. There are two kinds of queries supported:
# Retrieving a single custom group. Retrieves exactly one custom group by name.
# Retrieving one or more custom groups. Retrieves 1..n custom group objects wrapped by an XML {{<customGroups>}} collection or a JSON object with a {{customGroups}} array member.
h6. 22.1.1 Method: GET a Single Custom Group by Unique Name
{color:#4a86e8}GET /api/customgroups/\{customGroupName\}{color}
h6. 22.1.2 HTTP Query and Path Parameters
|| Field || Type || Description || Required ||
| customGroupName | Path | the unique name of the custom group | yes |
h6. 22.1.3 Method: GET Custom Groups
{color:#4a86e8}GET /api/customgroups?query=(query criteria see below){color}
h6. 22.1.4 HTTP Query and Path Parameters
|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no \*\* |
| first | Query | Paging for query. First record to start from | no |
| count | Query | Paging for query. Number of records to include when paging | no |
| appType | Query | Application type name filter for custom groups | no |
| agentId | Query | Agent id filter for custom groups | no |
_\**Note: If a query parameter is not provided, all custom groups will be retrieved._
h6. 22.1.5 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. 22.1.6 Query Fields
Because custom groups are implemented as categories, supported query fields are identical. However, entityType shortcuts and fully qualified fields are hardcoded for custom groups and should not be used in a query.
|| Field || Description || Alias ||
| id | Custom group integer id | categoryId |
| name | The custom group primary unique name | |
| description | The description of this custom group | |
| root | Boolean flag indicating a root custom group of a hierarchy | |
| categoryEntities | A prefix for the host or service groups associated with this custom group. Valid sub-fields are: \\
categoryEntities.categoryEntityID \\
categoryEntities.objectID \\
categoryEntities.entityType.name \\
categoryEntities.entityType.entityTypeId \\
categoryEntities.entityType.description \\
categoryEntities.entityType.LogicalEntity \\
categoryEntities.entityType.applicationTypeSupported | |
| ancestors | A prefix for the ancestor parent custom groups. Valid sub-fields include all query fields recursively | |
| parents | A prefix for the parent custom groups. Valid sub-fields include all query fields recursively | |
| children | A prefix for the child custom groups. Valid sub-fields include all query fields recursively | |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._
h6. 22.1.7 Example Queries
_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# _query for all custom groups_
{color:#4a86e8}GET /api/customgroups{color}
# _query for all custom groups order by name descending_
{color:#4a86e8}GET /api/customgroups?query=order by name desc{color}
# _query for a single custom group named 'TEST-CUSTOM-GROUP-0'_
{color:#4a86e8}GET /api/customgroups/TEST-CUSTOM-GROUP-0{color}
# _a like query to find all custom groups starting with 'TEST-'_
{color:#4a86e8}GET /api/customgroups?query=name like 'TEST-%'{color}
# _query for one or more custom group names using IN query syntax_
{color:#4a86e8}GET /api/customgroups?query=name in ('CALL-CENTER','DATA-CENTER'){color}
# _query for all custom groups with application type 'VEMA'_
{color:#4a86e8}GET /api/customgroups/?appType=VEMA{color}
# _query for custom groups with a specific host group entity_
{color:#4a86e8}GET /api/customgroups/?query=categoryEntities.objectID = 512 and categoryEntities.entityType.name = 'HOST_GROUP'{color}
# _query for custom groups with a specific service group entity and agent id '007'_
{color:#4a86e8}GET /api/customgroups/?query=categoryEntities.objectID = 1024 and categoryEntities.entityType.name = 'SERVICE_GROUP'&agentId=007{color}
h6. 22.1.8 HTTP Status Codes
200 - One or more query results returned
404 - No query results found
500 - An internal server error occurred
h6. 22.1.9 Example Responses
Results of requesting a single entity is always wrapped with a single {{<customGroup>}} XML element. Here is an XML example of the result of a query finding one custom group. All simple fields are displayed as attributes. Collections of host and service groups appear as subelements.
{code: language=html/xml}
<customGroup id="82" name="TEST-CUSTOM-GROUP-0" description="TEST-CUSTOM-GROUP-0" appType="NAGIOS" agentId="TEST-AGENT" root="true">
<hostGroups>
<hostGroup id="20" name="TEST-HOST-GROUP-0" alias="TEST-HOST-GROUP-0" appType="NAGIOS"/>
</hostGroups>
</customGroup>
{code}
Result of queries are always wrapped in a {{<customGroups>}} XML collection element, with one or more {{<customGroup>}} subelements.
{code: language=html/xml}
<customGroups>
<customGroup id="82" name="TEST-CUSTOM-GROUP-0" description="TEST-CUSTOM-GROUP-0" appType="NAGIOS" agentId="TEST-AGENT" root="true">
<hostGroups>
<hostGroup id="20" name="TEST-HOST-GROUP-0" alias="TEST-HOST-GROUP-0" appType="NAGIOS"/>
</hostGroups>
</customGroup>
<customGroup id="83" name="TEST-CUSTOM-GROUP-1" agentId="TEST-AGENT" root="true">
<serviceGroups>
<serviceGroup id="77" name="TEST-SERVICE-GROUP-0"/>
</serviceGroups>
</customGroup>
<customGroup id="84" name="TEST-CUSTOM-GROUP-2" appType="NAGIOS" root="true"/>
<customGroup id="85" name="TEST-CUSTOM-GROUP-3" root="true"/>
</customGroups>
{code}
Here is a JSON example of the result of a query finding one custom group.
{code: language=javascript}
{
"id" : 78,
"name" : "TEST-CUSTOM-GROUP-0",
"description" : "TEST-CUSTOM-GROUP-0",
"appType" : "NAGIOS",
"agentId" : "TEST-AGENT",
"root" : true,
"hostGroups" : [ {
"id" : 20,
"name" : "TEST-HOST-GROUP-0",
"alias" : "TEST-HOST-GROUP-0",
"appType" : "NAGIOS"
} ]
}
{code}
The array results of queries are always wrapped in an object with a field named {{customGroups}}.
{code: language=javascript}
{
"customGroups" : [ {
"id" : 78,
"name" : "TEST-CUSTOM-GROUP-0",
"description" : "TEST-CUSTOM-GROUP-0",
"appType" : "NAGIOS",
"agentId" : "TEST-AGENT",
"root" : true,
"hostGroups" : [ {
"id" : 20,
"name" : "TEST-HOST-GROUP-0",
"alias" : "TEST-HOST-GROUP-0",
"appType" : "NAGIOS"
} ]
}, {
"id" : 79,
"name" : "TEST-CUSTOM-GROUP-1",
"agentId" : "TEST-AGENT",
"root" : true,
"serviceGroups" : [ {
"id" : 77,
"name" : "TEST-SERVICE-GROUP-0"
} ]
}, {
"id" : 80,
"name" : "TEST-CUSTOM-GROUP-2",
"appType" : "NAGIOS",
"root" : true
}, {
"id" : 81,
"name" : "TEST-CUSTOM-GROUP-3",
"root" : true
} ]
}
{code}
h5. 22.2 Create or Update Custom Groups
Persist a batch (1..n) of custom groups in foundation database. Custom groups will be created if they do not exist. If a custom group exists, it will be updated. You can also specify one or more host or service groups to be associated with the custom groups. Specified host or service groups will replace existing groups.
If one or more custom group creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual creation/update operation is returned back in the resultset described below with a status of success or failure.
h6. 22.2.1 Method: POST
{color:#4a86e8}POST /api/customgroups{color}
h6. 22.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 | your application name | True |
h6. 22.2.3 Post Data Attributes and Elements
|| Field || Description || Required || Type ||
| name | The unique custom group name | Yes | Attribute/Field |
| description | The description of this custom group | No | Attribute/Field |
| appType | Application type name of this custom group | No | Attribute/Field |
| agentId | Agent id of this custom group | No | Attribute/Field |
| hostGroupNames | Host group names to be associated with this custom group | No | Elements/Array Field |
| serviceGroupNames | Service group names to be associated with this custom group | No | Elements/Array Field |
h6. 22.2.4 Example Post Data
As with the results of queries, custom groups are always wrapped in a {{<customGroups>}} XML collection element, with one or more {{<customGroup>}} subelements. For JSON, custom groups are always wrapped in an object with a field named {{customGroups}}.
{code: language=html/xml}
<customGroups>
<customGroup name="TEST-CUSTOM-GROUP-0" description="TEST-CUSTOM-GROUP-0" appType="NAGIOS" agentId="TEST-AGENT">
<hostGroupNames>
<hostGroupName>TEST-HOST-GROUP-0</hostGroupName>
</hostGroupNames>
</customGroup>
<customGroup name="TEST-CUSTOM-GROUP-1" agentId="TEST-AGENT">
<serviceGroupNames>
<serviceGroupName>TEST-SERVICE-GROUP-0</serviceGroupName>
</serviceGroupNames>
</customGroup>
<customGroup name="TEST-CUSTOM-GROUP-2" appType="NAGIOS"/>
<customGroup name="TEST-CUSTOM-GROUP-3"/>
</customGroups>
{code}
{code: language=javascript}
{
"customGroups" : [ {
"name" : "TEST-CUSTOM-GROUP-0",
"description" : "TEST-CUSTOM-GROUP-0",
"appType" : "NAGIOS",
"agentId" : "TEST-AGENT",
"hostGroupNames" : [ "TEST-HOST-GROUP-0" ]
}, {
"name" : "TEST-CUSTOM-GROUP-1",
"agentId" : "TEST-AGENT",
"serviceGroupNames" : [ "TEST-SERVICE-GROUP-0" ]
}, {
"name" : "TEST-CUSTOM-GROUP-2",
"appType" : "NAGIOS"
}, {
"name" : "TEST-CUSTOM-GROUP-3"
} ]
}
{code}
h6. 22.2.5 HTTP Status Codes
200 - Zero or more custom groups were created without any internal server errors
500 - An internal server error occurred
h6. 22.2.6 Example Responses
In this example, we use the POST data above: four custom groups were successfully created.
Note that the results collection also returns the location of the created or updated custom group which can be directly used by the GET operation.
{code: language=html/xml}
<results successful="4" failed="0" entityType="CustomGroup" operation="Update" warning="0" count="4">
<result>
<entity>TEST-CUSTOM-GROUP-0</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-0</location>
<status>success</status>
</result>
<result>
<entity>TEST-CUSTOM-GROUP-1</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-1</location>
<status>success</status>
</result>
<result>
<entity>TEST-CUSTOM-GROUP-2</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-2</location>
<status>success</status>
</result>
<result>
<entity>TEST-CUSTOM-GROUP-3</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-3</location>
<status>success</status>
</result>
</results>
{code}
{code: language=javascript}
{
"successful" : 4,
"failed" : 0,
"entityType" : "CustomGroup",
"operation" : "Update",
"warning" : 0,
"results" : [ {
"entity" : "TEST-CUSTOM-GROUP-0",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-0"
}, {
"entity" : "TEST-CUSTOM-GROUP-1",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-1"
}, {
"entity" : "TEST-CUSTOM-GROUP-2",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-2"
}, {
"entity" : "TEST-CUSTOM-GROUP-3",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-3"
} ],
"count" : 4
}
{code}
h5. 22.3 Add or Delete Custom Group Members
Host and service groups are associated with custom groups and can be manipulated via these PUT operations.
h6. 22.3.1 Method: PUT adding members with POST Data
{color:#4a86e8}PUT /api/customgroups/addmembers{color}
h6. 22.3.2 Method: PUT deleting members with POST Data
{color:#4a86e8}PUT /api/customgroups/deletemembers{color}
h6. 22.3.3 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. 22.3.4 Post Data Attributes and Elements
|| Field || Description || Required || Type ||
| name | The unique custom group name | Yes | Attribute/Field |
| hostGroupNames | Host group names to be added to or removed from the custom group | No | Elements/Array Field |
| serviceGroupNames | Service group names to be added to or removed from the custom group | No | Elements/Array Field |
h6. 22.3.5 Example POST Data
{code: language=html/xml}
<customGroup name="TEST-CUSTOM-GROUP-0">
<hostGroupNames>
<hostGroupName>TEST-HOST-GROUP-1</hostGroupName>
</hostGroupNames>
</customGroup>
{code}
{code: language=javascript}
{
"name" : "TEST-CUSTOM-GROUP-0",
"hostGroupNames" : [ "TEST-HOST-GROUP-1" ]
}
{code}
h6. 22.3.6 HTTP Status Codes
200 - Custom groups were updated without any internal server errors
500 - An internal server error occurred
h6. 22.3.7 Example Responses
Note that the results collection also returns the location of the updated custom group which can be directly used by the GET operation.
{code: language=html/xml}
<results successful="1" failed="0" entityType="CustomGroup" operation="Update" warning="0" count="1">
<result>
<entity>TEST-CUSTOM-GROUP-0</entity>
<location>http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-0</location>
<status>success</status>
</result>
</results>
{code}
{code: language=javascript}
{
"successful" : 1,
"failed" : 0,
"entityType" : "CustomGroup",
"operation" : "Update",
"warning" : 0,
"results" : [ {
"entity" : "TEST-CUSTOM-GROUP-0",
"status" : "success",
"location" : "http://localhost:8080/foundation-webapp/api/customgroups/TEST-CUSTOM-GROUP-0"
} ],
"count" : 1
}
{code}
h5. 22.4 Delete Custom Groups
Deletes one or more custom groups from the Collage database. Deletes are specified with POST data, passing in custom group names.
Note that while deleting hierarchical custom groups is supported for backward compatibility, this is not recommended. Hierarchical custom group delete operations should be carried out using the hierarchy-specific APIs for categories.
h6. 22.4.1 Method: DELETE with POST Data
{color:#4a86e8}DELETE /api/customgroups{color}
h6. 22.4.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. 22.4.3 Post Data Attributes and Elements
|| Field || Description || Required || Type ||
| name | The unique custom group name | Yes | Attribute/Field |
h6. 22.4.4 Example POST Data
The post data should be formatted like a POST payload, but the only required field is the custom group name.
{code: language=html/xml}
<customGroups>
<customGroup name="TEST-CUSTOM-GROUP-1"/>
<customGroup name="TEST-CUSTOM-GROUP-2"/>
</customGroups>
{code}
{code: language=javascript}
{
"customGroups" : [ {
"name" : "TEST-CUSTOM-GROUP-1"
}, {
"name" : "TEST-CUSTOM-GROUP-2"
} ]
}
{code}
h6. 22.4.5 HTTP Status Codes
200 - Custom groups were deleted successfully
500 - An internal server error occurred
h6. 22.4.6 Example Responses
{code: language=html/xml}
<results successful="2" failed="0" entityType="CustomGroup" operation="Delete" warning="0" count="2">
<result>
<entity>TEST-CUSTOM-GROUP-1</entity>
<message>Custom Group TEST-CUSTOM-GROUP-1 deleted.</message>
<status>success</status>
</result>
<result>
<entity>TEST-CUSTOM-GROUP-2</entity>
<message>Custom Group TEST-CUSTOM-GROUP-2 deleted.</message>
<status>success</status>
</result>
</results>
{code}
{code: language=javascript}
{
"successful" : 2,
"failed" : 0,
"entityType" : "CustomGroup",
"operation" : "Delete",
"warning" : 0,
"results" : [ {
"entity" : "TEST-CUSTOM-GROUP-1",
"status" : "success",
"message" : "Custom Group TEST-CUSTOM-GROUP-1 deleted."
}, {
"entity" : "TEST-CUSTOM-GROUP-2",
"status" : "success",
"message" : "Custom Group TEST-CUSTOM-GROUP-2 deleted."
} ],
"count" : 2
}
{code}
h5. 22.5 Custom Group Name Autocomplete
Get limited number of sorted existing Custom Group names that match a specified prefix. Matching and sorting is done in a case-insensitive fashion. The special wildcard prefix '*' matches all names. Autocomplete names are updated asynchronously when Custom Group names are modified.
h6. 22.5.1 Method: GET Custom Group Name Autocomplete
{color:#4a86e8}GET /api/customgroups/autocomplete/\{prefix\}{color}
h6. 22.5.2 Path Parameters
|| Field || Type || Description || Required ||
| prefix | Path | Encoded Custom Group name prefix to match | yes |
h6. 22.5.3 HTTP Headers
|| Header || Valid Values || Required ||
| Accept | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |
h6. 22.5.4 HTTP Status Codes
|| Code || Description ||
| 200 | Autocomplete names for prefix returned |
| 404 | No autocomplete names for prefix |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while processing autocomplete prefix |
h6. 22.5.5 Example Responses
Here is an XML example of the autocomplete names returned.
XML results are always wrapped in an {{<names>}} collection element, with one or more {{<name>}} subelements.
{code: language=html/xml}
<names>
<name>CG1</name>
<name>CG2</name>
</names>
{code}
Here is a JSON example of the autocomplete names returned.
JSON results are always wrapped in an object with a {{names}} array member, with one or more name strings.
{code: language=javascript}
{
"names" : [ "CG1", "CG2" ]
}
{code}