21.0 Device Template APIs

WAS THIS PAGE HELPFUL? Leave Feedback

21.0 Device Template Profiles APIs

21.1 Query Device Template Profiles

Retrieve device template profile records by query. Device template profiles provide a mapping between devices and Cacti host templates or Monarch host profiles. Queries would typically be used to drive feeders, administration browsers, and similar tooling. Queried device template profiles, (one or more), are always returned wrapped in an XML <deviceTemplateProfiles> element or JSON object with an deviceTemplateProfiles array member. Getting a single device template profile record is not wrapped.

21.1.1 Method: GET Device Template Profiles

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

21.1.2 Method: GET a Single Device Template Profile by Device Identification

GET /api/devicetemplateprofiles/{deviceIdentification}

21.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, the number of records to include when paging no
deviceIdentification Path the device identification to retrieve yes

If neither the deviceIdentification path parameter nor query query parameter are provided, all device template profile records will be retrieved. The first and count paging parameters can be used to avoid excessive retrieval.

21.1.4 HTTP Headers
Header Valid Values Required
Accept application/xml or application/json False
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
21.1.5 Query Fields

The table below contains valid fields in the value of the 'query' query parameter.

Field Description Alias
deviceTemplateProfileId primary key id
deviceIdentification device identification device
deviceDescription device description description
cactiHostTemplate mapped Cacti host template template
monarchHostProfile mapped Monarch host profile profile

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

21.1.6 Example Queries

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

  1. query for first page of all device template profiles
    GET /api/devicetemplateprofiles?count=25
  2. query for SERVER's device template profile
    GET /api/devicetemplateprofiles/SERVER
  3. query for the second page of device template profiles that start with a prefix, (ordered by deviceIdentification)
    GET /api/devicetemplateprofiles?query=deviceIdentification ilike 'server_%' ORDER BY deviceIdentification&first=25&count=25
21.1.7 HTTP Status Codes
Code Description
200 Query returned no device template profiles
200 Query returned one or more device template profiles
401 Authentication/authorization error occurred
500 An internal server error occurred while querying device template profiles
21.1.8 Example Query Results

Here is an XML example of the result of a query finding device template profiles.

XML query results are always wrapped in an <deviceTemplateProfiles> collection element, with one or more <deviceTemplateProfile> subelements.

<deviceTemplateProfiles>
    <deviceTemplateProfile deviceTemplateProfileId="10" deviceIdentification="test-device-identification-0" deviceDescription="test device identification 0" timestamp="2014-11-25T20:45:33.264-0700"/>
    <deviceTemplateProfile deviceTemplateProfileId="11" deviceIdentification="test-device-identification-1" deviceDescription="test device identification 1" cactiHostTemplate="cacti-host-template" timestamp="2014-11-25T20:45:33.264-0700"/>
    <deviceTemplateProfile deviceTemplateProfileId="12" deviceIdentification="test-device-identification-2" deviceDescription="test device identification 2" monarchHostProfile="monarch-host-profile" timestamp="2014-11-25T20:45:33.264-0700"/>
</deviceTemplateProfiles>

Here is a JSON example of the result of a query finding device template profiles.

JSON query results are always wrapped in an object with a deviceTemplateProfiles array member, with one or more object members.

{
  "deviceTemplateProfiles" : [ {
    "deviceTemplateProfileId" : 13,
    "deviceIdentification" : "test-device-identification-0",
    "deviceDescription" : "test device identification 0",
    "timestamp" : "2014-11-25T20:45:34.229-0700"
  }, {
    "deviceTemplateProfileId" : 14,
    "deviceIdentification" : "test-device-identification-1",
    "deviceDescription" : "test device identification 1",
    "cactiHostTemplate" : "cacti-host-template",
    "timestamp" : "2014-11-25T20:45:34.229-0700"
  }, {
    "deviceTemplateProfileId" : 15,
    "deviceIdentification" : "test-device-identification-2",
    "deviceDescription" : "test device identification 2",
    "monarchHostProfile" : "monarch-host-profile",
    "timestamp" : "2014-11-25T20:45:34.229-0700"
  } ]
}
21.1.9 Example Get Single Results

Here is an XML example of the get device template profile result.

<deviceTemplateProfile deviceTemplateProfileId="11" deviceIdentification="test-device-identification-1" deviceDescription="test device identification 1" cactiHostTemplate="cacti-host-template" timestamp="2014-11-25T20:45:33.264-0700"/>

Here is a JSON example of the get device template profile result.

{
  "deviceTemplateProfileId" : 14,
  "deviceIdentification" : "test-device-identification-1",
  "deviceDescription" : "test device identification 1",
  "cactiHostTemplate" : "cacti-host-template",
  "timestamp" : "2014-11-25T20:45:34.229-0700"
}
21.2 Create or Update Device Template Profiles

Add or update device template profiles by post. Any number of device template profiles can be posted to the server in a single request. Device template profile ids will be generated by the server. Requests are considered updates if the device template profile referenced by the device template profile id or device identification exists. Updates that specify both the id and device identification are assumed to change the device identification. Updates that set the Cacti host template clear the Monarch host profile if set and vice versa.

21.2.1 Method: POST Device Template Profiles

POST /api/devicetemplateprofiles

21.2.2 HTTP Headers
Header Valid Values Required
Content-Type application/xml or application/json True
Accept application/xml or application/json True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
21.2.3 POST Data Example

Here is an XML example post data creating three device template profiles on the server, (the wrapping <devicetemplateprofiles> collection element is always required, even for a single device template profile element):

<deviceTemplateProfiles>
    <deviceTemplateProfile deviceIdentification="test-device-identification-0" deviceDescription="test device identification 0"/>
    <deviceTemplateProfile deviceIdentification="test-device-identification-1" deviceDescription="test device identification 1" cactiHostTemplate="cacti-host-template"/>
    <deviceTemplateProfile deviceIdentification="test-device-identification-2" deviceDescription="test device identification 2" monarchHostProfile="monarch-host-profile"/>
</deviceTemplateProfiles>

Here are XML examples of post data to update device template profiles, (the first changes the device identification primary key, id required, and the second modifies the device description and sets the Monarch host profile):

<deviceTemplateProfiles>
    <deviceTemplateProfile deviceTemplateProfileId="11" deviceIdentification="test-device-identification-1-changed"/>
</deviceTemplateProfiles>
<deviceTemplateProfiles>
    <deviceTemplateProfile deviceIdentification="test-device-identification-1-changed" deviceDescription="test device identification 1 changed" monarchHostProfile="monarch-host-profile"/>
</deviceTemplateProfiles>

Here is a JSON example post data creating three device template profiles, (the wrapping object with the deviceTemplateProfiles array member is always required, even for a single device template profile object):

{
  "deviceTemplateProfiles" : [ {
    "deviceIdentification" : "test-device-identification-0",
    "deviceDescription" : "test device identification 0",
  }, {
    "deviceIdentification" : "test-device-identification-1",
    "deviceDescription" : "test device identification 1",
    "cactiHostTemplate" : "cacti-host-template"
  }, {
    "deviceIdentification" : "test-device-identification-2",
    "deviceDescription" : "test device identification 2",
    "monarchHostProfile" : "monarch-host-profile"
  } ]
}

Here are JSON examples of post data to update device template profiles, (the first changes the device identification primary key, id required, and the second modifies the device description and sets the Monarch host profile):

{
  "deviceTemplateProfiles" : [ {
    "deviceTemplateProfileId" : 14,
    "deviceIdentification" : "test-device-identification-1-changed",
  } ]
}
{
  "deviceTemplateProfiles" : [ {
    "deviceIdentification" : "test-device-identification-1-changed",
    "deviceDescription" : "test device identification 1 changed",
    "monarchHostProfile" : "monarch-host-profile"
  } ]
}
21.2.4 HTTP Status Codes
Code Description
200 Zero or more device template profiles were created or updated
401 Authentication/authorization error occurred
500 An internal server error occurred while creating device template profiles
21.2.5 Example Responses

Here are XML create responses:

<results successful="3" failed="0" entityType="DeviceTemplateProfile" operation="Insert" warning="0" count="3">
    <result><entity>test-device-identification-0</entity><location>http://localhost:8080/foundation-webapp/api/devicetemplateprofiles/test-device-identification-0</location><status>success</status></result>
    <result><entity>test-device-identification-1</entity><location>http://localhost:8080/foundation-webapp/api/devicetemplateprofiles/test-device-identification-1</location><status>success</status></result>
    <result><entity>test-device-identification-2</entity><location>http://localhost:8080/foundation-webapp/api/devicetemplateprofiles/test-device-identification-2</location><status>success</status></result>
</results>
<results successful="0" failed="1" entityType="DeviceTemplateProfile" operation="Insert" warning="0" count="1">
    <result><entity>test-device-identification-fail</entity><message>Failed to create DeviceTemplateProfile: DeviceTemplateProfile with device identification test-device-identification-fail cannot be saved with both a Cacti Host Template and a Monarch Host Profile.</message><status>failure</status></result>
</results>

Here is an XML update response:

<results successful="1" failed="0" entityType="DeviceTemplateProfile" operation="Update" warning="0" count="1">
    <result><entity>test-device-identification-1-changed</entity><location>http://localhost:8080/foundation-webapp/api/devicetemplateprofiles/test-device-identification-1-changed</location><status>success</status></result>
</results>

Here are JSON create responses:

{
  "successful" : 3,
  "failed" : 0,
  "entityType" : "DeviceTemplateProfile",
  "operation" : "Insert",
  "warning" : 0,
  "results" : [ {
    "entity" : "test-device-identification-0",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/devicetemplateprofiles/test-device-identification-0"
  }, {
    "entity" : "test-device-identification-1",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/devicetemplateprofiles/test-device-identification-1"
  }, {
    "entity" : "test-device-identification-2",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/devicetemplateprofiles/test-device-identification-2"
  } ],
  "count" : 3
}
{
  "successful" : 0,
  "failed" : 1,
  "entityType" : "DeviceTemplateProfile",
  "operation" : "Insert",
  "warning" : 0,
  "results" : [ {
    "entity" : "test-device-identification-fail",
    "status" : "failure",
    "message" : "Failed to create DeviceTemplateProfile: DeviceTemplateProfile with device identification test-device-identification-fail cannot be saved with both a Cacti Host Template and a Monarch Host Profile."
  } ],
  "count" : 1
}

Here is a JSON update response:

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "DeviceTemplateProfile",
  "operation" : "Update",
  "warning" : 0,
  "results" : [ {
    "entity" : "test-device-identification-1-changed",
    "status" : "success",
    "location" : "http://localhost:8080/foundation-webapp/api/devicetemplateprofiles/test-device-identification-1-changed"
  } ],
  "count" : 1
}
21.3 Delete or Clear Device Template Profiles

Delete or clear device template profiles by delete. Any number of device template profiles can be deleted to the server in a single request. Device template profile ids or device identifications must be specified as part of the delete url or body request.

21.3.1 Method: Delete Device Template Profiles

DELETE /api/devicetemplateprofiles

21.3.2 Method: Delete Device Template Profiles by Device Identifications

DELETE /api/devicetemplateprofiles/{deviceIdentifications}

21.3.3 HTTP Query and Path Parameters
Field Type Description Required
clear Query A boolean flag to indicate whether the device template or profile should be cleared or if the device template profile should be deleted. Default is false, (delete device template profile). Valid values are true or false. False
deviceIdentifications Path List of device identifications to delete or clear, (comma separated list) True
21.3.4 HTTP Headers
Header Valid Values Required
Content-Type application/xml or application/json True
Accept application/xml or application/json True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
21.3.5 POST Data Example

Here is an XML example post data deleting or clearing two device template profiles on the server, (the wrapping <devicetemplateprofiles> collection element is always required, even for a single device template profile element):

<deviceTemplateProfiles>
    <deviceTemplateProfile deviceTemplateProfileId="11" deviceIdentification="test-device-identification-1-changed" deviceDescription="test device identification 1 changed" monarchHostProfile="monarch-host-profile" timestamp="2014-11-25T20:45:33.674-0700"/>
    <deviceTemplateProfile deviceTemplateProfileId="12" deviceIdentification="test-device-identification-2" deviceDescription="test device identification 2" monarchHostProfile="monarch-host-profile" timestamp="2014-11-25T20:45:33.264-0700"/>
</deviceTemplateProfiles>

Here is a JSON example post data deleting or clearing two device template profiles, (the wrapping object with the deviceTemplateProfiles array member is always required, even for a single device template profile object):

{
  "deviceTemplateProfiles" : [ {
    "deviceTemplateProfileId" : 14,
    "deviceIdentification" : "test-device-identification-1-changed",
    "deviceDescription" : "test device identification 1 changed",
    "monarchHostProfile" : "monarch-host-profile",
    "timestamp":1416973534485
  }, {
    "deviceTemplateProfileId":15,
    "deviceIdentification":"test-device-identification-2",
    "deviceDescription":"test device identification 2",
    "monarchHostProfile":"monarch-host-profile",
    "timestamp":1416973534229
  } ]
}
21.3.6 HTTP Status Codes
Code Description
200 Zero or more device template profiles were deleted or cleared successfully
401 Authentication/authorization error occurred
500 An internal server error occurred while creating device template profiles
21.3.7 Example Responses

Here are XML delete and clear responses:

<results successful="2" failed="0" entityType="DeviceTemplateProfile" operation="Delete" warning="0" count="2">
    <result><entity>11</entity><message>DeviceTemplateProfile deleted</message><status>success</status></result>
    <result><entity>12</entity><message>DeviceTemplateProfile deleted</message><status>success</status></result>
</results>
<results successful="1" failed="0" entityType="DeviceTemplateProfile" operation="Clear" warning="0" count="1">
    <result><entity>18</entity><message>DeviceTemplateProfile cleared</message><status>success</status></result>
</results>

Here are JSON delete responses:

{
  "successful" : 2,
  "failed" : 0,
  "entityType" : "DeviceTemplateProfile",
  "operation" : "Delete",
  "warning" : 0,
  "results" : [ {
    "entity" : "14",
    "status" : "success",
    "message" : "DeviceTemplateProfile deleted"
  }, {
    "entity" : "15",
    "status" : "success",
    "message" : "DeviceTemplateProfile deleted"
  } ],
  "count" : 2
}
{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "DeviceTemplateProfile",
  "operation" : "Clear",
  "warning" : 0,
  "results" : [ {
    "entity" : "21",
    "status" : "success",
    "message" : "DeviceTemplateProfile cleared"
  } ],
  "count" : 1
}