Cisco Physical Access Control API Reference Guide, Release 1.2.0 and higher
API Functions
Downloads: This chapterpdf (PDF - 843.0KB) The complete bookPDF (PDF - 2.47MB) | Feedback

API Functions

Table Of Contents

API Functions

Function Summary

API Functions

Authentication APIs

authenticateUser

logoutUser

Physical Security Integration Management (PSIM) APIs

getAcDeviceTypes

getEventTypes

getAllEventsCategories

getAllCameraDevices

getAllAcDevices

getDeviceChildren

getAllDoorGroups

getAllDoorsByGroup

getAllPerson

getAllPersonTypeIds

getAllPersonStatusIds

getAllPersonByType

enrollPerson

updatePerson

getPersonInfo

getAllOrganizations

getAllDepartments

getAllEventsByCategory

getAllEventsByType

getUserAccessEvents

getAccessEventsByDoor

getAllAlarmsByCategory

getAllAlarmsByType

getAllAlarmUpdates

clearAlarm

ackAlarm

getVersionInfo

getAlarmDuplicates

Event Notification

registerAcEventCallback

registerAcEventXMLCallback

unregisterAcEventCallback

notifyAcEvent

Example to Implement and Register a Service Interface

Door Command APIs

grantDoorAccess

setDoorMode

resetDoorMode

getDoorMode

setDoorModeConfig

Badge Enrollment APIs

getAllAccessLevels

getAllAccessLevelNames

getAccessLevelByName

getAllSchedules

getAllScheduleNames

getScheduleByName

enrollBadge

assignAccessLevel

getAllBadgesByPerson

getBadgeValidityTypes

getCredentialTemplateNames

getBadgeRoles

getAllBadgeTemplateNames

getAccessLevelByPerson

getBadgeByCardNum

updateBadge

getAccessLevelByUnid

getAllBadgeTypeIds

getAllBadgeRefs

Recording External Events

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

recordExtEvent

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

API Functions

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 

Function Name and Reference
Description

Functions for Authentication

authenticateUser

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.

logoutUser

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)

getAcDeviceTypes

Returns a list of physical access control device types, including the deviceTypeId, name, and a list of the possible device states.

getEventTypes

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.

getAllEventsCategories

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.

getAllCameraDevices

Returns a list of the camera devices in Cisco PAM. Cameras are associated with one or more access control devices, such as a door.

getAllAcDevices

Returns a list of all access control devices configured in Cisco PAM.

getDeviceChildren

Returns the child devices of the specified device.

getAllDoorGroups

Returns the names of all door groups, including the unique ID for each group name.

getAllDoorsByGroup

Returns all doors configured for the specified door group.

getAllPerson

Returns the first name, last name, person ID and unique ID for access control personnel configured in Cisco PAM.

getAllPersonTypeIds

Returns all the personnel types defined in Cisco PAM.

getAllPersonStatusIds

Returns a list of Status definitions for personnel in Cisco PAM.

getAllPersonByType

Returns the personnel records for a specified personnel type.

enrollPerson

Adds a personnel record to Cisco PAM.

updatePerson

Updates a person's record in the Cisco PAM database. All properties in Cisco PAM are replaced by the new properties.

getPersonInfo

Returns information for a personnel record, including a picture if available.

getAllOrganizations

Returns detailed information for the organizations defined in Cisco PAM.

getAllDepartments

Returns all the departments defined in Cisco PAM.

getAllEventsByCategory

Lists the events and alarms defined by the selected parameters, including event category, time interval, and the unique ID for the device.

getAllEventsByType

Lists events and alarms defined by the selected parameters, including event type, time interval, and the device unique ID.

getUserAccessEvents

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.

getAccessEventsByDoor

Returns access events and alarms related for a door.

getAllAlarmsByCategory

Lists alarms filtered by event category, time interval, and device ID.

getAllAlarmsByType

Lists alarms filtered by event type, time interval, and device ID.

getAllAlarmUpdates

Retrieves all alarm updates by getting a list of alarm annotations.

clearAlarm

Clears a specified alarm.

ackAlarm

Acknowledges an alarm.

getVersionInfo

Returns access control web service version information.

getAlarmDuplicates

Returns duplicates for a specified alarm.

Event Notification APIs

registerAcEventCallback

Registers an event callback endpoint reference. Using this callback, events or alarms are notified to the endpoint referred by the endpoint reference.

registerAcEventXMLCallback

Registers an event callback endpoint URL. Using this callback events or alarms are notified to the endpoint pointed to by the service URL.

unregisterAcEventCallback

Unregisters an event callback. This is called when application is no loner interested getting notifications.

notifyAcEvent

Notifies a client application that registered a notification callback when an event or alarm occurs.

Door Commands

grantDoorAccess

Grants access to a specified door using the Grant Door Access command.

setDoorMode

Sets the door mode for a specified door and overrides the current door mode.

resetDoorMode

Resets the door mode to the original Cisco PAM configuration.

getDoorMode

Returns the current door mode for a specified door.

setDoorModeConfig

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

getAllAccessLevels

Returns detailed information for all access levels defined in Cisco PAM.

getAllAccessLevelNames

Returns names of all the access level defined in Cisco PAM.

getAccessLevelByName

Returns detailed information for a specified access level.

getAllSchedules

Returns information for all schedules defined in Cisco PAM.

getAllScheduleNames

Returns names of all the access schedules defined in Cisco PAM.

getScheduleByName

Returns detailed information for a specified access schedule.

enrollBadge

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.

assignAccessLevel

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.

getAllBadgesByPerson

Returns badge details for the badges assigned to a specified person.

getBadgeValidityTypes

Returns a list of Cisco PAM badge validity types.

getCredentialTemplateNames

Returns a list of names of Credential templates defined in CPAM

getBadgeRoles

Returns the Badge type (roles) defined in Cisco PAM.

getAllBadgeTemplateNames

Returns the Badge Template names defined in Cisco PAM. The names are used as a parameter in the enrollBadge API.

getAccessLevelByPerson

Returns a list of the access levels for all badges assigned to a person. The person is identified by a unique ID.

getBadgeByCardNum

Retrieves a badge record for a specified card number.

updateBadge

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.

getAccessLevelByUnid

Returns information about an access level specified by the access level unid.

getAllBadgeTypeIds

Returns the unique identifiers for Cisco PAM badge types.

getAllBadgeRefs

Returns a range of badge references based on required beginning and ending card number parameters.

Recording External Events

Note This section also includes instructions to define the events used the Cisco PAM External Events module. See Recording External Events.

recordExtEvent

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:

Function name—Name of the function.

Description—General behavior for the function.

Parameters—Parameters that the function requires.

Sample Request—Example of the API request.

Return result—Describes the result for the function.

Sample response—Example of a response that the function can receive.


NoteThe Method for all Cisco PAM APIs is POST.

Sample request and response payloads are provided for each API. APIs can use either SOAP/HTTP or XML/HTTP. The sample requests and responses are for illustration purposes only.


Authentication APIs

authenticateUser

Function name

authenticateUser

Description

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.

Method

Post

Parameters

username: (required) unique Cisco PAM log in ID.

password: (required) Cisco PAM user password.

Sample request

<ns2:authenticateUser xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<username>cpamadmin</username>
	<password>cpamadmin</password>
</ns2:authenticateUser>

Return result

A security token is returned if authentication is successful. The token references a security context object maintained on the Cisco PAM API service. This object also maintains user session information. The token number must be provided using the secCtx parameter in each subsequent API call.

Sample response

<ns2:authenticateUserResponse
	xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing" token="23886766"

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

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:logoutUser xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<in token="6193613" />
</ns2:logoutUser>

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

<ns2:logoutUserResponse xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/" />

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

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAcDeviceTypes xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="6193613" />
</ns2:getAcDeviceTypes>

Return result

A list of the physical access control device types, including the type ID, name, and possible device states.

Sample response

		<ns2:getAcDeviceTypesResponse xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<deviceTypes>
				<dtype deviceTypeName="Camera" deviceTypeId="CB.CAMERA">
					<deviceStates>
						<state state="VX.DISABLED" />
						<state state="VX.OFFLINE" />
						<state state="VX.UNK" />
						<state state="VX.ONLINE" />
					</deviceStates>
				</dtype>
......................
......................

				<dtype deviceTypeName="Door" deviceTypeId="GW.DOOR">
					<deviceStates>
						<state state="GW.FORCED_OPEN" />
						<state state="VX.DISABLED" />
						<state state="GW.DOOR_CLOSE" />
						<state state="GW.INOPERATIONAL" />
						<state state="GW.DOOR_OPEN" />
						<state state="GW.UP" />
						<state state="VX.UNK" />
						<state state="GW.HELD_OPEN" />
						<state state="GW.DOWN" />
					</deviceStates>
				</dtype>
			</deviceTypes>
		</ns2:getAcDeviceTypesResponse>

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

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getEventTypes xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="6193613" />
</ns2:getEventTypes>

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

<ns2:getEventTypesResponse xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<eventTypes>
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="The Door is not an APB enabled door"
			unid="GW.EV_ALLOWED_NOT_APBDOOR" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="Access allowed on APB exempt"
			unid="GW.EV_ALLOWED_ON_APBEXEMPT" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="The reader type is not valid for APB area"
			unid="GW.EV_APB_NOTVALID_READER" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="APB policy retrieval failed."
			unid="GW.EV_APB_RETRIEVAL_FAILED" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="APB State reset by User. " unid="GW.EV_APB_STATE_RESET" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="Badge is authorized" unid="GW.EV_BADGE_AUTHORIZED" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="The badge is blacklisted" unid="GW.EV_BADGE_BLACK_LISTED" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="The badge is disabled" unid="GW.EV_BADGE_IS_DISABLED" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="The badge is not active" unid="GW.EV_BADGE_NOT_ACTIVE" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="Badge is not authorized" unid="GW.EV_BADGE_NOT_AUTHORIZED" />
		<evtType category="GW.EV_MAJOR_ID_POLICY" description="Event"
			name="The badge has not active date" unid="GW.EV_BADGE_NO_ACTV_DTE"
/>
......................
......................

	</eventTypes>
</ns2:getEventTypesResponse>

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

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAllEventCategories xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="7163697" />
</ns2:getAllEventCategories>

Return result

A list of the event categories in CPAM.

Sample response

<ns2:getAllEventCategoriesResponse
xmlns:ns3="http://www.w3.org/2005/08/addressing" 
xmlns:ns2="http://cisco.com/physec/acws/">
	<eventCategory>GW.EV_MAJOR_ID_CAM</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_CFG</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_CMD</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_CPAM</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_CRAFT_IF</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_CRED</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_DEVICE</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_DOOR</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_EDI</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_INTF</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_MODULE</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_POLICY</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_SYS</eventCategory>
	<eventCategory>GW.EV_MAJOR_ID_URL</eventCategory>
</ns2:getAllEventCategoriesResponse>

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

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAllCameraDevices xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="1826753" />
</ns2:getAllCameraDevices>

Return result

A list of camera devices with unique ID, name, type and list of associated devices.

Sample response

<ns2:getAllCameraDevicesResponse
	xmlns:ns2="http://cisco.com/physec/acws/" 
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<cameras>
		<devices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xmlns:ns5="http://cisco.com/physec/video/" xsi:type="ns5:CameraDevice"
			type="CB.CAMERA" name="S1 Cam Lab 1" unid="2ZuPNca/QMeVjVl9XEjlPA==" />
		<devices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xmlns:ns5="http://cisco.com/physec/video/" xsi:type="ns5:CameraDevice"
			type="CB.CAMERA" name="Panasonic1_new" unid="9cKGFhFPTdKxewHjI01wmg==">
			<devices>
				<devices xsi:type="ns2:AcDoorDevice" enabled="true"
					siteId="DsL5KGP8Tpm+c2z/oN4C5g==" deviceState="GW.UP"
					location="Cisco Iodc/Building 9/First floor" 
									address="/SanJose/pgw_123/Door/door00"
					type="GW.DOOR" name="door00" unid="Tu9M06ZcSi+HlC4f4pGuPw==">
					<cameras>
						<devices xsi:type="ns5:CameraDevice" type="CB.CAMERA"
							name="Panasonic1_new" unid="9cKGFhFPTdKxewHjI01wmg==" />
						<devices xsi:type="ns5:CameraDevice" type="CB.CAMERA"
							name="Panasonic_1" unid="e/ZRlB/lSVKKfp43lqFgGg==" />
					</cameras>
					<adminStatus>ADMINUP</adminStatus>
					<associatedDevice enabled="true"
						siteId="DsL5KGP8Tpm+c2z/oN4C5g==" deviceState="GW.UP"
						address="/SanJose/pgw_123/m00/input01/rex" type="GW.REX" name="rex"
						unid="/cUCkOHIRwKGlXiIBK4A5Q==">
						<adminStatus>ADMINUP</adminStatus>
					</associatedDevice>
					<associatedDevice enabled="true"
						siteId="DsL5KGP8Tpm+c2z/oN4C5g==" deviceState="GW.UP"
						address="/SanJose/pgw_123/m00/rdr01/reader" type="GW.RDR" 
										name="reader"
						unid="wPfDHYC7SXu1Zgr7SlGY2g==">
						<adminStatus>ADMINUP</adminStatus>
					</associatedDevice>
					<associatedDevice enabled="true"
						siteId="DsL5KGP8Tpm+c2z/oN4C5g==" deviceState="GW.UP"
						address="/SanJose/pgw_123/m00/input02/doorSensor" 
										type="GW.DOORSENSOR"
						name="doorSensor" unid="Dmpm7RP0QfmCbj9+2Kfm5w==">
						<adminStatus>ADMINUP</adminStatus>
					</associatedDevice>
					<associatedDevice enabled="true"
						siteId="DsL5KGP8Tpm+c2z/oN4C5g==" deviceState="GW.UP"
						address="/SanJose/pgw_123/m00/output02/lock" type="GW.LOCK"
						name="lock" unid="UUI40rvoR+aG749S18s5SQ==">
						<adminStatus>ADMINUP</adminStatus>
					</associatedDevice>
				</devices>
			</devices>
		</devices>
	</cameras>	
</ns2:getAllCameraDevicesResponse>

getAllAcDevices

Function name

getAllAcDevices

Description

Returns a list of all access control devices configured in Cisco PAM.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

dtypes: (optional) a collection of device types. Only the access control devices of the specified device types will be returned in the result. If not specified, all access control devices types are returned.

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

<ns2:getAllAcDevicesResponse xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<devices>
		<devices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xsi:type="ns2:AcDoorDevice" enabled="true"
			siteId="v5OyH3XSQdqNRECjcKcAsQ=="
			deviceState="VX.UNK" address="/SanJose/pgw_1001/Door/door00"
			type="GW.DOOR"
			name="FrontDoor" unid="XMT6EusqSaaBeM7H8eFQxw==">
			<cameras>
				<devices xmlns:ns5="http://cisco.com/physec/video/"
					xsi:type="ns5:CameraDevice" type="CB.CAMERA"
					name="2500-SD-Dual"
					unid="CquVLWW6RZOLYos6xfMUrA==" />
				<devices xmlns:ns5="http://cisco.com/physec/video/"
					xsi:type="ns5:CameraDevice" type="CB.CAMERA" name="702 Xp3 0"
					unid="8evRj5pOTaSzX7Dt0N9vlQ==" />
			</cameras>
			<adminStatus>PROVISIONED</adminStatus>
			<associatedDevice enabled="true"
				siteId="v5OyH3XSQdqNRECjcKcAsQ==" deviceState="VX.UNK"
				address="/SanJose/pgw_1001/m00/input01/rex" type="GW.REX"
				name="rex"
				unid="cEWC1cqmRsWTv3KdfSPc2g==">
				<adminStatus>PROVISIONED</adminStatus>
			</associatedDevice>
			<associatedDevice enabled="true"
				siteId="v5OyH3XSQdqNRECjcKcAsQ==" deviceState="VX.UNK"
				address="/SanJose/pgw_1001/m00/input02/doorSensor"
				type="GW.DOORSENSOR"
				name="doorSensor" unid="ZlIj4u1CTDKY83ToAbrgcw==">
				<adminStatus>PROVISIONED</adminStatus>
			</associatedDevice>
			<associatedDevice enabled="true"
				siteId="v5OyH3XSQdqNRECjcKcAsQ==" deviceState="VX.UNK"
				address="/SanJose/pgw_1001/m00/rdr01/reader" type="GW.RDR"
				name="reader"
				unid="pxLjvv8URRWDtDZ+vJ9xZw==">
				<adminStatus>PROVISIONED</adminStatus>
			</associatedDevice>
			<associatedDevice enabled="true"
				siteId="v5OyH3XSQdqNRECjcKcAsQ==" deviceState="VX.UNK"
				address="/SanJose/pgw_1001/m00/output01/lock" type="GW.LOCK"
				name="lock"
				unid="5+knHfL2Q/6P+77VF8ciEA==">
				<adminStatus>PROVISIONED</adminStatus>
			</associatedDevice>
		</devices>
	</devices>	</ns2:getAllAcDevicesResponse>

getDeviceChildren

Function name

getDeviceChildren

Description

Returns the child devices of the specified device.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

deviceId: (required) the unique ID of the device.

Sample request

<ns2:getDeviceC lns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token=>
		<deviceId>eR1h+Nk/QWGnjQMogmeacQ==</deviceId>
</ns2:getDeviceChildren>

Return result

The child devices of the device specified by device unique ID (deviceId).

Sample response

<ns2:getDeviceChildrenResponse
	xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<children>
		<devices enabled="true" siteId="v5OyH3XSQdqNRECjcKcAsQ=="
			deviceState="VX.UNK" address="/SanJose/pgw_1001/m00" type="GW.MOD"
			name="m00" unid="lVCGMw4GSu2iepz0qL0wSw==">
			<cameras>
				<devices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
					xmlns:ns5="http://cisco.com/physec/video/"
					xsi:type="ns5:CameraDevice"
					type="CB.CAMERA" name="702 Xp3 0"
					unid="8evRj5pOTaSzX7Dt0N9vlQ==" />
			</cameras>
		</devices>
	</children>
</ns2:getDeviceChildrenResponse>

getAllDoorGroups

Function name

getAllDoorGroups

Description

Returns the names of all door groups, including the unique ID for each group name.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAllDoorGroups xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="9440512" />
</ns2:getAllDoorGroups>

Return result

The names and unique ID of all door groups configured in Cisco PAM.

Sample response

<ns2:getAllDoorGroupsResponse xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<doorGroups name="Cube-doors" unid="0LYtFLOKS1SfM0kpnpIlew==" />
</ns2:getAllDoorGroupsResponse>

getAllDoorsByGroup

Function name

getAllDoorsByGroup

Description

Returns all doors configured for the specified door group.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

groupId: (required) unique ID of the door group.

Sample request

<ns2:getAllDoorsByGroup xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="29223376" />
	<groupId>0LYtFLOKS1SfM0kpnpIlew==</groupId>
</ns2:getAllDoorsByGroup>

Return result

A list of the doors and door details assigned to the specified door group.

Sample response

<ns2:getAllDoorsByGroupResponse
	xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<doors enabled="true" siteId="v5OyH3XSQdqNRECjcKcAsQ=="
		deviceState="VX.UNK" address="/SanJose/pgw_1001/Door/door01"
		type="GW.DOOR"
		name="SideDoor" unid="YZkTWA0UQJm0HUCHY4fGWQ==">
		<cameras>
			<devices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				xmlns:ns5="http://cisco.com/physec/video/"
				xsi:type="ns5:CameraDevice"
				type="CB.CAMERA" name="2500-SD-Dual"
				unid="CquVLWW6RZOLYos6xfMUrA==" />
			<devices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				xmlns:ns5="http://cisco.com/physec/video/"
				xsi:type="ns5:CameraDevice"
				type="CB.CAMERA" name="702 Xp3 0"
				unid="8evRj5pOTaSzX7Dt0N9vlQ==" />
		</cameras>
		<adminStatus>PROVISIONED</adminStatus>
		<associatedDevice enabled="true"
			siteId="v5OyH3XSQdqNRECjcKcAsQ==" deviceState="VX.UNK"
			address="/SanJose/pgw_1001/m00/pwrfail01/doorSensor"
			type="GW.DOORSENSOR"
			name="doorSensor" unid="DRdu+K9QSy+GGKwY1m2omA==">
			<adminStatus>PROVISIONED</adminStatus>
		</associatedDevice>
		<associatedDevice enabled="true"
			siteId="v5OyH3XSQdqNRECjcKcAsQ==" deviceState="VX.UNK"
			address="/SanJose/pgw_1001/m00/output02/lock" type="GW.LOCK"
			name="lock"
			unid="AmjWoa3XThySwn+PJRqf6A==">
			<adminStatus>PROVISIONED</adminStatus>
		</associatedDevice>
		<associatedDevice enabled="true"
			siteId="v5OyH3XSQdqNRECjcKcAsQ==" deviceState="VX.UNK"
			address="/SanJose/pgw_1001/m00/input03/rex" type="GW.REX" name="rex"
			unid="kF8Wt/PiQfyqn9Y230mfVA==">
			<adminStatus>PROVISIONED</adminStatus>
		</associatedDevice>
		<associatedDevice enabled="true"
			siteId="v5OyH3XSQdqNRECjcKcAsQ==" deviceState="VX.UNK"
			address="/SanJose/pgw_1001/m00/rdr02/reader" type="GW.RDR"
			name="reader"
			unid="pno3y3H0SMG0+suupRQtrw==">
			<adminStatus>PROVISIONED</adminStatus>
		</associatedDevice>
	</doors>
             ....
</ns2:getAllDoorsByGroupResponse>

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

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAllPerson xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="32015437" />
</ns2:getAllPerson>

Return result

A list of the access control persons, including first name, last name, person ID and unique ID.

Sample response

<ns2:getAllPersonResponse xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<persons>
		<person lname="TestUser_LastName" fname="TestUser_FirstName"
			personId="123456" unid="wWyRKdm6QyuCNes9J3NXaA==" />
	</persons>
</ns2:getAllPersonResponse>

getAllPersonTypeIds

Function name

getAllPersonTypeIds

Description

Returns all the personnel types defined in Cisco PAM.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAllPersonTypeIds xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="7163697" />
</ns2:getAllPersonTypeIds>

Return result

List of the personnel types.

To view the list in Cisco PAM:

Select Personnel from the Users menu.

Open a personnel record and click the Occupational Information tab.

Click the Personnel types menu to display the list.

Sample response

<ns2:getAllPersonTypeIdsResponse
xmlns:ns3="http://www.w3.org/2005/08/addressing" 
xmlns:ns2="http://cisco.com/physec/acws/">
			<personType>EMPLOYEE</personType>
			<personType>EMPLOYEE_FULL_TIME</personType>
			<personType>EMPLOYEE_PART_TIME</personType>
			<personType>CONTRACTOR</personType>
			<personType>VENDOR</personType>
			<personType>INTERN</personType>
			<personType>VISITOR</personType>
			<personType>OTHER</personType>
</ns2:getAllPersonTypeIdsResponse>

getAllPersonStatusIds

Function name

getAllPersonStatusIds

Description

Returns a list of Status definitions for personnel in Cisco PAM.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAllPersonStatusIds xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="7163697" />
</ns2:getAllPersonStatusIds>

Return result

List of the Status definitions.

To view the list in Cisco PAM:

Select Personnel from the Users menu.

Open a personnel record and click the Occupational Information tab.

Click the Status menu to display the list.

Sample response

<ns2:getAllPersonStatusIdsResponse
xmlns:ns3="http://www.w3.org/2005/08/addressing" 
xmlns:ns2="http://cisco.com/physec/acws/">
			<status>ACTIVE</status>
			<status>INACTIVE</status>
			<status>ON_LEAVE</status>
			<status>RETIRED</status>
			<status>TERMINATED</status>
</ns2:getAllPersonStatusIdsResponse>

getAllPersonByType

Function name

getAllPersonByType

Description

Returns the personnel records for a specified personnel type.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

typeId: (required) one of the personnel types returned using the getAllPersonTypeIds API.

Sample request

<ns2:getAllPersonByType xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="32015437" />
	<typeId>EMPLOYEE_FULL_TIME</typeId>
</ns2:getAllPersonByType>

Return result

Returns a list of personnel records for the specified personnel type.

Sample response

<ns2:getAllPersonByTypeResponse 
xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<persons>
		<person lname="TestUser_LastName" fname="TestUser_FirstName"
			personId="123456" unid="wWyRKdm6QyuCNes9J3NXaA==" />
	</persons>
</ns2:getAllPersonByTypeResponse>

enrollPerson

Function name

enrollPerson

Description

Adds a personnel record to Cisco PAM.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

personInfo: (required) data assigned to the personnel record. This can include the personId, first name, last name, organizationId (can be fetched from the getAllOrganizations API), departmentId (can be fetched from the getAllDepartments API), statusId, and typeId. The personnel record can also include a base 64 encoded JPG image of the person.

Sample request

<ns2:enrollPerson xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="4557655" />
			<pinfo statusId="ACTIVE" typeId="EMPLOYEE_FULL_TIME"
				departmentId="4MbV9fvNSWGc7Igu7B7SjQ==" 
				organizationId="kYIGV6k9TGCUFVOMucOM0g=="
				lname="Last_3" fname="First_3" personId="4444">
				<picture>
					<picture>
/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja3kAAQAEAAAAPAAA/+4AJkFkb2JlAGTAAAAAAQMAFQQ
DBgoNAAAOtwAAE40AACJ5AAA+9//bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAoKCwoKDBA

..................

MDAwMDAwQDA4PEA8ODBMTFBQTExwbGxscHx8fHx8fHx8fHwEHBwcNDA0YEBAYGhURFRofHx8fHx8fNd
n6Tj/5g+NP/9k=

					</picture>
					<type>JPEG</type>
				</picture>
			</pinfo>
</ns2:enrollPerson>

Return result

If the person is enrolled successfully, the unique ID of the person is returned.

Sample response

<ns2:enrollPersonResponse xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<personId>4444</personId>
</ns2:enrollPersonResponse>

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

secCtx: (required) the security context object returned by authenticateUser.

Pinfo: (required) the information for the person's record.

Sample request

<ns2:updatePerson xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="4065879" />
	<pinfo statusId="ACTIVE" lname="Albert" fname="Richard"
		personId="000000013" unid="xx4M7jMiRX2x/cZRsEANDg==" />	
</ns2:updatePerson>

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

<ns2:updatePersonResponse xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing" />

getPersonInfo

Function name

getPersonInfo

Description

Returns information for a personnel record, including a picture if available.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

personId: (required) the unique ID of the person.

Sample request

<ns2:getPersonInfo xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="9052243" />
	<personId>Z4JT5umCTzyCmVfvI6RAKw==</personId>
</ns2:getPersonInfo>

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

<ns2:getPersonInfoResponse xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<personInfo statusId="ACTIVE" lname="Last_5302" fname="First_5302"
		personId="5302" unid="Z4JT5umCTzyCmVfvI6RAKw==" />
</ns2:getPersonInfoResponse>

getAllOrganizations

Function name

getAllOrganizations

Description

Returns detailed information for the organizations defined in Cisco PAM.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAllOrganizations xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="7163697" />
</ns2:getAllOrganizations>

Return result

List of organizations in Cisco PAM, including the unique ID, name and a list of department IDs.

Sample response

<ns2:getAllOrganizationsResponse
xmlns:ns3="http://www.w3.org/2005/08/addressing" 
xmlns:ns2="http://cisco.com/physec/acws/">
		<org>
			<uniqueId>kYIGV6k9TGCUFVOMucOM0g==</uniqueId>
			<name>Engineering</name>
			<deptIds>4MbV9fvNSWGc7Igu7B7SjQ==</deptIds>
		</org>
		<org>
			<uniqueId>zKhxXl7pSV6y1ZZP/7sGkg==</uniqueId>
			<name>Marketing</name>
			<deptIds>fmVolZqCTUSotR7m6JRJ5Q==</deptIds>
		</org>
</ns2:getAllOrganizationsResponse>

getAllDepartments

Function name

getAllDepartments

Description

Returns all the departments defined in Cisco PAM.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

Sample request

<ns2:getAllDepartments xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="7163697" />
</ns2:getAllDepartments>

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

<ns2:getAllDepartmentsResponse
xmlns:ns3="http://www.w3.org/2005/08/addressing" 
xmlns:ns2="http://cisco.com/physec/acws/">
		<dept>
				<uniqueId>4MbV9fvNSWGc7Igu7B7SjQ==
				</uniqueId>
				<name>PSBUAccessControl</name>
				<orgId>kYIGV6k9TGCUFVOMucOM0g==</orgId>
			</dept>
			<dept>
				<uniqueId>fmVolZqCTUSotR7m6JRJ5Q==
				</uniqueId>
				<name>VideoSurvellance</name>
				<orgId>zKhxXl7pSV6y1ZZP/7sGkg==</orgId>
			</dept>
</ns2:getAllDepartmentsResponse>

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

secCtx: (required) the security context object returned by authenticateUser.

category: (string: required): the event category.

beginTime: (long: optional) the interval start time. The beginning of a time interval, specified as number of milliseconds from epoch time. All events within this time interval are included in the result.

endTime: (long: optional) the interval endTime. Ending time for a time interval, specified as number of milliseconds from epoch time.

deviceId: (optional) the unique ID of the device. If a unique ID is included, events and alarms are only returned for the specified device. If blank, events of all devices are included.

Sample request

<ns2:getAllEventsByCategory xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="11563709" />
	<category>GW.EV_MAJOR_ID_DOOR</category>
	<begTime>1244498633952</begTime>
	<endTime>1247090633952</endTime>
</ns2:getAllEventsByCategory>

Return result

Returns the events and alarms by event category and other optional parameters.

Sample response

<ns2:getAllEventsByCategoryResponse
			xmlns:ns2="http://cisco.com/physec/acws/" 
           xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<events>
				<event evtTime="1228950257000" isAlarm="true" 
					 type="GW.EV_DOOR_FORCED_OPEN"                   
					 deviceId="GgXIKOh2Rciu33wuB5jXdA=="
					 unid="126">
					 <description>Door Forced Open</description>
				</event>
				<event evtTime="1228950535000" isAlarm="true" 
					 type="GW.EV_DOOR_FORCED_OPEN" 
					 deviceId="GgXIKOh2Rciu33wuB5jXdA=="
					 unid="129">
					 <description>Door Forced Open</description>
				</event>
				<event evtTime="1228950633000" isAlarm="true" 
					 type="GW.EV_DOOR_FORCED_OPEN" 
					 deviceId="GgXIKOh2Rciu33wuB5jXdA=="
					 unid="133">
					 <description>Door Forced Open</description>
				</event>
				<event evtTime="1228955167000" isAlarm="true" 
					 type="GW.EV_DOOR_FORCED_OPEN" 
					 deviceId="GgXIKOh2Rciu33wuB5jXdA=="
					 unid="139">
					 <description>Door Forced Open</description>
				</event>
				<event evtTime="1229014038000" isAlarm="true" 
					 type="GW.EV_DOOR_FORCED_OPEN" 
					 deviceId="GgXIKOh2Rciu33wuB5jXdA=="
					 unid="168">
					 <description>Door Forced Open</description>
				</event>
			</events>
		</ns2:getAllEventsByCategoryResponse>

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

secCtx: (required) the security context object returned by authenticateUser.

evtTypeUnid: (string: required) the unique ID of the event type.

beginTime: (long: optional) the interval start time. The beginning of a time interval, specified as number of milliseconds from epoch time. All events within this time interval are included in the result.

endTime: (long: optional) the interval endTime. Ending time for a time interval, specified as number of milliseconds from epoch time.

deviceId: (optional) the unique ID of the device. If blank, all devices are included.If a device ID is included, events and alarms are only returned for the specified device.

Note If an invalid evtTypeUnid or deviceId is specified, no matching events will be returned.

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 If an invalid evtTypeUnid or deviceId is specified, no matching events will be returned.

Sample response

<ns2:getAllEventsByTypeResponse
	xmlns:ns2="http://cisco.com/physec/acws/" 
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<events>
		<event evtTime="1228950257000" 
				isAlarm="true" 
				type="GW.EV_DOOR_FORCED_OPEN" 
				deviceId="GgXIKOh2Rciu33wuB5jXdA=="
				unid="126">
				<description>Door Forced Open</description>
		</event>
		<event evtTime="1228950535000" isAlarm="true" 
				type="GW.EV_DOOR_FORCED_OPEN"                   
				deviceId="GgXIKOh2Rciu33wuB5jXdA=="
				unid="129">
				<description>Door Forced Open</description>
		</event>
		<event evtTime="1228950633000" isAlarm="true" 
				type="GW.EV_DOOR_FORCED_OPEN" 
				deviceId="GgXIKOh2Rciu33wuB5jXdA=="
				unid="133">
				<description>Door Forced Open</description>
		</event>
		<event evtTime="1228955167000" isAlarm="true" 
				type="GW.EV_DOOR_FORCED_OPEN" 
				deviceId="GgXIKOh2Rciu33wuB5jXdA=="
				unid="139">
				<description>Door Forced Open</description>
		</event>
	</events>
</ns2:getAllEventsByTypeResponse>

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 Events include all events in the GW.EV_MAJOR_ID_DOOR category. This includes door access grant or deny events.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

beginTime: (long: optional) the interval start time. The beginning of a time interval, specified as number of milliseconds from epoch time. All events within this time interval are included in the result.

endTime: (long: optional) the interval endTime. Ending time for a time interval, specified as number of milliseconds from epoch time.

personId: (optional) the unique ID of an access control user. If not specified, door access events for all users are returned.

deviceId: (optional) the unique ID of the door device. If a deviceID is not included, events for all door devices are returned. If a device unique ID is included, events and alarms are only returned for the specified device.

max: (int: optional) specifies the maximum number of events.

recent: (bool: optional) if true, the most recent events are returned first. If false or null, the oldest events are returned first.

Note If an invalid personId or deviceId is specified, no matching events will be returned.

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 If an invalid eventType or deviceId is specified, no matching events will be returned.

Sample response

<ns2:getUserAccessEventsResponse
	xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<events />
</ns2:getUserAccessEventsResponse>

getAccessEventsByDoor

Function name

getAccessEventsByDoor

Description

Returns access events and alarms related for a door.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

beginTime: (long: optional) the interval start time. The beginning of a time interval, specified as number of milliseconds from epoch time. All events within this time interval are included in the result.

endTime: (long: optional) the interval endTime. Ending time for a time interval, specified as number of milliseconds from epoch time.

deviceId: (required) the unique ID of the door device. Returns events and alarms for the specified device. If blank, a fault is returned (see Chapter 3, "Fault Codes").

max: (int: optional) specifies the maximum number of events.

recent: (bool: optional) if true, the most recent events are returned first. If false or null, the oldest events are returned first.

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

<ns2:getAccessEventsByDoorResponse
			xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<events>
				<event priority="2" evtTime="1237326065000" isAlarm="false"
					type="GW.EV_DOOR_FORCED_OPEN_CLEAR"
					deviceId="foGrYqOjT7yuxPDOw6/9Yg==" unid="168">
					<description>Door Forced Open Cleared</description>
				</event>
				<event count="1" priority="8" evtTime="1237326060000"
					isAlarm="true"
					status="CLEARED" 
					type="GW.EV_DOOR_FORCED_OPEN"
					deviceId="foGrYqOjT7yuxPDOw6/9Yg==" unid="167">
					<description>Door Forced Open</description>
				</event>
				<event priority="2" evtTime="1237325666000" isAlarm="false"
					type="GW.EV_DOOR_FORCED_OPEN_CLEAR"
					deviceId="foGrYqOjT7yuxPDOw6/9Yg==" unid="160">
					<description>Door Forced Open Cleared</description>
				</event>
				<event count="1" priority="8" evtTime="1237324372000"
					isAlarm="true"
					status="CLEARED" 
					type="GW.EV_DOOR_FORCED_OPEN"
					deviceId="foGrYqOjT7yuxPDOw6/9Yg==" unid="159">
					<description>Door Forced Open</description>
				</event>
				<event priority="1" evtTime="1237324363000" isAlarm="false"
					deviceId="foGrYqOjT7yuxPDOw6/9Yg=="
					unid="158">
					<description>Door Opened</description>
				</event>
				<event priority="1" evtTime="1237316957000" isAlarm="false"
					deviceId="foGrYqOjT7yuxPDOw6/9Yg=="
					unid="157">
					<description>Door Opened</description>
				</event>
			</events>
		</ns2:getAccessEventsByDoorResponse>

getAllAlarmsByCategory

Function name

getAllAlarmsByCategory

Description

Lists alarms filtered by event category, time interval, and device ID.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

category: (string: required): the event category.

beginTime: (long: optional) the interval start time. The beginning of a time interval, specified as number of milliseconds from epoch time. All events within this time interval are included in the result.

endTime: (long: optional) the interval endTime. Ending time for a time interval, specified as number of milliseconds from epoch time.

deviceId: (optional) the unique ID of the device. If blank, all devices are included.If a device ID is included, events and alarms are only returned for the specified device.

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

<ns2:getAllAlarmsByCategoryResponse
	xmlns:ns3=http://www.w3.org/2005/08/addressing
	xmlns:ns2="http://cisco.com/physec/acws/">
	<alarms>
		<event isAnnotation="false" siteId="LxQqj4cuTaO1YLINZk/dzA=="
			count="1" priority="8" evtTime="1247160358000" isAlarm="true"
			status="ACTIVE"
			type="GW.EV_DOOR_FORCED_OPEN"
			deviceId="szhUH331QKSq29LfkuVX/g=="
			unid="519">
			<description>Door Forced Open</description>
		</event>
	</alarms>
</ns2:getAllAlarmsByCategoryResponse>

getAllAlarmsByType

Function name

getAllAlarmsByType

Description

Lists alarms filtered by event type, time interval, and device ID.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

evtType: (string: required) the event type.

beginTime: (long: optional) the interval start time. The beginning of a time interval, specified as number of milliseconds from epoch time. All events within this time interval are included in the result.

endTime: (long:optional) the interval end time. Ending time for a time interval, specified as number of milliseconds from epoch time.

deviceId: (optional) the unique ID of the device. If blank, all devices are included.If a device ID is included, events and alarms are only returned for the specified device.

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

<ns2:getAllAlarmsByTypeResponse
			xmlns:ns2="http://cisco.com/physec/acws/" 
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<alarms>
				<event evtTime="1228950257000" 
					 isAlarm="true" 
					 type="GW.EV_DOOR_FORCED_OPEN"  
					 deviceId="GgXIKOh2Rciu33wuB5jXdA=="
					 unid="126">
					<description>Door Forced Open</description>
				</event>
			</alarms>
		</ns2:getAllAlarmsByTypeResponse>

getAllAlarmUpdates

Function name

getAllAlarmUpdates

Description

Retrieves all alarm updates by getting a list of alarm annotations.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

beginTime: (long:optional) the interval start time. The beginning of a time interval, specified as number of milliseconds from epoch time. All events within this time interval are included in the result.

endTime: (long: optional) the interval end time. Ending time for a time interval, specified as number of milliseconds from epoch time.

Sample request

<ns2:getAllAlarmUpdates xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="32448635" />
	<beginTime>1235259620358</beginTime>
	<endTime>1237851620358</endTime>
</ns2:getAllAlarmUpdates>

Return result

Returns a list of alarm annotation. Alarm annotation includes the following:

unid: unique ID of annotation

alarmId: alarm ID that it annotates.

state: state of the related alarm.

siteId: site identifier that owns the alarm annotation.

alarmDeviceId: the unique ID of the device on which alarm is generated.

Sample response

<ns2:getAllAlarmUpdatesResponse 
	xmlns:ns2="http://cisco.com/physec/acws/" 
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<annotations>
		<unid>11651</unid>
		<alarmId>11501</alarmId>
		<state>CLEARED</state>
		<siteId>RqNfHyJ3Qu6nxrUs9W4nkw==</siteId>
		<alarmDeviceId>hHHiu6oyQBm6u+y/xP3j8A==</alarmDeviceId>
	</annotations>
	<annotations>
		<unid>11661</unid>
		<alarmId>11411</alarmId>
		<state>CLEARED</state>
		<siteId>RqNfHyJ3Qu6nxrUs9W4nkw==</siteId>
		<alarmDeviceId>hHHiu6oyQBm6u+y/xP3j8A==</alarmDeviceId>
	</annotations>
	<annotations>
		<unid>11671</unid>
		<alarmId>8011</alarmId>
		<state>CLEARED</state>
		<siteId>RqNfHyJ3Qu6nxrUs9W4nkw==</siteId>
		<alarmDeviceId>hHHiu6oyQBm6u+y/xP3j8A==</alarmDeviceId>
	</annotations>
	<annotations>
		<unid>11681</unid>
		<alarmId>5631</alarmId>
		<state>CLEARED</state>
		<siteId>RqNfHyJ3Qu6nxrUs9W4nkw==</siteId>
		<alarmDeviceId>hHHiu6oyQBm6u+y/xP3j8A==</alarmDeviceId>
	</annotations>
	<annotations>
		<unid>11781</unid>
		<alarmId>11741</alarmId>
		<state>CLEARED</state>
		<siteId>RqNfHyJ3Qu6nxrUs9W4nkw==</siteId>
		<alarmDeviceId>hHHiu6oyQBm6u+y/xP3j8A==</alarmDeviceId>
	</annotations>
</ns2:getAllAlarmUpdatesResponse></soap:Body></soap:Envelope>

clearAlarm

Function name

clearAlarm

Description

Clears a specified alarm.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

alarmId: (required) specifies the unique ID of the alarm

notes: (optional) notes that are saved with the alarm.

Sample request

<ns2:getAllAlarmUpdates xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="32448635" />
	<beginTime>1235259620358</beginTime>
	<endTime>1237851620358</endTime>
</ns2:getAllAlarmUpdates>

Return result

"True" if the request is successful.

Sample response

		<ns2:getAllAlarmUpdatesResponse
			xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<annotations>
				<unid>165</unid>
				<alarmId>159</alarmId>
				<state>CLEARED</state>
				<siteId>AOL5p+ksQCKfBTBYQfumpQ==</siteId>
			</annotations>
			<annotations>
				<unid>166</unid>
				<alarmId>123</alarmId>
				<state>CLEARED</state>
				<siteId>AOL5p+ksQCKfBTBYQfumpQ==</siteId>
			</annotations>
			<annotations>
				<unid>169</unid>
				<alarmId>167</alarmId>
				<state>CLEARED</state>
				<siteId>AOL5p+ksQCKfBTBYQfumpQ==</siteId>
			</annotations>
			<annotations>
				<unid>174</unid>
				<alarmId>167</alarmId>
				<state>CLEARED</state>
				<siteId>AOL5p+ksQCKfBTBYQfumpQ==</siteId>
			</annotations>
			<annotations>
				<unid>175</unid>
				<alarmId>159</alarmId>
				<state>CLEARED</state>
				<siteId>AOL5p+ksQCKfBTBYQfumpQ==</siteId>
			</annotations>
			<annotations>
				<unid>176</unid>
				<alarmId>123</alarmId>
				<state>CLEARED</state>
				<siteId>AOL5p+ksQCKfBTBYQfumpQ==</siteId>
			</annotations>
			<annotations>
				<unid>245</unid>
				<alarmId>244</alarmId>
				<state>CLEARED</state>
				<siteId>AOL5p+ksQCKfBTBYQfumpQ==</siteId>
			</annotations>
			<annotations>
				<unid>254</unid>
				<alarmId>249</alarmId>
				<state>CLEARED</state>
				<siteId>AOL5p+ksQCKfBTBYQfumpQ==</siteId>
			</annotations>
          .. . . . . . .

		</ns2:getAllAlarmUpdatesResponse>

ackAlarm

Function name

ackAlarm

Description

Acknowledges an alarm.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

alarmId: (required) specifies the unique ID of the alarm

notes: (string:optional) notes that are saved with the alarm that is acknowledged.

Sample request

<ns2:ackAlarm xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<secCtx token="25785386" />
			<eventId>382</eventId>
			<notes>This is alarm notes</notes>
		</ns2:ackAlarm>

Return result

"True" if the request is successful.

Sample response

<ns3:ackAlarmResponse xmlns:ns2="http://www.w3.org/2005/08/addressing"
		xmlns:ns3="http://cisco.com/physec/acws/">
		<result>true</result>
</ns3:ackAlarmResponse>

getVersionInfo

Function name

getVersionInfo

Description

Returns access control web service version information.

Method

Post

Parameters

None.

Sample request

<ns2:getVersionInfo xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
</ns2:getVersionInfo>

Return result

The following information is returned:

major version

minor version

release version

build version

Sample response

<ns2:getVersionInfoResponse  
	xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<version build="265" maint="0" minor="1" major="1" />
</ns2:getVersionInfoResponse>

getAlarmDuplicates

Function name

getAlarmDuplicates

Description

Returns duplicates for a specified alarm.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

eventId: (required) specifies the unique ID of the alarm.

Sample request

<ns2:getAlarmDuplicates xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="25360171" />
	<alarmId>428451</alarmId>
</ns2:getAlarmDuplicates>

Return result

Returns a list of the duplicate alarms.

Sample response

<ns2:getAlarmDuplicatesResponse
	xmlns:ns2="http://cisco.com/physec/acws/" 
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<alarms>
		<event alarmDuplicateOf="428451" isAnnotation="false"
			siteId="d63KEPvzTBqujjBxWx1egQ==" count="2" priority="1"
			evtTime="1255022267000" isAlarm="true" status="CLEARED" 
			type="GW.EV_REX_OPEN" deviceId="4uSOaOAMRzKcOKqEw8TLPw==" unid="428471">
			<description>REX Open</description>
			<srcDeviceName>rex</srcDeviceName>
		</event>
	</alarms>
</ns2:getAlarmDuplicatesResponse>

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 Implement a service interface on the client.

Step 2 Register the service interface (endpoint) on Cisco PAM using either SOAP/HTTP or XML/HTTP.

To implement a SOAP/HTTP binding on the client, use registerAcEventCallback. This is used to register a W3CEndPointReference for an endpoint service that implements AcEventPortType.

To implement an XML/HTTP binding, use registerAcEventXMLCallback to register an endpoint URL.


Tip Use unregisterAcEventCallback to unregister a callback endpoint.


Step 3 Use the notifyAcEvent API to notify a client application when an event or alarm occurs.


For more information, see the following:

registerAcEventCallback

registerAcEventXMLCallback

unregisterAcEventCallback

notifyAcEvent

Example to Implement and Register a Service Interface

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 If an error is encountered in notifying events/alarms to the endpoint, the endpoint reference is automatically removed from the callback registry.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

evtTypes: (required) one or more event types for the notification.

evtCallback: (required) the callback interface used to notify event/alarms.

alarmsOnly: (required) true if only alarms are sent. False if events and alarm notifications are sent.

Sample request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:registerAcEventCallback xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<secCtx token="8413945" />
			<eventCallback>
				<ns3:Address>http://localhost:8090/callback/notifyacevent
				</ns3:Address>
				<ns3:ReferenceParameters>
					<wsa:ReferenceParameters 
xmlns:wsa="http://www.w3.org/2005/08/addressing">
						<testParameter1>testValue1</testParameter1>
						<testParameter2>testValue2</testParameter2>
					</wsa:ReferenceParameters>
				</ns3:ReferenceParameters>
				<ns3:Metadata>
					<wsaw:ServiceName 
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
						xmlns:wsa="http://www.w3.org/2005/08/addressing" 
EndpointName="AcEventPortTypePort">
						ns2:AcEventService</wsaw:ServiceName>
				</ns3:Metadata>
			</eventCallback>
			<alarmsOnly>false</alarmsOnly>
		</ns2:registerAcEventCallback>
	</soap:Body>
</soap:Envelope>

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:registerAcEventCalbackResponse
			xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<return>1001</return>
		</ns2:registerAcEventCalbackResponse>
	</soap:Body>
</soap:Envelope>

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 If a notification error occurs, the endpoint is automatically removed from the callback registry.

Method

Post

Parameters

secCtx: (required) the security context object returned by authenticateUser.

evtTypes: (AcEventTypeList: required) one or more event types that will be notified.

serviceUrl: (string: required) the callback URL. This URL points to an endpoint which implements AcEventPortType interface.

alarmsOnly: (bool:required) if true only alarms are notified.

Sample request

<ns2:registerAcEventXMLCallback
	xmlns:ns3=http://www.w3.org/2005/08/addressing
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="9507071" />
	<evtTypes>
		<evtType unid="VX.ALMCLEAR" />
		<evtType unid="GW.EV_DOOR_FORCED_OPEN" />
	</evtTypes>
	<serviceUrl>http://localhost:8090/callback/notifyaceventxml
	</serviceUrl>
	<alarmsOnly>false</alarmsOnly>
</ns2:registerAcEventXMLCallback>

Return result

registrationKey: the key that identifies the callback registration. This value is returned when callback is registered successfully. See unregisterAcEventCallback.

Sample response

<ns2:registerAcEventXMLCallbackResponse
	xmlns:ns3=http://www.w3.org/2005/08/addressing
	xmlns:ns2="http://cisco.com/physec/acws/">
	<return>1001</return>
</ns2:registerAcEventXMLCallbackResponse>

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

secCtx: (required) the security context object returned by authenticateUser.

registrationKey: (required) the key that identifies the callback registration. This value is returned when callback is registered successfully. See registerAcEventCallback.

Sample request

<ns2:unregisterAcEventCallback xmlns:ns3="http://www.w3.org/2005/08/addressing"
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="6846226" />
	<registrationKey>1007</registrationKey>
</ns2:unregisterAcEventCallback>

Return result

None.

Sample response

<ns2:unregisterAcEventCallbackResponse
	xmlns:ns3="http://www.w3.org/2005/08/addressing" 
xmlns:ns2="http://cisco.com/physec/acws/" />

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:notifyAcEvent xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<event evtTime="1229014038427" isAlarm="true
				"type="GW.EV_DOOR_FORCED_OPEN"
				deviceId="GgXIKOh2Rciu33wuB5jXdA=="
				unid="168">
				<description>Door Forced Open</description>
			</event>
		</ns2:notifyAcEvent>
	</soap:Body>
</soap:Envelope>

Return result

True if the event was handled. False if it was not.

Sample response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:notifyAcEventResponse xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<return>true</return>
		</ns2:notifyAcEventResponse>
	</soap:Body>
</soap:Envelope>

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 be
        System.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:Metadata
      xmlns: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:ServiceName 
             EndpointName="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

secCtx: the security context object returned by authenticateUser.

doorId: door unique ID

Sample request

<ns2:grantDoorAccess xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="27224694" />
	<doorId>fBU5hRu3RuegMSrmSfm5xg==</doorId>
</ns2:grantDoorAccess>

Return result

True if the command is successful. False if it is not.

Sample response

<ns2:grantDoorAccessResponse    xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<result>true</result>
</ns2:grantDoorAccessResponse>

setDoorMode

Function name

setDoorMode

Description

Sets the door mode for a specified door and overrides the current door mode.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

doorId: door unique ID.

mode: defines the new door mode (DoorModeType).

Sample request

<ns2:setDoorMode xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<ctx token="24806017" />
	<doorId>PpDjVmWMSP69gjW/4nAvCg==</doorId>
	<mode>LOCK</mode>
</ns2:setDoorMode>

Return result

None

Sample response

<ns2:setDoorModeResponse xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing" />

resetDoorMode

Function name

resetDoorMode

Description

Resets the door mode to the original Cisco PAM configuration.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

doorId: door unique ID

Note This function overrides the door mode set using setDoorMode.

Sample request

<ns2:resetDoorMode xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<ctx token="5428681" />
	<doorId>PpDjVmWMSP69gjW/4nAvCg==</doorId>
</ns2:resetDoorMode>

Return result

None.

Sample response

<ns2:resetDoorModeResponse xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing" />

getDoorMode

Function name

getDoorMode

Description

Returns the current door mode for a specified door.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

doorId: door unique ID

Sample request

<ns2:getDoorMode xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="13567485" />
	<doorId>PpDjVmWMSP69gjW/4nAvCg==</doorId>
</ns2:getDoorMode>

Return result

The door mode for the specified door.

Sample response

<ns2:getDoorModeResponse xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<currentMode>OPEN</currentMode>
</ns2:getDoorModeResponse>

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

secCtx: the security context object returned by authenticateUser.

doorId: unique ID of a door device in Cisco PAM. The door mode will be configured for the door specified in this parameter.

defMode: the default door mode. The default mode can be one of the following:

OPEN

LOCK

SECURE

schName: the name of the door schedule for changing door mode.

schMode: the door mode used by the specified schedule.

OPEN

LOCK

SECURE

Sample request

<ns2:setDoorModeConfig xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<ctx token="31410451" />
	<doorId>PpDjVmWMSP69gjW/4nAvCg==</doorId>
	<defMode>OPEN</defMode>
	<schName>Always Scheduled</schName>
	<schMode>LOCK</schMode>
</ns2:setDoorModeConfig>

Return result

None.

Sample response

<ns2:setDoorModeConfigResponse
	xmlns:ns2="http://cisco.com/physec/acws/" 	
xmlns:ns3="http://www.w3.org/2005/08/addressing" />

Badge Enrollment APIs

getAllAccessLevels

Function name

getAllAccessLevels

Description

Returns detailed information for all access levels defined in Cisco PAM.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getAllAccessLevels xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<ctx token="18492755" />
</ns2:getAllAccessLevels>

Return result

List of access level definitions, including type and schedule.

Sample response

<ns2:getAllAccessLevelsResponse
	xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<accessLevels>
		<ns2:accessLevelInfo unid="85MMlASIQFOxSkJeWrT6JA=="
			deActivationDuration="0" enable="true" name="TestAL2">
			<ns2:accessLevelEntry doorId="EWyzrhOuRjGO+3D1+89vWA=="
				accesslevelentrytype="DOOR" scheduleName="Always Permit" />
		</ns2:accessLevelInfo>
	</accessLevels>
	<accessLevels>
		<ns2:accessLevelInfo unid="iw3wxU4lSfSimYKGCFr+Ig=="
			deActivationDuration="0" enable="true" name="TestAL1">
			<ns2:accessLevelEntry doorId="EWyzrhOuRjGO+3D1+89vWA=="
				accesslevelentrytype="DOOR" scheduleName="Default Schedule" />
		</ns2:accessLevelInfo>
	</accessLevels>
</ns2:getAllAccessLevelsResponse>

getAllAccessLevelNames

Function name

getAllAccessLevelNames

Description

Returns names of all the access level defined in Cisco PAM.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getAllAccessLevelNames xmlns:ns2="http://cisco.com/physec/acws/">
	<ctx token="27660152" />
</ns2:getAllAccessLevelNames>

Return result

List of all access level names defined in Cisco PAM.

Sample response

<ns2:getAllAccessLevelNamesResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<accessLevelNames>al1</accessLevelNames>
	<accessLevelNames>lab access level</accessLevelNames>
	<accessLevelNames>al2</accessLevelNames>
	<accessLevelNames>Always Permit</accessLevelNames>
</ns2:getAllAccessLevelNamesResponse>

getAccessLevelByName

Function name

getAccessLevelByName

Description

Returns detailed information for a specified access level.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

alname: name of access level.

Sample request

<ns2:getAccessLevelByName xmlns:ns2="http://cisco.com/physec/acws/">
	<ctx token="13605586" />
	<alname>al1</alname>
</ns2:getAccessLevelByName>

Return result

The specified access level definition.

Sample response

<ns2:getAccessLevelByNameResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<accessLevel>
		<ns2:accessLevelInfo unid="0zG0ACarRAidbEGXdpunkQ=="
			deActivationDuration="0" enable="true" name="al1">
		<ns2:accessLevelEntry doorId="PpDjVmWMSP69gjW/4nAvCg=="
			accesslevelentrytype="DOOR" scheduleName="Always Permit" />
		<ns2:accessLevelEntry doorId="J4aJ3RaMRCS4CTWJOmD1qA=="
			accesslevelentrytype="DOOR" scheduleName="Always Permit" />
		<ns2:accessLevelEntry doorId="ChnmStRYREKeAjvo9xy2IA=="
			accesslevelentrytype="DOOR" scheduleName="Always Permit" />
			<description>Access Level </description>
		</ns2:accessLevelInfo>
	</accessLevel>
</ns2:getAccessLevelByNameResponse>

getAllSchedules

Function name

getAllSchedules

Description

Returns information for all schedules defined in Cisco PAM.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getAllSchedules xmlns:ns2="http://cisco.com/physec/acws/">
	<ctx token="4905582" />
</ns2:getAllSchedules>

Return result

Definitions for all access schedules configured in Cisco PAM.

Sample response

<ns2:getAllSchedulesResponse xmlns:ns2="http://cisco.com/physec/acws/">
<schedule scheduleType="ACCESSPOLICY"
	descr="All working days 8AM to 6PM schedule " name="Default Schedule">
	<ns2:scheduleEntry>
	<ns2:timemaps>
		<ns2:timemap
		name="TIMEMAP/WWK/Default Work Week/Default Time Range Group/1/1">
			<ns2:year end="65535" begin="65535">
				<ns2:month end="255" begin="255">
					<ns2:week end="255" begin="255">
						<ns2:day end="5" begin="1">
							<ns2:timeInterval end="64800999" begin="28800000" />
						</ns2:day>
					</ns2:week>
				</ns2:month>
			</ns2:year>
			</ns2:timemap>
		</ns2:timemaps>
		<scheduleAction>PERMIT</scheduleAction>
		</ns2:scheduleEntry>
	</schedule>
	............................
	...........................
	</schedule>
	<schedule scheduleType="DOORPOLICY" descr="Always use the default door mode"
		name="Always Default">
		<ns2:scheduleEntry>
			<ns2:timemaps>
				<ns2:timemap
					name="TIMEMAP/WWK/All Days Work Week/Always Time Range Group/1/1">
					<ns2:year end="65535" begin="65535">
						<ns2:month end="255" begin="255">
							<ns2:week end="255" begin="255">
								<ns2:day end="6" begin="0">
									<ns2:timeInterval end="86399999" begin="0" />
								</ns2:day>
							</ns2:week>
						</ns2:month>
					</ns2:year>
				</ns2:timemap>
			</ns2:timemaps>
			<scheduleAction>PERMIT</scheduleAction>
		</ns2:scheduleEntry>
	</schedule>
</ns2:getAllSchedulesResponse>

getAllScheduleNames

Function name

getAllScheduleNames

Description

Returns names of all the access schedules defined in Cisco PAM.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getAllScheduleNames xmlns:ns2="http://cisco.com/physec/acws/">
	<ctx token="17117710" />
</ns2:getAllScheduleNames>

Return result

List of all access schedules defined in Cisco PAM.

Sample response

<ns2:getAllScheduleNamesResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<scheduleName>Work Week Event Policy Schdule</scheduleName>
	<scheduleName>Default Schedule</scheduleName>
	<scheduleName>Always Permit Event Policy</scheduleName>
	<scheduleName>Always Scheduled</scheduleName>
	<scheduleName>Always Deny Event Policy</scheduleName>
	<scheduleName>Work Schedule</scheduleName>
	<scheduleName>Always Permit</scheduleName>
	<scheduleName>Always Default</scheduleName>
</ns2:getAllScheduleNamesResponse>

getScheduleByName

Function name

getScheduleByName

Description

Returns detailed information for a specified access schedule.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getScheduleByName xmlns:ns2="http://cisco.com/physec/acws/">
	<ctx token="14185214" />
	<schName>Always Permit</schName>
</ns2:getScheduleByName>

Return result

Definition for a specified access schedule.

Sample response

<ns2:getScheduleByNameResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<schedule scheduleType="ACCESSPOLICY" descr="Always Permit Schedule Description"
		name="Always Permit">
		<ns2:scheduleEntry>
			<ns2:timemaps>
				<ns2:timemap
					name="TIMEMAP/WWK/All Days Work Week/Always Time Range Group/1/1">
					<ns2:year end="65535" begin="65535">
						<ns2:month end="255" begin="255">
							<ns2:week end="255" begin="255">
								<ns2:day end="6" begin="0">
									<ns2:timeInterval end="86399999" begin="0" />
								</ns2:day>
							</ns2:week>
						</ns2:month>
					</ns2:year>
				</ns2:timemap>
			</ns2:timemaps>
			<scheduleAction>PERMIT</scheduleAction>
		</ns2:scheduleEntry>
	</schedule>
</ns2:getScheduleByNameResponse>

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:

The gwBadge extension defines properties such as credential template, use limit, and role.

The HsBadge extension defines properties relevant for HSPD Badges.

Note The HsBadge extension is experimental and may be changed or removed in future Cisco PAM releases. For this reason, the extension should not be used in a production setting.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

personInfo: information for the personnel record for the assigned badge.

templateName: the credential template name used to create the badge. Once the badge is created, a badge template specifies the intiail properties of the badge.

BadgeList: List of Badges where each of the badge can have one or more badge extensions specified.

Sample request

In the following sample:

A personId identifies the person in the Cisco PAM. If the personId exists, the record is updated with the properties and badges information. If the personId does not exist in Cisco PAM, a new record is created for the personId.

A Base64 encoded (JPEG) image is added to the record.

A Badge Template ("TestTemplate") is used to create the badges.

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

		<ns2:enrollBadgeResponse xmlns:ns2="http://cisco.com/physec/acws/">
			<personId>247595849</personId>
		</ns2:enrollBadgeResponse>

assignAccessLevel

Function name

assignAccessLevel

Description

Assigns one or more access levels to a specified badge associated with a person.

Note This API replaces all the access levels on the specified badge.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

personUnid: the unique ID of the personnel record.

badgeId: the badge ID assigned to the specified person.

accessLevel: a list of access level unique IDs assigned to the badge.

Sample request

<ns2:assignAccessLevel xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="18492755" />
	<personUnid>D/DRqX4uToSMtLLXKO42LA==</personUnid>
	<badgeId>ObuzbsVOTQOECwkZ38v0uA==</badgeId>
	<accessLevel>iw3wxU4lSfSimYKGCFr+Ig==
	</accessLevel>
	<accessLevel>85MMlASIQFOxSkJeWrT6JA==
	</accessLevel>
</ns2:assignAccessLevel>

Return result

None or void.

Sample response

<ns2:assignAccessLevelResponse
			xmlns:ns2="http://cisco.com/physec/acws/" 
xmlns:ns3="http://www.w3.org/2005/08/addressing" />

getAllBadgesByPerson

Function name

getAllBadgesByPerson

Description

Returns badge details for the badges assigned to a specified person.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

personId: the person unique ID.

Sample request

<ns2:getAllBadgesByPerson xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<secCtx token="18492755" />
	<personId>dte70tHfS2qSUEsGWADW/w==</personId>
</ns2:getAllBadgesByPerson>

Return result

Detailed information for the badges assigned to the personnel unique ID.

Sample response

<ns2:getAllBadgesByPersonResponse
	xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
		<badgeList>
			<badges cardNumber="5306" badgeId="ZrOXe9ozQFeqvrD9+nTNRQ==">
				<expDate>1263715200000</expDate>
				<type>VX.STANDARD</type>
				<useCount>0</useCount>
				<effectiveDate>1105948800000</effectiveDate>
				<site>VtkNkl4hR5e/taeTsJEOKQ==</site>
				<summaryData>5306</summaryData>
				<extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
						xsi:type="ns2:HsBadge" ici="0" credentialSeries="0"
						credentialNumber="0" hsCardType="CARD_TYPE_NONE" agencyCode="0" />
			</badges>
		</badgeList>
</ns2:getAllBadgesByPersonResponse>

getBadgeValidityTypes

Function name

getBadgeValidityTypes

Description

Returns a list of Cisco PAM badge Validity types.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getBadgeValidityTypes 
				xmlns:ns2="http://cisco.com/physec/acws/">
		<secCtx token="22627865" />
</ns2:getBadgeValidityTypes>

Return result

Returns a list of Cisco PAM badge Validity types. For example: Blacklist and Revoked.

Tip To view the list in Cisco PAM, open the Badges module, click the General tab, and select the Validity drop-menu.

Sample response

		<ns2:getBadgeValidityTypesResponse
			xmlns:ns2="http://cisco.com/physec/acws/">
			<types>GW.BLACKLIST</types>
			<types>HS.REVOKED</types>
			<types>VX.ACTIVE</types>
			<types>VX.DESTROYED</types>
			<types>VX.INACTIVE</types>
			<types>VX.LOST</types>
			<types>VX.STOLEN</types>
		</ns2:getBadgeValidityTypesResponse>

getCredentialTemplateNames

Function name

getCredentialTemplateNames

Description

Returns a list of names of Credential templates defined in CPAM

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<<ns2:getCredentialTemplateNames
		xmlns:ns2="http://cisco.com/physec/acws/">
		<secCtx token="22627865" />
</ns2:getCredentialTemplateNames>

Return result

List of Credential Template names. For example: 26BitWiegandCT and 26BitWiegandKeypadCT.

Tip To view the list in Cisco PAM, select Doors: Templates: Credential Templates.

Sample response

<ns2:getCredentialTemplateNamesResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<credTemplateNames>26BitWiegandCT</credTemplateNames>
	<credTemplateNames>26BitWiegandKeypadCT
	</credTemplateNames>
	<credTemplateNames>HID_CORP_1000_H500xx
	</credTemplateNames>
	<credTemplateNames>KeyPad_BCD4</credTemplateNames>
</ns2:getCredentialTemplateNamesResponse>

getBadgeRoles

Function name

getBadgeRoles

Description

Returns the Badge type (roles) defined in Cisco PAM.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getBadgeRoles xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="22627865" />
</ns2:getBadgeRoles>

Return result

List of Badge type (roles) in Cisco PAM. For example: Employee, Contractor, Vendor, and Temporary.

Tip To view the list in Cisco PAM, open the Badges module, click the General tab, and select the Badge type drop-menu.

Sample response

<ns2:getBadgeRolesResponse xmlns:ns2="http://cisco.com/physec/acws/">
	<roles>EMPLOYEE</roles>
	<roles>CONTRACTOR</roles>
	<roles>VENDOR</roles>
	<roles>TEMPORARY</roles>
</ns2:getBadgeRolesResponse>

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

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getAllBadgeTemplateNames  
	xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="22627865" />
</ns2:getAllBadgeTemplateNames>

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

<ns2:getAllBadgeTemplateNamesResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<badgeTemplates>TestTemplate</badgeTemplates>
</ns2:getAllBadgeTemplateNamesResponse>

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

secCtx: the security context object returned by authenticateUser.

personUnid: unique ID that identifies the person.

Sample request

<ns2:getAccessLevelByPerson xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="32189659" />
	<personUnid>xcZZjt7+QYKcjUzMmpC27w==
	</personUnid>
</ns2:getAccessLevelByPerson>

Return result

A list of the access levels for all badges held by the specified access control user.

Sample response

<ns2:getAccessLevelByPersonResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<accessLevels>LimitedAccess</accessLevels>
</ns2:getAccessLevelByPersonResponse>

getBadgeByCardNum

Function name

getBadgeByCardNum

Description

Retrieves a badge record for a specified card number.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

cardNumber: the unique card number for the badge.

Sample request

<ns2:getBadgeByCardNum xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="31616571" />
	<cardNumber>1295</cardNumber>
</ns2:getBadgeByCardNum>

Return result

Badge details for the specified card number.

Sample response

<ns2:getBadgeByCardNumResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<badge cardNumber="1295" badgeId="UHiZJfc5QjqHHyN0K3Rqyw==">
		<expDate>1248646619000</expDate>
		<type>VX.STANDARD</type>
		<site>d63KEPvzTBqujjBxWx1egQ==</site>
		<summaryData>1295</summaryData>
		<accessLevels>0zG0ACarRAidbEGXdpunkQ==
		</accessLevels>
		<extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xsi:type="ns2:gwBadge">
			<credTemplateName>26BitWiegandCT</credTemplateName>
			<role>EMPLOYEE</role>
			<execCredential>false</execCredential>
			<pinExempt>false</pinExempt>
			<adaEnabled>false</adaEnabled>
		</extensions>
		<extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xsi:type="ns2:HsBadge" ici="0" credentialSeries="0"
			credentialNumber="0" hsCardType="CARD_TYPE_NONE" agencyCode="0" />
	</badge>
</ns2:getBadgeByCardNumResponse>

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

secCtx: the security context object returned by authenticateUser.

BadgeList: the list of badges to update.

personUnid: unique ID of person associated with the badges. If the specified ID does not exist, a fault is returned.

assign:

enter true if the specified badges are associated with the specified person

enter false the association is removed.

Sample request

<ns2:updateBadge xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="23402047" />
	<badge>
		<badges pin="5300" facilityCode="1" cardNumber="5300"
			badgeId="Zi3b2oe+TtuxLGEvyBSIWQ==">
			<expDate>1263715200000</expDate>
			<type>VX.STANDARD</type>
			<validityType>VX.INACTIVE</validityType>
			<effectiveDate>1105948800000</effectiveDate>
			<site>qq09fJRiQqGmAPgaVkF+wQ==</site>
			<summaryData>5300</summaryData>
			<accessLevels>TestPolicy1</accessLevels>
		</badges>
	</badge>
	<assign>true</assign>
</ns2:updateBadge>

Return result

A fault is returned if no badge is found in the database.

Sample response

<ns2:updateBadgeResponse xmlns:ns2="http://cisco.com/physec/acws/" />

getAccessLevelByUnid

Function name

getAccessLevelByUnid

Description

Returns information about an access level specified by the access level unid.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

unid: the unique ID of an access level.

Sample request

<ns2:getAccessLevelByUnid xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="21700915" />
	<unid>467cWZt+SK2EwMXXeTpUYw==</unid>
</ns2:getAccessLevelByUnid>

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

<ns2:getAccessLevelByUnidResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<accessLevel>
		<ns2:accessLevelInfo unid="467cWZt+SK2EwMXXeTpUYw=="
			deActivationDuration="0" enable="true" name="TestPolicy2">
			<ns2:accessLevelEntry doorId="rfghaHzARcu8E4Fhvv7hIw=="
				accesslevelentrytype="DOOR" scheduleName="Always Permit" />
		</ns2:accessLevelInfo>
	</accessLevel>
</ns2:getAccessLevelByUnidResponse>

getAllBadgeTypeIds

Function name

getAllBadgeTypeIds

Description

Returns the unique identifiers for Cisco PAM badge types.

Method

Post

Parameters

secCtx: the security context object returned by authenticateUser.

Sample request

<ns2:getAllBadgeTypeIds xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="8789085" />
</ns2:getAllBadgeTypeIds>

Return result

Cisco PAM badge types such as the following:

VX.VISITOR

VX.TEMP

VX.STANDARD

Sample response

<ns2:getAllBadgeTypeIdsResponse
	xmlns:ns2="http://cisco.com/physec/acws/">
	<typeIds>VX.STANDARD</typeIds>
	<typeIds>VX.TEMP</typeIds>
	<typeIds>VX.VISITOR</typeIds>
</ns2:getAllBadgeTypeIdsResponse>

getAllBadgeRefs

Function name

getAllBadgeRefs

Description

Returns a range of badge references based on required beginning and ending card number parameters.

Note A Badge Reference is an object that includes a badge unique ID and card number. The badge reference is used with the getBadgeByCardNum API to obtain complete badge information.

Method

Post

Parameters

Note The beginCardNumber and endCardNumber parameters are required. The other parameters are optional and are used to further filter the results.

secCtx: the security context object returned by authenticateUser.

beginCardNumber: (long: required) Card numbers equal to or greater than this number are included in the results.

endCardNumber: (long: required) Card numbers equal to or less than this number are included in the results.

Tip A "long" parameter is a signed 64 bit number.

badgeTypeId: (string: optional) Only badges with the specified badge type are included in the results. If the specified badge type is invalid, a fault is returned.

validityTypeId: (string: optional) Only badges with the specified validity type are included in the results. If the specified validity type is invalid, a fault is returned.

onlyUnassigned: (boolean: required) if the value is true, only badges not associated to any person are included in the result. If the value is false, all badges are included.

Sample request

<ns2:getAllBadgeRefs xmlns:ns2="http://cisco.com/physec/acws/">
	<secCtx token="11813864" />
	<beginCardNumber>5303</beginCardNumber>
	<endCardNumber>5307</endCardNumber>
	<onlyUnassigned>true</onlyUnassigned>
</ns2:getAllBadgeRefs>

Return result

List of badges references, including the badge unique ID and card number for the reference.

Sample response

<ns2:getAllBadgeRefsResponse xmlns:ns2="http://cisco.com/physec/acws/">
	<badgeRef>
		<unid>vVPfk6p+Sc6rA/cVpWGmWg==</unid>
		<cardNumber>5305</cardNumber>
	</badgeRef>
</ns2:getAllBadgeRefsResponse>

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. Define External Event Types Using the Event Definition Format. This file also defines the categories for the log codes.

2. Create a Text File to Define the Event Names in Cisco PAM.

3. Import the Files into Cisco PAM.

4. Add external events and alarms to Cisco PAM using recordExtEvent.
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:

The concatenation rule is: AE.<logcode_prefix>_<logcode>

Event category: AE.Cisco_VSM

The log codes for the category are: AE.VS_VSM_Sample1 and AE.VS_VSM_Sample2


<appext_eventdefns
   xmlns: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.

 
To do this
Use this display

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. Select the XML and Properties files.

The XML file defines the event log codes and category for the external events.

The Properties file defines the text string for each code and category. The text string is the name that appears in Cisco PAM.

b. Click Next to preview the settings, or click Finish to save the changes.

For instructions to create these files, see:

Define External Event Types Using the Event Definition Format

Create a Text File to Define the Event Names in Cisco PAM

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

secCtx: the security context object returned by authenticateUser.

appName: the application name that calls the recordExtEvent API. This information is saved in the data field of the event.

AcEvent: event to be recorded. The following fields are required:

srcDeviceName: the source device where the event originated. If the device name matches an existing entry (device of type AE.DEVICE) the event is associated with the existing device. If the device name does not exist, a new device of type AE.DEVICE with the specified name is created.

eventTime: the time the event occurred (in milliseconds, since epoch time).

type: specifies the event type for the event being recorded. This type must be imported in Cisco PAM before an event that belongs to the type can be recorded.

srcDeviceType: the type of source device where event originated. This information is saved in the data field of the event.

Sample request

		<ns2:recordExtEvent xmlns:ns2="http://cisco.com/physec/acws/"
			xmlns:ns3="http://www.w3.org/2005/08/addressing">
			<appName>Cisco_VSM</appName>
			<event evtTime="1251242603168" type="AE.VS_VSM_Sample1">
				<srcDeviceName>FrontDomeCamera</srcDeviceName>
			</event>
			<srcDeviceType>External_Camera</srcDeviceType>
		</ns2:recordExtEvent>

Return result

Once an event is recorded, it is displayed in the Cisco PAM Event Monitoring module.

Sample response

<ns2:recordExtEventResponse xmlns:ns2="http://cisco.com/physec/acws/"
	xmlns:ns3="http://www.w3.org/2005/08/addressing">
	<result isAnnotation="false" siteId="XFAx5kFhQ9CYGQCltUCLGg=="
		priority="10" evtTime="1251242603168" isAlarm="false" name="Sample Event-1"
		type="AE.VS_VSM_Sample1" deviceId="Uf4lTSWYSe+1RF1CRCHhCQ==" unid="159">
		<description>Sample Event-1</description>
	</result>
</ns2:recordExtEventResponse>

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 Service
private final static QName SERVICE = new QName("http://cisco.com/physec/acws/", 
"PSIMWsService");
// WSDL location URL
private 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 user
UserCredentialType uct = new UserCredentialType();
uct.setUsername("username");
uct.setPassword("password");
_ctx = _ PSIMWsInterface.authenticateUser(uct);

...

//Call methods using interface handles
AcEvent 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 Service
private 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 user
UserCredentialType uct = new UserCredentialType();
uct.username = "username";
uct.password = "password";
_ctx = _ psimBinding.authenticateUser(uct);

...

//Call methods using interface handles
recordExtEvent ree = new recordExtEvent();
ree.secCtx = _ctx; // From authenticateUser call
ree.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 session
logoutUser lu = new logoutUser();
lu.setCtx = _ctx;
_ psimBinding.logoutUser(lu);