8.0 Category APIs

WAS THIS PAGE HELPFUL? Leave Feedback

8.0 Category APIs

8.1 Query Categories

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

  1. Retrieving a single category. Retrieves exactly one category wrapped by an XML <category> element.
  2. Retrieving one or more categories. Retrieves 1..n category objects wrapped by an XML <categories> collection.

Categories can be retrieved with shallow, deep, or full depth. Full depth categories include all hierarchy child categories nested recursively.

8.1.1 Method: GET a single category by unique category name

GET /api/categories/{categoryName}/{entityType}

8.1.2 HTTP Query and Path Parameters
Field Type Description Required
categoryName Path the unique name of the category yes
entityType Path the name of the entity type name of the category yes
depth Query The depth of the response data. Either ‘shallow’, ‘deep’, or 'full'. Defaults to shallow no
8.1.3 Method: GET Categories

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

8.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
depth Query The depth of the response data. Either ‘shallow’, ‘deep’, or 'full'. Defaults to shallow no
name Query The name of the root category in hierarchy no **
entityTypeName Query The entity type name of categories no **
roots Query Boolean flag for category roots filter, defaults to 'false' no
entityObjectId Query Category entity object id no **
entityEntityTypeName Query Category entity entity type name yes, with entityObjectId
entityRoots Query Boolean flag for entity category roots filter, defaults to 'true' no

*Note: **If neither a query, name, entityTypeName, or entityObjectId query parameter is not provided, all categories will be retrieved. The entityTypeName is required if name or entityObjectId is specified._

8.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
8.1.6 Query Fields
Field Description Depth Alias
id Category integer id Shallow categoryId
name The category primary unique name Shallow
description The description of this category Shallow
entityTypeName Shortcut to entityType.name Shallow entityType.name
root Boolean flag indicating a root category of a hierarchy Shallow
entityType A prefix for the associated entity type of this category. Valid queried sub-fields are:
entityType.name
entityType.entityTypeId
entityType.description
entityType.LogicalEntity
entityType.applicationTypeSupported 		Deep
categoryEntities A prefix for the child category entities associated with this category. Valid sub-fields are:
categoryEntities.categoryEntityID
categoryEntities.objectID
categoryEntities.entityType.name
categoryEntities.entityType.entityTypeId
categoryEntities.entityType.description
categoryEntities.entityType.LogicalEntity
categoryEntities.entityType.applicationTypeSupported 		Deep
ancestors A prefix for the ancestor parent categories. Valid sub-fields include all query fields recursively Not serialized
parents A prefix for the parent categories. Valid sub-fields include all query fields recursively Deep
children A prefix for the child categories. Valid sub-fields include all query fields recursively Deep and Full

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

8.1.7 Example Queries

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

  1. query for all categories, with shallow depth
    GET /api/categories
  2. query for all categories, with deep depth, order by name descending
    GET /api/categories?depth=deep&query=order by name desc
  3. query for a single category named 'HeavyLoad' and entity type 'SERVICE_GROUP' with depth of shallow
    GET /api/categories/HeavyLoad/SERVICE_GROUP
  4. query for a single category named 'TopPriority' and entity type 'SERVICE_GROUP' with depth of deep
    GET /api/categories/TopPriority/SERVICE_GROUP?depth=deep
  5. query for a single category named 'TEST-A' and entity type 'SERVICE_GROUP' with a depth of full, (nested hierarchy)
    GET /api/categories/TEST-A/SERVICE_GROUP?depth=full
  6. a like query to find all categories starting with 'SERVICE'_
    GET /api/categories?query=name like 'SERVICE_%'
  7. query for all categories of type 'SERVICE_GROUP' ordered by name
    GET /api/categories?query=entityType.name = 'SERVICE_GROUP' order by name
  8. query for one or more category names using IN query syntax
    GET /api/categories?query=name in ('americas','east-region','west-region')
  9. query for one or more categories by object id of child collection of Category Entities
    GET /api/categories?query=categoryEntities.objectID = 22
  10. query for categories with entity type 'SERVICE_GROUP'
    GET /api/categories/?entityTypeName=SERVICE_GROUP
  11. query for root categories with entity type 'SERVICE_GROUP'
    GET /api/categories/?entityTypeName=SERVICE_GROUP&roots=true
  12. query for a categories hierarchy with root named 'TEST-A' and entity type 'SERVICE_GROUP'
    GET /api/categories/?name=TEST-A&entityTypeName=SERVICE_GROUP
  13. query for root categories of hierarchies of an entity type 'SERVICE_GROUP' that have a specific entity
    GET /api/categories/?entityTypeName=SERVICE_GROUP&entityObjectId=1024&entityEntityTypeName=SERVICE_STATUS
  14. query for categories of an entity type 'SERVICE_GROUP' that have a specific entity
    GET /api/categories/?entityTypeName=SERVICE_GROUP&entityObjectId=1024&entityEntityTypeName=SERVICE_STATUS&entityRoots=false

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 is always wrapped with a single <category> entity element. Here is an XML example of the result of a query finding one category. All fields are displayed as attributes.

<category id="2" name="SG1" description="Service Group 1" entityTypeName="SERVICE_GROUP" root="true"/>

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

<categories>
  <category id="2" name="SG1" description='Service Group 1' entityTypeName="SERVICE_GROUP" root="true"/>
  <category id="1" name="North" description='North Region servers' entityTypeName="SERVICE_GROUP" root="true"/>
</categories>

The full entity type will be displayed when depth = deep. Also, category entities are displayed.

<category id="2" name="SG1" entityTypeName="SERVICE_GROUP" root="true">
  <applicationType/>
  <entityType id="23" name="SERVICE_GROUP" description="com.groundwork.collage.model.impl.ServiceGroup"
isLogicalEntity="true" applicationTypeSupported="false" />
  <entities>
    <entity id="10" objectID="3" entityTypeId="2" />
    <entity id="9" objectID="44" entityTypeId="2" />
  </entities>
</category>

When a category is part of a hierarchy, parent and children names are included when depth = shallow.

<category id="8" name="TEST-B" entityTypeName="SERVICE_GROUP" root="false">
  <parentNames>
    <parentName>TEST-A</parentName>
  </parentNames>
  <childNames>
    <childName>TEST-C</childName>
    <childName>TEST-D</childName>
  </childNames>
</category>

When a hierarchy category is serialized with depth = full, all categories in the hierarchy, (i.e. children), are rendered as with depth = full. Parents are rendered as with depth = shallow.

<category id="7" name="TEST-A" entityTypeName="SERVICE_GROUP" root="true">
  <childNames>
    <childName>TEST-B</childName>
  </childNames>
  <applicationType/>
  <entityType id="23" name="SERVICE_GROUP" description="com.groundwork.collage.model.impl.ServiceGroup" isLogicalEntity="true" applicationTypeSupported="false"/>
  <children>
    <category id="8" name="TEST-B" entityTypeName="SERVICE_GROUP" root="false">
      <parentNames>
        <parentName>TEST-A</parentName>
      </parentNames>
      <childNames>
        <childName>TEST-D</childName>
        <childName>TEST-C</childName>
      </childNames>
      <applicationType/>
      <entityType id="23" name="SERVICE_GROUP" description="com.groundwork.collage.model.impl.ServiceGroup" isLogicalEntity="true" applicationTypeSupported="false"/>
      <parents>
        <category id="7" name="TEST-A" entityTypeName="SERVICE_GROUP" root="true">
          <childNames>
            <childName>TEST-B</childName>
          </childNames>
        </category>
      </parents>
      <children>
        <category id="10" name="TEST-D" entityTypeName="SERVICE_GROUP" root="true">
          <parentNames>
            <parentName>TEST-B</parentName>
          </parentNames>
          <applicationType/>
          <entityType id="23" name="SERVICE_GROUP" description="com.groundwork.collage.model.impl.ServiceGroup" isLogicalEntity="true" applicationTypeSupported="false"/>
          <parents>
            <category id="8" name="TEST-B" entityTypeName="SERVICE_GROUP" root="false">
              <parentNames>
                <parentName>TEST-A</parentName>
              </parentNames>
              <childNames>
                <childName>TEST-D</childName>
                <childName>TEST-C</childName>
              </childNames>
            </category>
          </parents>
        </category>
        <category id="9" name="TEST-C" entityTypeName="SERVICE_GROUP" root="false">
          <parentNames>
            <parentName>TEST-B</parentName>
          </parentNames>
          <applicationType/>
          <entityType id="23" name="SERVICE_GROUP" description="com.groundwork.collage.model.impl.ServiceGroup" isLogicalEntity="true" applicationTypeSupported="false"/>
          <parents>
            <category id="8" name="TEST-B" entityTypeName="SERVICE_GROUP" root="false">
              <parentNames>
                <parentName>TEST-A</parentName>
              </parentNames>
              <childNames>
                <childName>TEST-D</childName>
                <childName>TEST-C</childName>
              </childNames>
            </category>
          </parents>
          <entities>
            <entity id="12" objectID="1024" entityTypeId="2" entityTypeName="SERVICE_STATUS"/>
          </entities>
        </category>
      </children>
    </category>
  </children>
</category>

Example Query Results in JSON

Here is a JSON example of the result of a query finding one category.

{
  "id" : 3,
  "name" : "TEST-A",
  "entityTypeName" : "SERVICE_GROUP",
  "root" : true
}

The array results of queries are always wrapped in an object with a field named categories. When a category is part of a hierarchy, parent and children names are included when depth = shallow.

{
  "categories" : [ {
    "id" : 3,
    "name" : "TEST-A",
    "entityTypeName" : "SERVICE_GROUP",
    "childNames" : [ "TEST-B" ],
    "root" : true
  }, {
    "id" : 4,
    "name" : "TEST-B",
    "entityTypeName" : "SERVICE_GROUP",
    "parentNames" : [ "TEST-A" ],
    "childNames" : [ "TEST-D", "TEST-C" ],
    "root" : false
  }, {
    "id" : 5,
    "name" : "TEST-C",
    "entityTypeName" : "SERVICE_GROUP",
    "parentNames" : [ "TEST-B" ],
    "root" : false
  }, {
    "id" : 6,
    "name" : "TEST-D",
    "entityTypeName" : "SERVICE_GROUP",
    "parentNames" : [ "TEST-B" ],
    "root" : true
  } ]
}

The full entity type will be displayed when depth = deep. Also, category entities are displayed.

{
  "id" : 3,
  "name" : "TEST-A",
  "entityTypeName" : "SERVICE_GROUP",
  "childNames" : [ "TEST-B" ],
  "root" : true,
  "applicationType" : {
    "properties" : {
    }
  },
  "entityType" : {
    "id" : 23,
    "name" : "SERVICE_GROUP",
    "description" : "com.groundwork.collage.model.impl.ServiceGroup",
    "applicationTypeSupported" : false,
    "logicalEntity" : true
  },
  "children" : [ {
    "id" : 4,
    "name" : "TEST-B",
    "entityTypeName" : "SERVICE_GROUP",
    "parentNames" : [ "TEST-A" ],
    "childNames" : [ "TEST-D", "TEST-C" ],
    "root" : false
  } ]
}

When a hierarchy category is serialized with depth = full, all categories in the hierarchy, (i.e. children), are rendered as with depth = deep. Parents are rendered as with depth = shallow.

{
  "id" : 3,
  "name" : "TEST-A",
  "entityTypeName" : "SERVICE_GROUP",
  "childNames" : [ "TEST-B" ],
  "root" : true,
  "applicationType" : {
    "properties" : {
    }
  },
  "entityType" : {
    "id" : 23,
    "name" : "SERVICE_GROUP",
    "description" : "com.groundwork.collage.model.impl.ServiceGroup",
    "applicationTypeSupported" : false,
    "logicalEntity" : true
  },
  "children" : [ {
    "id" : 4,
    "name" : "TEST-B",
    "entityTypeName" : "SERVICE_GROUP",
    "parentNames" : [ "TEST-A" ],
    "childNames" : [ "TEST-C", "TEST-D" ],
    "root" : false,
    "applicationType" : {
      "properties" : {
      }
    },
    "entityType" : {
      "id" : 23,
      "name" : "SERVICE_GROUP",
      "description" : "com.groundwork.collage.model.impl.ServiceGroup",
      "applicationTypeSupported" : false,
      "logicalEntity" : true
    },
    "parents" : [ {
      "id" : 3,
      "name" : "TEST-A",
      "entityTypeName" : "SERVICE_GROUP",
      "childNames" : [ "TEST-B" ],
      "root" : true
    } ],
    "children" : [ {
      "id" : 5,
      "name" : "TEST-C",
      "entityTypeName" : "SERVICE_GROUP",
      "parentNames" : [ "TEST-B" ],
      "root" : false,
      "applicationType" : {
        "properties" : {
        }
      },
      "entityType" : {
        "id" : 23,
        "name" : "SERVICE_GROUP",
        "description" : "com.groundwork.collage.model.impl.ServiceGroup",
        "applicationTypeSupported" : false,
        "logicalEntity" : true
      },
      "parents" : [ {
        "id" : 4,
        "name" : "TEST-B",
        "entityTypeName" : "SERVICE_GROUP",
        "parentNames" : [ "TEST-A" ],
        "childNames" : [ "TEST-C", "TEST-D" ],
        "root" : false
      } ],
      "entities" : [ {
        "id" : 11,
        "objectID" : 1024,
        "entityTypeId" : 2,
        "entityTypeName" : "SERVICE_STATUS"
      } ]
    }, {
      "id" : 6,
      "name" : "TEST-D",
      "entityTypeName" : "SERVICE_GROUP",
      "parentNames" : [ "TEST-B" ],
      "root" : true,
      "applicationType" : {
        "properties" : {
        }
      },
      "entityType" : {
        "id" : 23,
        "name" : "SERVICE_GROUP",
        "description" : "com.groundwork.collage.model.impl.ServiceGroup",
        "applicationTypeSupported" : false,
        "logicalEntity" : true
      },
      "parents" : [ {
        "id" : 4,
        "name" : "TEST-B",
        "entityTypeName" : "SERVICE_GROUP",
        "parentNames" : [ "TEST-A" ],
        "childNames" : [ "TEST-C", "TEST-D" ],
        "root" : false
      } ]
    } ]
  } ]
}

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

8.2 Create or Update Categories

Persist a batch (1..n) of categories in foundation database. Categories will be created if they do not exist. If a category exists, it will be updated. You can also specify one or more category entities to be created or associated with the category. Category entities will be created if they do not already exist in the system.

Note that while creating or updating hierarchy categories with parents is supported for backward compatibility, this is not recommended. Hierarchical category create and updated operations should be carried out using the hierarchy-specific APIs documented below.

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

8.2.1 Method: POST

POST /api/categories

8.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
8.2.3 Post Data Attributes and Elements
Field Description Required Type
name The unique category name Yes Attribute
description The description of this caetgory No Attribute
entityTypeName The unique entity type name. Required to associate this category with an entity type Yes Attribute
entities The element wrapper (collection) of one or more category entities to add to this category. Note these entities will be auto-created if they do not exist No Element
entityType The unique entity type name. If entityTypeName attribute is not provided, entityType.name attribute is required No Element
8.2.4 CategoryEntity Attributes and Elements
Field Description Required
objectID The object ID for this entity Yes
entityTypeName The unique entity type name. Required to associate this category entity with an entity type Yes
8.2.5 XML POST Data Example
<categories>
  <category name="west-region" description="servers in the west region" entityTypeName="SERVICE_GROUP"/>
  <category name="east-region" description="servers in the east region" entityTypeName="SERVICE_GROUP"/>
</categories>
8.2.6 JSON POST Data Example
{
  "categories" : [ {
    "name" : "TEST-C",
    "entityTypeName" : "SERVICE_GROUP",
    "entities" : [ {
      "objectID" : 1024,
      "entityTypeName" : "SERVICE_STATUS"
    } ]
  } ]
}
8.2.7 HTTP Status Codes

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

8.2.8 Example Responses

In this example, we use the POST data above. For the XML POST data, two categories were successfully created. One category was updated with the JSON POST data example.

Note that the results collection also returns the location of the created or updated category which can be directly used by the GET operation. The result entities are formed by the concatenation of the category and entity type names.

<results successful="2" failed="0" entityType="Category" operation="Update" warning="0" count="2">
  <result>
    <entity>west-region:SERVICE_GROUP</entity>
    <location>http://localhost/api/categories/west-region:SERVICE_GROUP</location>
    <status>success</status>
  </result>
  <result>
    <entity>east-region:SERVICE_GROUP</entity>
    <location>http://localhost/api/categories/east-region:SERVICE_GROUP</location>
    <status>success</status>
  </result>
</results>

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "Category",
  "operation" : "Update",
  "warning" : 0,
  "count" : 1,
  "results" : [ {
    "entity" : "TEST-C:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-C/SERVICE_GROUP"
  } ]
}
8.3 Creating, Modifying, and Deleting Hierarchical Categories

Hierarchical categories can be created, modified, and deleted transactionally. These operations are specified in a list of cateory updates. These operations should be used for hierarchical category manipulation since they properly maintain parent, child, and ancestor relationships between the categories. Modifying operations are only vaild on categories that have a homogeneous entity types. Categories specified by name only are looked up using the primary category entity type.

Because multiple operations are usually dependent on each other, the operations are processed within one database transaction. Any failure will roll back any previous operations.

The following operations are supported for creating categories:

  1. AS_ROOT - create a new category as a root category
  2. AS_CHILD - create a new category as a leaf of a specified parent
  3. AS_CHILD_WITH_PARENT_CHILDREN - create a new category as a child of a specified parent adopting its children

Operations supported to clone an existing category:

  1. AS_ROOT - clone category as a root category
  2. AS_ROOT_WITH_CHILDREN - clone category as a root category sharing children
  3. AS_LEAF_WITH_PARENTS - clone category sharing parents
  4. WITH_PARENTS_AND_CHILDREN - clone category sharing both parents and children

Operations supported to modify a category:

  1. ROOT - mark a child category as a root category
  2. ROOT_REMOVE_PARENTS - remove category parents and make root
  3. UNROOT - unmark a root child category
  4. REMOVE_PARENTS - remove specified parents from category
  5. REMOVE_CHILDREN - remove specified children from category
  6. MOVE_CHILD - move a child category to new parents
  7. ADD_CHILD - add a category as child to parents
  8. MOVE_PARENT - move a parent to new children
  9. ADD_PARENT - add a parent to new children
  10. SWAP_PARENTS - swap parents between child categories

Operations supported to delete categories:

  1. LEAF_ONLY - delete category only if it has no children
  2. CASCADE - delete category and all children deeply excluding shared children
  3. CASCADE_ALL - delete category and all children deeply including shared children
  4. ORPHAN_CHILDREN_AS_ROOTS - delete category making children root categories
  5. ADD_CHILDREN_TO_PARENTS - delete category copying children to all parents

These operations require or utilize the following category update fields:

Field/Element Type Operation Types Description
agentId string create agent id for new category
appType string create application type name for new category
applicationType ApplicationType create application type for new category
category Category clone, modify, or delete existing category
categoryName string clone, modify, or delete existing category name
childrenOnly boolean delete delete children only flag, defaults to "false"
clone string clone clone operation
cloneName string clone category name for cloned category
create string create create operation
delete string delete delete operation
description string create description for new category
entityType EntityType create, clone, modify, or delete entity type of new or existing category
entityTypeName string create, clone, modify, or delete entity type name of new or existing category
modify string modify modify operation
otherCategories list of Category modify other categories for modification
otherCategoryNames list of string modify other category names for modification
parent Category create parent category for new category
parentName string create parent category name for new category
Operation Type Operation Supported Fields/Elements
create AS_ROOT entityType/entityTypeName,
agentId,
appType/applicationType,
description
create AS_CHILD entityType/entityTypeName,
agentId,
appType/applicationType,
description,
parent/parentName
create AS_CHILD_WITH_PARENT_CHILDREN entityType/entityTypeName,
agentId,
appType/applicationType,
description,
parent/parentName
clone AS_ROOT category/categoryName,
entityType/entityTypeName,
cloneName
clone AS_ROOT_WITH_CHILDREN category/categoryName,
entityType/entityTypeName,
cloneName
clone AS_LEAF_WITH_PARENTS category/categoryName,
entityType/entityTypeName,
cloneName
clone WITH_PARENTS_AND_CHILDREN category/categoryName,
entityType/entityTypeName,
cloneName
modify ROOT category/categoryName,
entityType/entityTypeName
modify ROOT_REMOVE_PARENTS category/categoryName,
entityType/entityTypeName
modify UNROOT category/categoryName,
entityType/entityTypeName
modify REMOVE_PARENTS category/categoryName,
entityType/entityTypeName,
otherCategories/otherCategoryNames
modify REMOVE_CHILDREN category/categoryName,
entityType/entityTypeName,
otherCategories/otherCategoryNames
modify MOVE_CHILD category/categoryName,
entityType/entityTypeName,
otherCategories/otherCategoryNames
modify ADD_CHILD category/categoryName,
entityType/entityTypeName,
otherCategories/otherCategoryNames
modify MOVE_PARENT category/categoryName,
entityType/entityTypeName,
otherCategories/otherCategoryNames
modify ADD_PARENT category/categoryName,
entityType/entityTypeName,
otherCategories/otherCategoryNames
modify SWAP_PARENTS category/categoryName,
entityType/entityTypeName,
otherCategories/otherCategoryNames
delete LEAF_ONLY category/categoryName,
entityType/entityTypeName
delete CASCADE category/categoryName,
entityType/entityTypeName,
childrenOnly
delete CASCADE_ALL category/categoryName,
entityType/entityTypeName,
childrenOnly
delete ORPHAN_CHILDREN_AS_ROOTS category/categoryName,
entityType/entityTypeName
delete ADD_CHILDREN_TO_PARENTS category/categoryName,
entityType/entityTypeName
8.3.1 Method: PUT with POST Data

PUT /api/categories

Individual category update operations are wrapped in a <categoryUpdates> tag for XML or are contained in a wrapping object array field named categoryUpdates for JSON. Category update operations are specified in the create, clone, modify, and delete fields as strings outlined above. Other category update fields/elements are required by or interpreted based on the operation.

Examples

<categoryUpdates>
  <categoryUpdate entityTypeName="SERVICE_GROUP" categoryName="TEST-A" create="AS_ROOT"/>
  <categoryUpdate entityTypeName="SERVICE_GROUP" categoryName="TEST-B" create="AS_CHILD" parentName="TEST-A"/>
  <categoryUpdate entityTypeName="SERVICE_GROUP" categoryName="TEST-C" create="AS_CHILD" parentName="TEST-B"/>
  <categoryUpdate entityTypeName="SERVICE_GROUP" categoryName="TEST-C" clone="AS_LEAF_WITH_PARENTS" cloneName="TEST-D"/>
  <categoryUpdate entityTypeName="SERVICE_GROUP" categoryName="TEST-D" modify="ROOT"/>
  <categoryUpdate entityTypeName="SERVICE_GROUP" categoryName="TEST-D" modify="ADD_CHILD">
    <otherCategoryNames>
      <categoryName>TEST-A</categoryName>
    </otherCategoryNames>
  </categoryUpdate>
  <categoryUpdate entityTypeName="SERVICE_GROUP" categoryName="TEST-A" modify="REMOVE_CHILDREN">
    <otherCategoryNames>
      <categoryName>TEST-D</categoryName>
    </otherCategoryNames>
  </categoryUpdate>
</categoryUpdates>

{
  "categoryUpdates" : [ {
    "entityTypeName" : "SERVICE_GROUP",
    "categoryName" : "TEST-A",
    "create" : "AS_ROOT"
  }, {
    "entityTypeName" : "SERVICE_GROUP",
    "categoryName" : "TEST-B",
    "create" : "AS_CHILD",
    "parentName" : "TEST-A"
  }, {
    "entityTypeName" : "SERVICE_GROUP",
    "categoryName" : "TEST-C",
    "create" : "AS_CHILD",
    "parentName" : "TEST-B"
  }, {
    "entityTypeName" : "SERVICE_GROUP",
    "categoryName" : "TEST-C",
    "clone" : "AS_LEAF_WITH_PARENTS",
    "cloneName" : "TEST-D"
  }, {
    "entityTypeName" : "SERVICE_GROUP",
    "categoryName" : "TEST-D",
    "modify" : "ROOT"
  }, {
    "entityTypeName" : "SERVICE_GROUP",
    "categoryName" : "TEST-D",
    "modify" : "ADD_CHILD",
    "otherCategoryNames" : [ "TEST-A" ]
  }, {
    "entityTypeName" : "SERVICE_GROUP",
    "categoryName" : "TEST-A",
    "modify" : "REMOVE_CHILDREN",
    "otherCategoryNames" : [ "TEST-D" ]
  } ]
}
8.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
8.3.3 HTTP Status Codes

200 - Categories were deleted successfully
500 - An internal server error occurred

8.3.4 Example Responses

XML and JSON examples are successful responses to 7 operations in the request examples above.

Note that the results collection also returns the location of the created, cloned, or modified category which can be directly used by the GET operation. Deleted categories successful results include a message indicating such. Result entities are formed by the concatenation of the category and entity type names.

<results successful="7" failed="0" entityType="Category" operation="Update" warning="0" count="7">
  <result>
    <entity>TEST-A:SERVICE_GROUP</entity>
    <location>http://localhost:8080/foundation-webapp/api/categories/TEST-A/SERVICE_GROUP</location>
    <status>success</status>
  </result>
  <result>
    <entity>TEST-B:SERVICE_GROUP</entity>
    <location>http://localhost:8080/foundation-webapp/api/categories/TEST-B/SERVICE_GROUP</location>
    <status>success</status>
  </result>
  <result>
    <entity>TEST-C:SERVICE_GROUP</entity>
    <location>http://localhost:8080/foundation-webapp/api/categories/TEST-C/SERVICE_GROUP</location>
    <status>success</status>
  </result>
  <result>
    <entity>TEST-C:SERVICE_GROUP</entity>
    <location>http://localhost:8080/foundation-webapp/api/categories/TEST-C/SERVICE_GROUP</location>
    <status>success</status>
  </result>
  <result>
    <entity>TEST-D:SERVICE_GROUP</entity>
    <location>http://localhost:8080/foundation-webapp/api/categories/TEST-D/SERVICE_GROUP</location>
    <status>success</status>
  </result>
</results>

{
  "successful" : 7,
  "failed" : 0,
  "entityType" : "Category",
  "operation" : "Update",
  "warning" : 0,
  "count" : 7,
  "results" : [ {
    "entity" : "TEST-A:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-A/SERVICE_GROUP"
  }, {
    "entity" : "TEST-B:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-B/SERVICE_GROUP"
  }, {
    "entity" : "TEST-C:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-C/SERVICE_GROUP"
  }, {
    "entity" : "TEST-C:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-C/SERVICE_GROUP"
  }, {
    "entity" : "TEST-D:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-D/SERVICE_GROUP"
  }, {
    "entity" : "TEST-D:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-D/SERVICE_GROUP"
  }, {
    "entity" : "TEST-A:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-A/SERVICE_GROUP"
  } ]
}
8.4 Add/Delete Category Members

Adds or deletes category members/entities. Adding category members can also be done by saving categories, but these operations must be used to delete.

8.4.1 Method: PUT with POST Data
  1. add category members
    PUT /api/categories/addmembers
  2. delete category members
    PUT /api/categories/deletemembers

The post data for both adding and deleting should be formatted like a POST payload, but the only valid fields are the category and entity type names.

Examples

<category name="TEST-B" entityTypeName="SERVICE_GROUP">
  <entities>
    <entity objectID="2048" entityTypeName="SERVICE_STATUS"/>
  </entities>
</category>

{
  "name" : "TEST-B",
  "entityTypeName" : "SERVICE_GROUP",
  "entities" : [ {
    "objectID" : 2048,
    "entityTypeName" : "SERVICE_STATUS"
  } ]
}
8.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
8.4.3 HTTP Status Codes

200 - Category member entities were added or deleted successfully
500 - An internal server error occurred

8.4.4 Example Responses

Note that the result entities are formed by the concatenation of the category and entity type names.

<results successful="1" failed="0" entityType="Category" operation="Update" warning="0" count="1">
  <result>
    <entity>TEST-B:SERVICE_GROUP</entity>
    <location>http://localhost:8080/foundation-webapp/api/categories/TEST-B/SERVICE_GROUP</location>
    <status>success</status>
  </result>
</results>

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "Category",
  "operation" : "Update",
  "warning" : 0,
  "results" : [ {
    "entity" : "TEST-B:SERVICE_GROUP",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/categories/TEST-B/SERVICE_GROUP"
  } ],
  "count" : 1
}
8.5 Delete Categories

Deletes one or more categories from the Collage database. Deletes are specified with POST data, passing in category and entity type names.

Note that while deleting hierarchy categories is supported for backward compatibility, this is not recommended. Hierarchical category delete operations should be carried out using the hierarchy-specific APIs documented above.

8.5.1 Method: DELETE with POST Data

DELETE /api/categories

The post data should be formatted like a POST payload, but the only required fields are the category and entity type names.

Examples

<categories>
  <category name="west-region" entityTypeName="SERVICE_GROUP"/>
  <category name="east-region" entityTypeName="SERVICE_GROUP"/>
</categories>

{
  "categories" : [ {
    "name" : "TEST-A",
    "entityTypeName" : "SERVICE_GROUP"
  } ]
}
8.5.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
8.5.3 HTTP Status Codes

200 - Categories were deleted successfully
500 - An internal server error occurred

8.5.4 Example Responses

Note that the result entities are formed by the concatenation of the category and entity type names.

<results successful="2" failed="0" entityType="Category" operation="Delete" warning="0" count="2">
  <result>
    <entity>west-region:SERVICE_GROUP</entity>
    <message>Category deleted.</message>
    <status>success</status>
  </result>
  <result>
    <entity>east-region:SERVICE_GROUP</entity>
    <message>Category deleted.</message>
    <status>success</status>
  </result>
</results>

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "Category",
  "operation" : "Delete",
  "warning" : 0,
  "count" : 1,
  "results" : [ {
    "entity" : "TEST-A:SERVICE_GROUP",
    "status" : "success",
    "message" : "Category deleted."
  } ]
}
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.