CH A P T E R
2
Web Services API Functions
This chapter describes the Cisco web services API functions. It provides general information and
detailed descriptions for each function, and a summary of the functions, arranged by category.
This chapter includes these topics:
•
Function Guidelines, page 2-1
•
Function Summary, page 2-2.
•
Function Descriptions, page 2-8
Function Guidelines
When you use the Cisco web service API functions as documented in this chapter, be aware of the
following:
•
In general, the API functions consider only items (users, channels, photographs, radios, videos, or
VTGs), that are associated with the Cisco IPICS ops view of the user who is logged in to
Cisco IPICS web services and executes the function. If you belong to the Cisco IPICS system ops
view, the API functions consider all ops views
In particular, be aware that the find and get functions retrieve only items that are associated with
your ops view. For example, if you execute a function that retrieves all incidents or VTGs, only
incidents or VTGs that are associated with your ops view are retrieved.
•
You must have a specific Cisco IPICS role to use some functions. If you execute a function when
you do not have a valid role to do so, the function returns an ErrorVO.
•
Functions that make changes to an active VTG may cause Cisco IPICS to reprogram the RMS, which
can consume significant system resources for a long time. If you use these functions, it is a best
practice to make all VTG changes in as few web service calls as possible, or to execute these
functions at off-peak hours.
•
The function descriptions refer to various value objects (VOs). For more detailed information, see
Chapter 3, “Value Objects.”
•
Many functions require at least one identifier (ID) to indicate the item that the function is to affect.
For example, a function might require the ID of an incident (incidentId), user (userID), or VTG
(vtgId). You can obtain these IDs by using various “get” functions. See the function descriptions to
determine the function that returns the information that you need.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-1
Chapter 2
Web Services API Functions
Function Summary
Function Summary
Table 2-1 provides a summary of the Cisco IPICS API functions. Each function is described in detail in
the section that is listed.
Table 2-1
API Function Summary
Function Name and Reference
Description
Functions for User Management
addUserToUserGroup, page 2-14
Adds a user to a user group
associateChannelsToUser, page 2-17
Associates one or more channels with a user
associatePhonesToUser, page 2-18
Associates one or more phones with a user
associateRadiosToUser, page 2-18
Associates one or more radios with a designated user
createUser, page 2-22
Creates a Cisco IPICS user
createUserGroup, page 2-23
Creates a user group
deletePmcProfile, page 2-28
Deletes IDC profile information for the designated user
disableUser, page 2-34
Disables a Cisco IPICS user
enableUser, page 2-35
Enables a Cisco IPICS user
isActiveUser, page 2-93
Determines if a user is active or disabled
removePhoneAssociatedToUser,
page 2-97
Disassociates a phone from a user
savePmcProfile, page 2-101
Saves IDC profile information for the designated user
setBelongingOpsViewForUser,
page 2-102
Assigns an ops view to a designated user
setDialPreference, page 2-102
Adds a new dial preference for a user
setDigitId, page 2-103
Sets digit IDs for a user
setDigitPassword, page 2-104
Sets a digit password for a user
setNotificationPreference, page 2-107
Adds a new notification preference for a user
setUserAddress, page 2-107
Adds a physical address for a user
setUserAudioStatus, page 2-108
Enables or disables the ability of a user to hear and transmit
audio on a PMC
setUserListenerStatus, page 2-109
Enables or disables the ability of a user to transmit audio
on a PMC
updateUserGroup, page 2-113
Modifies various attributes of a user group
Functions for VTG Management
activateVtg, page 2-9
Activates a VTG (if it is not activated already)
addChannelToVtg, page 2-10
Adds a channel to an active or inactive VTG
addRadioToVtg, page 2-13
Adds a radio to an active or inactive VTG
addParticipantsToVtg, page 2-11
Adds any combination of resources (channel, radio, user,
and VTG) to a VTG
addResourcesToVtg, page 2-13
Adds one or more resources of the same type (users,
channels, radios, or VTGs) to a VTG
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-2
OL-21552-01
Chapter 2
Web Services API Functions
Function Summary
Table 2-1
API Function Summary (continued)
Function Name and Reference
Description
addUserToVtg, page 2-14
Adds a user to an active or inactive VTG
addVtgParticipants, page 2-16
Adds any combination of resources (channels, radios,
users, and VTGs) to a VTG
addVtgToVtg, page 2-17
Add a VTG to another VTG
createVtg, page 2-24
Creates a VTG with the designated name
deactivateVtg, page 2-27
Deactivates a VTG
isActiveVtg, page 2-93
Determines if a VTG is active or disabled
removeChannelFromVtg, page 2-96
Removes a channel from a VTG
removeUserFromVtg, page 2-99
Removes a user from a VTG
removeRadioFromVtg, page 2-98
Removes a radio from a VTG.
removeVtgFromVtg, page 2-100
Removes a VTG from a VTG
setVtgOptions, page 2-109
Sets various options for a VTG
setVtgUserOptions, page 2-110
Sets various options for a designated user in a VTG
updateVirtualTalkGroup, page 2-114
Modifies various attributes of a video
Functions for Incident Management
activateIncident, page 2-8
Activates an incident (if it is not activated already)
activateIncidentVtg, page 2-9
Creates and activates an incident VTG for a designated
incident
addJournalToIncident, page 2-11
Creates a journal entry and associates it with an incident
addPhotoToIncident, page 2-12
Adds the URL of a photograph to an incident and
associates the photograph with the incident
addVideoToIncident, page 2-15
Creates the URL of a video to an incident and associates
the video with the incident
associateResourcesToIncident, page 2-19 Associates one or more resources of the same type (users,
channels, photographs, radios, videos, or VTGs) with an
incident.
createIncident, page 2-21
Creates an incident
createPhoto, page 2-21
Adds the URL of a photograph to Cisco IPICS
createVideo, page 2-23
Adds the URL of a video to Cisco IPICS
deactivateIncident, page 2-26
Deactivates an incident
deactivateIncidentVtg, page 2-26
Deactivates an incident VTG
isActiveIncidentVtg, page 2-92
Determines if an incident VTG in a designated incident is
active or inactive
removeResourceFromIncident, page 2-98 Disassociates one or more resource from an incident
removeVtgParticipants, page 2-100
Removes one or more participants from a VTG
setIncidentVtgOptions, page 2-105
Sets various options for an incident VTG
setIncidentVtgUserOptions, page 2-106
Sets various options for a designated user in an incident
VTG
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-3
Chapter 2
Web Services API Functions
Function Summary
Table 2-1
API Function Summary (continued)
Function Name and Reference
Description
updateIncident, page 2-112
Modifies various attributes of an incident
updatePhoto, page 2-113
Modifies various attributes of a photograph
updateVideo, page 2-114
Modifies various attributes of a video
Functions for Channel Management
createChannel, page 2-20
Creates a channel
disableChannel, page 2-33
Changes a channel to DISABLED state if the current
channel state is IDLE
enableChannel, page 2-35
Changes a channel IDLE state if the current channel state
is DISABLED
isActiveChannel, page 2-91
Determines if a channel is active or disabled
Functions for Policy and Dial Function Management
dialAllIncidentVtgMembers, page 2-29
Dials out to all user who are members of an incident VTG
dialAllVtgMembers, page 2-30
Dials out to all users who are members of a VTG, including
members of user groups that are part of the VTG
dialIncidentVtgMember, page 2-31
Dials out to the specified member of an incident VTG
dialVtgMember, page 2-32
Dials out to the specified member of a VTG
executeNotificationPolicy, page 2-36
Executes the notification policy that has the designated ID
executePolicy, page 2-37
Executes a designated policy
notifyAllIncidentVtgMembers, page 2-94 Sends a notification to each user in the incident VTG of the
designated incident
notifyAllVtgMembers, page 2-94
Sends a notification to each user in the incident VTG of the
designated incident
notifyIncidentVtgMember, page 2-95
Notifies a designated member of an incident VTG
notifyVtgMember, page 2-96
Notifies a specific member of a VTG
Functions for Obtaining Information
findChannelGroups, page 2-38
Retrieves each channel group with a name that matches a
designated search criterion
findChannels, page 2-38
Retrieves each channel with a name that matches a
designated search criterion
findIncidents, page 2-39
Retrieves each incident with a name that matches a
designated search criterion
findPhotos, page 2-40
Retrieves each photograph with a name that matches a
designated search criterion
findRadios, page 2-41
Retrieves each radio with a name that matches a designated
search criterion
findUserGroups, page 2-41
Retrieves each user group with a name that matches a
designated search criterion
findUsers, page 2-42
Retrieves each user with a user name that matches a
designated search criterion
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-4
OL-21552-01
Chapter 2
Web Services API Functions
Function Summary
Table 2-1
API Function Summary (continued)
Function Name and Reference
Description
findVideos, page 2-43
Retrieves each video with a name that matches a designated
search criterion
findVtgs, page 2-44
Retrieves each VTG with a name that matches a designated
search criterion
getAllChannels, page 2-45
Retrieves all channels that are associated with your
Cisco IPICS ops view
getAllChannelGroups, page 2-44
Retrieves all channel groups that are associated with your
Cisco IPICS ops view
getAllChannelsInChannelGroup,
page 2-45
Retrieves all channels that are in the designated channel
group
getAllIncidents, page 2-46
Retrieves all incidents that are associated with your
Cisco IPICS ops view
getAllIncidentsWithIVtgStatus,
page 2-47
Retrieves all incidents that are associated with your
Cisco IPICS ops view and the status of each incident VTG
that is associated with an incident
getAllPhotos, page 2-47
Retrieves all photographs that are associated with your
Cisco IPICS ops view
getAllPolicies, page 2-48
Retrieves all policies that are associated with your
Cisco IPICS ops view
getAllRadios, page 2-48
Retrieves all radios that are associated with your
Cisco IPICS ops view
getAllUserGroups, page 2-49
Retrieves all user groups that are associated with your
Cisco IPICS ops view
getAllUsers, page 2-50
Retrieves all Cisco IPICS users that are associated with
your Cisco IPICS ops view
getAllVideos, page 2-50
Retrieves all videos that are associated with your
Cisco IPICS ops view
getAllVtgs, page 2-51
Retrieves all VTGs that are associated with your Cisco
IPICS ops view
getBelongingOpsViewForUser,
page 2-51
Retrieves the ops view to which a designated user belongs
getChannel, page 2-52
Retrieves summary information about a designated channel
getChannelDetails, page 2-53
Retrieves detailed information about a designated channel
getChannelGroupsForVtg, page 2-53
Retrieves a list of channel groups s that are associated with
a designated VTG.
getChannelsAssociatedToUser,
page 2-54
Retrieves all channels that are associated with a user
getChannelsForIncident, page 2-55
Retrieves a list of channels that are associated with an
incident
getChannelsForVtg, page 2-55
Retrieves a list of channels that are associated with a VTG
getDigitId, page 2-56
Retrieves the digit ID for a user
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-5
Chapter 2
Web Services API Functions
Function Summary
Table 2-1
API Function Summary (continued)
Function Name and Reference
Description
getDigitPassword, page 2-57
Retrieves the digit password for a user
getIncident, page 2-58
Retrieves summary information about a designated
incident
getIncidentDetails, page 2-58
Retrieves detailed information about a designated incident
getIncidentParticipants, page 2-59
Retrieves all resources (channels, journals, radios,
photographs, users, videos, and VTGs) that are associated
with an incident.
getIncidentsForUser, page 2-59
Retrieves a list of all incidents that are associated with a
designated user.
getIncidentVtg, page 2-60
Retrieves information about the incident VTG that is
associated with a designated incident
getIncidentVtgOptions, page 2-61
Retrieves VTG options for the incident VTG that is
associated with a designated incident
getIncidentVtgUserOptions, page 2-61
Retrieves incident VTG options for an incident VTG user.
getIpicsVersion, page 2-62
Retrieves the version of Cisco IPICS that is running on
active Cisco IPICS server
getJournal, page 2-63
Retrieves summary information about a designated journal
getJournalDetails, page 2-63
Retrieves summary information about a designated journal
getJournalsForIncident, page 2-64
Retrieves all journals for a designated incident
getPhonesAssociatedToUser, page 2-64
Retrieves all phones that are associated with a designated
user
getPhoto, page 2-65
Retrieves summary information about a photograph
getPhotoDetails, page 2-66
Retrieves detailed information about a photograph
getPhotosForIncident, page 2-66
Retrieves a list of photographs that are associated with a
designated incident.
getPmcProfile, page 2-67
Retrieves IDC profile information for the designated user
getPoliciesAssociatedToUser, page 2-67
Retrieves all policies that are associated with a designated
user
getPolicy, page 2-68
Retrieves summary information about a policy
getPolicyDetails, page 2-69
Retrieves detailed information about a policy
getPolicyExecutionStatus, page 2-69
Retrieves the status of the execution of a designated policy
getPolicyExecutionStatusDetails,
page 2-70
Retrieves detailed status information about the execution
of each policy that is associated with a designated user
getRadiosAssociatedToUser, page 2-71
Retrieves a list of radios that are associated with a
designated user
getRadiosForIncident, page 2-71
Retrieves a list of radios that are associated with a
designated incident.
getRadiosForVtg, page 2-72
Retrieves a list of radios that are associated with a
designated VTG.
getUser, page 2-72
Retrieves summary information about the designated user
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-6
OL-21552-01
Chapter 2
Web Services API Functions
Function Summary
Table 2-1
API Function Summary (continued)
Function Name and Reference
Description
getUserAddress, page 2-73
Retrieves the physical address of a designated user
getUserAudioStatus, page 2-74
Retrieves a flag that indicates if the PMC of a user has
audio disabled or enabled
getUserDetails, page 2-74
Retrieves detailed information about a designated user
getUserDialPreference, page 2-75
Retrieves the dial preference that is associated with a
designated user
getUserDirectory, page 2-75
Retrieves the users for whom a direct connect number is
assigned in the designated serial radio descriptor file
getUserGroup, page 2-76
Retrieves summary information about the designated user
group
getUserGroupMembers, page 2-77
Retrieves all the users in a designated user group
getUserGroupsForVtg, page 2-77
Retrieves user groups that are associated with a designated
VTG
getUserId, page 2-78
Retrieves the system-generated user ID for the designated
user
getUserListenerStatus, page 2-78
Retrieves a flag that indicates whether the PMC of a user is
in listen-only mode
getUserNotificationPreference,
page 2-79
Retrieves the notification preference that is associated with
a designated user
getUserRoles, page 2-80
Retrieves the list of roles for a designated user
getUsersAssociatedToRadio, page 2-81
Return a list of users that are associated with a designated
radio
getUsersForIncident, page 2-81
Retrieves a list of users that are associated with a
designated incident
getUsersForVtg, page 2-82
Retrieves a list of users that are associated with a
designated VTG
getUserStatus, page 2-83
Retrieves the active status of one or more users
getVideo, page 2-83
Retrieves summary information about the designated video
getVideoDetails, page 2-84
Retrieves detailed information about the designated video
getVideosForIncident, page 2-84
Retrieves a list of videos that are associated with a
designated incident
getVtgDetails, page 2-85
Retrieves detailed information about the designated VTG
getVtgOptions, page 2-86
Retrieves information about the status of a variety of
options for a VTG
getVtgParticipants, page 2-86
Retrieves all participants in a VTG
getVtgParticipantStatus, page 2-87
Retrieves the status of VTG participant
getVtgsAssociatedToUser, page 2-88
Retrieves all VTGs that are associated with a user
getVtgsForIncident, page 2-89
Retrieves a list of VTGs that are associated with a
designated incident
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-7
Chapter 2
Web Services API Functions
Function Descriptions
Table 2-1
API Function Summary (continued)
Function Name and Reference
Description
getVtgsForVtg, page 2-89
Retrieves a list of VTGs that are associated with a
designated VTG.
getVtgStatus, page 2-90
Retrieves the ID, name, description, and status of a VTG
getVtgUserOptions, page 2-91
Retrieves the settings of the latch, listen only, and rxmute
VTG options settings for a designated VTG and user
Functions for General Operations
deleteResources, page 2-28
Deletes designated resources
endSession, page 2-36
Ends a web services session
startSession, page 2-111
Starts a web services session
Function Descriptions
The following sections describe each Cisco IPICS API function in detail. The function descriptions
provide the following information:
Note
•
Function name—Name of the function.
•
Description—General behavior for the function.
•
Role—Cisco IPICS role that you must have to use the function. If you execute a function when you
do not have a valid role to do so, the function returns an ErrorVO. At a minimum, everyone who uses
Cisco IPICS has the User role, so functions for which the Role is identified as “User” are available
to all Cisco IPICS users.
•
Parameters—Parameters that the function requires.
•
Return result—Describes the result that Cisco IPICS returns for the function.
•
Sample response—Example of a response that the function can receive.
The “Function Guidelines” section on page 2-1 provides important information that relates to many of
the functions that the following sections describe.
activateIncident
Function name
activateIncident
Description
Activates an incident (if it is not activated already).
Role
Dispatcher
Parameters
•
sessionId (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.
•
incidentId (int)—ID of the incident to be activated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-8
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Return result
IntegerVO that contains 1 if the designated incident is activated or 0
if it is not activated.
The IntegerVO also contains an ErrorVO, which is empty if the
incident is activated, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="activateIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
activateIncidentVtg
Function name
activateIncidentVtg
Description
Creates and activates an incident VTG for a designated incident.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident for which to activate the
incident VTG.
BooleanVO that contains true if the incident VTG is created and
activated, or false if the incident VTG is not created and activated.
The BooleanVO also contains an ErrorVO, which is empty if the
incident VTG is created and activated, or contains an explanation if
an exception occurs when the function executes.
Sample response
<xs:element name="activateIncidentVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
activateVtg
Description
Activates a VTG (if it is not activated already).
activateVtg
Role
•
IDC patch—User (with advanced IDC permissions)
•
VTG—Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-9
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG to be activated.
BooleanVO that contains true if the VTG is activated, or false if the
VTG is not activated.
The BooleanVO also contains an ErrorVO, which is empty if the VTG
is activated, or contains an explanation if an exception occurs when
the function executes.
Sample response
<xs:element name="activateVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
addChannelToVtg
Function name
addChannelToVtg
Description
Adds a channel to an active or inactive VTG.
Role
Parameters
Return result
•
IDC patch—User (with advanced IDC permissions)
•
VTG—Dispatcher
•
sessionId (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.
•
vtgId (int)—ID of the VTG to which the user is to be added.
•
channelId (int)—ID of the channel to be added to the designated
VTG.
BooleanVO that contains true if the channel is added to the VTG, or
false if the channel is not added to the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the
channel is added, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="addChannelToVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-10
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
addJournalToIncident
Function name
addJournalToIncident
Description
Creates a journal entry and associates it with an incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)— ID of the incident to which the journal entry is
to be added.
•
journalVO (JournalDetailsVO)—Journal to add.
IntegerVO that contains the ID of the new journal if the journal is
created and associated with the designated incident, or 0 if the journal
is not created and associated with the designated incident.
The IntegerVO also contains an ErrorVO, which is empty if the
journal is created and added, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="addJournalToIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
addParticipantsToVtg
Function name
addParticipantsToVtg
Description
Adds any combination of resources to a VTG. Resources can be
channels, radios, users, and VTGs. This function provides the same
functionality as the addVtgParticipants function, with the addition of
the ability to add a description for each resource.
Role
Dispatcher
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG to which the list of resources is to be
added.
•
vtgParticipants (VtgParticipantVO[])—Array of resources to be
added to the VTG.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-11
Chapter 2
Web Services API Functions
Function Descriptions
Return result
BooleanVO that contains true if the resources are added to the VTG,
or false if the resources are not added to the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the
resources are added, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="addParticipantsToVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0"
name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
addPhotoToIncident
Function name
addPhotoToIncident
Description
Adds the URL of a photograph to an incident and associates the
photograph with the incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident to which the photograph is to
be added.
•
photo (PhotoDetailsVO)—Information about the photograph
URL to add to the incident.
•
autoDelete (boolean)—If true, the Cisco IPICS database record
for the photograph and the photograph file (if the file exists on the
Cisco IPICS server) are deleted automatically when all incidents
with which the photograph are associated are deleted. If false, the
Cisco IPICS database record for the photograph and the
photograph file are never deleted automatically.
IntegerVO that contains the ID the record of the photograph if the
photograph is associated with an incident, or 0 if an error occurs.
The IntegerVO also contains an ErrorVO, which is empty if the
photograph is associated, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="addPhotoToIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-12
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
addRadioToVtg
Function name
addRadioToVtg
Description
Adds a radio to an active or inactive VTG.
Role
Parameters
Return result
•
IDC patch—User (with advanced IDC permissions)
•
VTG—Dispatcher
•
sessionId (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.
•
vtgId (int)—ID of the VTG to which the radio is to be added.
•
radioId (int)—ID of the radio to add.
BooleanVO that contains true if the radio is added to the VTG, or
false if the radio is not added to the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the radio
is added, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="addRadioToVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
addResourcesToVtg
Function name
addResourcesToVtg
Description
Adds one or more resources of the same type to a VTG. Resources can
be users, channels, radios, or VTGs.
Role
Dispatcher
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG to which the list of resources is to be
added.
•
resourceIds (int[])—Array of IDs of each resource to add to the
VTG.
•
resourceType (String)—Type of resource to add (user, channel,
radio, or VTG).
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-13
Chapter 2
Web Services API Functions
Function Descriptions
Return result
BooleanVO that contains true if the resources are added to the VTG,
or false the resources are not added to the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the
resources are added, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="addResourcesToVtgResponse">
<xs:complexType>
<xs:sequence>
<xxs:element minOccurs="0"
name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
addUserToUserGroup
Function name
addUserToUserGroup
Description
Adds a user to a user group.
Role
Operator
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user to be
added to the specified user group. This parameter must be entered
in all lower case.
•
userGroupId (int)—ID of the user group to which the user is to
be added.
BooleanVO that contains true if the user is added to the user group,
or false if the user is not added to the user group.
The BooleanVO also contains an ErrorVO, which is empty if the user
is added, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="addUserToUserGroupResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
addUserToVtg
addUserToVtg
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-14
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Description
Role
Parameters
Return result
Adds a user to an active or inactive VTG.
•
IDC patch—User (with advanced IDC permissions)
•
VTG—Dispatcher
•
sessionId (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.
•
vtgId (int)—ID of the VTG to which the user is to be added.
•
userLogin (String)—Cisco IPICS user name of the user to be
added to the specified VTG. This parameter must be entered in
all lower case.
BooleanVO that contains true if the user is added to the VTG, or false
if the user is not added to the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the user
added, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="addUserToVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
addVideoToIncident
Function name
addVideoToIncident
Description
Creates the URL of a video to an incident and associates the video
with the incident.
Role
User
Parameters
•
sessionId (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.
•
incidentId (int)—ID of the incident to which the video is to be
added.
•
video (VideoDetailsVO)—Information about the video URL to
add to the incident.
•
autoDelete (boolean)—If true, the Cisco IPICS database record
for the video and the video file (if the file exists on the Cisco
IPICS server) are deleted automatically when all incidents with
which the video are associated are deleted. If false, the Cisco
IPICS database record for the video and the video file are never
deleted automatically.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-15
Chapter 2
Web Services API Functions
Function Descriptions
Return result
IntegerVO that contains the ID the record of the photograph if the
video is associated with an incident, or 0 if an error occurs.
The IntegerVO also contains an ErrorVO, which is empty if the video
is associated, or contains an explanation if an exception occurs when
the function executes.
Sample response
<xs:element name="addVideoToIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
addVtgParticipants
Function name
addVtgParticipants
Description
Adds any combination of resources to a VTG. Resources include
channels, radios, users, and VTGs. This function provides the same
functionality as the addParticipantsToVtg function, but does not
include the ability to add a description for each resource.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG to which the participants are to be
added.
•
parts (ResourceContainerVO)—VO that contains the list of
participants to add to the VTG.
IntegerVO that contains the number of resources that are added to the
VTG.
The IntegerVO also contains an ErrorVO, which is empty if all
designated resources are added, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="addVtgParticipantsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-16
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
addVtgToVtg
Function name
addVtgToVtg
Description
Adds a VTG to another active or inactive VTG.
Role
Parameters
Return result
•
IDC patch—User (with advanced IDC permissions)
•
VTG—Dispatcher
•
sessionId (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.
•
vtgIdAdd (int)—ID of the VTG to be added.
•
vtgId (int)—ID of the VTG to which the other VTG is to be
added.
BooleanVO that contains true if the VTG is added to the VTG, or
false if the VTG is not added to the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the VTG
is added, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="addVtgToVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
associateChannelsToUser
Function name
associateChannelsToUser
Description
Associates one or more channels with a user.
Role
Operator
Parameters
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user with
whom to associate one or more channels. This parameter must be
entered in all lower case.
•
channels (ChannelContainerVO)—Collection of channel value
objects, each of which contains a channel ID and channel name.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-17
Chapter 2
Web Services API Functions
Function Descriptions
Return result
BooleanVO that contains true if the channel is associated with the
user, or false if the channel is not associated with the user.
The BooleanVO also contains an ErrorVO, which is empty if the
channel is associated, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="associateChannelsToUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
associatePhonesToUser
Function name
associatePhonesToUser
Description
Associates one or more phones with a user.
Role
Operator
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user with
whom to associate one more phones. This parameter must be
entered in all lower case.
•
dialNumbers (String[])—Dial number of each phone to associate
with the user.
BooleanVO that contains true if the phone is associated with the user,
or false if the phone is not associated with the user.
The BooleanVO also contains an ErrorVO, which is empty if the
phone is associated, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="associatePhonesToUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
associateRadiosToUser
Function name
associateRadiosToUser
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-18
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Description
Associates one or more radios with a user.
Role
Operator
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user with
whom to associate one or more radios. This parameter must be
entered in all lower case.
•
radios (RadioContainerVO)—A collection of radio value objects,
each of which contains a radio ID and radio name.
BooleanVO that contains true if the radio is associated with the user,
or false if the radio is not associated with the user.
The BooleanVO also contains an ErrorVO, which is empty if the radio
is associated, or contains an explanation if an exception occurs when
the function executes.
Sample response
<xs:element name="associateRadiosToUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
associateResourcesToIncident
Function name
associateResourcesToIncident
Description
Associates one or more resources of the same type with an incident.
Resources can be users, channels, photographs, radios, videos, or
VTGs.
Role
•
To associate a channel—Administrator or Dispatcher
•
To associate a photograph—User
•
To associate a radio—Administrator or Dispatcher
•
To associate a user—Dispatcher or Operator
•
To associate a video—User
•
To associate a VTG—Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-19
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident that is to include the
resource.
•
resourceType—Type of resource (user, channel, photograph,
radio, video, or VTG).
•
resourceIds (int[])—IDs of the resources to add to the incident.
IntegerVO that contains a value that indicates how many resources
have been associated with the incident.
The IntegerVO also contains an ErrorVO, which is empty if all
designated resources are associated, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="associateResourcesToIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
createChannel
Function name
createChannel
Description
Creates a channel with the specified name and short name.
Role
Administrator
Parameters
Return result
•
sessionId (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.
•
channelName (String)—Unique name of the channel to be
created. The name can include up to 20 characters and spaces.
The following characters are not allowed: ! @ $ % ^ & * + = [ ]
\;{}|“<>?~‘
•
channelShortName (String)—Unique short name of the channel
to be created. The name can include up to 5 alphanumeric
characters and spaces. The following characters are not allowed:
!@$%^&*+=[]\;{}|“<>?~‘
IntegerVO that contains the ID of the channel, if the channel is
created.
The IntegerVO also contains an ErrorVO, which is empty if the
channel is created, or contains an explanation if an exception occurs
when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-20
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="createChannelResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
createIncident
Function name
createIncident
Description
Creates an incident that is in the active state.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
incident (IncidentDetailsVO)—Information about the incident to
be created.
IntegerVO that contains the ID of the of the incident, if the incident
is created.
The IntegerVO also contains an ErrorVO, which is empty if the
incident is created, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="createIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
createPhoto
Description
Adds the URL of a photograph to Cisco IPICS. The URL can be used
to associate the photograph with an incident later.
Role
User
createPhoto
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-21
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
photo (PhotoDetailsVO)—URL of a photograph to add to Cisco
IPICS.
•
autoDelete—If true, the Cisco IPICS database record for the
photograph and the photograph file (if the file exists on the Cisco
IPICS server) are deleted automatically when all incidents with
which the photograph are associated are deleted. If false, the
Cisco IPICS database record for the photograph and the
photograph file are never deleted automatically.
IntegerVO that contains the ID of the of the photograph, if the
photograph is created.
The IntegerVO also contains an ErrorVO, which is empty if the
photograph is created, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="createPhotoResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
createUser
Description
Creates a Cisco IPICS user
Role
Operator
createUser
Parameters
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user to be
created. This parameter must be entered in all lower case.
•
userPassword (String)—Password of the user to be created. The
password can include letters, numbers, and special characters,
but no spaces. The system validates the password according the
parameters that are configured in Cisco IPICS Administration.
•
firstName (String)—First name of the user.
•
lastName (String)—Last name of the user
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-22
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Return result
IntegerVO that contains the ID of the of the user, if the user is created.
The IntegerVO also contains an ErrorVO, which is empty if the user
is created, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="createUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
createUserGroup
Function name
createUserGroup
Description
Creates a Cisco IPICS user group with the specified name and
description.
Role
Operator
Parameters
Return result
•
sessionId (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.
•
groupName (String)—Name of the user group to be created. This
string can contain up to 32 characters, including spaces.
•
groupDescription (String)—Description of the user group to be
created. This string can contain up to 85 characters, including
spaces.
IntegerVO that contains the ID of the of the user group, if the user
group is created.
The IntegerVO also contains an ErrorVO, which is empty if the user
group is created, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="createUserGroupResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
createVideo
createVideo
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-23
Chapter 2
Web Services API Functions
Function Descriptions
Description
Adds the URL of a video to Cisco IPICS. The URL can be used to
associate the video with an incident later.
Role
User
Parameters
Return result
•
sessionId (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.
•
video (VideoDetailsVO)—URL of a video to add to Cisco IPICS.
•
autoDelete—If true, the Cisco IPICS database record for the
video and the video file (if the file exists on the Cisco IPICS
server) are deleted automatically when all incidents with which
the video are associated are deleted. If false, the Cisco IPICS
database record for the video and the video file are never deleted
automatically.
IntegerVO that contains the ID of the of the video, if the video is
created.
The IntegerVO also contains an ErrorVO, which is empty if the video
is created, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="createVideoResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
createVtg
createVtg
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-24
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Description
Creates a VTG with the designated name.
The VTG can be either a regular VTG or a patch VTG. A regular
VTG, which also can be created through the Cisco IPICS
Administration Console or the VTG tab in the IDC, remains in the
system and can be activated and deactivated as needed. A patch VTG,
which you create in the IDC by using the Patch button in the Dial Pad
and Channel Patch Area or the Patch button in the PTT and Patch
Controls Area, is a temporary VTG that is deleted when the patch is
removed.
The following guidelines apply when the createVtg function is used
to create a patch VTG:
•
Advanced IDC Permissions must be configured in the
Cisco IPICS Administration Console for the user who is creating
the patch.
•
The name of the patch VTG can contain a maximum of 40
characters and must be named patchnumber.user, where
– number is a unique numerical sequence
– user is the Cisco IPICS user name of the user who is created
the patch
Role
Parameters
Return result
•
A user can have 1 patch VTG in effect at a time.
•
When this function executes, the API program calls createVtg(),
followed by addParticipantsToVtg(), followed by activateVtg().
•
When the client (program) unpatches, it calls deactivateVtg(),
followed by deleteResources(session, int[] { vtgid }, VTG, true).
•
When the client shuts down or logs out, the unpatch occurs
automatically.
•
IDC patch—User (with advanced IDC permission)
•
VTG—Dispatcher
•
sessionId (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.
•
vtgName (String)—Name of the VTG to be created.
•
description (String)—Description of the VTG.
IntegerVO that contains the ID of the of the VTG, if the VTG is
created.
The IntegerVO also contains an ErrorVO, which is empty if the VTG
is created, or contains an explanation if an exception occurs when the
function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-25
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="createVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
deactivateIncident
Function name
deactivateIncident
Description
Deactivates an Incident. This action changes the incident state from
Active to Inactive, deactivates its incident VTG if it is activated, and
releases the incident VTG resources.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident to deactivate.
IntegerVO that contains 1 if the incident is deactivated, or 0 if the
incident is not deactivated.
The IntegerVO also contains an ErrorVO, which is empty if the
incident is deactivated, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="deactivateIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
deactivateIncidentVtg
Function name
deactivateIncidentVtg
Description
Deactivates an incident VTG.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-26
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident that includes the incident
VTG to deactivate.
BooleanVO that contains true if the incident VTG is deactivated, or
false if the incident VTG is not deactivated.
The BooleanVO also contains an ErrorVO, which is empty if the
incident VTG is deactivated, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="deactivateIncidentVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
deactivateVtg
Description
Deactivates a VTG.
deactivateVtg
Role
Parameters
Return result
•
IDC patch—User (with advanced IDC permissions)
•
VTG—Dispatcher
•
sessionId (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.
•
vtgId (int)—ID of the VTG to deactivate.
BooleanVO that contains true if the VTG is deactivated, or false if
the VTG is not deactivated.
The BooleanVO also contains also contains an ErrorVO, which is
empty if the VTG is deactivated, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="deactivateVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-27
Chapter 2
Web Services API Functions
Function Descriptions
deletePmcProfile
Function name
deletePmcProfile
Description
Deletes Cisco IPICS Dispatch Console (IDC) profile information for
the designated user. The system uses profile information to cause an
IDC to appear and function in the same way for a user regardless of
the PC on which the user runs the IDC.
Role
User
Parameters
Return result
•
sessionId (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.
•
id (int)—ID of the user whose profile is to be deleted.
IntegerVO that contains 1 if the IDC profile information is deleted, or
0 if the IDC profile information is not deleted.
The IntegerVO also contains also contains an ErrorVO, which is
empty if the IDC profile information is deleted, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="deletePmcProfileResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
deleteResources
Function name
deleteResources
Description
Deletes one or more resources of the same type from Cisco IPICS.
Resources can be users, channels, photographs, radios, videos, or
VTGs.
Role
•
To delete a channel or radio—Administrator
•
To delete a photograph or video—User
•
To delete a user—Operator
•
To delete a VTG—Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-28
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
resourceIds (int[])—ID of the resource to delete. If you specify
more than one resourceId parameter, each must be the same type.
•
resourceType (String)—Type of resource to delete (user, channel,
photograph, radio, video, or VTG).
•
autoDeleteReferences (boolean)—If true, the Cisco IPICS
database records for the resources and the resource files (if the
files exists for photographs or videos on the Cisco IPICS server)
are deleted automatically when all incidents and VTGs with
which the resources are associated are deleted. If false, the Cisco
IPICS database record for the resources and the resource files are
never deleted automatically.
BooleanVO that contains true if some or all of the designated
resources are deleted, or false if none of the resources are deleted.
The BooleanVO also contains an ErrorVO, which is empty if all
designated resources are deleted, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="deleteResourcesResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
dialAllIncidentVtgMembers
Function name
dialAllIncidentVtgMembers
Description
Dials out to all user users who are members of an incident VTG.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-29
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
•
sessionId (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.
•
incidentId (int)—ID of the incident that includes the incident
VTG whose members you want to dial.
•
trigger (String)—Name of the trigger that invokes a custom
dial-out script.
If the trigger parameter is null, the system uses its default dial-out
application.
The trigger parameter is a string in the form /<trigger_name> and
optionally followed by HTTP parameters that a custom dial-out
application requires. For example, the trigger could be
/custom_dialout?param1=value1 if an additional parameter is
required, or /custom_dialout if no additional parameters are
required.
Return result
BooleanVO that contains true if the dial out is successful to all
members of the incident VTG, or false if the dial out is not successful
to all members of the incident VTG.
The BooleanVO also contains an ErrorVO, which is empty if the dial
out is successful to all members of the incident VTG, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="dialAllIncidentVtgMembersResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
dialAllVtgMembers
Function name
dialAllVtgMembers
Description
Dials out to all user who are members of a VTG, including members
of user groups that are part of the VTG.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-30
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG that includes the members to be dialed.
•
trigger (String)—Name of the trigger that invokes a custom
dial-out script.
If the trigger parameter is null, the system uses its default dial-out
application.
The trigger parameter is a string in the form /<trigger_name>,
optionally followed by HTTP parameters that a custom dial-out
application requires. For example, the trigger could be
/custom_dialout?param1=value1 if an additional parameter is
required, or /custom_dialout if no additional parameters are
required.
Return result
BooleanVO that contains true if the dial out is successful to all
members of the VTG, or false if the dial out is not successful to all
members of the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the dial
out is successful to all members of the VTG, or contains an explanation
if an exception occurs when the function executes.
Sample response
<xs:element name="dialAllVtgMembersResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
dialIncidentVtgMember
Function name
dialIncidentVtgMember
Description
Dials out to the specified member of an incident VTG.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-31
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
•
sessionId (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.
•
incidentId (int)—ID of the incident that includes the incident
VTG with the member to dial.
•
trigger (String)—Name of the trigger that invokes a custom
dial-out script.
If the trigger parameter is null, the system uses its default dial-out
application.
The trigger parameter is a string in the form /<trigger_name>,
optionally followed by HTTP parameters that a custom dial-out
application requires. For example, the trigger could be
/custom_dialout?param1=value1 if an additional parameter is
required, or /custom_dialout if no additional parameters are
required.
•
Return result
userLogin (String)—Cisco IPICS user name of the incident VTG
member to be dialed. This parameter must be entered in all lower
case.
BooleanVO that contains true if the dial out is successful to the
incident VTG member, or false if the dial out is not successful to the
incident VTG member.
The BooleanVO also contains an ErrorVO, which is empty if the dial
out is successful to the incident VTG member, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="dialIncidentVtgMemberResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
dialVtgMember
Function name
dialVtgMember
Description
Dials out to the specified member of a VTG.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-32
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG that includes the member to dial.
•
trigger (String)—Name of the trigger that invokes a custom
dial-out script.
If the trigger parameter is null, the system uses its default dial-out
application.
The trigger parameter is a string in the form /<trigger_name>,
optionally followed by HTTP parameters that a custom dial-out
application requires. For example, the trigger could be
/custom_dialout?param1=value1 if an additional parameter is
required, or /custom_dialout if no additional parameters are
required.
•
Return result
userLogin—Cisco IPICS user name of the VTG member to be
dialed. This parameter must be entered in all lower case.
BooleanVO that contains true if the dial out is successful to the VTG
member, or false if the dial out is not successful to the VTG member.
The BooleanVO also contains an ErrorVO, which is empty if the dial
out is successful to the VTG member, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="dialVtgMemberResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
disableChannel
Function name
disableChannel
Description
Changes a channel to DISABLED state. Applies only if the current
channel state is IDLE.
Role
Administrator
Parameters
•
sessionId (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.
•
channelId (int)—ID of the channel to disable.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-33
Chapter 2
Web Services API Functions
Function Descriptions
Return result
BooleanVO that contains true if the channel is disabled, or false if the
channel is not disabled.
The BooleanVO also contains an ErrorVO, which is empty if the
channel is disabled, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="disableChannelResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
disableUser
Description
Changes a user to the Disabled state in Cisco IPICS. If you execute
this function for a user who is logged in to the Cisco IPICS
Administration Console the user is logged out automatically when
trying to perform an activity. If you execute this function for a user
who is logged in to the IDC, the user is logged out automatically the
next time that the IDC polls the IPICS server.
Role
Operator
disableUser
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user to
disable. This parameter must be entered in all lower case.
BooleanVO that contains true if the user is disabled, or false if the
user is not disabled.
The BooleanVO also contains an ErrorVO, which is empty if the user
is disabled, or contains an explanation if an exception occurs when
the function executes.
Sample response
<xs:element name="disableUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-34
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
enableChannel
Function name
enableChannel
Description
Changes a channel IDLE state. Applies only if the current channel
state is DISABLED.
Role
Administrator
Parameters
Return result
•
sessionId (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.
•
channelId (int)—ID of the channel to enable.
BooleanVO that contains true if the channel is enabled, or false if the
channel is not enabled.
The BooleanVO also contains an ErrorVO, which is empty if the
channel is enabled, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="enableChannelResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
enableUser
Description
Changes a user to the Enabled state in Cisco IPICS.
Role
Operator
enableUser
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user to
enabled. This parameter must be entered in all lower case.
BooleanVO that contains true if the user is enabled, or false if the
user is not enabled.
The BooleanVO also contains an ErrorVO, which is empty if the user
is enabled, or contains an explanation if an exception occurs when the
function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-35
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="enableUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
endSession
Description
Ends a designated web services session. A user with the Cisco IPICS
Administrator role or the All role can end any session. Users with
other Cisco IPICS roles can end only sessions that belong to them.
Role
—
endSession
Parameters
Return result
•
sessionId (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.
BooleanVO that contains true if the session is ended, or false if the
session is not ended.
The BooleanVO also contains an ErrorVO, which is empty if the
session is ended, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="endSessionResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
executeNotificationPolicy
Function name
executeNotificationPolicy
Description
Executes a designated notification policy. When the notification
policy executes, the prerecorded prompt that is defined in the
Notification (Dial) action is overridden with a text-to-speech (TTS)
prompt that is generated from the designated text message.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-36
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
policyId (int)—ID of the policy to execute.
•
msgText (String)—Text of message that the TTS function to play
to recipients.
BooleanVO that contains true if the notification is executed, or false
if the notification is not executed.
The BooleanVO also contains an ErrorVO, which is empty if the
notification is executed, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="executeNotificationPolicyResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
executePolicy
Function name
executePolicy
Description
Executes a designated policy.
Role
User
Parameters
Return result
•
sessionId (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.
•
policyId (int)—ID of the policy to execute.
BooleanVO that contains true if the policy is executed, or false if the
policy is not executed.
The BooleanVO also contains an ErrorVO, which is empty if the
policy is executed, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="executePolicyResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-37
Chapter 2
Web Services API Functions
Function Descriptions
findChannelGroups
Function name
findChannelGroups
Description
Retrieves each channel group with a name that matches a designated
search criterion.
Role
User
Parameters
Return result
•
sessionId (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.
•
channelGroupVO (ChannelGroupVO)—Search criterion for the
name to retrieve. The search criterion can be the complete name,
or the beginning character or characters of the name. The name is
sensitive and the percent character (%) can be used as a wildcard
to match any character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channel groups are returned
and these results are not paginated.
ChannelGroupContainerVO that contains channel groups that match
the search criterion.
The ChannelGroupContainerVO also contains an ErrorVO, which is
empty if one or more channel groups are retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="findChannelGroupsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelGroupContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
findChannels
Description
Retrieves each channel with a name that matches a designated search
criterion.
Role
User
findChannels
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-38
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
channel (ChannelVO)—Search criterion for the name to retrieve.
The search criterion can be the complete name, or the beginning
character or characters of the name. The name is sensitive and the
percent character (%) can be used as a wildcard to match any
character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channels are returned and these
results are not paginated.
ChannelContainerVO that contains channels that match the search
criterion.
The ChannelContainerVO also contains an ErrorVO, which is empty
if one or more channels are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="findChannelsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
findIncidents
Description
Retrieves each incident with a name that matches a designated search
criterion.
Role
User
findIncidents
Parameters
•
sessionId (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.
•
incident (IncidentDetailsVO)—Search criterion for the name to
retrieve. The search criterion can be the complete name, or the
beginning character or characters of the name. The name is
sensitive and the percent character (%) can be used as a wildcard
to match any character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all incidents are returned and these
results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-39
Chapter 2
Web Services API Functions
Function Descriptions
Return result
IncidentContainerVO that contain incidents that match the search
criterion.
The IncidentContainerVO also contains an ErrorVO, which is empty
if one or more incidents are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="findIncidentsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
findPhotos
Description
Retrieves each photograph with a name that matches a designated
search criterion.
Role
User
findPhotos
Parameters
Return result
•
sessionId (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.
•
photo (PhotoDetailsVO)—Search criterion for the name to
retrieve. The search criterion can be the complete name, or the
beginning character or characters of the name. The name is
sensitive and the percent character (%) can be used as a wildcard
to match any character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all photographs are returned and
these results are not paginated.
PhotoContainerVO that contains an array of photographs that match
the search criterion.
The PhotoContainerVO also contains an ErrorVO, which is empty if
one or more photographs are retrieved, or contains an explanation if
an exception occurs when the function executes.
Sample response
<xs:element name="findPhotosResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PhotoContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-40
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
findRadios
Function name
findRadios
Description
Retrieves each radio with a name that matches a designated search
criterion.
Role
User
Parameters
Return result
•
sessionId (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.
•
radio (RadioDetailsVO)—Search criterion for the name to
retrieve. The search criterion can be the complete name, or the
beginning character or characters of the name. The name is
sensitive and the percent character (%) can be used as a wildcard
to match any character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all radios are returned and these
results are not paginated.
RadioContainerVO that contains an array of radios that match the
search criterion.
The RadioContainerVO also contains an ErrorVO, which is empty if
one or more radios are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="findRadiosResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:RadioContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
findUserGroups
Function name
findUserGroups
Description
Retrieves each user group with a name that matches a designated
search criterion.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-41
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
group (UserGroupDetailsVO)—Search criterion for the name to
retrieve. The search criterion can be the complete name, or the
beginning character or characters of the name. The name is
sensitive and the percent character (%) can be used as a wildcard
to match any character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all user groups are returned and
these results are not paginated.
UserGroupContainerVO that contains an array of user groups that
match the search criterion.
The UserGroupContainerVO also contains an ErrorVO, which is
empty if one or more user groups are retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="findUserGroupsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserGroupContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
findUsers
Description
Retrieves each user with a user name that matches a designated search
criterion.
Role
User
findUsers
Parameters
•
sessionId (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.
•
user (UserDetailsVO)—Search criterion for the name to retrieve.
The search criterion can be the complete name, or the beginning
character or characters of the name. The name is sensitive and the
percent character (%) can be used as a wildcard to match any
character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all users are returned and these
results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-42
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Return result
UserContainerVO that contains an array of users that match the
search criterion.
The UserContainerVO also contains an ErrorVO, which is empty if
one or more users are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="findUsersResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
findVidoes
Description
Retrieves each video that matches a designated search criterion.
Role
User
findVideos
Parameters
Return result
•
sessionId (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.
•
video VideoDetailsVO—Search criterion for the name to
retrieve. The search criterion can be the complete name, or the
beginning character or characters of the name. The name is
sensitive and the percent character (%) can be used as a wildcard
to match any character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all videos are returned and these
results are not paginated.
VideoContainerVO that contains an array of videos that match the
search criterion.
The VideoContainerVO also contains an ErrorVO, which is empty if
one or more videos are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="findVideosResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VideoContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-43
Chapter 2
Web Services API Functions
Function Descriptions
findVtgs
Function name
findVtgs
Description
Retrieves VTGs with a name that matches a designated search
criterion.
Role
User
Parameters
Return result
•
sessionId (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.
•
vtg (VtgVO)—Search criterion for the name to retrieve. The
search criterion can be the complete name, or the beginning
character or characters of the name. The name is sensitive and the
percent character (%) can be used as a wildcard to match any
character.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all VTGs are returned and these
results are not paginated.
VtgContainerVO that contains an array of VtgVOs that match the
search criterion.
The VtgContainerVO also contains an ErrorVO, which is empty if
one or more VTGs are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="findVtgsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getAllChannelGroups
Function name
getAllChannelGroups
Description
Retrieves all channel groups that are associated with your
Cisco IPICS ops view.
Role
User
Parameters
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channel groups are returned
and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-44
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Return result
ChannelGroupContainerVO that contains an array of
ChannelGroupVO value objects.
The ChannelGroupContainerVO also contains an ErrorVO, which is
empty if all channel groups are retrieved, or contains an explanation
if an exception occurs when the function executes.
Sample response
<xs:element name="getAllChannelsInChannelGroupResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelGroupContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getAllChannels
Function name
getAllChannels
Description
Retrieves all channels.
Role
User
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channels are returned and these
results are not paginated.
ChannelContainerVO that contains an array of ChannelVO value
objects.
The ChannelContainerVO also contains an ErrorVO, which is empty
if all channels are retrieved, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="getAllChannelsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getAllChannelsInChannelGroup
Function name
getAllChannelsInChannelGroup
Description
Retrieves all channels that are in the designated channel group.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-45
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
channelGroupId (int)—ID of the channel group from which to
retrieve all channels.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channels in the designated
channel group are returned and these results are not paginated.
ChannelContainerVO that contains an array of ChannelVO value
objects for all channels in the channel group.
The ChannelContainerVO also contains an ErrorVO, which is empty
if all channels in the channel group are retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getAllChannelsInChannelGroupResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getAllIncidents
Function name
getAllIncidents
Description
Retrieves all incidents that are associated your Cisco IPICS ops view.
Role
User
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all incidents are returned and these
results are not paginated.
ChannelContainerVO that contains an array of IncidentVO value
objects.
The ChannelContainerVO also contains an ErrorVO, which is empty
if all incidents are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getAllIncidentsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-46
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
getAllIncidentsWithIVtgStatus
Function name
getAllIncidentsWithIVtgStatus
Description
Retrieves all incidents that are associated with your Cisco IPICS ops
view and the status of each incident VTG that is associated with an
incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all incidents are returned and these
results are not paginated.
IncidentContainerVO containing that contains an array of IncidentVO
value objects.
The ChannelContainerVO also contains an ErrorVO, which is empty
if the function executes properly, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getAllIncidentsWithIVtgStatusResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getAllPhotos
Description
Retrieves all photographs that are associated with your Cisco IPICS
ops view.
Role
User
getAllPhotos
Parameters
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all photographs are returned and
these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-47
Chapter 2
Web Services API Functions
Function Descriptions
Return result
PhotoContainerVO that contains an array of PhotoVO value objects.
The PhotoContainerVO also contains an ErrorVO, which is empty if
all photographs are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getAllPhotosResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PhotoContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getAllPolicies
Function name
getAllPolicies
Description
Retrieves all policies that are associated with your Cisco IPICS ops
view.
Role
User
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all policies are returned and these
results are not paginated.
PolicyContainerVO that contains an array of PolicyVO value objects.
The PolicyContainerVO also contains an ErrorVO, which is empty if
all policies are retrieved, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="getAllPoliciesResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PolicyContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getAllRadios
Description
Retrieves all radios that are associated with your Cisco IPICS ops
view.
Role
User
getAllRadios
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-48
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all radios are returned and these
results are not paginated.
RadioContainerVO that contains an array of RadioVO value objects.
The RadioContainerVO also contains an ErrorVO, which is empty if
all radios are retrieved, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="getAllRadiosResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:RadioContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getAllUserGroups
Function name
getAllUserGroups
Description
Retrieves all user groups that are associated with your Cisco IPICS
ops view.
Role
User
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all user groups are returned and
these results are not paginated.
UserGroupContainerVO that contains an array of UserGroupVO
value objects.
The UserGroupContainerVO also contains an ErrorVO, which is
empty if all user groups are retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getAllUserGroupsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserGroupContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-49
Chapter 2
Web Services API Functions
Function Descriptions
getAllUsers
Function name
getAllUsers
Description
Retrieves all Cisco IPICS users that are associated with your Cisco
IPICS ops view.
Role
User
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all users are returned and these
results are not paginated.
UserContainerVO that contains an array of UserVO value objects
The UserContainerVO also contains an ErrorVO, which is empty if all
users are retrieved, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="getAllUsersResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getAllVideos
Description
Retrieves all videos that are associated with your Cisco IPICS ops
view.
Role
User
getAllVideos
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all videos are returned and these
results are not paginated.
VideoContainerVO that contains an array of VideoVO value objects.
The VideoContainerVO also contains an ErrorVO, which is empty if
all videos are retrieved, or contains an explanation if an exception
occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-50
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="getAllVideosResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VideoContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getAllVtgs
Description
Retrieves all VTGs that are associated with your Cisco IPICS ops
view.
Role
User
getAllVtgs
Parameters
Return result
•
sessionId (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.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all VTGs are returned and these
results are not paginated.
VtgContainerVO that contains an array of VtgVO value objects.
The VtgContainerVO also contains an ErrorVO, which is empty if all
VTGs are retrieved, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="getAllVtgsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getBelongingOpsViewForUser
Function name
getBelongingOpsViewForUser
Description
Retrieves the ops view to which a user belongs.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-51
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user whose
ops view you want to retrieve. This parameter must be entered in
all lower case.
IntegerVO that contains the ops view of the designated user.
The IntegerVO also contains an ErrorVO, which is empty if the ops
view is retrieved, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="getBelongingOpsViewForUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getChannel
Description
Retrieves summary information about a designated channel.
Role
User
getChannel
Parameters
Return result
•
sessionId (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.
•
channelId (int)—ID of the channel for which to retrieve
information.
ChannelVO that contains summary information about the designated
channel.
The ChannelVO also contains an ErrorVO, which is empty if
summary information about the channel is retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getChannelResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-52
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
getChannelDetails
Function name
getChannelDetails
Description
Retrieves detailed information about a designated channel.
Role
User
Parameters
Return result
•
sessionId (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.
•
channelId (int)—ID of the channel for which to retrieve detailed
information.
ChannelDetailVO that contains detailed information about the
designated channel.
The ChannelDetailVO also contains an ErrorVO, which is empty if
detailed information about the channel is retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getChannelDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelDetailVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getChannelGroupsForVtg
Function name
getChannelGroupsForVtg
Description
Retrieves channel groups that are associated with a designated VTG.
Role
User
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG for which to retrieve associated
channel groups.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channel groups are returned
and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-53
Chapter 2
Web Services API Functions
Function Descriptions
Return result
ChannelGroupContainerVO that contains an array of
ChannelGroupVO value objects for all channel groups that are
associated with the VTG.
The ChannelGroupContainerVO also contains an ErrorVO, which is
empty if all channels that are associated with the VTG are retrieved,
or contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getChannelGroupsForVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgParticipantContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getChannelsAssociatedToUser
Function name
getChannelsAssociatedToUser
Description
Retrieves all channels that are associated with a designated user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve associated channels. This parameter must be entered
in all lower case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channels that are associated
with the designated user are returned and these results are not
paginated.
ChannelContainerVO that contains an array of ChannelVO value
objects for all channels that are associated with the user.
The ChannelContainerVO also contains an ErrorVO, which is empty
if all channels that are associated with the user are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getChannelsAssociatedToUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-54
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
getChannelsForIncident
Function name
getChannelsForIncident
Description
Retrieves a list of channels that are associated with a designated
incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident for which to retrieve
associated channels.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channels that are associated
with the incident are returned and these results are not paginated.
ChannelContainerVO that contains an array of ChannelVO value
objects for all channels that are associated with the incident.
The ChannelContainerVO also contains an ErrorVO, which is empty
if all channels that are associated with the incident are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getChannlesForIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:ChannelContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getChannelsForVtg
Function name
getChannelsForVtg
Description
Retrieves a list of channels that are associated with a designated VTG.
Role
User
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG for which to retrieve associated
channels.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all channels that are associated
with the VTG are returned and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-55
Chapter 2
Web Services API Functions
Function Descriptions
Return result
ChannelContainerVO that contains an array of ChannelVO value
objects for all channels that are associated with the designated VTG.
The ChannelContainerVO also contains an ErrorVO, which is empty
if all channels that are associated with the VTG are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getChannelsForVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgParticipantContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getChannelStatus
Function name
getChannelStatus
Description
Retrieves the status of the designated channel.
Role
User
Parameters
Return result
•
sessionId (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.
•
channelId (int)—ID of the channel for which to retrieve status.
StringVO that contains the status of the designated channel.
The StringVO also contains an ErrorVO, which is empty if the status
of the channel is retrieved, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="getChannelStatusResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getDigitId
Description
Retrieves the digit ID for a user.
Role
User
getDigitId
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-56
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve the digit ID. This parameter must be entered in all
lower case.
StringVO that contains the digit ID of the user.
The StringVO also contains an ErrorVO, which is empty if the digit
ID is retrieved, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="getDigitIdResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getDigitPassword
Function name
getDigitPassword
Description
Retrieves the digit password for a user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve the digit password. This parameter must be entered in
all lower case.
StringVO that contains the digit password the user.
The StringVO also contains an ErrorVO, which is empty if the
password is retrieved, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="getDigitPasswordResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-57
Chapter 2
Web Services API Functions
Function Descriptions
getIncident
Function name
getIncident
Description
Retrieves summary information about a designated incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident for which to retrieve
summary information.
IncidentVO that contains summary information about the incident.
The IncidentVO also contains an ErrorVO, which is empty if
summary information about the incident is retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getIncidentDetails
Function name
getIncidentDetails
Description
Retrieves detailed information about a designated incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident for which to retrieve
summary information.
IncidentVO that contains detailed information about the incident.
The IncidentVO also contains an ErrorVO, which is empty if detailed
information about the incident is retrieved, or contains an explanation
if an exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-58
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="getIncidentDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentDetailsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getIncidentParticipants
Function name
getIncidentParticipants
Description
Retrieves all resources that are associated with an incident. Resources
include channels, journals, radios, photographs, users, videos, and
VTGs.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (String)—ID of the incident for which to retrieve
resources (channels, journals, radios, photographs, users, videos,
and VTGs).
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all incident resources are returned
and these results are not paginated.
IncidentParticipantContainerVO that contains an array of
IncidentParticipantVO value objects for each resource that is
associated with the incident.
The IncidentParticipantContainerVO also contains an ErrorVO,
which is empty if all resources that are associated with the incident
are retrieved, or contains an explanation if an exception occurs when
the function executes.
Sample response
<xs:element name="getIncidentParticipantsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentParticipantContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getIncidentsForUser
Function name
getIncidentsForUser
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-59
Chapter 2
Web Services API Functions
Function Descriptions
Description
Retrieves a list of all incidents that are associated with a designated
user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userId (int)—System-generated ID of the user for whom to
retrieve associated incidents.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all incidents that are associated
with the user are returned and these results are not paginated.
IncidentContainerVO that contains an array of IncidentVO value
objects for each incident that is associated with the user.
The IncidentContainerVO also contains an ErrorVO, which is empty
if all incidents that are associated with the user are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getIncidentsForUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getIncidentVtg
Function name
getIncidentVtg
Description
Retrieves information about the incident VTG that is associated with
a designated incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident for which to retrieve the
incident VTG information.
VtgDetailVO that contains information about the incident VTG.
The VtgDetailVO also contains an ErrorVO, which is empty if
information about the incident VTG is retrieved, or contains an
explanation if an exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-60
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="getIncidentVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgDetailVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getIncidentVtgOptions
Function name
getIncidentVtgOptions
Description
Retrieves VTG options for the incident VTG that is associated with a
designated incident. Options include the allow VAD, latch, listen
only, region ID, and RX mute settings.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident from which to retrieve the
incident VTG options.
IncidentVtgOptionsVO that contains VTG options for the incident
VTG.
The IncidentVtgOptionsVO also contains an ErrorVO, which is
empty if VTG options for the incident VTG are retrieved, or contains
an explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getIncidentVtgOptionsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentVtgOptionsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getIncidentVtgUserOptions
Function name
getIncidentVtgUserOptions
Description
Retrieves incident VTG options for an incident VTG user. Options
include latch, listen only, and RX mute.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-61
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident from which to retrieve the
incident VTG user options.
•
userId (int)—System-generated ID of the user for whom to
retrieve options.
IncidentVtgUserOptionsVO that contains incident VTG user options.
The IncidentVtgUserOptionsVO also contains an ErrorVO, which is
empty if incident VTG options for the incident VTG are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getIncidentVtgUserOptionsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IncidentVtgUserOptionsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getIpicsVersion
Function name
getIpicsVersion
Description
Retrieves the version of Cisco IPICS that is running on the active
Cisco IPICS server.
Role
User
Parameters
Return result
•
sessionId (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.
StringVO that contains the version of Cisco IPICS that is running on
the active Cisco IPICS server.
The StringVO also contains an ErrorVO, which is empty if the version
of Cisco IPICS is retrieved, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="getIpicsVersionResponse">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0"
name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-62
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
getJournal
Function name
getJournal
Description
Retrieves summary information about a designated journal.
Role
User
Parameters
Return result
•
sessionId (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.
•
journalId (int)—ID of the journal for which to retrieve summary
information.
JournalVO that contains summary information about the journal.
The JournalVO also contains an ErrorVO, which is empty if summary
information about the journal is retrieved, or contains an explanation
if an exception occurs when the function executes.
Sample response
<xs:element name="getJournalResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:JournalVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getJournalDetails
Function name
getJournalDetails
Description
Retrieves detailed information about a designated journal.
Role
User
Parameters
Return result
•
sessionId (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.
•
journalId (int)—ID of the journal for which to retrieve detailed
information.
JournalDetailsVO that contains detailed information about the
journal.
The JournalDetailsVO also contains an ErrorVO, which is empty if
detailed information about the journal is retrieved, or contains an
explanation if an exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-63
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="getJournalDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:JournalDetailsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getJournalsForIncident
Function name
getJournalsForIncident
Description
Retrieves all journals for a designated incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident for which to retrieve journals.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all journals that are associated
with the incident are returned and these results are not paginated.
JournalContainerVO that contains an array of JournalVO value
objects for all journals that are associated with the incident.
The JournalContainerVO also contains an ErrorVO, which is empty if
all journals that are associated with the incident are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getJournalsForIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:JournalContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getPhonesAssociatedToUser
Function name
getPhonesAssociatedToUser
Description
Retrieves all phones that are associated with a designated user.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-64
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve associated phones. This parameter must be entered in
all lower case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all phones that are associated with
the user are returned and these results are not paginated.
PhoneContainerVO that contains an array of PhoneVO value objects
for all phones that are associated with the user.
The PhoneContainerVO also contains an ErrorVO, which is empty if
all phones that are associated with the user are retrieved, or contains
an explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getPhonesAssociatedToUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PhoneContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getPhoto
Description
Retrieves summary information about a photograph.
Role
User
getPhoto
Parameters
Return result
•
sessionId (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.
•
photoId (int)—ID of the photograph for which to retrieve
summary information.
PhotoVO that contains summary information about the photograph.
The PhotoVO also contains an ErrorVO, which is empty if summary
information about the photograph is retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getPhotoResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PhotoVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-65
Chapter 2
Web Services API Functions
Function Descriptions
getPhotoDetails
Function name
getPhotoDetails
Description
Retrieves detailed information about a photograph.
Role
User
Parameters
Return result
•
sessionId (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.
•
photoId (int)—ID of the photograph for which to retrieve detailed
information.
PhotoDetailsVO that contains detailed information about the
photograph.
The PhotoDetailsVO also contains an ErrorVO, which is empty if
detailed information about the photograph is retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getPhotoDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PhotoDetailsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getPhotosForIncident
Function name
getPhotosForIncident
Description
Retrieves a list of photographs that are associated with a designated
incident.
Role
User
Parameters
•
sessionId (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.
•
incidentId (int)—ID of the incident for which to retrieve
associated photos.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all photographs that are associated
with the incident are returned and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-66
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Return result
PhotoContainerVO that contains an array of PhotoVO value objects
for all photographs that are associated with the incident.
The PhotoContainerVO also contains an ErrorVO, which is empty if
all photographs that are associated with the incident are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getPhotosForIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PhotoContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getPmcProfile
Function name
getPmcProfile
Description
Retrieves IDC profile information for the designated user. The system
uses profile information to cause an IDC to appear and function in the
same way for a user regardless of the PC on which the user runs the
IDC.
Role
User
Parameters
Return result
•
sessionId (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.
•
id (int)—System-generated ID of the user for whom to retrieve
IDC profile information.
StringVO that contains IDC profile information.
The StringVO also contains an ErrorVO, which is empty if IDC
profile information is retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getPmcProfileResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getPoliciesAssociatedToUser
Function name
getPoliciesAssociatedToUser
Description
Retrieves all policies that are associated with a designated user.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-67
Chapter 2
Web Services API Functions
Function Descriptions
Role
Parameters
Return result
User
•
sessionId (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.
•
userLogin (String)— Cisco IPICS user name of the user for
whom to retrieve associated policies. This parameter must be
entered in all lower case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all policies that are associated
with the user are returned and these results are not paginated.
PolicyContainerVO that contains an array of PolicyVO value objects
for all policies that are associated with the user.
The PolicyContainerVO also contains an ErrorVO, which is empty if
all policies that are associated with the user are retrieved, or contains
an explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getPoliciesAssociatedToUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PolicyContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getPolicy
Description
Retrieves summary information about a policy.
Role
User
getPolicy
Parameters
Return result
•
sessionId (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.
•
policyId (int)—ID of the policy for which to retrieve summary
information.
PolicyVO that contains summary information about the policy.
The PolicyVO also contains an ErrorVO, which is empty if summary
information about the policy is retrieved, or contains an explanation
if an exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-68
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="getPolicyResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PolicyVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getPolicyDetails
Function name
getPolicyDetails
Description
Retrieves detailed information about a policy.
Role
User
Parameters
Return result
•
sessionId (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.
•
policyId (int)—ID of the policy for which to retrieve detailed
information.
PolicyDetailsVO that contains detailed information about the policy.
The PolicyDetailsVO also contains an ErrorVO, which is empty if
detailed information about the policy is retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getPolicyDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PolicyDetailsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getPolicyExecutionStatus
Function name
getPolicyExecutionStatus
Description
Retrieves summary status information about a the last execution of a
policy.
Role
User
Parameters
•
sessionId (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.
•
policyId (int)—ID of the policy for which to retrieve a status
summary of the execution.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-69
Chapter 2
Web Services API Functions
Function Descriptions
Return result
PolicyExecutionStatusVO that contains summary information about
of the last execution of the designated policy.
The PolicyExecutionStatusVO also contains an ErrorVO, which is
empty if summary information is retrieved, or contains an explanation
if an exception occurs when the function executes.
Sample response
<xs:element name="getPolicyExecutionStatusResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PolicyExecutionStatusVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getPolicyExecutionStatusDetails
Function name
getPolicyExecutionStatusDetails
Description
Retrieves detailed status information about the execution of each
policy that is associated with a designated user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve detailed information about of the last execution of
associated policies. This parameter must be entered in all lower
case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, the execution status of all policies
that are associated with the user are returned and these results are
not paginated.
PolicyExecutionStatusContainerVO that contains an array of
PolicyExecutionStatusVO value objects that provide detailed
information about the execution of a policy and its action.
The PolicyExecutionStatusContainerVO also contains an ErrorVO,
which is empty if detailed information is retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getPolicyExecutionStatusDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:PolicyExecutionStatusContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-70
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
getRadiosAssociatedToUser
Function name
getRadiosAssociatedToUser
Description
Retrieves a list of radios that are associated with a designated user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve associated radios. This parameter must be entered in
all lower case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all radios that are associated with
the user are returned and these results are not paginated.
RadioContainerVO that contains an array of RadioVO value objects
for all radios that are associated with the user.
The RadioContainerVO also contains an ErrorVO, which is empty if
all radios that are associated with the user are retrieved, or contains
an explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getRadiosAssociatedToUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:RadioContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getRadiosForIncident
Function name
getRadiosForIncident
Description
Retrieves a list of radios that are associated with a designated
incident.
Role
User
Parameters
•
sessionId (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.
•
incidentId (String)—ID of the incident for which to retrieve
associated radios.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all radios that are associated with
the incident are returned and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-71
Chapter 2
Web Services API Functions
Function Descriptions
Return result
RadioContainerVO that contains an array of RadioVO value objects
for all radios that are associated with the incident.
The RadioContainerVO also contains an ErrorVO, which is empty if
all radios that are associated with the incident are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getRadiosForIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:RadioContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getRadiosForVtg
Function name
getRadiosForVtg
Description
Retrieves a list of radios that are associated with a designated VTG.
Role
User
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG for which to retrieve associated
radios.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all radios that are associated with
the VTG are returned and these results are not paginated.
RadioContainerVO that contains an array of RadioVO value objects
for all radios that are associated with the designated VTG.
The RadioContainerVO also contains an ErrorVO, which is empty if
all radios that are associated with the VTG are retrieved, or contains
an explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getRadiosForVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgParticipantContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getUser
getUser
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-72
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Description
Retrieves summary information about the designated user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userId (int)—System-generated ID of the user for whom to
retrieve summary information.
UserVO that contains summary information about the user.
The UserVO also contains an ErrorVO, which is empty if summary
information about the user is retrieved, or contains an explanation if
an exception occurs when the function executes.
Sample response
<xs:element name="getUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUserAddress
Function name
getUserAddress
Description
Retrieves the physical address of a designated user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve the address. This parameter must be entered in all
lower case.
AddressVO that contains address information of the user.
The AddressVO also contains an ErrorVO, which is empty if address
information of the user is retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getUserAddressResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:AddressVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-73
Chapter 2
Web Services API Functions
Function Descriptions
getUserAudioStatus
Function name
getUserAudioStatus
Description
Retrieves a flag that indicates if the IDC of a user has audio disabled
or enabled. When audio is disabled, the IDC cannot transmit or
receive audio.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve the IDC audio status. This parameter must be entered
in all lower case.
BooleanVO that contains true if IDC audio is disabled for the user, or
false if IDC audio is not disabled for the user.
The BooleanVO also contains an ErrorVO, which is empty if IDC
audio is disabled for the user, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getUserAudioStatusResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUserDetails
Function name
getUserDetails
Description
Retrieves detailed information about a designated user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userId (int)—System-generated ID of the user for whom to
retrieve detailed information.
UserDetailsVO that contains detailed information about the user.
The UserDetailsVO also contains an ErrorVO, which is empty if
detailed information about the user is retrieved, or contains an
explanation if an exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-74
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="getUserDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserDetailsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUserDialPreference
Function name
getUserDialPreference
Description
Retrieves the dial preferences that are associated with a designated
user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve the dial preference. This parameter must be entered in
all lower case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all dial preferences for the user are
returned and these results are not paginated.
DialAddressContainerVO that contains an array of DialAddressVO
value objects for all dial preferences that are associated with the user.
The DialAddressContainerVO also contains an ErrorVO, which is
empty if dial preferences are retrieved, or contains an explanation if
an exception occurs when the function executes.
Sample response
<xs:element name="getUserDialPreferenceResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:DialAddressContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUserDirectory
Function name
getUserDirectory
Description
Retrieves the users for whom a direct connect number is assigned in
the designated serial radio descriptor file.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-75
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
descriptorId (String)—ID of the radio descriptor file from which
to retrieve users for whom a direct connect number is assigned.
StringVO that contains, in an XML string, the users for whom a direct
connect number is assigned in the designated serial radio descriptor
file.
The StringVO also contains an ErrorVO, which is empty if the users
are retrieved, or contains an explanation if an exception occurs when
the function executes.
Sample response
<xs:element name="getUserDirectoryResponse">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0"
name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getUserGroup
Description
Retrieves summary information about the designated user group.
Role
User
getUserGroup
Parameters
Return result
•
sessionId (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.
•
groupId (int)—ID of the user group for which to retrieve
summary information.
UserGroupVO that contains summary information about the
designated user group.
The UserGroupVO also contains an ErrorVO, which is empty if
summary information is retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getUserGroupResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserGroupVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-76
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
getUserGroupMembers
Function name
getUserGroupMembers
Description
Retrieves all the users in a designated user group.
Role
User
Parameters
Return result
•
sessionId (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.
•
userGroupId (int)—ID of the group user for which to retrieve all
members.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all members in the user group are
returned and these results are not paginated.
UserContainerVO that contains an array of UserVO value objects for
all members of the user group.
The UserContainerVO also contains an ErrorVO, which is empty if all
members of the user group are retrieved, or contains an explanation if
an exception occurs when the function executes.
Sample response
<xs:element name="getUserGroupMembersResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUserGroupsForVtg
Function name
getUserGroupsForVtg
Description
Retrieves user groups that are associated with the designated VTG.
Role
User
Parameters
•
sessionId (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.
•
vtgId (String)—ID of the VTG for which to retrieve associated
user groups.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all users groups that are associated
with the VTG are returned and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-77
Chapter 2
Web Services API Functions
Function Descriptions
Return result
VtgParticipantContainerVO that contains an array of
VtgParticipantVO value objects for all user groups that are associated
with the VTG.
The VtgParticipantContainerVO also contains an ErrorVO, which is
empty if all user groups that are associated with the VTG are
retrieved, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="getUserGroupsForVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgParticipantContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getUserId
Description
Retrieves the system-generated user ID for the designated user.
Role
User
getUserId
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for which
to retrieve the system-generated user ID. This parameter must be
entered in all lower case.
IntegerVO that contains system-generated user ID for the designated
user.
The VtgParticipantContainerVO also contains an ErrorVO, which is
empty if the user ID is retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getUserIdResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUserListenerStatus
Function name
getUserListenerStatus
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-78
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Description
Retrieves a flag that indicates whether the IDC of a user is in
listen-only mode. In this mode, the user is muted.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve the IDC audio status. This parameter must be entered
in all lower case.
BooleanVO that contains true if the IDC is in listen-only mode
(muted), or false if the IDC is not in listen-only mode.
The BooleanVO also contains an ErrorVO, which is empty if the
mode is returned, or contains an explanation if an exception occurs
when the function executes
Sample response
<xs:element name="getUserListenerStatusResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUserNotificationPreference
Function name
getUserNotificationPreference
Description
Retrieves the notification preferences that is associated with a
designated user.
Role
User
Parameters
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve the notification preference. This parameter must be
entered in all lower case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all dial preferences for the user are
returned and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-79
Chapter 2
Web Services API Functions
Function Descriptions
Return result
NotificationAddressContainerVO that contains an array of
NotificationAddressVO value objects for all notification preferences
that are associated with the user.
The NotificationAddressContainerVO also contains an ErrorVO,
which is empty if all notification preferences that are associated with
the user are retrieved, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="getUserNotificationPreferenceResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:NotificationAddressContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getUserRoles
Description
Retrieves the list of roles for a designated user.
Role
User
getUserRoles
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user whose
roles to retrieve. This parameter must be entered in all lower case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. For this function, you should always pass
null.
UserRoleContainerVO that contains an array of UserRoleVO value
objects for all roles that are assigned to the user.
The UserRoleContainerVO also contains an ErrorVO, which is empty
if all roles that are assigned to the user are retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getUserRolesResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserRoleContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-80
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
getUsersAssociatedToRadio
Function name
getUsersAssociatedToRadio
Description
Retrieves a list of users that are associated with a radio.
Role
User
Parameters
Return result
•
sessionId (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.
•
radioId (String)—ID of the radio for which to retrieve associated
users.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all users that are associated with
the radio are returned and these results are not paginated.
UserContainerVO that contains an array of UserVO value objects for
all users that are associated with the designated radio.
The UserContainerVO also contains an ErrorVO, which is empty if all
users that are associated with the radio are retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getUsersAssociatedToRadioResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUsersForIncident
Function name
getUsersForIncident
Description
Retrieves a list of users that are associated with a designated incident.
Role
User
Parameters
•
sessionId (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.
•
incidentId (String)—ID of the incident for which to retrieve
associated users.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all users that are associated with
the incident are returned and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-81
Chapter 2
Web Services API Functions
Function Descriptions
Return result
UserContainerVO that contains an array of UserVO value objects for
all users that are associated with the incident.
The UserContainerVO also contains an ErrorVO, which is empty if all
users that are associated with the incident are retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getUsersForIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:UserContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getUsersForVtg
Function name
getUsersForVtg
Description
Retrieves a list of users that are associated with a designated VTG.
Role
User
Parameters
Return result
•
sessionId (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.
•
vtgtId (String)—ID of the VTG for which to retrieve associated
VTGs.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all users that are associated with
the VTG are returned and these results are not paginated.
VtgParticipantContainerVO that contains an array of
VtgParticipantVO value objects for all users that are associated with
the VTG.
The VtgParticipantContainerVO also contains an ErrorVO, which is
empty if all users that are associated with the VTG are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name=" getUsersForVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgParticipantContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-82
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
getUserStatus
Function name
getUserStatus
Description
Retrieves the Cisco IPICS status of the designated user. The status can
be enabled or disabled. A user with the disabled status cannot log in
to Cisco IPCS.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of each user for
whom to retrieve active status. This parameter must be entered in
all lower case.
StringVO that contains enabled or disabled, which indicates the
Cisco IPICS status of designated user.
The StringVO also contains an ErrorVO, which is empty if the status
is retrieved, or contains an explanation if an exception occurs when
the function executes.
Sample response
<xs:element name="getUserStatusResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getVideo
Description
Retrieves summary information about the designated video.
Role
User
getVideo
Parameters
Return result
•
sessionId (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.
•
videoId (int)—ID of the video for which to retrieve summary
information.
VideoVO that contains summary information about the designated
video.
The VideoVO also contains an ErrorVO, which is empty if summary
information about the video is retrieved, or contains an explanation if
an exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-83
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
xs:element name="getVideoResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VideoVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getVideoDetails
Function name
getVideoDetails
Description
Retrieves detailed information about the designated video.
Role
User
Parameters
Return result
•
sessionId (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.
•
videoId (int)—ID of the video for which to retrieve detailed
information.
VideoDetailsVO that contains detailed information for the designated
video.
The VideoVO also contains an ErrorVO, which is empty if detailed
information about the video is retrieved, or contains an explanation if
an exception occurs when the function executes.
Sample response
<xs:element name="getVideoDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VideoDetailsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getVideosForIncident
Function name
getVideosForIncident
Description
Retrieves a list of videos that are associated with a designated
incident.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-84
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
incidentId (int) —ID of the incident for which to retrieve
associated videos.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all videos that are associated with
the VTG are returned and these results are not paginated.
VideoContainerVO that contains an array of VideoVO value objects
for all videos that are associated with the designated incident.
The VideoContainerVO also contains an ErrorVO, which is empty if
all videos that are associated with the incident are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getVideosForIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VideoContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getVtgDetails
Description
Retrieves detailed information about the designated VTG.
Role
User
getVtgDetails
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG for which to retrieve detailed
information.
VtgDetailVO that contains detailed information about the designated
VTG.
The VtgDetailVO also contains an ErrorVO, which is empty if
detailed information about the VTG is retrieved, or contains an
explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getVtgDetailsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgDetailVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-85
Chapter 2
Web Services API Functions
Function Descriptions
getVtgOptions
Function name
getVtgOptions
Description
Retrieves information about the status of a variety of options for a
VTG.
Role
User
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG for which to retrieve option status
information.
VtgOptionsVO that contains information about the status of a variety
of options for the designated VTG.
The VtgOptionsVO also contains an ErrorVO, which is empty if VTG
options are retrieved, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="getVtgOptionsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgOptionsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getVtgParticipants
Function name
getVtgParticipants
Description
Retrieves all participants in a designated VTG. Participants include
channels, channel groups, radios, users, user groups, and VTGs.
Role
User
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG from which to retrieve all participants
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all participants in the VTG are
returned and these results are not paginated.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-86
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Return result
VtgParticipantContainerVO that contains an array of
VtgParticipantVO value objects for all participants (channels,
channel groups, radios, users, user groups, and VTGs) that are in the
designated VTG.
The VtgParticipantContainerVO also contains an ErrorVO, which is
empty if all participants that are in the VTG are retrieved, or contains
an explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getVtgParticipantsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgParticipantContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getVtgParticipantStatus
Function name
getVtgParticipantStatus
Description
Retrieves the status of a VTG participant. The participant can be a
user, user group, channel, channel group, or VTG. Status can be
disconnected, error, pending, or active.
Role
User
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG that contains the participant for
which the status is to be retrieved.
•
participantID (int)—ID of the participant whose status is be
retrieved.
•
resourceType (String)—Participant type: user, user-group,
channel, channel-group, vtg, or radio.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-87
Chapter 2
Web Services API Functions
Function Descriptions
Return result
StringVO that contains the status of the designated VTG participant.
Status can be any of the following:
•
active—Participant is associated with the VTG.
•
pending—Participant is in the process of becoming associated
with the VTG.
•
error—Participant could not be associated with the VTG. (This
situation typically occurs if there are insufficient system
resources.)
•
disconnected—The participant could not be connected to the
RMS or could not be configured on the RMS.
The StringVO also contains an ErrorVO, which is empty if the status
of the VTG participant is retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getVtgParticipantStatusResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getVtgsAssociatedToUser
Function name
getVtgsAssociatedToUser
Description
Retrieves all VTGs that are associated with a user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to retrieve associated VTGs. This parameter must be entered in
all lower case.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all VTGs that are associated with
the user are returned and these results are not paginated.
VtgContainerVO that contains an array VtgVO value objects for all
VTGs that are associated with the designated user.
The VtgContainerVO also contains an ErrorVO, which is empty if all
VTGs that are associated with the user are retrieved, or contains an
explanation if an exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-88
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="getVtgsAssociatedToUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getVtgsForIncident
Function name
getVtgsForIncident
Description
Retrieves a list of VTGs that are associated with a designated
incident.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (String)—ID of the incident for which to retrieve
associated VTGs.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all VTGs that are associated with
the incident are returned and these results are not paginated.
VtgContainerVO that contains an array of VtgVO value objects for all
VTGs that are associated with the designated incident.
The VtgContainerVO also contains an ErrorVO, which is empty if all
VTGs that are associated with the incident are retrieved, or contains
an explanation if an exception occurs when the function executes.
Sample response
<xs:element name="getVtgsForIncidentResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getVtgsForVtg
Description
Retrieves a list of VTGs that are associated with a designated VTG.
Role
User
getVtgsForVtg
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-89
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
vtgtId (String)—ID of the VTG for which to retrieve associated
VTGs.
•
pc (PaginationContextVO)—Specifies format and limits of the
output of this function. If null, all VTGs that are associated with
the VTG are returned and these results are not paginated.
VtgParticipantContainerVO that contains an array of
VtgParticipantVO value objects for all VTGs that are associated with
the designated VTG.
The VtgParticipantContainerVO also contains an ErrorVO, which is
empty if all VTGs that are associated with the VTG are retrieved, or
contains an explanation if an exception occurs when the function
executes.
Sample response
<xs:element name="getVtgsForVtgResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgParticipantContainerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
getVtgStatus
Description
Retrieves the ID, name, description, and status (active, idle, or
pending) of a VTG. “Pending” indicates a VTG that is in transition
from active to idle state or from idle to active state.
Role
User
getVtgStatus
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG for which to retrieve information.
StringVO that contains information for the designated VTG.
The StringVO also contains an ErrorVO, which is empty if status
information is retrieved, or contains an explanation if an exception
occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-90
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="getVtgStatusResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:StringVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
getVtgUserOptions
Function name
getVtgUserOptions
Description
Retrieves the settings of the latch, listen only, and rxmute VTG
options settings for a designated VTG and user.
Role
User
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG that includes the user for whom to
retrieve option settings.
•
userId (int)—System-generated ID of the user users for whom to
retrieve VTG option settings.
VtgUserOptionsVO that contains the latch, listen only, and rxmute
information for the designated user in the designated VTG.
The VtgUserOptionsVO also contains an ErrorVO, which is empty if
option information is retrieved, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="getVtgUserOptionsResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:VtgUserOptionsVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
isActiveChannel
Function name
isActiveChannel
Description
Determines if a channel is active or disabled.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-91
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
channelId (int)—ID of the channel to query.
BooleanVO that contains true if the channel is active, or false if the
channel is disabled.
The BooleanVO also contains an ErrorVO, which is empty if the
function returns a value, or contains explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="isActiveChannelResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
isActiveIncidentVtg
Function name
isActiveIncidentVtg
Description
Determines if an incident VTG in a designated incident is active or
inactive.
Role
User
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident that includes the incident
VTG for which to determine status.
BooleanVO that contains true if the incident VTG is active, or false
if the incident VTG is inactive.
The BooleanVO also contains an ErrorVO, which is empty if the
function returns a value, or contains explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="isActiveIncidentVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-92
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
isActiveUser
Function name
isActiveUser
Description
Determines if a user is active or disabled.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user to query.
This parameter must be entered in all lower case.
BooleanVO that contains true if the user is active, or false if the user
is disabled.
The BooleanVO also contains an ErrorVO, which is empty if the
function returns a value, or contains explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="isActiveUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
isActiveVtg
Description
Determines if a VTG is active or inactive.
Role
User
isActiveVtg
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG to query.
BooleanVO that contains true if the VTG is active, or false if the
VTG is inactive.
The BooleanVO also contains an ErrorVO, which is empty if the
function returns a value, or contains explanation if an exception
occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-93
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="isActiveVtgResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
notifyAllIncidentVtgMembers
Function name
notifyAllIncidentVtgMembers
Description
Sends a notification to each user in the incident VTG of the
designated incident. The notification method that the system uses for
a user is configured in the communications preferences for that user
in the Cisco IPICS Administration Console or by the
setNotificationPreferences API function.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident that includes the incident
VTG whose members are to be notified.
BooleanVO that contains true if all members of the incident VTG in
the designed incident are notified, or false if not all members are
notified.
The BooleanVO also contains an ErrorVO, which is empty if all
members of the incident VTG are notified, or contains an explanation
if an exception occurs when the function executes.
Sample response
<xs:element name="notifyAllIncidentVtgMembersResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
notifyAllVtgMembers
Function name
notifyAllVtgMembers
Description
Sends a notification to each user in the designated VTG, including
members of user groups in the VTG. The notification method that the
system uses for a user is configured in the communications
preferences for that user in the Cisco IPICS Administration Console
or by the setNotificationPreferences API function.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-94
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Role
Parameters
Return result
Dispatcher
•
sessionId (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.
•
vtgId (int)—ID of the VTG that includes members to be notified.
BooleanVO that contains true if all members of the VTG are notified,
or false if not all members are notified.
The BooleanVO also contains an ErrorVO, which is empty if all
members of the VTG are notified, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name=" notifyAllVtgMembersResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
notifyIncidentVtgMember
Function name
notifyIncidentVtgMember
Description
Notifies a designated member of an incident VTG. The notification
method is based on notification options as configured for the user in
the Cisco IPICS Administration Console.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident that includes the incident
VTG with the member is to be notified.
•
userLogin (String)—Cisco IPICS user name of the incident VTG
member to be notified. This parameter must be entered in all
lower case.
BooleanVO that contains true if the designated incident VTG
member is notified, or false if the designated incident VTG member
is not notified.
The BooleanVO also contains an ErrorVO, which is empty if the
incident VTG member is notified, or contains an explanation if an
exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-95
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="notifyIncidentVtgMemberResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
notifyVtgMember
Function name
notifyVtgMember
Description
Notifies a designated member of a VTG. The notification method that
the system uses for a user is configured in the communications
preferences for that user in the Cisco IPICS Administration Console
or by the setNotificationPreferences API function.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG that includes the member is to be
notified.
•
userLogin (String)—Cisco IPICS user name of the VTG member
to be notified. This parameter must be entered in all lower case.
BooleanVO that contains true if the designated VTG member is
notified, or false if the designated VTG member is not notified.
The BooleanVO also contains an ErrorVO, which is empty if the VTG
member is notified, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="notifyVtgMemberResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
removeChannelFromVtg
Function name
removeChannelFromVtg
Description
Removes a channel from a VTG.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-96
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG from which to remove the channel.
•
channelId (int)—Unique of the channel to be removed from the
VTG.
BooleanVO that contains true if the channel is removed from the
VTG, or false if the channel is not removed from the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the
channel is removed from the VTG, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="removeChannelFromVtgResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
removePhoneAssociatedToUser
Function name
removePhoneAssociatedToUser
Description
Disassociates a phone from a user.
Role
Operator
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user from
whom to disassociate a phone. This parameter must be entered in
all lower case.
•
dialNumber (String)—Dial number of the phone to disassociate
from the user.
BooleanVO that contains true if the phone is disassociated from the
user, or false if the phone is not disassociated from the user.
The BooleanVO also contains an ErrorVO, which is empty if the
phone is disassociated from the user, or contains an explanation if an
exception occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-97
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="removePhoneAssociatedToUserResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
removeRadioFromVtg
Function name
removeRadioFromVtg
Description
Removes a radio from a VTG.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG from which to remove the radio.
•
radioId (int)—ID of the radio to be removed from the VTG.
BooleanVO that contains true if the radio is removed from the VTG,
or false if the radio is not removed from the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the radio
is removed from the VTG, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="removeRadioFromVtgResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
removeResourceFromIncident
Function name
removeResourceFromIncident
Description
Disassociates one or more resource from an incident.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-98
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
incidentId (int)—ID of the incident from which to remove the
resource.
•
resourceIds (int[])—IDs of the resources to remove.
•
resourceType (String)—The type of resource to remove from the
incident: User, Video, Photo, Channel, Radio, or Vtg.
IntegerVO that contains the number of resource that were removed
from the incident.
The IntegerVO also contains an ErrorVO, which is empty if the
function executes properly, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="removeResourceFromIncidentResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
removeUserFromVtg
Function name
removeUserFromVtg
Description
Removes a user from a VTG.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user to be
removed from the VTG. This parameter must be entered in all
lower case.
•
vtgId (int)—ID of the VTG from which to remove the user.
BooleanVO that contains true if the user is removed from the VTG,
or false if the user is not removed from the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the user
is removed from the VTG, or contains an explanation if an exception
occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-99
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="removeUserFromVtgResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
removeVtgFromVtg
Function name
removeVtgFromVtg
Description
Removes a VTG from a VTG.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
vtgIdRem (int)— ID of the VTG to remove.
•
vtgId (int)—ID of the VTG from which to remove the other VTG.
BooleanVO that contains true if the VTG is removed from the VTG,
or false if the VTG is not removed from the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the VTG
is removed from the VTG, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="removeVtgFromVtgResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
removeVtgParticipants
Function name
removeVtgParticipants
Description
Removes one or more participants from a VTG.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-100
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
vtgId (int)—ID of the VTG from which to remove participants.
•
parts (ResourceContainerVO)—The array of participants to be
removed from VTG.
BooleanVO that contains true if the participants are removed from
the VTG, or false if the participants are not removed from the VTG.
The BooleanVO also contains an ErrorVO, which is empty if the
function executes properly, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="removeVtgParticipantsResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
savePmcProfile
Function name
savePmcProfile
Description
Saves IDC profile information for the designated user. The system
uses profile information to cause an IDC to appear and function in the
same way for a user regardless of the PC on which the user runs the
IDC.
Role
User
Parameters
Return result
•
sessionId (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.
•
id (int)—System-generated ID of the user for whom to retrieve
IDC profile information
•
xmlString (String)—IDC profile information for the designated
user.
IntegerVO that contains 1 if the IDC profile is saved, or 0 if it is not.
The IntegerVO also contains an ErrorVO, which is empty if the IDC
profile is saved, or contains an explanation if an exception occurs
when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-101
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="savePmcProfileResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setBelongingOpsViewForUser
Function name
setBelongingOpsViewForUser
Description
Assigns an ops view to a user.
Role
Operator
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS use name of the user to whom
to assign an ops view. This parameter must be entered in all lower
case.
•
opsViewId (int)—ID of the ops view to assign to the user.
BooleanVO that contains true if the ops view is assigned to the user,
or false if is not.
The BooleanVO also contains an ErrorVO, which is empty if the ops
view is assigned, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="setBelongingOpsViewForUserResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setDialPreference
Function name
setDialPreference
Description
Adds a new dial preference for a user.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-102
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to set dial preferences. This parameter must be entered in all
lower case.
•
dialType (String)—Label for the dial number (BUSINESS,
BUSINESS2, BUSINESS3, CAR, HOME, HOME2, HOME3,
MOBILE, MOBILE2, MOBILE3, OTHER, PRIMARY,
SECONDARY).
•
dialNumber (String)—Phone number to dial.
•
dialOrder (int)—Order in which the system dials phone numbers
is if more than one dial number is configured.
BooleanVO that contains true if the dial preference is added for the
user, or false if the dial preference is not added.
The BooleanVO also contains an ErrorVO, which is empty if the dial
preference is added, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="setDialPreferenceResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
setDigitId
Description
Sets digit ID for a user. A digit ID is a numeric ID that a user enters
when accessing the Cisco IPICS service from a Cisco Unified IP
Phone or when accessing the Cisco IPICS telephony user interface.
Role
User
setDigitId
Parameters
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to set digit IDs. This parameter must be entered in all lower case.
•
digitId (String)—Digit ID for the user. Valid characters are
numerals 0 through 9.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-103
Chapter 2
Web Services API Functions
Function Descriptions
Return result
BooleanVO that contains true if the digit ID is set for the user, or
false if the digit ID is not set for the user.
The BooleanVO also contains an ErrorVO, which is empty if the digit
ID is set, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="setDigitIdResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setDigitPassword
Function name
setDigitPassword
Description
Sets a digit password for a user. A digit password is a password that
a user enters when accessing the Cisco IPICS service from a
Cisco Unified IP Phone or PIN that the user enters when accessing the
Cisco IPICS telephony user interface.
You specify requirements for passwords, including length and
character requirements, in the Administration > Options
window in the Cisco IPICS Administration Console.
Note
Role
Parameters
Return result
User
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to set a digit password. This parameter must be entered in all
lower case.
•
password (String)—Password of the user to be created. The
password can include letters, numbers, and special characters,
but no spaces. The system validates the password according the
parameters that are configured in Cisco IPICS Administration.
BooleanVO that contains true if the digit password is set for the user,
or false if the digit password is no set for the user.
The BooleanVO also contains an ErrorVO, which is empty if the digit
password is set, or contains an explanation if an exception occurs
when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-104
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="setDigitPasswordResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setIncidentVtgOptions
Function name
setIncidentVtgOptions
Description
Sets various options for an incident VTG.
Role
Dispatcher
Parameters
•
sessionId (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.
•
incidentId (int)—ID of the incident that contains the incident
VTG for which to set options.
•
latch (boolean):
– true—Enables the latch function for the incident VTG
– false—Disables the latch function
•
listenOnly (boolean):
– true—Enables listen only mode for the incident VTG
– false—Disables listen only mode
•
rxMute (String):
– all—When PTT is engaged, RX (receive transmission) is
muted on all voice resources
– this—When PTT is engaged, RX is muted on this incident
VTG
– none—When PTT is engaged, no voice resources are muted
•
allowVad (boolean):
– true—Enables the VAD function for the incident VTG
– false—Disables the VAD function
•
Return result
pmcRegionId (int)—Indicates the preferred region in which the
IDC displays the incident VTG.
BooleanVO that contains true if all designated incident VTG options
are set, or false if not all options are not set.
The BooleanVO also contains an ErrorVO, which is empty if the
function executes properly, or contains an explanation if an exception
occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-105
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="setIncidentVtgOptionsResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setIncidentVtgUserOptions
Function name
setIncidentVtgUserOptions
Description
Sets various options for a designated user in an incident VTG.
Role
Dispatcher
Parameters
•
sessionId (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.
•
incidentId (int)—ID of the incident that contains the incident
VTG for which to set options.
•
userId (int)—System-generated ID of the user for whom to set
incident VTG options
•
latch (boolean)—Enables or disables the latch function for the
designated user in the designated incident VTG as follows:
– true—Enables the latch function
– false—Disables the latch function
•
listenOnly (boolean)—Enables or disables listen only mode for
the designated user in the designated incident VTG as follows:
– true—Enables listen only mode
– false—Disables listen only mode
•
rxMute (boolean):
– true—Prevents the designated user from listening or
speaking in the designated incident VTG
– false—Allows the designated user to listen or speak in the
designated incident VTG
Return result
BooleanVO that contains true if the incident VTG options are set for
the user, or false incident VTG options are not set.
The BooleanVO also contains an ErrorVO, which is empty if the
function executes properly, or contains an explanation if an exception
occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-106
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="setIncidentVtgUserOptionsResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setNotificationPreference
Function name
setNotificationPreference
Description
Adds a new notification preference for a user.
Role
User
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to set notification preferences. This parameter must be entered in
all lower case.
•
notificationType (String)—Notification type preference
(EMAIL, PAGER, SMS)
•
notificationAddress (String)—Address for the designated
notification type.
BooleanVO that contains true if the notification preference is added
for the user, or false if the notification preference is not added for the
user.
The BooleanVO also contains an ErrorVO, which is empty if the
notification preference is added, or contains an explanation if an
exception occurs when the function executes.
Sample response
<xs:element name="setNotificationPreferenceResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setUserAddress
Function name
setUserAddress
Description
Adds a physical address for a user.
Role
User
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-107
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to add a physical address. This parameter must be entered in all
lower case.
•
address (AddressVO)—Address information.
BooleanVO that contains true if the address is added for the user, or
false if the address is not added for the user.
The BooleanVO also contains an ErrorVO, which is empty if the
address is added, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="setUserAddressResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setUserAudioStatus
Function name
setUserAudioStatus
Description
Enables or disables the ability of a user to hear and transmit audio on
an IDC.
Note
Role
Parameters
Return result
A user is not able to transmit audio (the user is muted) if audio
status for the user is enabled but listener status for the user is
disabled. See the “setUserListenerStatus” section on
page 2-109.
Operator
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
to enable or disable IDC audio. This parameter must be entered
in all lower case.
•
audioDisabled (boolean)—If true, the audio capability is
disabled. If false, the audio capability is enabled.
BooleanVO that contains true if the audio status is updated for the
user, or false if the audio status is not updated for the user.
The BooleanVO also contains an ErrorVO, which is empty if the
audio status is updated, or contains an explanation if an exception
occurs when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-108
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="setUserAudioStatusResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setUserListenerStatus
Function name
setUserListenerStatus
Description
Enables or disables the ability of a user to transmit audio on an IDC
(unmutes or mutes a user).
Note
Role
Parameters
Return result
If the audio status for a user is disabled (see the
“setUserAudioStatus” section on page 2-108), a user cannot
transmit audio in any case.
Operator
•
sessionId (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.
•
userLogin (String)—Cisco IPICS user name of the user for whom
enable or disable IDC audio. This parameter must be entered in
all lower case.
•
mute (boolean)—If true, the user is muted. If false, the user is
not muted.
BooleanVO that contains true if the audio status is updated for the
user, or false if the audio status is not updated for the user.
The BooleanVO also contains an ErrorVO, which is empty if the
audio status is updated, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="setUserListenerStatusResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
setVtgOptions
Description
Sets various options for a VTG.
setVtgOptions
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-109
Chapter 2
Web Services API Functions
Function Descriptions
Role
Parameters
Dispatcher
•
sessionId (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.
•
vtgId (int)—ID of the VTG for which to set options.
•
latch (boolean):
– true—Enables the latch function for the VTG
– false—Disables the latch function
•
listenOnly (boolean):
– true—Enables listen only mode for the VTG
– false—Disables listen only mode
•
rxMute (String):
– all—When PTT is engaged, RX (receive transmission) is
muted on all voice resources
– this—When PTT is engaged, RX is muted on this incident
VTG
– none—When PTT is engaged, no voice resources are muted
•
allowVad (boolean):
– true—Enables the VAD function for the incident VTG
– false—Disables the VAD function
•
Return result
pmcRegionId (int)—Indicates the preferred region in which the
IDC displays the VTG.
BooleanVO that contains true if the VTG options are set, or false if
the VTG options are not set.
The BooleanVO also contains an ErrorVO, which is empty if the
function executes properly, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="setVtgOptionsResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
setVtgUserOptions
Function name
setVtgUserOptions
Description
Sets various options for a designated user in a VTG.
Role
Dispatcher
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-110
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG for which to set options for a user.
•
userId (int)—System-generated ID of the user for whom to set
incident VTG options
•
latch (boolean):
– true—Enables the latch function for the VTG
– false—Disables the latch function
•
listenOnly (boolean):
– true—Enables listen only mode for the VTG
– false—Disables listen only mode
•
rxMute (boolean):
– true—Prevents the designated user from listening or
speaking in the designated incident VTG
– false—Allows the designated user to listen or speak in the
designated incident VTG
Return result
BooleanVO that contains true if the VTG options are set for the user,
or false if the VTG options are not set.
The BooleanVO also contains an ErrorVO, which is empty if the VTG
options are set, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="setVtgUserOptionsResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
startSession
Description
Logs into the IPICS web service, authenticates that the user has a
valid IPICS user account, starts a session, and returns a unique
session ID (sessionId), which must be used for subsequent web
service calls. Logging into the IPICS web service does not consume
a Cisco IPICS license.
Role
—
startSession
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-111
Chapter 2
Web Services API Functions
Function Descriptions
Parameters
Return result
•
userLogin (String)—Cisco IPICS user name of the user who is
executing the API client code.
•
password (String)—Cisco IPICS user password of the user who
is executing the API client code. This parameter is case sensitive.
•
clientDescriptorVO (ClientDescriptorVO)—Type of client that is
connecting to the web service.
SessionVO that contains the session ID.
The SessionVO also contains an ErrorVO, which is empty if the
session starts, or contains an explanation if an exception occurs when
the function executes.
Sample response
<xs:element name="startSessionResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:SessionVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
updateIncident
Function name
updateIncident
Description
Modifies various attributes of an incident.
Role
Dispatcher
Parameters
Return result
•
sessionId (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.
•
incident (IncidentDetailsVO)—Incident attributes to update.
IntegerVO that contains 1 if the incident is updated, or 0 if the
incident is not updated.
The IntegerVO also contains an ErrorVO, which is empty if the
incident is updated, or contains an explanation if an exception occurs
when the function executes.
Sample response
<xs:element name="updateIncidentResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-112
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
updatePhoto
Function name
updatePhoto
Description
Modifies various attributes of a photograph.
Role
User
Parameters
Return result
•
sessionId (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.
•
photo (PhotoDetailsVO)—Photograph attributes.
IntegerVO that contains 1 if the photograph is updated, or 0 if the
photograph is not updated.
The IntegerVO also contains an ErrorVO, which is empty if the
photograph is updated, or contains an explanation if an exception
occurs when the function executes.
Sample response
<xs:element name="updatePhotoResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
updateUserGroup
Function name
updateUserGroup
Description
Modifies various attributes of a user group.
Role
Operator
Parameters
Return result
•
sessionId (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.
•
group (UserGroupDetailsVO)—User group attributes.
BooleanVO that contains true if the user group is updated, or false if
the user group is not updated.
The IntegerVO also contains an ErrorVO, which is empty if the user
group is updated, or contains an explanation if an exception occurs
when the function executes.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-113
Chapter 2
Web Services API Functions
Function Descriptions
Sample response
<xs:element name="updateUserGroupResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:BooleanVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Function name
updateVideo
Description
Modifies various attributes of a video.
Role
User
updateVideo
Parameters
Return result
•
sessionId (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.
•
video (VideoDetailsVO)—Video attributes.
IntegerVO that contains 1 if the video is updated, or 0 if the video is
not updated.
The IntegerVO also contains an ErrorVO, which is empty if the video
is updated, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="updateVideoResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
updateVirtualTalkGroup
Function name
updateVirtualTalkGroup
Description
Modifies various attributes of a VTG.
Role
Dispatcher
Parameters
•
sessionId (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.
•
vtgId (int)—ID of the VTG to modify.
•
vtgName (String)—Name to set for the VTG.
•
vtgDescription (String)—Description to set for the VTG.
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-114
OL-21552-01
Chapter 2
Web Services API Functions
Function Descriptions
Return result
IntegerVO that contains 1 if the VTG is updated, or 0 if the VTG is
not updated.
The IntegerVO also contains an ErrorVO, which is empty if the VTG
is updated, or contains an explanation if an exception occurs when the
function executes.
Sample response
<xs:element name="updateVirtualTalkGroupResponse>">
<xs:complexType>
<xs:sequence>
<xs:element name="return" nillable="true"
type="ns1:IntegerVO"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
OL-21552-01
2-115
Chapter 2
Web Services API Functions
Function Descriptions
Cisco IPICS API Reference Guide, Cisco IPICS Release 4.0
2-116
OL-21552-01