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.

query for first page of all device template profiles
GET /api/devicetemplateprofiles?count=25
query for SERVER's device template profile
GET /api/devicetemplateprofiles/SERVER
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
}