Cisco IPICS API Reference Guide, Release 4.0
REST API Function
Downloads: This chapterpdf (PDF - 124.0KB) The complete bookPDF (PDF - 6.21MB) | Feedback

REST API Function

Table Of Contents

REST API Function

REST Function Description

Function URL

Function Parameters

Return Result

REST Examples

Example 1: Uploading a Video File

Example 2: Uploading a Video File with Debug Output

Example 3: Uploading a Photograph URL

Example 4: Uploading Journal Text


REST API Function


This chapter describes the Cisco IPICS API uploadData function, which is a REST function that uploads a resource (photograph, video, or journal) to the Cisco IPICS server and associates it with an incident.

This chapter includes these topics:

REST Function Description

REST Examples

REST Function Description

The uploadData function uploads a resource (photograph, video, or journal) to the Cisco IPICS server and associates the resource with a designated incident. The resource can be uploaded as a URL or a file (for a photograph or video) or text (for a journal).

This function must be invoked through an HTTP library. You can use a library of your choice.

Before you call this function, you must use the Cisco IPICS API startSession function to start a web services session. When you are finished uploading resources, use the endSession function to end the web services session. For information about these functions, see the "startSession" section on page 2-111 and the "endSession" section on page 2-36.

You can view or download the XML schema for the uploadData function from the following URL. Replace servername with the fully-qualified host name of the Cisco IPICS server if you are using DNS in your deployment, or the IP address of the Cisco IPICS serve, if you are not using DNS.

https://servername/documents/schema1.xsd

Function URL

The URL for the uploadData function is as follows:

https://servername/ipics_server/handsetservice/incident/incidentId/uploaddata

where:

servername—Fully-qualified host name of the Cisco IPICS server if you are using DNS in your deployment, or IP address of the Cisco IPICS server if you are not using DNS.

incidentId—Identifier of the incident with which to associate the resource that you are uploading. You can use the Cisco IPICS API getIncident or the getIncidentDetails function to determine this identifier. For more information, see the "getIncident" section on page 2-58 or the "getIncidentDetails" section on page 2-58.

Function Parameters

Table 4-1 describes the HTTP library parameters for the uploadData function.

Table 4-1 HTTP Library Parameters for the uploadData Function 

Parameter
Type
Description

autoDelete

Request header or parameter of boolean type

Designates whether the system deletes the Cisco IPICS database record for the uploaded resource and the resource file (if the file exists on the Cisco IPICS server) automatically when all incidents with which the resource is associated are deleted.

Valid values are:

true—The database record and the resource file (if it exists) are deleted automatically

false—The database record and the resource file (if it exists) are never deleted automatically

This parameter is optional. By default, the database record and the resource file are not deleted.

body

HTTP POST request

The content of the file, URL, or text of the resource to upload.

This parameter is required.

clientId

Request header or parameter

Unique ID of the developer workstation that you are using to execute the function.

This ID can contain up to 32 characters. You can use any unique ID, for example, the MAC address of the developer workstation.

This parameter is required.

Content-Length

Request header or parameter

Designates the length, in bytes, of the resource that you are uploading.

If you are uploading a file, enter the size of the file. If you are uploading a URL, enter the number of bytes in the URL string.

This parameter is required by the HTTP protocol. You do not need to enter this parameter if your library calculates it automatically.

Content-Type

Request header or parameter

Identifies the type of content that you are sending over HTTP. This parameter must be set to one of the following values:

application/octet-stream—Use this value for photograph or video files

text/plain—Use this value for journals and URLs

This parameter is required.

debug

Request header or parameter

Designates whether the HTTP request is echoed to the developer workstation.

true—The HTTP request is echoed to the developer workstation

false—The HTTP request is not echoed to the developer workstation

This parameter is optional.By default, HTTP requests are not echoed.

description

Request header or parameter

Description of the resource, which appears in the IDC and Cisco IPICS mobile client.

The description can contain up to 255 characters.

This parameter is optional.

documentType

Request header or parameter

The type of resource to upload. Valid values are:

Journal

Photo

Video

This parameter is required.

filename

Request header or parameter

File name of the photograph or video to upload. If the filename exists, the Cisco IPICS server modifies it to make it unique.

This parameter is required for a photograph or video. Do not include this parameter when you are uploading a journal.

referenceType

Request header or parameter

Designates the type of video that you are uploading. Valid values are:

Clip—Use when you are uploading a video file

Stream—Use when you are uploading a URL of a live video

This option required if you are uploading video. It is not used for photographs or resources.

spwd

Request header or parameter

Unique session ID. This ID is generated and returned when you use the startSession function to log in to Cisco IPICS web services and is used for the entire web services session.

This parameter is required.


Return Result

Cisco IPICS returns the following for the uploadData function:

resourceId—Unique identifier that the Cisco IPICS server assigns to the resource that you uploaded

errorCode—One of the following:

SUCCESS—The function executed successfully

FAIL_AUTH—An invalid session ID was specified with the spwd parameter

FAIL_DOCUMENT_NOTSUPPORTED—An invalid value for the DocumentType parameter was specified

FAIL_FIELD_VALIDATION—An invalid parameter was entered

FAIL_FILETOOOBIG—You are attempting to upload a file that is too big to fit on Cisco IPICS server disk, or you are attempting to upload a video file that exceeds that maximum size for a video file that is configured in the Cisco IPICS Administration Console

FAIL_INTERNAL—An internal error occurred

FAIL_IO—The disk on the Cisco IPICS server experienced a problem or the disk is full.

FAIL_MODULECONTEXT—This Cisco IPICS server to which you want to upload the resource is not on line

FAIL_UNSUPPORTED_FILE_FORMAT—You are attempting to upload a photograph or video file that is in a format that Cisco IPICS does not support

WARN_FILENAME_CHANGED—You uploaded a file with the same name as a file that exists on the Cisco IPICS server and the system changed the name of the file that you uploaded

WARN_INCORRECT_MIMETYPE—The Content-Type parameter was not set or was set incorrectly

WARN_INVALID_URL—An invalid URL was entered

REST Examples

The following sections show examples of the uploadData function. These examples use the HTTP curl library, but you can use any HTTP library with this function.

Example 1: Uploading a Video File

Example 2: Uploading a Video File with Debug Output

Example 3: Uploading a Photograph URL

Example 4: Uploading Journal Text

Example 1: Uploading a Video File

The following example shows a request and response when using the uploadData function to upload a video file.

In this example:

The incident ID is 279

The session ID is 1275427188568415217882

The client ID is idc123

The video file to upload is named fire.wmv

Request

curl -X POST http://ipicsserver.com/ipics_server/handsetservice/incident/279/uploaddata 
-H "spwd: 1275427188568415217882" -H "clientId: idc123" -H "filename: fire.wmv" 
-H "documentType: Video" -H "referenceType: Clip" -d @fire.wmv -H "Content-Type: 
application/octet-stream" -H "description: curl video" -H "autoDelete: true"

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><result resourceId="42" 
incidentId="279" errorCode="WARN_FILENAME_CHANGED"/>

Example 2: Uploading a Video File with Debug Output

The following example shows a request and response when using the uploadData function to upload a video file with the debug parameter set to "true":

In this example:

The incident ID is 279

The session ID is 1275427188568415217882

The client ID is idc123

The video file to upload is named fire.wmv

Request

curl -X POST http://ipicsserver.com/ipics_server/handsetservice/incident/279/uploaddata -H 
"spwd: 1275427188568415217882" -H "clientId: idc123" -H "filename: fire.wmv" -H 
"documentType: Video" -H "referenceType: Clip" -d @fire.wmv -H "Content-Type: 
application/octet-stream" -H "description: curl video" -H "autoDelete: true" 
-H "debug: true"

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><result resourceId="39" 
incidentId="279" errorCode="WARN_FILENAME_CHANGED"><request><autoDelete>true 
</autoDelete><description>curl video</description><documentType>Video</documentType> 
<filename>1.279.3fire.wmv</filename><incidentId>279</incidentId><mediaType/><pmcId>idc123<
/pmcId><referenceType>Clip</referenceType><sessionId>1275427188568415217882</sessionId> 
<spectrum>long</spectrum></request></result>

Example 3: Uploading a Photograph URL

The following example shows a request and response when using the uploadData function to upload a photograph URL:

In this example:

The incident ID is 279

The session ID is 1275427188568415217882

The client ID is idc123

The photograph URL to upload is http://www.cisco.com//images/logo.jpg

Request

curl -X POST http://ipicsserver.com/ipics_server/handsetservice/incident/279/uploaddata 
-H "spwd: 1275427188568415217882" -H "clientId: idc123" -H "documentType: Photo" 
-H "Content-Type: text/plain" -H "description: curl photo" 
-d "http://www.cisco.com//images/logo.jpg"

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><result resourceId="42" 
incidentId="279" errorCode="SUCCESS"/>

Example 4: Uploading Journal Text

The following example shows a request and response when using the uploadData function to upload journal text:

In this example:

The incident ID is 279

The session ID is 1275427188568415217882

The client ID is idc123

The journal text to upload is "Here is a new journal entry"

Request

curl -X POST http://ipicsserver.com/ipics_server/handsetservice/incident/279/uploaddata 
-H "spwd: 1275427188568415217882" -H "clientId: idc123" -H "documentType: Journal" 
-H "Content-Type: text/plain" -H "description: journal" -d "Here is a new journal entry"

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><result resourceId="42" 
incidentId="279" errorCode="SUCCESS"/>