© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 1 of 28
API Programmer Guide for Cisco Digital Signs
Cisco Digital Media Suite 5.2.0
API Programmer Guide for Cisco Digital Signs
Version 0.8.5 Revised: September 13, 2010
Contents About This Guide ................................................................................................................ 2
Who Should Use This Guide ................................................................................................ 2
Introduction to Cisco DMS APIs .......................................................................................... 2
Getting Started ................................................................................................................... 2
Installation Notes ............................................................................................................ 3
Before You Begin ............................................................................................................ 3
Checking API Status ........................................................................................................ 4
Workflow ........................................................................................................................ 4
Making a Web Service Call .............................................................................................. 4
Digital Signs APIs ................................................................................................................. 5
DMP Groups .................................................................................................................... 6
DMPs ............................................................................................................................. 10
Content Asset Provisioning ........................................................................................... 14
Application provisioning ............................................................................................... 18
Playlist Provisioning ...................................................................................................... 19
Insertions and Requestors ............................................................................................ 21
Proof of Play .................................................................................................................. 25
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 2 of 28
Schedule Provisioning ................................................................................................... 26
Emergency .................................................................................................................... 27
About This Guide
Cisco Digital Signs is one component of Cisco Digital Media Suite (Cisco DMS). This guide describes Cisco APIs for third-party application developers whose products should extend or interoperate with Cisco Digital Signs. These APIs are a mechanism to insert, retrieve, update, and remove data. Similar guides on Cisco.com describe the APIs for other components of Cisco Digital Media Suite, such as Cisco Show and Share.
Who Should Use This Guide
This guide is a technical resource for application developers who build custom user interfaces, workflows, and vertical-specific applications that extend Cisco Digital Signs. You should have an advanced level of understanding of web technology, operation, and terminology and be familiar with Cisco Digital Signs. Application developers who use this application programming interface (API) should also have an understanding of a high-level programming language, such as Java or an equivalent language. Additionally, we recommend that you have knowledge of the following:
● XML and XML Schema
● Representational State Transfer (REST) and RESTful Services
You should be familiar with using Cisco Digital Signs to manage your digital signage network. In most cases, API operations correlate to GUI operations.
Introduction to Cisco DMS APIs
This API uses the REST architecture, which leverages XML, HTTP, and HTTPS. This API executes requests by sending XML data to the API server. The server returns an XML response that combines an encoded REST message with an HTTP status code that states whether your request succeeded or failed. You can use this API to perform some of the same operations that are available in the web-based user interface for Cisco Digital Signs.
NOTE
Our implementations of Cisco DMS APIs might change over time in response to the changing needs of our partner community. We will maintain backward compatibility whenever possible but we encourage you to expect differences in future releases.
Getting Started
Topics in this section describe how to begin provisioning services with this API, verify the status of the API, and learn the steps in a typical workflow.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 3 of 28
Installation Notes
Cisco Digital Signs includes all components for its own API. Aside from the requirement for a Cisco Digital Media Manager (DMM) appliance that is configured and operating correctly, this API imposes no additional startup or shutdown requirements. The only user interfaces for this API are XML-encoded messages.
Before You Begin
ATTENTION
All applications that use API calls for Cisco Digital Signs must pass their XML data with the content type set to application/xml.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 4 of 28
Checking API Status
NOTE
Cisco Systems neither supports nor offers any warranties for DMS API Tester. Our partner community built and maintains this software utility.
To test the APIs:
1. Download the Adobe AIR runtime from http://get.adobe.com/air/ and install it on your
computer.
2. Download DMS_API_Tester.air from http://developer.cisco.com
3. Install DMS_API_Tester.air., and then open it.
4. Complete these steps in DMS API Tester:
a. Enter the fully qualified domain name (FQDN) of your DMM appliance in the Hostname
field. For example: digitalsigns.cisco.com
b. Enter the administrator’s username. For example: superuser
c. Enter the administrator’s password.
d. Choose xTAS-core/services/ From the Service list.
e. Choose dmpGroup_getAll from the Template list.
f. Click Submit.
g. Accept the security alert.
h. Verify that you receive a response like this one:
<?xml version="1.0" encoding="UTF-8"?>
<DmpGroup>
<id>4</id>
<name>ALL DMPs</name>
<uri>http://:8080/xTAS-core/services/dmp/dmps/4/</uri>
</DmpGroup>
Workflow
Each Digital Signs API call requires user authentication through the HTTP Basic Authentication method. Your application should pass in the username and password on each API call to guarantee a valid logged in user. All Digital Signs APIs (except multipart file uploads) support and should use HTTPS over port 8443.
Making a Web Service Call
The simplest way to make a web service call is to install the DMS API Tester AIR application. See Checking API Status above. This application helps you to test your API calls.
ATTENTION
Digital Signs uses a self-signed SSL certificate in Cisco DMS 5.2. This triggers a security alert when the first request is made using the DMS API Tester. You must accept this warning manually every time you launch the DMS API Tester and you must also ensure programmatically that your API calls accept this self-signed certificate.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 5 of 28
Digital Signs APIs
Topics in this section describe APIs for operations that are specific to Cisco Digital Signs. These APIs are RESTful. This means that:
You must set the content type for each request to “application/xml”.
Each request leverages some combination of POSTs, GETs, PUTs, and DELETEs.
Additionally, there are four main base URL entry points for Digital Signs servicers.
/xTAS-core/services/
/xTAS-core/api/rest/
/proofofplay_core/services/
/proofofplay_campaign/services/
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 6 of 28
DMP Group Provisioning
DMPs are organized in logical groups. This approach favors simultaneous deployments to all members of a DMP group. A less efficient and scalable approach is to schedule sequential deployments that target individual DMPs one-by-one.
Get All DMP Groups
This API returns the hierarchy of your DMP groups. The “ALL DMPs” group at the root of this hierarchy contains all DMPs that are known to your DMM appliance.
ACTION GET
URL /xTAS-core/services/dmpgroup/hierarchy/all/
PREREQUISITES N/A
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Add DMP Group
This API allows for the creation of a new DMP group.
ACTION POST
URL /xTAS-core/services/dmpgroup/dmpgroups/
PREREQUISITES
parentId: the ID of the parent group
name: the name of the dmp group
description: the description of the group
REQUEST <n1:dmpGroup xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/dmpManagement">
<name>____DMP_GROUP_NAME____</name>
<parentId>____DMP_GROUP_PARENT_ID____</parentId>
<description>____DMP_GROUP_DESCRIPTION____</description>
</n1:dmpGroup>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
NOTE
We do not perform any validation for the parent ID value. Please ensure that you pass only valid parent IDs.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 7 of 28
Update a DMP Group
This API allows one to update a DMP group.
ACTION PUT
URL /xTAS-core/services/dmpgroup/dmpgroups/{id}
PREREQUISITES
id: the ID of the dmp group
parentId: the id of the parent group
name: the name of the dmp group
description: the description of the group
REQUEST
<n1:dmpGroup xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/dmpManagement">
<id>____DMP_GROUP_ID____</id>
<name>____DMP_GROUP_NAME____</name>
<parentId>____DMP_GROUP_PARENT_ID____</parentId>
<description>____DMP_GROUP_DESCRIPTION____</description>
</n1:dmpGroup>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
NOTE
Update DMP Group only updates: name, description, and title. It does not update parent Id.
Delete a DMP Group
This API allows for the deletion of a new DMP group.
ACTION DELETE
URL /xTAS-core/services/dmpgroup/dmpgroups/{id}
PREREQUISITES N/A
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Get DMPs that belong to a group
This API allows for fetching all the DMPs that belong to a particular DMP Group.
ACTION GET
URL /xTAS-core/services/dmpgroup/dmps/dmpgroup/{id}
PREREQUISITES
id: the ID of the group.
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 8 of 28
Assign DMPs to a DMP groups
This API allows for assigning existing DMP(s) to existing DMP Group(s).
ACTION PUT
URL /xTAS-core/services/dmpgroup/dmpdmpgroup
PREREQUISITES
associationAction: make sure this set to “set”
dmpIdList id: the ids of the dmps you want to add to the dmp groups
dmpGroupIdList id: the ids of the dmp groups you want the dmps added to.
REQUEST
<n1:dmpGroupToDmpAssociation xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/dmpManagement">
<associationAction>set</associationAction>
<dmpIdList>
<id>____DMP_ID_1____</id>
<id>____DMP_ID_2____</id>
</dmpIdList>
<dmpGroupIdList>
<id>____DMP_GROUP_ID_1____</id>
<id>____DMP_GROUP_ID_2____</id>
</dmpGroupIdList>
</n1:dmpGroupToDmpAssociation>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Unassign DMP from DMP Group
This API allows for removing existing DMP(s) from existing DMP Group(s).
ACTION PUT
URL /xTAS-core/services/dmpgroup/dmpdmpgroup
PREREQUISITES
associationAction: make sure this set to “unset”
dmpIdList id: the ids of the dmps you want to remove from the dmp groups
dmpGroupIdList id: the ids of the dmp groups you want the dmps removed from.
REQUEST
<n1:dmpGroupToDmpAssociation xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/dmpManagement">
<associationAction>unset</associationAction>
<dmpIdList>
<id>____DMP_ID_1____</id>
<id>____DMP_ID_2____</id>
</dmpIdList>
<dmpGroupIdList>
<id>____DMP_GROUP_ID_1____</id>
<id>____DMP_GROUP_ID_2____</id>
</dmpGroupIdList>
</n1:dmpGroupToDmpAssociation>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 9 of 28
Assigning DMP configuration parameters to DMP Groups
This API sets configuration parameter(s) to all the DMPs in a DMP group.
ACTION PUT
URL /xTAS-core/services/dmpgroup/dmpgroupsconfig/
PREREQUISITES
dmpGroupIdList id: the ids of the dmp groups you want the dmps removed from.
Valid parameter(s) and value(s) to set and in the correct order
REQUEST
<n1:dmpConfigure xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/dmpManagement">
<dmpGroupIdList>
<id>____DMP_GROUP_ID_1____</id>
<id>____DMP_GROUP_ID_2____</id>
</dmpGroupIdList>
<parameters>
<nvp>
<name>____MIB_1____</name>
<value>____MIB_VALUE_1____</value>
</nvp>
<nvp>
<name>____MIB_2____</name>
<value>____MIB_VALUE_2____</value>
</nvp>
</parameters>
</n1:dmpConfigure>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
NOTE
The values and parameters are defined in the Digital Media Player API documentation.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 10 of 28
DMP Provisioning
DMPs are the most granular target that can be used to deploy an application to a screen.
Get DMP Details
This API gives details about the DMP configuration: Name, IP address, MAC address, description and status (up or down).
ACTION GET
URL /xTAS-core/services/dmp/dmps/{id}
PREREQUISITES
id: the ID of the dmp
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Add a DMP
This API allows you to add a DMP to Digital Signs
ACTION POST
URL /xTAS-core/services/dmp/dmps
PREREQUISITES
name: the name of the dmp you are adding
ipAddress: the ip address of the dmp you are adding
macAddress: the mac address of the dmp you are adding
description: the description of the dmp you are adding
REQUEST
<n1:dmp xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/dmpManagement">
<name>____DMP_NAME____</name>
<ipAddress>____DMP_IP____</ipAddress>
<macAddress>____DMP_MAC_ADDRESS___</macAddress>
<description>____DMP_DESCRIPTION____</description>
</n1:dmp>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 11 of 28
Update DMP
This API allows you to update a DMP that is already in Digital Signs.
ACTION PUT
URL /xTAS-core/services/dmp/dmps/{id}
PREREQUISITES
id: the ID of the dmp you are updating
name: the name of the dmp you are adding
ipAddress: the ip address of the dmp you are adding
macAddress: the mac address of the dmp you are adding
description: the description of the dmp you are adding
REQUEST
<n1:dmp xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/dmpManagement">
<id>____DMP_ID____</id>
<name>____DMP_NAME____</name>
<ipAddress>____DMP_IP____</ipAddress>
<macAddress>____DMP_MAC_ADDRESS___</macAddress>
<description>____DMP_DESCRIPTION____</description>
</n1:dmp>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Delete DMP
This API allows you to delete a DMP from Digital Signs
ACTION DELETE
URL /xTAS-core/services/dmp/dmps/{id}
PREREQUISITES
id: the id of the dmp
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Get DMP process status
This API gets the status of the processes running on a DMP.
ACTION GET
URL /xTAS-core/services/dmp/dmpprocesses/{id}
PREREQUISITES
id: the ID of the DMP
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 12 of 28
Get DMP settings
This API gets all the settings of a DMP
ACTION GET
URL /xTAS-core/services/dmp/dmpsettings/{id}
PREREQUISITES
id: the ID of the dmp
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Assign configuration parameters to DMP(s)
This API sets configuration parameters on DMP(s).
ACTION PUT
URL /xTAS-core/services/dmp/dmpsconfig/
PREREQUISITES
dmpGroupIdList id: the ids of the dmp groups you want the dmps removed from.
Valid parameter(s) and value(s) to set and in the correct order
REQUEST <n1:dmpConfigure
xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/dmpManagement">
<dmpIdList>
<id>____DMP_ID_1____</id>
<id>____DMP_ID_2____</id>
</dmpIdList>
<parameters>
<nvp>
<name>____MIB_1____</name>
<value>____MIB_VALUE_1____</value>
</nvp>
<nvp>
<name>____MIB_2____</name>
<value>____MIB_VALUE_2____</value>
</nvp>
</parameters>
</n1:dmpConfigure>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
NOTE
The values and parameters are defined in the Digital Media Player API documentation.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 13 of 28
Publish application to a DMP
This API publishes an application to a DMP.
ACTION POST
URL /xTAS-core/api/rest/application/{app_id}/dmp/{dmp_id}
PREREQUISITES
app_id: the ID of athe application you want to publish
dmp_id: the ID of the dmp you want the application published to
REQUEST <application/>
RESULT The intended audience for this programmer guide can anticipate and understand the
result that this API call returns. Nonetheless, we might document this result in a future
revision to this guide.
NOTE
We do not validate the DMP ID . Therefore, this API will return an HTTP status code “200 OK” message even when you pass an DMP ID that is not valid.
Please ensure that you pass the “<application/>” tag, if you do not pass it you will get a 404 Not Found exception.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 14 of 28
Content Asset Provisioning
Assets in Digital Signs are files that are used to create applications. Assets can not directly be deployed to DMPs. Assets have to be wrapped in applications to be deployed to DMPs. The smallest application that can be deployed to a sign is a single asset inside of a playlist (playlist is an application). These APIs allow for the creation and management of Digital Signs’ assets.
Get Category Tree
Assets are organized in hierarchical categories. Each asset can only belong to one category branch. This API is used to identify each category.
ACTION GET
URL /xTAS-core/services/content/categories/
PREREQUISITES N/A
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the
result that this API call returns. Nonetheless, we might document this result in a future
revision to this guide.
NOTE
In Cisco DMS 5.2, you cannot use this API to add, update or delete asset categories.
Get Content Asset List for a Category
This API returns a list of the assets in a particular category.
ACTION GET
URL /xTAS-core/services/content/assets/category/{id}
PREREQUISITES id: the ID of the category
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 15 of 28
Upload an Asset
This API is used to create a new asset in the Digital Signs’ media library by uploading a file. Uploading an asset is done through a multi-part form. This multipart form uploads a file with the input name “upfile” and also the xml with the input name “data”.
ACTION POST
URL /xTAS-core/services/content/assets/
PREREQUISITES title: the title for the asset
filename: the file’s name
description: the description of the file
fileType: can be FLASH, HTML, IMAGES,UDP, or VIDEO
estimatedDuration: the default amount of time the asset should stay on screen
categoryIdList id: the ID of the category the asset should belong to
assetOwner: the username of the owner adding the asset
REQUEST This sample HTML file shows how to upload an asset:
<html>
<body>
<form action="http://____YOUR_HOSTNAME____:8080/xTAS-
core/services/content/assets/" enctype="multipart/form-data"
method="POST">
File to upload:
<input type="file" name="upload_file"/>
<br/>
data:
<textarea cols="40" rows="20" name="data"></textarea>
<br/>
<input type="submit" value="Upload"/>
</form>
</body>
</html>
“data” should be of the XML format:
<n1:asset
xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/contentManagement"
>
<title>____ASSET_TITLE____</title>
<fileName>____ASSET_FILE_NAME___</fileName>
<description>____ASSET_DESCRIPTION____</description>
<fileType>____VALID_FILE_TYPE____</fileType>
<estimatedDuration>
<Hours>0</Hours>
<Minutes>0</Minutes>
<Seconds>0</Seconds>
</estimatedDuration>
<categoryIdList>
<id>____CATEGORY_ID____</id>
</categoryIdList>
<assetOwner>____USER_NAME____</assetOwner>
<storageType>file</storageType>
<downloadurl>true</downloadurl>
</n1:asset>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 16 of 28
Add Asset from URL
This API is used to create a new asset in the Digital Signs’ media library from a valid URL. Uploading an asset is done through a multi-part form. This multipart form only contains an xml with the input name “data”.
ACTION POST
URL /xTAS-core/services/content/assets/
PREREQUISITES
title: thte title for the asset
filename: the url to the file
description: the description of the file
fileType: can be FLASH, HTML, IMAGES,UDP, or VIDEO
estimatedDuration: the default amount of time the asset should stay on screen
categoryIdList id: the ID of the category the asset should belong to
assetOwner: the username of the owner adding the asset
REQUEST This sample HTML illustrates how to upload an asset:
<html>
<body>
<form action="http://____YOUR_HOSTNAME____:8080/xTAS-
core/services/content/assets/" enctype="multipart/form-data"
method="POST">
data:
<textarea cols="40" rows="20" name="data"></textarea>
<br/>
<input type="submit" value="Upload"/>
</form>
</body>
</html>
“data” should be of the xml format:
<n1:asset
xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/contentManagement"
>
<title>____ASSET_TITLE____</title>
<fileName>____ASSET_FILE_NAME___</fileName>
<description>____ASSET_DESCRIPTION____</description>
<fileType>____VALID_FILE_TYPE____</fileType>
<estimatedDuration>
<Hours>0</Hours>
<Minutes>0</Minutes>
<Seconds>0</Seconds>
</estimatedDuration>
<categoryIdList>
<id>____CATEGORY_ID____</id>
</categoryIdList>
<assetOwner>____USER_NAME____</assetOwner>
<storageType>url</storageType>
<downloadurl>true</downloadurl>
</n1:asset>
NOTE
● Titles must be unique and cannot be blank.
● Please ensure that your DMM appliance can resolve any URL that you use the API to pass. Verify that DNS settings are correct in the Application Administration Interface (AAI) command shell.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 17 of 28
Get Asset Details
This API returns details about a specific asset.
ACTION GET
URL /xTAS-core/services/content/assets/{id}
PREREQUISITES
id: the asset ID
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Update Asset
This API helps you to edit the metadata for a specific asset.
ACTION POST
URL /xTAS-core/services/content/assets/
PREREQUISITES
The asset details should be retrieved first using “Get Asset details” API above
REQUEST This sample HTML illustrates how to upload an asset:
<html>
<body>
<form action="http://____YOUR_HOSTNAME____:8080/xTAS-
core/services/content/assets/" enctype="multipart/form-data"
method="POST">
data:
<textarea cols="40" rows="20" name="data"></textarea>
<br/><input type="submit" value="Upload"/>
</form>
</body>
</html>
“data” should be of the xml format:
<n1:editAsset
xmlns:n1="http://www.cisco.com/dms/xml/ns/dsm/contentMan
agement">
<id>____ASSET_ID____</id>
<assetBasic>
<title>____ASSET_TITLE____</title>
<fileName>____ASSET_FILE_NAME___</fileName>
<description>____ASSET_DESCRIPTION____</description>
<fileType>____VALID_FILE_TYPE____</fileType>
<estimatedDuration>
<Hours>0</Hours>
<Minutes>0</Minutes>
<Seconds>0</Seconds>
</estimatedDuration>
<categoryIdList>
<id>____CATEGORY_ID____</id>
</categoryIdList>
<assetOwner>____USER_NAME____</assetOwner>
<storageType>____url_OR_file____</storageType>
<downloadurl>true</downloadurl>
</assetBasic>
<keepexisting>true</keepexisting>
</n1:editAsset>
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 18 of 28
Delete Asset
This API helps you to delete an asset from the media library.
ACTION DELETE
URL /xTAS-core/services/content/assets/{id}
PREREQUISITES
id: the asset ID
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Application Provisioning
Applications are the smallest unit in Digital Signs that can be deployed to a DMP or a DMP group.
NOTE
Except for the Playlist application, DMS 5.2 APIs do not expose the creation or deletion of applications.
Get all Applications
This API returns a list of all applications.
ACTION GET
URL /xTAS-core/services/app/apps/
PREREQUISITES N/A
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 19 of 28
Application Provisioning - Playlists
A playlist is a Digital Signs application which plays and loops Digital Signs assets.
Add a Playlist
This API helps you to create a playlist.
ACTION POST
URL /xTAS-core/api/rest/playlist
PREREQUISITES
resolution: e.g. 1024X768
randomize: “true” if the playlist order should be random, otherwise “false”
popEnable: “true” if proof of play should be used on this playlist, otherwise “false”
description: the description of the playlist
title: the title of the playlist
hours: can be set to 0, or the amount of hours for the asset to stay on screen
minutes: can be set to 0, or the amount of minutes for the asset to stay on screen
seconds: can be set to 0, or the amount of seconds for the asset to stay on screen
assetId: the asset to be used
REQUEST <n2:playlist
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:n2="http://www.cisco.com/dms/xml/ns/playlistManage
ment">
<n2:resolution>____RESOLUTION____</n2:resolution>
<n2:randomize>____IS_RANDOMIZED____</n2:randomize>
<n2:popEnable>____IS_POP_ENABLED____</n2:popEnable>
<n2:description>____DESCRIPTION____</n2:description>
<n2:owner>____USERNAME____</n2:owner>
<n2:title>____TITLE____</n2:title>
<n2:playlistItems>
<n2:item>
<n2:plannedDuration>
<n2:hours>____HOURS____</n2:hours>
<n2:minutes>____MINUTES____</n2:minutes>
<n2:seconds>____SECONDS____</n2:seconds>
</n2:plannedDuration>
<n2:asset>
<n2:assetId>____ASSET_ID____</n2:assetId>
</n2:asset>
</n2:item>
</n2:playlistItems>
</n2:playlist>
RESULT The intended audience for this programmer guide can anticipate and understand the
result that this API call returns. Nonetheless, we might document this result in a future
revision to this guide.
Get playlist details
This API returns information about a particular playlist.
ACTION GET
URL /xTAS-core/api/rest/playlist/detail/{id}
PREREQUISITES id: the ID of the playlist
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 20 of 28
Edit a playlist
This API helps you to edit a playlist
ACTION PUT
URL /xTAS-core/api/rest/playlist/{id}
PREREQUISITES
id: the ID of the playlist
resolution: e.g. 1024X768
randomize: “true” if the playlist order should be random, otherwise “false”
popEnable: “true” if proof of play should be used on this playlist, otherwise “false”
description: the description of the playlist
title: the title of the playlist
hours: can be set to 0, or the amount of hours for the asset to stay on screen
minutes: can be set to 0, or the amount of minutes for the asset to stay on screen
seconds: can be set to 0, or the amount of seconds for the asset to stay on screen
assetId: the asset to be used
REQUEST <n2:playlist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:n2="http://www.cisco.com/dms/xml/ns/playlistManagement">
<n2:id>____PLAYLIST_ID____</n2:id>
<n2:resolution>____RESOLUTION____</n2:resolution>
<n2:randomize>____IS_RANDOMIZED____</n2:randomize>
<n2:popEnable>____IS_POP_ENABLED____</n2:popEnable>
<n2:description>____DESCRIPTION____</n2:description>
<n2:owner>____USERNAME____</n2:owner>
<n2:title>____TITLE____</n2:title>
<n2:playlistItems>
<n2:item>
<n2:plannedDuration>
<n2:hours>____HOURS____</n2:hours>
<n2:minutes>____MINUTES____</n2:minutes>
<n2:seconds>____SECONDS____</n2:seconds>
</n2:plannedDuration>
<n2:asset>
<n2:assetId>____ASSET_ID____</n2:assetId>
</n2:asset>
</n2:item>
</n2:playlistItems>
</n2:playlist>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Delete playlist
This API helps you to delete a playlist.
ACTION DELETE
URL /xTAS-core/api/rest/playlist/{id}
PREREQUISITES id: the ID of the playlist
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 21 of 28
Insertion and Requestor Provisioning
Cisco DMS 5.2 introduces two new concepts: Insertions and Requestors. A Requestor is a named entity that makes use of named Insertions. Insertions are containers for assets. We use information about Requestors and Insertions both, when we generate Proof of Play reports. A note on nomenclature: Insertions and Requestors were previously named Campaigns and Agencies, respectively. While this update in nomenclature is used throughout this document, the API calls themselves still refer to the older terms.
Get All Requestors
This API returns a list of all named Requestors.
ACTION GET
URL /proofofplay_campaign/services/agencies
PREREQUISITES N/A
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Get Requestor detail
This API returns details about a particular Requestor.
ACTION GET
URL /proofofplay_campaign/services/agencies/{id}
PREREQUISITES id: the Requestor id
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Create new Requestor
This API helps you to create a new Requestor.
ACTION POST
URL /proofofplay_campaign/services/agencies
PREREQUISITES
name: the name of the Requestor
description: the description of the Requestor
REQUEST <ns2:agency
xmlns:ns2="http://www.cisco.com/dms/xml/ns/campaignManagement">
<name>____REQUESTOR_NAME____</name>
<description>__REQUESTOR_DESCRIPTION____</description>
</ns2:agency>
RESULT The intended audience for this programmer guide can anticipate and understand the
result that this API call returns. Nonetheless, we might document this result in a future
revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 22 of 28
Edit Requestor
This API helps you to edit the metadata that describes a Requestor.
ACTION PUT
URL /proofofplay_campaign/services/agencies/{id}
PREREQUISITES
id: the ID of the Requestor
name: the name of the Requestor
description: the description of the Requestor
REQUEST <ns2:agency
xmlns:ns2="http://www.cisco.com/dms/xml/ns/campaignManagement">
<name>____REQUESTOR_NAME____</name>
<description>__REQUESTOR_DESCRIPTION____</description>
</ns2:agency>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Delete Requestor
This API helps you to delete a Requestor.
ACTION DELETE
URL /proofofplay_campaign/services/agencies/{id}
PREREQUISITES
id: the ID of the Requestor
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Get list of Insertions
This API is used to get a list of Insertions
ACTION GET
URL /proofofplay_campaign/services/campaigns?start={startValue}&limit={limitValue}
PREREQUISITES
Pagination params are optional. If they exist, they should be >=1
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 23 of 28
Add New Insertion
This API is used to add a new Insertion
ACTION POST
URL /proofofplay_campaign/services/campaigns
PREREQUISITES
name: the name of the insertion
startDate: the start date of the insertion
requestorId: the ID of the Requestor the insertion belongs to
resource id: the ID of the application this insertion should track
REQUEST <ns2:campaign
xmlns:ns2="http://www.cisco.com/dms/xml/ns/campaignManag
ement">
<name>____INSERTION_NAME____</name>
<description>____INSERTION_DESCRIPTION____</description>
<startDate>__START_DATE__YYYY-MM-DD____</startDate>
<endDate>__OPTIONAL_END_DATE__YYYY-MM-DD____</endDate>
<agencyId>____REQUESTOR_ID____</agencyId>
<resources>
<resource>
<id>____APPLICATION_ID____</id>
<resourceType>DSM::APPLICATION</resourceType>
</resource>
</resources>
</ns2:campaign>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Edit Insertion
This API is used to update a particular Insertion.
ACTION PUT
URL /proofofplay_campaign/services/campaigns/{id}
PREREQUISITES
insertionId: the ID of the Insertion
name: the name of the Insertion
startDate: the start date of the Insertion
requestorId: the ID of the Requestor the insertion belongs to
resource id: the ID of the application this insertion should track
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 24 of 28
REQUEST <ns2:campaign
xmlns:ns2="http://www.cisco.com/dms/xml/ns/campaignManag
ement">
<name>____INSERTION_NAME____</name>
<description>___INSERTION_DESCRIPTION____</description>
<startDate>__START_DATE__YYYY-MM-DD____</startDate>
<endDate>__OPTIONAL_END_DATE__YYYY-MM-DD____</endDate>
<agencyId>____REQUESTOR_ID____</agencyId>
<resources>
<resource>
<id>____APPLICATION_ID____</id>
<resourceType>DSM::APPLICATION</resourceType>
</resource>
</resources>
</ns2:campaign>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Delete Insertion
This API is used to delete a particular Insertion.
ACTION POST
URL /proofofplay_campaign/services/campaigns/batchDeletion
PREREQUISITES
insertionId: the ID of the insertion you want to delete
REQUEST <ns2:campaignDeletion
xmlns:ns2="http://www.cisco.com/dms/xml/ns/campaignManagement">
<id>____INSERTION_ID____</id>
</ns2:campaignDeletion>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 25 of 28
Proof of Play
Proof of Play APIs allow you to generate reports for each Insertion.
Get Insertion summary reports
This API returns a summary report for a particular Insertion.
ACTION GET
URL /proofofplay_core/services/reports/ERROR/CAMPAIGN/{id}/fromDate/{YYYYMMDD}/toDate/{YYYYMMDD}/
PREREQUISITES
id: Insertion id
fromDate: desired start date of the report
toDate: desired end date of the report
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Get Insertion success reports
This API returns a success report for a particular Insertion.
ACTION GET
URL /proofofplay_core/services/reports/SUCCESS/CAMPAIGN/{id}/fromDate/{YYYYMMDD}/toDate/{YYYYMMDD}/
PREREQUISITES
id: insertion id
fromDate: desired start date of the report
toDate: desired end date of the report
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Get Insertion error reports
This API returns an error report for a particular Insertion.
ACTION GET
URL /proofofplay_core/services/reports/SUCCESS/CAMPAIGN/{id}/fromDate/{YYYYMMDD}/toDate/{YYYYMMDD}/
PREREQUISITES
id: insertion id
fromDate: desired start date of the report
toDate: desired end date of the report
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 26 of 28
Schedule Provisioning
These APIs help you see future deployments of applications to DMPs.
Get all applications scheduled for a date
This API returns a list of all applications that are scheduled to deploy on a given date.
ATTENTION
This API requires media type to be set to “text/xml” NOT “application/xml”
ACTION GET
URL /xTAS-core/api/rest/scheduler/schedule/date/{YYYY-MM-DD}
PREREQUISITES
date: the date for which you’d like to get the schedule
REQUEST N/A
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 27 of 28
Emergency
These APIs help you to override the saved schedule and publish an emergency application to a group of DMPs.
Start Emergency Messaging
This API starts the emergency.
ACTION POST
URL /xTAS-core/api/rest/emergency/start
PREREQUISITES
emergencyApplication id: the ID of the application to use as an emergency
group id: the ID of the group to which the emergency application applies
REQUEST <singleEmergencyStart
xsi:noNamespaceSchemaLocation="http://www.cisco.com/dms/emergency/xsd/ap
i/Emergency.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<emergencyApplication id="____APPLICATION_ID____">
<groupList>
<group id="____DMP_GROUP_ID____"/>
</groupList>
</emergencyApplication>
</singleEmergencyStart>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
Stop Emergency messaging
This API stops the emergency.
ACTION POST
URL /xTAS-core/api/rest/emergency/stop
PREREQUISITES
group id: the ID of the group to which the emergency application applies
REQUEST <singleEmergencyStop>
<groupList>
<group id="__DMP_GROUP_ID____"/>
</groupList>
</singleEmergencyStop>
RESULT The intended audience for this programmer guide can anticipate and understand the result that this API call returns. Nonetheless, we might document this result in a future revision to this guide.
API Programmer Guide for Cisco Digital Signs
© 2010 Cisco Systems, Inc. All rights reserved. This document is Cisco Public Information. Page 28 of 28
Printed in USA CXX-XXXXXX-XX 01/10
Top Related