Feedback
Table Of Contents
Physical Security Integration Management (PSIM) APIs
Example to Implement and Register a Service Interface
Define External Event Types Using the Event Definition Format
Create a Text File to Define the Event Names in Cisco PAM
Import the Files into Cisco PAM
Examples: Using Java and C# Code
API Functions
This chapter provide detailed descriptions for each function in the Cisco Physical Access Control API. It includes these topics:
Function Summary
Table 2-1 provides a summary of theCisco Physical Access Control API functions. Each function is described in detail in the section that is listed.
Table 2-1 API Function Summary
Functions for Authentication
Authenticates the username and password and returns a security context object which must be passed in all subsequent API calls. This method must be called before any other method is called.
Ends an authenticated session. The security context object is expired and a new object must be generated to start a new API session.
Physical Security Integration Management (PSIM)
Returns a list of physical access control device types, including the deviceTypeId, name, and a list of the possible device states.
This method returns a list of event types defined in Cisco PAM. Each event type indicates event type unique ID, name and category of event.
Returns a list of the Cisco PAM event categories. Event categories can be used to call all the events that occurred for the event types that belong to that category.
Returns a list of the camera devices in Cisco PAM. Cameras are associated with one or more access control devices, such as a door.
Returns a list of all access control devices configured in Cisco PAM.
Returns the child devices of the specified device.
Returns the names of all door groups, including the unique ID for each group name.
Returns all doors configured for the specified door group.
Returns the first name, last name, person ID and unique ID for access control personnel configured in Cisco PAM.
Returns all the personnel types defined in Cisco PAM.
Returns a list of Status definitions for personnel in Cisco PAM.
Returns the personnel records for a specified personnel type.
Adds a personnel record to Cisco PAM.
Updates a person's record in the Cisco PAM database. All properties in Cisco PAM are replaced by the new properties.
Returns information for a personnel record, including a picture if available.
Returns detailed information for the organizations defined in Cisco PAM.
Returns all the departments defined in Cisco PAM.
Lists the events and alarms defined by the selected parameters, including event category, time interval, and the unique ID for the device.
Lists events and alarms defined by the selected parameters, including event type, time interval, and the device unique ID.
Returns door access events related to granting or denying user access. Events can be returned for a specific user or device, or for all users and devices.
Returns access events and alarms related for a door.
Lists alarms filtered by event category, time interval, and device ID.
Lists alarms filtered by event type, time interval, and device ID.
Retrieves all alarm updates by getting a list of alarm annotations.
Clears a specified alarm.
Acknowledges an alarm.
Returns access control web service version information.
Returns duplicates for a specified alarm.
Event Notification APIs
Registers an event callback endpoint reference. Using this callback, events or alarms are notified to the endpoint referred by the endpoint reference.
Registers an event callback endpoint URL. Using this callback events or alarms are notified to the endpoint pointed to by the service URL.
Unregisters an event callback. This is called when application is no loner interested getting notifications.
Notifies a client application that registered a notification callback when an event or alarm occurs.
Door Commands
Grants access to a specified door using the Grant Door Access command.
Sets the door mode for a specified door and overrides the current door mode.
Resets the door mode to the original Cisco PAM configuration.
Returns the current door mode for a specified door.
Sets the door mode and door configuration for the specified door. Any outstanding configuration changes from Cisco PAM are also applied.
Functions for Access Level and Schedule
Returns detailed information for all access levels defined in Cisco PAM.
Returns names of all the access level defined in Cisco PAM.
Returns detailed information for a specified access level.
Returns information for all schedules defined in Cisco PAM.
Returns names of all the access schedules defined in Cisco PAM.
Returns detailed information for a specified access schedule.
Adds one or more new badge credentials to an existing personnel record, or a new personnel record. If a new personnel record is specified, a picture in JPEG format can be included. Only new badges can be added using this API.
Assigns one or more access levels to a badge associated with a person.
Note
This API replaces all the access levels on the specified badge.
Returns badge details for the badges assigned to a specified person.
Returns a list of Cisco PAM badge validity types.
Returns a list of names of Credential templates defined in CPAM
Returns the Badge type (roles) defined in Cisco PAM.
Returns the Badge Template names defined in Cisco PAM. The names are used as a parameter in the enrollBadge API.
Returns a list of the access levels for all badges assigned to a person. The person is identified by a unique ID.
Retrieves a badge record for a specified card number.
Updates a list of badge credential in the Cisco PAM database. All properties on a badge in Cisco PAM are replaced by the new properties for the specified badge.
Returns information about an access level specified by the access level unid.
Returns the unique identifiers for Cisco PAM badge types.
Returns a range of badge references based on required beginning and ending card number parameters.
Recording External Events
Note
Records an external event or alarm in Cisco PAM.
API Functions
The following sections describe each Cisco Physical Access Control API function in detail. The function descriptions provide the following information:
•
•
•
•
•
•
Note
•
Authentication APIs
authenticateUser
logoutUser
Function name
logoutUser
Description
Ends an authenticated session. The security context object is expired and a new object must be generated to start a new API session.
Method
Post
Parameters
•
Sample request
Return result
All notification listeners registered in the user session are removed. Users must log back in using authenticateUser to retrieve a new security context object before executing additional APIs.
Sample response
Physical Security Integration Management (PSIM) APIs
getAcDeviceTypes
Function name
getAcDeviceTypes
Description
Returns a list of physical access control device types, including the deviceTypeId, name, and a list of the possible device states.
Method
Post
Parameters
•
Sample request
Return result
A list of the physical access control device types, including the type ID, name, and possible device states.
Sample response
getEventTypes
Function name
getEventTypes
Description
This method returns a list of event types defined in Cisco PAM. Each event type indicates event type unique ID, name and category of event.
Method
Post
Parameters
•
Sample request
Return result
A list of event types defined in Cisco PAM. Each event type indicates event type unique ID, name and category of event.
Sample response
getAllEventsCategories
Function name
getAllEventsCategories
Description
Returns a list of the Cisco PAM event categories. Event categories can be used to call all the events that occurred for the event types that belong to that category.
Method
Post
Parameters
•
Sample request
Return result
A list of the event categories in CPAM.
Sample response
getAllCameraDevices
Function name
getAllCameraDevices
Description
Returns a list of the camera devices in Cisco PAM. Cameras can be associated with one or more access control devices, such as a door.
Method
Post
Parameters
•
Sample request
Return result
A list of camera devices with unique ID, name, type and list of associated devices.
Sample response
getAllAcDevices
Function name
getAllAcDevices
Description
Returns a list of all access control devices configured in Cisco PAM.
Method
Post
Parameters
•
•
Sample request
In the following XML sample request, only door devices are requested.
<ns2:getAllAcDevices xmlns:ns2="http://cisco.com/physec/acws/"xmlns:ns3="http://www.w3.org/2005/08/addressing"><secCtx token="1826753" /><dtypes><dtype deviceTypeName="Door" deviceTypeId="GW.DOOR" /></dtypes></ns2:getAllAcDevices>Return result
Collection of access control devices defined in Cisco PAM.
Sample response
getDeviceChildren
Function name
getDeviceChildren
Description
Returns the child devices of the specified device.
Method
Post
Parameters
•
•
Sample request
Return result
The child devices of the device specified by device unique ID (deviceId).
Sample response
getAllDoorGroups
Function name
getAllDoorGroups
Description
Returns the names of all door groups, including the unique ID for each group name.
Method
Post
Parameters
•
Sample request
Return result
The names and unique ID of all door groups configured in Cisco PAM.
Sample response
getAllDoorsByGroup
Function name
getAllDoorsByGroup
Description
Returns all doors configured for the specified door group.
Method
Post
Parameters
•
•
Sample request
Return result
A list of the doors and door details assigned to the specified door group.
Sample response
getAllPerson
Function name
getAllPerson
Description
Returns the first name, last name, person ID and unique ID for access control personnel configured in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
A list of the access control persons, including first name, last name, person ID and unique ID.
Sample response
getAllPersonTypeIds
Function name
getAllPersonTypeIds
Description
Returns all the personnel types defined in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
List of the personnel types.
To view the list in Cisco PAM:
•
•
•
Sample response
getAllPersonStatusIds
Function name
getAllPersonStatusIds
Description
Returns a list of Status definitions for personnel in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
List of the Status definitions.
To view the list in Cisco PAM:
•
•
•
Sample response
getAllPersonByType
Function name
getAllPersonByType
Description
Returns the personnel records for a specified personnel type.
Method
Post
Parameters
•
•
Sample request
Return result
Returns a list of personnel records for the specified personnel type.
Sample response
enrollPerson
Function name
enrollPerson
Description
Adds a personnel record to Cisco PAM.
Method
Post
Parameters
•
•
Sample request
Return result
If the person is enrolled successfully, the unique ID of the person is returned.
Sample response
updatePerson
Function name
updatePerson
Description
Updates a person's record in the Cisco PAM database. All properties in Cisco PAM are replaced by the new properties.
Method
Post
Parameters
•
•
Sample request
Return result
No return result if the action is successful. A fault is returned if the person object is not found in the database.
The following sample is for a successful action.
Sample response
getPersonInfo
Function name
getPersonInfo
Description
Returns information for a personnel record, including a picture if available.
Method
Post
Parameters
•
•
Sample request
Return result
Returns the information configured for the specified person (PersonInfo object). If the object includes the person's picture, a base 64 encoded JPG image is also included.
Sample response
getAllOrganizations
Function name
getAllOrganizations
Description
Returns detailed information for the organizations defined in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
List of organizations in Cisco PAM, including the unique ID, name and a list of department IDs.
Sample response
getAllDepartments
Function name
getAllDepartments
Description
Returns all the departments defined in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
List of the departments in Cisco PAM. A department has a unique ID, name and the ID of the organization that it is a part of.
Sample response
getAllEventsByCategory
Function name
getAllEventsByCategory
Description
Lists the events and alarms defined by the selected parameters, including event category, time interval, and the unique ID for the device.
Method
Post
Parameters
•
•
•
•
•
Sample request
Return result
Returns the events and alarms by event category and other optional parameters.
Sample response
getAllEventsByType
Function name
getAllEventsByType
Description
Lists events and alarms defined by the selected parameters, including event type, time interval, and the device unique ID.
Method
Post
Parameters
•
•
•
•
•
Note
Sample request
The following XML example request specifies a category and time interval:
<ns2:getAllEventsByType xmlns:ns3="http://www.w3.org/2005/08/addressing"xmlns:ns2="http://cisco.com/physec/acws/"><secCtx token="11563709" /><evtTypeUnid>GW.EV_DOOR_FORCED_OPEN</evtTypeUnid><begTime>1244498636499</begTime><endTime>1247090636499</endTime></ns2:getAllEventsByType>Return result
Returns the events and alarms by event type and other optional parameters.
Note
Sample response
getUserAccessEvents
Function name
getUserAccessEvents
Description
Returns door access events related to granting or denying user access. Events can be returned for a specific user or device, or for all users and devices.
Note
Method
Post
Parameters
•
•
•
•
•
•
•
Note
Sample request
In the following example, a time interval is specified, a maximum 1,000 events are included, and events are returned by most recent first:
<ns2:getUserAccessEvents xmlns:ns3="http://www.w3.org/2005/08/addressing"xmlns:ns2="http://cisco.com/physec/acws/"><secCtx token="11563709" /><begTime>1244498636515</begTime><endTime>1247090636515</endTime><maxCount>1000</maxCount><recent>true</recent></ns2:getUserAccessEvents>Return result
Returns information for events in the GW.EV_MAJOR_ID_DOOR category, including the following:
"EV_DOOR_GRANT_ACCESS""EV_DOOR_GRANT_ACCESS_EXTENDED""EV_DOOR_DENY_ACCESS_NO_ACC""EV_DOOR_DENY_ACCESS_DOORSCHED""EV_DOOR_DENY_ACCESS_WRONG_PIN""EV_DOOR_DENY_ACCESS_TIMED_APB""EV_DOOR_DENY_ACCESS_APB""EV_DOOR_DENY_ACCESS_BLACKLIST"Events are filtered by person, device, time interval and other optional parameters.
Note
Sample response
getAccessEventsByDoor
Function name
getAccessEventsByDoor
Description
Returns access events and alarms related for a door.
Method
Post
Parameters
•
•
•
•
•
•
Sample request
In the following example, a time interval is specified, a maximum 1,000 events are included, and events are returned by most recent first:
<ns2:getAccessEventsByDoor xmlns:ns2="http://cisco.com/physec/acws/"xmlns:ns3="http://www.w3.org/2005/08/addressing"><secCtx token="12272293" /><beginTime>1234746808724</beginTime><endTime>1237338808724</endTime><doorId>foGrYqOjT7yuxPDOw6/9Yg==</doorId><maxCount>5</maxCount><recent>true</recent></ns2:getAccessEventsByDoor>Return result
Returns events for the specified door filtered by device, time interval and other optional parameters.
Sample response
getAllAlarmsByCategory
Function name
getAllAlarmsByCategory
Description
Lists alarms filtered by event category, time interval, and device ID.
Method
Post
Parameters
•
•
•
•
•
Sample request
The following XML example request specifies a category and time interval:
<ns2:getAllAlarmsByCategory xmlns:ns3="http://www.w3.org/2005/08/addressing"xmlns:ns2="http://cisco.com/physec/acws/"><secCtx token="7980237" /><category>GW.EV_MAJOR_ID_DOOR</category><beginTime>1244680318628</beginTime><endTime>1247272318628</endTime></ns2:getAllAlarmsByCategory>Return result
Lists alarms filtered by event category, time interval, and device ID.
Sample response
getAllAlarmsByType
Function name
getAllAlarmsByType
Description
Lists alarms filtered by event type, time interval, and device ID.
Method
Post
Parameters
•
•
•
•
•
Sample request
The following XML example request specifies a category and time interval:
<ns2:getAllAlarmsByType xmlns:ns3="http://www.w3.org/2005/08/addressing"xmlns:ns2="http://cisco.com/physec/acws/"><secCtx token="2697030" /><type>GW.EV_DOOR_FORCED_OPEN</type><beginTime>1244499763553</beginTime><endTime>1247091763553</endTime></ns2:getAllAlarmsByType>Return result
Returns the events and alarms by event type and other optional parameters.
Sample response
getAllAlarmUpdates
Function name
getAllAlarmUpdates
Description
Retrieves all alarm updates by getting a list of alarm annotations.
Method
Post
Parameters
•
•
•
Sample request
Return result
Returns a list of alarm annotation. Alarm annotation includes the following:
•
•
•
•
•
Sample response
clearAlarm
Function name
clearAlarm
Description
Clears a specified alarm.
Method
Post
Parameters
•
•
•
Sample request
Return result
"True" if the request is successful.
Sample response
ackAlarm
Function name
ackAlarm
Description
Acknowledges an alarm.
Method
Post
Parameters
•
•
•
Sample request
Return result
"True" if the request is successful.
Sample response
getVersionInfo
getAlarmDuplicates
Function name
getAlarmDuplicates
Description
Returns duplicates for a specified alarm.
Method
Post
Parameters
•
•
Sample request
Return result
Returns a list of the duplicate alarms.
Sample response
Event Notification
A client application can receive event and alarm notifications from Cisco PAM by registering a callback interface with the Cisco PAM web service.
Step 1
Step 2
•
•
Tip
Step 3
For more information, see the following:
•
registerAcEventCallback
Function name
registerAcEventCallback
Description
Registers an event callback endpoint for clients using a SOAP/HTTP binding. When the specified events or alarms occur, a notification is sent to the registered endpoint.
Note
Method
Post
Parameters
•
•
•
•
Sample request
Return result
registrationKey: the key that identifies the callback registration. This value is returned when callback is registered successfully.
This key is also used to unregister the event callback. See unregisterAcEventCallback.
Sample response
registerAcEventXMLCallback
Function name
registerAcEventXMLCallback
Description
Registers an event callback endpoint URL for clients using an XML/HTTP binding. When the specified events or alarms occur, a notification is sent to the registered URL.
Note
Method
Post
Parameters
•
•
•
•
Sample request
Return result
registrationKey: the key that identifies the callback registration. This value is returned when callback is registered successfully. See unregisterAcEventCallback.
Sample response
unregisterAcEventCallback
Function name
unregisterAcEventCallback
Description
Unregisters an event callback. This is called when application is no loner interested getting notifications using the callback registered earlier.
Method
Post
Parameters
•
•
Sample request
Return result
None.
Sample response
notifyAcEvent
Function name
notifyAcEvent
Description
Notifies a client application when an event or alarm occurs. The client must have previously registered a notification callback using either registerAcEventCallback or registerAcEventXMLCallback.
Method
Post
Parameters
AcEvent: event or alarm
Sample request
Return result
True if the event was handled. False if it was not.
Sample response
Example to Implement and Register a Service Interface
To receive event and alarm notifications, the client application must implement a service interface (AcEventPortType) defined in acws.wsdl as:
public class AcEventPortTypeImpl implements AcEventPortType {For example:
public boolean notifyAcEvent(AcEvent event) {System.out.println("notifyAcEvent is called");// handle event/alarm as the case may beSystem.out.println(" Event = " + eventToString(event));return true;}}To create a service end point (for AcEventPortTypeImpl) and register it with PSIMWsPortType (ACWS web service), create an element referenceParameters: (<wsa:ReferenceParameters>)
In the following XML fragment, the service endpoint is created and registered using the API registerAcEventCallback.
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing"><wsa:Address>http://localhost:8090/callback/notifyacevent</wsa:Address><wsa:ReferenceProperties></wsa:ReferenceProperties><wsa:ReferenceParameters><testParameter1>testValue1</testParameter1><testParameter2>testValue2</testParameter2></wsa:ReferenceParameters><wsa:Metadataxmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance"xmlns:wsaw="http://www.w3.org/2005/02/addressing/wsdl"xmlns:ns="http://cisco.com/physec/acws/"><wsaw:ServiceNameEndpointName="CallbackPort">ns:AcEventService</wsaw:ServiceName></wsa:Metadata></wsa:EndpointReference>// code fragments for getting an endpoint reference// and registering a callback.m_cbEndpointReference = (W3CEndpointReference)m_evtEndpoint.getEndpointReference(referenceParameters);m_portType.registerAcEventCallback(m_ctx,null,m_cbEndpointReference,false);Door Command APIs
grantDoorAccess
Function name
grantDoorAccess
Description
Grants access to a specified door using the Grant Door Access command.
Method
Post
Parameters
•
•
Sample request
Return result
True if the command is successful. False if it is not.
Sample response
setDoorMode
Function name
setDoorMode
Description
Sets the door mode for a specified door and overrides the current door mode.
Method
Post
Parameters
•
•
•
Sample request
Return result
None
Sample response
resetDoorMode
Function name
resetDoorMode
Description
Resets the door mode to the original Cisco PAM configuration.
Method
Post
Parameters
•
•
Note
Sample request
Return result
None.
Sample response
getDoorMode
Function name
getDoorMode
Description
Returns the current door mode for a specified door.
Method
Post
Parameters
•
•
Sample request
Return result
The door mode for the specified door.
Sample response
setDoorModeConfig
Function name
setDoorModeConfig
Description
Sets the door mode configuration for a specified door. Any outstanding configuration changes from Cisco PAM are also applied.
Method
Post
Parameters
•
•
•
–
–
–
•
•
–
–
–
Sample request
Return result
None.
Sample response
Badge Enrollment APIs
getAllAccessLevels
Function name
getAllAccessLevels
Description
Returns detailed information for all access levels defined in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
List of access level definitions, including type and schedule.
Sample response
getAllAccessLevelNames
Function name
getAllAccessLevelNames
Description
Returns names of all the access level defined in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
List of all access level names defined in Cisco PAM.
Sample response
getAccessLevelByName
Function name
getAccessLevelByName
Description
Returns detailed information for a specified access level.
Method
Post
Parameters
•
•
Sample request
Return result
The specified access level definition.
Sample response
getAllSchedules
Function name
getAllSchedules
Description
Returns information for all schedules defined in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
Definitions for all access schedules configured in Cisco PAM.
Sample response
getAllScheduleNames
Function name
getAllScheduleNames
Description
Returns names of all the access schedules defined in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
List of all access schedules defined in Cisco PAM.
Sample response
getScheduleByName
Function name
getScheduleByName
Description
Returns detailed information for a specified access schedule.
Method
Post
Parameters
•
Sample request
Return result
Definition for a specified access schedule.
Sample response
enrollBadge
Function name
enrollBadge
Description
Adds one or more new badge credentials to an existing personnel record, or a new personnel record. If a new personnel record is specified, a picture in JPEG format can be included. Only new badges can be added using this API.
Usage Notes
A badge credential defines the properties for a user badge including one or more badge extensions. For example:
•
•
Note
Method
Post
Parameters
•
•
•
•
Sample request
In the following sample:
•
•
•
Sample request:
<ns2:enrollBadge xmlns:ns2="http://cisco.com/physec/acws/"><secCtx token="22627865" /><person statusId="ACTIVE" type="Standard" lname="Last_5000"fname="First_5000" personId="247595849"><picture><picture>/9j/4....................................................Note : Truncated base64 encoded JPEG Image...............................................................................................................................................................2Q==</picture><type>JPEG</type></picture></person><templateName>TestTemplate</templateName><badge><badges cardNumber="1322936685508915001"><expDate>1252628974196</expDate><validityType>VX.ACTIVE</validityType><extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="ns2:HsBadge" ici="2" crlLatestDate="1252628974196"crlInitialDate="1247444974196" credentialSeries="1"credentialNumber="123456789" hsCardType="PIV" agencyCode="123"><fascnHex>0123456789ABCDEF0123456789ABCDEF0123456789ABCDFFF0</fascnHex><cuidHex>0123456789ABCDEF0123</cuidHex><sha1HashHex>0123456789ABCDEF01230123456789ABCDEF0123</sha1HashHex></extensions><extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="ns2:gwBadge"><credTemplateName>26BitWiegandCT</credTemplateName><role>EMPLOYEE</role><adaEnabled>true</adaEnabled></extensions></badges><badges cardNumber="1322936685508915002"><expDate>1252628974196</expDate><validityType>VX.ACTIVE</validityType></badges></badge></ns2:enrollBadge>Return result
If badge is successfully enrolled, the personId is returned.
Sample response
assignAccessLevel
Function name
assignAccessLevel
Description
Assigns one or more access levels to a specified badge associated with a person.
Note
Method
Post
Parameters
•
•
•
•
Sample request
Return result
None or void.
Sample response
getAllBadgesByPerson
Function name
getAllBadgesByPerson
Description
Returns badge details for the badges assigned to a specified person.
Method
Post
Parameters
•
•
Sample request
Return result
Detailed information for the badges assigned to the personnel unique ID.
Sample response
getBadgeValidityTypes
Function name
getBadgeValidityTypes
Description
Returns a list of Cisco PAM badge Validity types.
Method
Post
Parameters
•
Sample request
Return result
Returns a list of Cisco PAM badge Validity types. For example: Blacklist and Revoked.
TipSample response
getCredentialTemplateNames
Function name
getCredentialTemplateNames
Description
Returns a list of names of Credential templates defined in CPAM
Method
Post
Parameters
•
Sample request
Return result
List of Credential Template names. For example: 26BitWiegandCT and 26BitWiegandKeypadCT.
TipSample response
getBadgeRoles
Function name
getBadgeRoles
Description
Returns the Badge type (roles) defined in Cisco PAM.
Method
Post
Parameters
•
Sample request
Return result
List of Badge type (roles) in Cisco PAM. For example: Employee, Contractor, Vendor, and Temporary.
TipSample response
getAllBadgeTemplateNames
Function name
getAllBadgeTemplateNames
Description
Returns the Badge Template names defined in Cisco PAM. The names are used as a parameter in the enrollBadge API.
Method
Post
Parameters
•
Sample request
Return result
List of the Badge Template names used as a parameter in the enrollBadge API. To view the template names in Cisco PAM, select the Badge Templates from the Users menu.
Sample response
getAccessLevelByPerson
Function name
getAccessLevelByPerson
Description
Returns a list of the access levels for all badges assigned to a person. The person is identified by a unique ID.
Method
Post
Parameters
•
•
Sample request
Return result
A list of the access levels for all badges held by the specified access control user.
Sample response
getBadgeByCardNum
Function name
getBadgeByCardNum
Description
Retrieves a badge record for a specified card number.
Method
Post
Parameters
•
•
Sample request
Return result
Badge details for the specified card number.
Sample response
updateBadge
Function name
updateBadge
Description
Updates a list of badge credential in the Cisco PAM database. All properties on a badge in Cisco PAM are replaced by the new properties for the specified badge.
Method
Post
Parameters
•
•
•
•
–
–
Sample request
Return result
A fault is returned if no badge is found in the database.
Sample response
getAccessLevelByUnid
Function name
getAccessLevelByUnid
Description
Returns information about an access level specified by the access level unid.
Method
Post
Parameters
•
•
Sample request
Return result
Access level configuration based on the unid. If an invalid unid is specified, null is returned (the response is returned with no records).
Sample response
getAllBadgeTypeIds
Function name
getAllBadgeTypeIds
Description
Returns the unique identifiers for Cisco PAM badge types.
Method
Post
Parameters
•
Sample request
Return result
Cisco PAM badge types such as the following:
•
•
•
Sample response
getAllBadgeRefs
Function name
getAllBadgeRefs
Description
Returns a range of badge references based on required beginning and ending card number parameters.
Note
Method
Post
Parameters
Note
•
•
•
Tip•
•
•
Sample request
Return result
List of badges references, including the badge unique ID and card number for the reference.
Sample response
Recording External Events
External applications can record events in Cisco PAM using the recordExtEvent API. Once recorded, the events are displayed in the Events & Alarms Monitoring modules.
External Event Types are defined using the Event Definition Format and imported using the steps described in the following sections.
To record events from external applications, do the following:
1.
2.
3.
4.
See also the Examples: Using Java and C# Code.Define External Event Types Using the Event Definition Format
Use the Event Definition Format to create an XML file that defines the event and alarm codes used to add external events to Cisco PAM. This file also defines the category for the events and is imported into Cisco PAM to create the codes.
Example
In the following XML example:
•
•
•
<appext_eventdefnsxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><appext_entry appname="Cisco_VSM" logcode_prefix="VS"><ext_event_defn logcode="VSM_Sample1"priority="10"description="VSM Sample Event-1"/><ext_event_defn logcode="VSM_Sample2"priority="10"description="VSM Sample Event-2"isAlarm="true"/></appext_entry></appext_eventdefns>The file is saved with the .xml extension. For example: SampleExtEventDefns.xml.
Create a Text File to Define the Event Names in Cisco PAM
To define the log code names displayed in Cisco PAM, create a text file that defines a string name for each event and the event category.
In the following example, the string name for the two events and the event category are defined:
VS_VSM_Sample1=Sample Event-1
VS_VSM_Sample2=Sample Event-2
Cisco_VSM=Cisco Video Surveillance Manager
The file is saved with the .properties extension. For example: AppExtMessages.properties.
Import the Files into Cisco PAM
Once the XML and properties files are created, import the files into the Cisco PAM External Events module.
Step 1
Log in to the Cisco PAM desktop application.
Step 2
Select External Events from the Events & Alarms menu.
Step 3
Click Import.
Step 4
a.
•
•
b.
For instructions to create these files, see:
•
Step 5
(Optional) Preview the settings.
Click Finish to save the changes
Click Back to select a different file.
Step 6
The new log codes are displayed in the main External Events window.
recordExtEvent
Function name
recordExtEvent
Description
Records an external event or alarm in Cisco PAM.
Method
Post
Parameters
•
•
•
–
–
–
•
Sample request
Return result
Once an event is recorded, it is displayed in the Cisco PAM Event Monitoring module.
Sample response
Examples: Using Java and C# Code
See Auto-Generating Java or C# Code from the WSDL File, page 1-5 for more information.
Sample Java Application Code to Record External Events
// The PSIMWsService Web Serviceprivate final static QName SERVICE = new QName("http://cisco.com/physec/acws/", "PSIMWsService");// WSDL location URLprivate final static URL WSDL_LOCATION = new URL("http://cpam-server/acws/services/psimws?wsld");PSIMWsService _webService = null;PSIMWsPortType m_ PSIMWsInterface = null;SecurityContext _ctx = null;...try{//Reference to the PSIMWsService web service_webService = new PSIMWsService(WSDL_LOCATION, SERVICE);//Get handle to PSIMWsPortType interface_ PSIMWsInterface = _webService.getPSIMWsSoapPort();}catch (WebServiceException e){//Handle exception}catch (Exception e){//Handle exception}....// Authenticate userUserCredentialType uct = new UserCredentialType();uct.setUsername("username");uct.setPassword("password");_ctx = _ PSIMWsInterface.authenticateUser(uct);...//Call methods using interface handlesAcEvent ev = new AcEvent();ev.setEvtTime(1234);ev.setType("AE.APP_EVENT_1");ev.setSrcDeviceName("deviceName");_ PSIMWsInterface.recordExtEvent(_ctx, "appName", ev, "Policy");...//In the end logout user and close the session_PSIMWsInterface.logoutUser(_ctx);Sample C# Application Code to Record External Events
// The PSIMWsService Web Serviceprivate String _PSIMServiceUrl = "http://cpam-server/acws/service/psimws";private String _AccessPolicyServiceUrl = "http://cpam-server/acws/service/acpolicy";private PSIMWsBinding _psimBinding;private AccessPolicyBinding _apBinding;private SecurityContext _ctx;...// PSIMWsPortType interface with SOAP/HTTP_ psimBinding = new PSIMWsBinding();_ psimBinding.Url = _PSIMServiceUrl;// AccessPolicyPortType interface with SOAP/HTTP_apBinding = new AccessPolicyBinding();_apBinding.URL = _AccessPolicyServiceUrl;....// Authenticate userUserCredentialType uct = new UserCredentialType();uct.username = "username";uct.password = "password";_ctx = _ psimBinding.authenticateUser(uct);...//Call methods using interface handlesrecordExtEvent ree = new recordExtEvent();ree.secCtx = _ctx; // From authenticateUser callree.appName = "appName";ree.srcDeviceType = "Policy";AcEvent ev = new AcEvent();ev.srcDeviceName = "deviceName"; ;ev.evtTime = 1234;ev.type = "AE.APP_EVENT_1";ree.@event = ev;recordExtEventResponse resp = m_psimBinding.recordExtEvent(ree);...//In the end logout user and close the sessionlogoutUser lu = new logoutUser();lu.setCtx = _ctx;_ psimBinding.logoutUser(lu);
