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.
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
Response if request is submitted successfully
<booleanVO value="true"/>
Response if an exception occurs
<booleanVO value="false">
<errorVO errorCode="Error">
validateSession: Database ExceptionSession not found. Invalid Session Id - Session not found. Invalid Session Id
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
HTTP library parameters for the request payload of the talkgroup/join function are as follows:
|
|
|
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
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>
</mediaConnectionContainerVO>
Response if an exception occurs
<mediaConnectionContainerVO pollFreq="0">
<errorVO errorCode="Error">
validateSession: Database ExceptionSession not found. Invalid Session Id - Session not found. Invalid Session Id
</mediaConnectionContainerVO>
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
HTTP library parameters for the request payload of the talkgroup/leave function are as follows:
|
|
|
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
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
<errorVO errorCode="Error">
alidateSession: Database ExceptionSession not found. Invalid Session Id - Session not found. Invalid Session Id
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:
|
|
|
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:
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"?>
<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">
<description>curl video</description>
<documentType>Video</documentType>
<filename>1.279.3fire.wmv</filename>
<incidentId>279</incidentId>
<referenceType>Clip</referenceType>
<sessionId>1275427188568415217882</sessionId>
<spectrum>long</spectrum>
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" />
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
Response if request is submitted successfully
<userDirectory id="<descriptorId>" version "1">
<id>12343<callnumber1></id>
Response if an exception occurs
<errorVO errorCode="Error getting list of direct connect users" />