CH A P T E R
3
REST-Based API Functions
This chapter describes the Cisco IPICS Representational State Transfer (REST)-based set of operations
API functions. It provides general information and detailed descriptions for each function.
This chapter includes these topics:
•
Function Guidelines, page 3-1
•
Function Summary, page 3-1
•
Function Descriptions, page 3-2
Function Guidelines
When you use the Cisco IPICS REST-based API functions, be aware of the following:
•
Each function must be invoked through an HTTP library. You can use a library of your choice.
•
Before you call a 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-127 and the “endSession” section on page 2-41.
•
You can view or download the XML schema for the REST-based functions 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 Summary
Table 3-1 provides a summary of the Cisco IPICS REST-based API functions. Each function is described
in detail in the section that is listed.
Table 3-1
REST-Based API Function Summary
Function Name and Reference
Description
policy, page 3-3
Executes a designated Cisco IPICS policy
talkgroup/join, page 3-4
Joins the logged in user to the designated talk group
(channel, radio, incident, or VTG)
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
OL-27164-01
3-1
Chapter 3
REST-Based API Functions
Function Descriptions
Table 3-1
REST-Based API Function Summary (continued)
Function Name and Reference
Description
talkgroup/leave, page 3-6
Causes the logged-in user to leave the designated talk
group (channel, radio, incident, or VTG)
uploaddata, page 3-8
Uploads a photograph, video, or journal to the Cisco IPICS
server and associates the resource with a designated
incident
userdirectory, page 3-13
Retrieves a list of all users who are associated with all
radios that use a designated radio descriptor
Function Descriptions
The following sections describe each Cisco IPICS REST-based API function in detail. The function
descriptions provide the following information:
Note
•
Description—Description of the function
•
Request—HTTP method and URI for the function
•
Request payload—Payload—Description of the request payload, if the function requires one
•
Response—Description of the expected response when the operation executes
•
Examples—Sample requests and responses for the operation
The “Function Guidelines” section on page 3-1 provides important information that relates to many of
the functions that the following sections describe.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
3-2
OL-27164-01
Chapter 3
REST-Based API Functions
Function Descriptions
policy
Description
The policy function executes a designated Cisco IPICS policy.
Request
GET https://servername/ipics_server/handsetservice/websvc/policy/policyId?u=username
&p=password
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.
policyId
Identifier of the policy to execute.
You can use the Cisco IPICS API getPolicy function or the getPolicyDetails
function to determine this identifier. For more information, see the
“getPolicy” section on page 2-79 or the “getPolicyDetails” section on
page 2-80.
username
Your Cisco IPICS user name.
password
Your Cisco IPICS password.
Request Payload
The policy function does not require a request payload.
Response
The policy function returns a BooleanVO that contains true if the request is submitted successfully, or
false if it is not.
If an exception occurs when the function executes, the function also returns an ErrorVO, which contains
an explanation of the exception.
Examples
The following example shows a request and responses when using the policy function execute a policy:
Request
GET https://ipicsserver.com/ipics_server/handsetservice/websvc/policy/1234?u=kim&p=abcd
Accept:application/xml
Response if request is submitted successfully
<booleanVO value="true"/>
Response if an exception occurs
<booleanVO value="false">
<errorVO errorCode="Error">
<errorMessages>
validateSession: Database ExceptionSession not found. Invalid Session Id - Session
not found. Invalid Session Id
</errorMessages>
</errorVO>
</booleanVO>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
OL-27164-01
3-3
Chapter 3
REST-Based API Functions
Function Descriptions
talkgroup/join
Description
The talkgroup/join function creates a SIP connection between the designated client and the designated
resource (channel, radio, incident, or VTG).
Request
POST https://servername/ipics_server/handsetservice/websvc/talkgroup/join/resourceId
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.
resourceId
Identifier of the talk group that the logged-in user is to join.
You can use the following Cisco IPICS API function to determine this
identifier:
Request Payload
•
For a channel—getChannel, page 2-59 or getChannelDetails, page 2-60
•
For a radio—getRadioDetails, page 2-82
•
For an incident—getIncident, page 2-65 or getIncidentDetails,
page 2-65
•
For a vtg—getVtgDetails, page 2-98
HTTP library parameters for the request payload of the talkgroup/join function are as follows:
Parameter
Type
Description
pmcId
String
Any unique ID, such as the MAC address, of the client to
be included in the SIP connection. This ID should remain
constant across sessions.
spwd
String
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.
locationId
Number
Identifier of the location in which the client is operating.
resourceId
Number
Identifier of the resource to be included in the connection
with the client.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
3-4
OL-27164-01
Chapter 3
REST-Based API Functions
Function Descriptions
Parameter
Type
Description
resourceType
String
Type of the talk group that the logged-in user is to join.
Valid values are:
connectionType
Response
String
•
Channel
•
Incident
•
ISSIGChannel
•
PooledRadioChannel
•
Radio
•
Vtg
Type of connection for a P25 talk group. Valid values are:
•
NATIVE—Use for a P25 channel in EndToEnd P25
mode
•
PROXYONLY—Use for a P25 channel in Gateway
P25 mode
The talkgroup/join function returns information about the connection that was established.
If an exception occurs when the function executes, the function also returns an ErrorVO, which contains
an explanation of the exception.
Examples
The following example shows a request and responses when using the talkgroup/join function:
Request
POST https://ipicsserver.com/ipics_server/handsetservice/websvc/talkgroup/join/70616
Accept:application/xml
Content-Type: application/x-www-form-urlencoded
pmcId=pmc-ops1user100--12345&spwd=1234567898&locationId=2&resourceId=70000&resourceType=
channel&connectionType=
Response if request is submitted successfully
<mediaConnectionContainerVO pollFreq="0">
<connections tgType="VTG" tgId="1282" state="success" codec="G.729" addrType="sip">
<addresses port="5060" ipaddress="10.194.154.153" dn="199000016590919192" />
<mediaServerType>0</mediaServerType>
</connections>
</mediaConnectionContainerVO>
Response if an exception occurs
<mediaConnectionContainerVO pollFreq="0">
<errorVO errorCode="Error">
<errorMessages>
validateSession: Database ExceptionSession not found. Invalid Session Id - Session
not found. Invalid Session Id
</errorMessages>
</errorVO>
</mediaConnectionContainerVO>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
OL-27164-01
3-5
Chapter 3
REST-Based API Functions
Function Descriptions
talkgroup/leave
Description
The talkgroup/leave function terminates the SIP connection between the designated client and the
designated resource (channel, radio, incident, or VTG).
Request
POST https://servername/ipics_server/handsetservice/websvc/talkgroup/leave/resourceId
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.
resourceId
Identifier of the talk group that the logged-in user is to leave.
You can use the following Cisco IPICS API function to determine this
identifier:
Request Payload
•
For a channel—getChannel, page 2-59 or getChannelDetails, page 2-60
•
For a radio—getRadioDetails, page 2-82
•
For an incident—getIncident, page 2-65 or getIncidentDetails,
page 2-65
•
For a VTG—getVtgDetails, page 2-98
HTTP library parameters for the request payload of the talkgroup/leave function are as follows:
Parameter
Type
Description
pmcId
String
Any unique ID, such as the MAC address, of the client that
is included in the SIP connection to be terminated. This ID
should remain constant across sessions.
spwd
String
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.
locationId
Number
Identifier of the location in which the client is operating.
resourceId
Number
Identifier of the resource that is included in the connection
to be terminated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
3-6
OL-27164-01
Chapter 3
REST-Based API Functions
Function Descriptions
Parameter
Type
Description
resourceType
String
Type of the talk group that the logged-in user is to join.
Valid values are:
connectionType
Response
String
•
Channel
•
Incident
•
ISSIGChannel
•
PooledRadioChannel
•
Radio
•
Vtg
Type of connection for a P25 talk group. Valid values are:
•
NATIVE—Use for a P25 channel in EndToEnd P25
mode
•
PROXYONLY—Use for a P25 channel in Gateway
P25 mode
The talkgroup/leave function returns a BooleanVO that contains true if the connection is terminated or
false if it is not.
If an exception occurs when the function executes, the function also returns an ErrorVO, which contains
an explanation of the exception.
Examples
The following example shows a request and responses when using the talkgroup/leave function:
Request
https://ipicsserver.com/ipics_server/handsetservice/websvc/talkgroup/leave/1282
Accept:application/xml
Content-Type: application/x-www-form-urlencoded
pmcId=pmc123&spwd=123456789&locationId=2&resourceId=1282&resourceType=vtg&connectionType=
Response if request is submitted successfully
<booleanVO value="true"/>
Response if an exception occurs
<booleanVO value="true">
<errorVO errorCode="Error">
<errorMessages>v
alidateSession: Database ExceptionSession not found. Invalid Session Id - Session
not found. Invalid Session Id
</errorMessages>
</errorVO>
</booleanVO>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
OL-27164-01
3-7
Chapter 3
REST-Based API Functions
Function Descriptions
uploaddata
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).
Request
The URL for the uploaddata function is as follows:
POST 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 function or the
getIncidentDetails function to determine this identifier. For more
information, see the “getIncident” section on page 2-65 or the
“getIncidentDetails” section on page 2-65.
Request Payload
HTTP library parameters for the request payload of the uploaddata function are as follows:
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.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
3-8
OL-27164-01
Chapter 3
REST-Based API Functions
Function Descriptions
Parameter
Type
Description
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.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
OL-27164-01
3-9
Chapter 3
REST-Based API Functions
Function Descriptions
Parameter
Type
Description
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.
Response
The uploaddata function returns the following:
•
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
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
3-10
OL-27164-01
Chapter 3
REST-Based API Functions
Function Descriptions
Examples
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"/>
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>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
OL-27164-01
3-11
Chapter 3
REST-Based API Functions
Function Descriptions
</request>
</result>
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" />
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.5
3-12
OL-27164-01
Chapter 3
REST-Based API Functions
Function Descriptions
userdirectory
Description
The userdirectory function retrieves a list of all users who are associated with all radios that use a
designated radio descriptor.
Request
GET https://servername/ipics_server/handsetservice/websvc/radio/userdirectory
?spwd=sessionId}&descriptorId=descriptorId
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.
sessionId
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.
descriptorId
System-assigned identifier of the radio descriptor.
You can use the Cisco IPICS API findRadios function this identifier. For
more information, see the “findRadios” section on page 2-46.
Request Payload
The userdirectory function does not require a request payload.
Response
The userdirectory function returns a list of users who are associated with all radios that use a designated
radio descriptor.
If an exception occurs when the function executes, the function also returns an ErrorVO, which contains
an explanation of the exception.
Examples
The following example shows a request and responses when using the policy function execute a policy:
Request
GET https://ipicsserver.com/ipics_server/handsetservice/websvc/radio/
userdirectory?spwd=12345-00444343}&descriptorId=2345
Accept:application/xml
Response if request is submitted successfully
<stringVO value="
<userDirectory id="<descriptorId>" version "1">
<users>
<user>
<alias>groupName</alias>
<ids>
<id>12343<callnumber1></id>
<id> callnumber2 </id>
</ids>
</user>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
OL-27164-01
3-13
Chapter 3
REST-Based API Functions
Function Descriptions
</users>
</userDirectory>" />” >
</stringVO>
Response if an exception occurs
<stringVO>
<errorVO errorCode="Error getting list of direct connect users" />
</stringVO>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5
3-14
OL-27164-01