CH A P T E R
4
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, page 4-1
•
REST Examples, page 4-4
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.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
4-1
Chapter 4
REST API Function
REST Function Description
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.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
4-2
OL-21552-01
Chapter 4
REST API Function
REST Function Description
Table 4-1
HTTP Library Parameters for the uploadData Function (continued)
Parameter
Type
Description
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.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
4-3
Chapter 4
REST API Function
REST Examples
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, page 4-4
•
Example 2: Uploading a Video File with Debug Output, page 4-5
•
Example 3: Uploading a Photograph URL, page 4-5
•
Example 4: Uploading Journal Text, page 4-6
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
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
4-4
OL-21552-01
Chapter 4
REST API Function
REST Examples
•
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
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
4-5
Chapter 4
REST API Function
REST Examples
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"/>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
4-6
OL-21552-01