Cisco IPICS API Reference Guide, Cisco IPICS Release 4.6

Book Contents

Find Matches in This Book

Available Languages

Download Options

Book Title

Cisco IPICS API Reference Guide, Cisco IPICS Release 4.6

Chapter Title

REST-Based API Functions

PDF - Complete Book (2.39 MB) PDF - This Chapter (208.0 KB)
View with Adobe Reader on a variety of devices

Results

Updated:: February 16, 2018

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

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 and the “endSession” section.
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 1-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 1-1 REST-Based API Function Summary
Function Name and Reference	Description
policy	Executes a designated Cisco IPICS policy
talkgroup/join	Joins the logged in user to the designated talk group (channel, radio, incident, or VTG)
talkgroup/leave	Causes the logged-in user to leave the designated talk group (channel, radio, incident, or VTG)
uploaddata	Uploads a photograph, video, or journal to the Cisco IPICS server and associates the resource with a designated incident
userdirectory	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:

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

Note The “Function Guidelines” section provides important information that relates to many of the functions that the following sections describe.

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 or the “getPolicyDetails” section.
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

Response if an exception occurs

validateSession: Database ExceptionSession not found. Invalid Session Id - Session not found. Invalid Session Id

</errorMessages>

</errorVO>

</booleanVO>

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:

For a channel—getChannel or getChannelDetails
For a radio—getRadioDetails
For an incident—getIncident or getIncidentDetails
For a vtg—getVtgDetails

Request Payload

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.
resourceType	String	Type of the talk group that the logged-in user is to join. Valid values are: Channel Incident ISSIGChannel PooledRadioChannel Radio Vtg
connectionType	String	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

Response

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

</connections>

</mediaConnectionContainerVO>

Response if an exception occurs

validateSession: Database ExceptionSession not found. Invalid Session Id - Session not found. Invalid Session Id

</errorMessages>

</errorVO>

</mediaConnectionContainerVO>

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:

For a channel—getChannel or getChannelDetails
For a radio—getRadioDetails
For an incident—getIncident or getIncidentDetails
For a VTG—getVtgDetails

Request Payload

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.
resourceType	String	Type of the talk group that the logged-in user is to join. Valid values are: Channel Incident ISSIGChannel PooledRadioChannel Radio Vtg
connectionType	String	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

Response

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

Response if an exception occurs

<errorMessages>v

alidateSession: Database ExceptionSession not found. Invalid Session Id - Session not found. Invalid Session Id

</errorMessages>

</errorVO>

</booleanVO>

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 or the “getIncidentDetails” section.

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.
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.

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

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"?>

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"?>

<autoDelete>true

</autoDelete>

<description>curl video</description>

<documentType>Video</documentType>

</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"?>

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"?>

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.

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> callnumber2 </id>

</ids>

</user>

</users>

</userDirectory>" />” >

</stringVO>

Response if an exception occurs

</stringVO>

Was this Document Helpful?

Feedback

Contact Cisco

Open a Support Case
(Requires a Cisco Service Contract)