Cisco Physical Access Manager User Guide, Release 1.4.1
System Integration
Downloads: This chapterpdf (PDF - 3.78MB) The complete bookPDF (PDF - 61.78MB) | Feedback

System Integration

Table Of Contents

System Integration

Contents

Configuring URL Actions

Creating or Modifying URL Actions

Creating Automated Rules for URL Actions

Viewing URL Events, Alarms, and Logs

Viewing URL Action Events

Viewing Alarms for Failed URL Action

Event and Alarm Response Codes for URL Actions

Viewing Logs for URL Action Output

URL Action Failure Due to Invalid Security Certificate

Synchronizing Data Using Enterprise Data Integration (EDI)

Before You Begin

Understanding Photo File Compression When Importing Personnel Records

Installing the EDI Licence and Desktop Application

Creating Active Directory Database Integration Projects Using EDI Studio

Creating Custom Employee Status Values

Creating SQL and Oracle Database Integration Projects Using EDI Studio

Importing, Starting, and Monitoring EDI Projects in Cisco PAM

Importing and Starting EDI Projects

Verifying EDI Projects (EDI Monitoring)

Modifying a Running EDI Project

Restarting a Failed EDI Project

Summary of EDI Administration Functions

Accessing the SQL Database

Personnel

Time and Attendance

User Tracking Data


System Integration


This chapter describes how to integrate the Cisco PAM data and actions with enterprise or third-party systems.

Contents

Configuring URL Actions

Creating or Modifying URL Actions

Creating Automated Rules for URL Actions

Viewing URL Events, Alarms, and Logs

Synchronizing Data Using Enterprise Data Integration (EDI)

Before You Begin

Understanding Photo File Compression When Importing Personnel Records

Installing the EDI Licence and Desktop Application

Creating Active Directory Database Integration Projects Using EDI Studio

Creating SQL and Oracle Database Integration Projects Using EDI Studio

Importing, Starting, and Monitoring EDI Projects in Cisco PAM

Accessing the SQL Database


Note See also the Cisco Physical Access Control API Reference Guide for information on Web Services support.


Configuring URL Actions

URL actions allow you to trigger actions in external systems when alarms or events occur in CPAM. For example, URL actions can trigger the following in other systems:

Cisco Energywise: a URL action can turn switch ports on or off, including any devices connected to those ports using Power-over-Ethernet (PoE). For example, when a user enters a building using a Cisco access control badge, the switch-powered equipment associated with that user can be turned on. When they exit the building, the equipment is turned off.

Camera integration: a URL action can control the pan, tilt and zoom (PZT) functions of cameras associated with a device. For example, the camera can turn and zoom toward a door when badge is swiped at a door.

Digital media player (DMP) integration: when a door event occurs, a URL action can display a custom HTML page on a DMP display.

To configure URL actions, select URL Actions from the Admin menu (Figure 14-1).

Figure 14-1 URL Actions Main Window

Click Preview to view the URL for an action.

Double-click an entry to view configuration settings.

Select an entry and click Invoke to run a static action (Dynamic actions cannot be manually invoked).

See the following sections for instructions to create and automate URL actions:

Creating or Modifying URL Actions

Creating Automated Rules for URL Actions

Viewing URL Events, Alarms, and Logs

Creating or Modifying URL Actions

To add or modify URL actions, complete the following instructions:

 
To do this

Step 1 

Select URL Actions from the Admin menu.

Step 2 

Click Add to create a new action, or select an existing action and click Edit.

Step 3 

Enter the basic properties in the URL Action window:

a. Name: enter a descriptive name.

b. Description: enter a short description of the rule.

c. Post / Get: select the method the listening server will implement.

d. Http / Https: Select the connection method. The Cisco PAM default for secure connections is to present a client certificate, and accept all secure certificates.

e. Enter the URL base.

This is the URL of the system that will be triggered.

For example: http://www.cisco.com

f. Select Enabled to enable or disable the action.

Notes Regarding Base URLs

Enter the URL exactly as it appears in the browser after URL encoding. Special characters in URLs, such as spaces, are replaced with the corresponding ASCII character when entered in a web browser. Enter the URL in a browser first, and then copy and paste the encoded URL in the URL base field.
For example: the URL http://www.yahoo.com?thread=Wall Street includes a space between Wall and Street. When entered in a web browser, the URL is converted to http://www.yahoo.com?thread=Wall%20Street
Copy and paste this converted URL into the URL base field.

Step 4 

(Optional) Enter any additional URL paths.

In the final URL, these values are separated from the base URL (and from each other) with a forward slash (/). The additional path value can be fixed text or an event attribute.

a. Select the Additional Path tab.

b. To enter a Value, select one of the following:

Fixed: enter the fixed text.

Event attribute: select an attribute from the drop-down menu.

Attributes include: Unique Event ID, Event Type/LogCode, Event Source, Device Type, Device Address, Location Site, Location Campus, Location Building, Location Floor, Location Area Name, Location Sub Area Name, Location Fully Qualified Name, Priority, Badge ID, User ID, Personnel ID, Person's Name (Last, First), Credential Watch Level, and Associated Camera ID.

c. Click Add. The additional path appears in the list.

d. Repeat these steps to create additional paths, if necessary.

e. Click Preview to view the complete URL.

Tip Always preview the URL before saving the URL action. Any dynamic elements in the URL are displayed in brackets (<>), and are replaced by the corresponding event used at run time.

For example, enter sample_action in the Fixed field. Click Add to add it to the list, and then Preview to view the URL: http://www.cosco.com/sample_action.

Next, select the Event attribute button and select Device Type from the drop-down menu. Click Preview to view the new URL: http://www.cosco.com/sample_action/<Device Type>

Step 5 

(Optional) Enter the parameters used to construct the URL.

URL parameters consist of a name and a value, and are separated from the URL with a question mark (?).

a. Select the Parameters tab.

b. Enter a Name for the parameter. The name is always fixed.

c. Select a Value option and enter one of the following. The value can be fixed or dynamic:

Fixed: enter the value text.

Event attribute: select an attribute from the drop-down menu. The parameter is captured from the specified event.

Attributes include: Unique Event ID, Event Type/LogCode, Event Source, Device Type, Device Address, Location Site, Location Campus, Location Building, Location Floor, Location Area Name, Location Sub Area Name, Location Fully Qualified Name, Priority, Badge ID, User ID, Personnel ID, Person's Name (Last, First), Credential Watch Level, and Associated Camera ID.

Complete event: Available for Post actions only. The entire event information is included as an xml segment in the data posted to the URL

d. Click Add. The parameter appears in the list.

e. Create additional parameters, if necessary. Parameters are separated in the URL with an ampersand (&).

f. Click Preview to view the complete URL.

In the following example, the Parameter entries are shown after the question mark, and are separated by an ampersand (&). http://www.cisco.com/sample_value/ <Device Type>?Fixed_Text=text_sample&Event_Attr=
<Device Address>

Step 6 

(Optional) Enter the username and password required to access the URL.

Note The username and password is used for servers requiring authentication. If authentication is unsuccessful, the server returns a response code: 401: Unauthorized. This code is placed in the data field of the event generated from executing the URL action.

Creating Automated Rules for URL Actions

Complete the following instructions to create a rule that automatically invokes a URL action based on a schedule or access control event. You can also create a rule that is manually triggered using a Quick Launch button or other method.

 
To do this

Step 1 

Select Global I/O from the Events & Alarms menu.

Step 2 

Click Add.

Step 3 

Enter a Name for the rule and select or deselect the Enabled checkbox.

Step 4 

Enter a trigger type for the rule.

Click New or Edit to define the Trigger Type. The choices are:

Event: The rule is invoked when an event occurs. Select Event and then click Edit Filter to select the event log code.

Periodic (time schedule): The rule is invoked according to a Monthly, Weekly, or Daily schedule. Select the day of week or day of month, if necessary, and the Time of day (in a 24-hour format).

Manual Only: The rule is invoked manually. Create a Quick Launch button for the rule or right-click the Automation Driver to select the rule.

Step 5 

Select a URL Action:

a. Click Add to add an action.

b. Select the Action type URL Action.

c. Select a URL Action from the drop-down menu.

d. (Optional) Click New or Edit to create or modify a URL action. Click Preview to view the URL for the action. See Configuring URL Actions for more information.

e. Click Save and Close.

Step 6 

Specify a Notification option to define where the notification or report file is sent. The options are:

E-mail: Sends the notification or report file to one or more e-mail addresses. To enable e-mail notifications, you must enter the SMTP server settings in the Automation driver. For instructions, see Enabling the Automation Driver.

FTP: Sends the file to the specified FTP server.

Host: The FTP server IP address or name.

Username: Log in username required by the FTP server.

Password: Password to log in to the FTP server.

Path: Path on the FTP server where files should be uploaded.

Syslog: Sends the notification or report to a Syslog.

Host: The Syslog server IP address or name.

Facility: The facility to use when recording the information to the Syslog.

Step 7 

Select the event options. These events occur when the rule is successfully invoked, or when rule options fail.

Click the check boxes to activate or deactivate the options:

Record event when rule invoked: Each time the rule is invoked, record an event.

Record event when trigger fails: Each time the trigger fails, record an event.

Record event when action fails: Each time the action fails, record an event

Record event when notification fails: Each time the notification fails, record an event.

Step 8 

Click Save and Close.

Viewing URL Events, Alarms, and Logs

An event is recorded each time a URL action is created or invoked. If a URL action fails, an alarm is recorded.

The URL Log in the Cisco PAM Server Administration utility also displays the output (HTTP response) from URL actions.

Examples of URL events, alarms, and log entries are shown in the following sections:

Viewing URL Action Events

Viewing Alarms for Failed URL Action

Event and Alarm Response Codes for URL Actions

Viewing Logs for URL Action Output

URL Action Failure Due to Invalid Security Certificate

Viewing URL Action Events

To view events, select Events from the Events & Alarms menu, under the Monitoring sub-menu.

Click the column titles to sort events by description, time, or other properties. Double-click the entry to view alarm details, or right-click an entry to select a command.

See Viewing Events for more information.

Figure 14-2 URL Action Events

Viewing Alarms for Failed URL Action

To view only failed URL actions, select Alarms from the Events & Alarms menu, under the Monitoring sub-menu. Use the Ack, Comment, and Clear buttons in the toolbar to clear the alarm or add comments. Double-click the entry to view alarm details, or right-click an entry and select a command.

See Viewing Alarms for more information.

Figure 14-3 URL Action Alarms

Event and Alarm Response Codes for URL Actions

The response code from the server is included in the data field. The response codes include the following:

Event Response Codes

HTTP Status Code 200:OK

HTTP Status Code 203:Non Authoritative

HTTP Status Code 204:No Content

HTTP Status Code 301:Moved Permanently

HTTP Status Code 302 or 307:Temporary Redirect

Alarm Response Codes

HTTP Status Code 400:Bad Request

HTTP Status Code 401:Unauthorized

HTTP Status Code 403:Forbidden

HTTP Status Code 404:Not Found

HTTP Status Code 405:Method Not Allowed

HTTP Status Code 406:Not Acceptable

HTTP Status Code HTTP Status Code 414:Request-URI Too Large

HTTP Status Code 500:Internal Server Error

HTTP Status Code 501:Not Implemented

HTTP Status Code 503:Service Unavailable

HTTP Status Code 505:HTTP Version Not Supported

Viewing Logs for URL Action Output

To display the output (HTTP response) from URL actions, open the URL Log in the Cisco PAM Server Administration utility.


Step 1 Log on to the Cisco PAM appliance as described in Logging on to the Cisco PAM Server Administration Utility.

Step 2 Select the Monitoring tab, and then select URL Log. Figure 14-4 shows the menu and sample log.

Figure 14-4 URL Action Log


URL Action Failure Due to Invalid Security Certificate

If a URL Action fails due to an invalid security certificate, the following log entry is displayed in the Cisco PAM Server Administration utility (see Viewing Logs for URL Action Output):

sun.security.validator.ValidatorException: PKIX path building failed: 
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid 
certification path to requested target.
 
   

To resolve this issue, do one of the following:

When the URL Action was invoked by clicking the Invoke button in the URL Action window, restart the Cisco PAM client and try again.

When the URL Action was invoked by an automated rule, stop and start the Cisco PAM server and try again. See Using the Web Admin Menus, Commands and Options for instructions to restart the server.

When the URL Action was invoked by a Quick Launch button, stop and start the Cisco PAM server and try again. See Using the Web Admin Menus, Commands and Options for instructions to restart the server.

Synchronizing Data Using Enterprise Data Integration (EDI)

EDI is used to synchronize data from Active Directory, Microsoft SQL Server, MySql and Oracle database to the Cisco PAM database. This section includes instructions to do the following:

Install the EDI license on the Cisco PAM server.

Download and install the Cisco EDI Studio desktop application on your PC.

Use the EDI Studio to define integration projects, including the database connection, schema, and synchronization schedule.

Import the data integration project file into Cisco PAM using the EDI Administration module.

Monitor and troubleshoot data integration events using the EDI Monitoring and Error Monitoring modules.

Complete the following instructions to create, run, and monitor EDI integration projects:

Before You Begin

Understanding Photo File Compression When Importing Personnel Records

Installing the EDI Licence and Desktop Application

Creating Active Directory Database Integration Projects Using EDI Studio

Creating SQL and Oracle Database Integration Projects Using EDI Studio

Importing, Starting, and Monitoring EDI Projects in Cisco PAM

Importing and Starting EDI Projects

Verifying EDI Projects (EDI Monitoring)

Modifying a Running EDI Project

Restarting a Failed EDI Project

Summary of EDI Administration Functions

Before You Begin

Review the following notes before creating EDI projects:

This feature requires an optional Cisco license. The EDI menu appears only after the license is installed on the Cisco PAM server. See Obtaining and Installing Optional Feature Licenses for instructions.

The source database records are the master version: imported records cannot be deleted in Cisco PAM.Test a few personnel records in a staging environment before implementing EDI projects.

Importing a large number of personnel records can cause system delays. To avoid system interruption, perform the initial import during off-peak hours, and stop the Gateway driver to allow the process to complete. To stop the driver, select Hardware from the Doors menu, right-click on the Access GW Driver, and select Disable. When the import is complete, select Enable.This process is only necessary when importing thousands of records, such as during the initial import of all database records.

Personnel records are unique based on the ID number of the record. If a record is imported with the same ID number, then the current record is overwritten with the new data.

EDI Active Directory (AD) projects run immediately when the camera driver is restarted, or when Cisco PAM is synchronized with the Cisco Video Surveillance Manager (Cisco VSM). The projects' scheduled run time are also reset.

For example, if an AD project is scheduled to run at 5 pm daily, and the camera driver is restarted at 10 am, the EDI project will run and the schedule will be reset to 10 am. To avoid this, stop the EDI project before restarting the camera driver or synchronizing the Cisco VSM server. Restart the EDI project after the actions are complete. For more information, see Summary of EDI Administration Functions and Managing the Camera Inventory.

Stop any running EDI projects before upgrading the Cisco PAM appliance software. After the upgrade, you can restart the projects. See Importing and Starting EDI Projects for instructions to stop, start and import EDI projects. If EDI projects are not stopped before a Cisco PAM upgrade, the project execution (or run) will not be successful. If this occurs, contact your Cisco support representative for assistance.


Note If upgrading from Release 1.0 or Release 1.1, you must also recreate the EDI projects using the EDI Studio application.


Only personnel photos in the .JPEG or .JPG format are supported for import. In addition, the photos must be in RGB format. Other image formats are ignored when importing personnel data.

Understanding Photo File Compression When Importing Personnel Records

Photo files that are imported into the Cisco PAM personnel database can be a maximum of 750 kb per image. If a photo is larger than the defined maximum, the file is automatically compressed by Cisco PAM.

You can define the maximum file size for imported photo files using the System Configuration module. For example, if you enter a maximum file size of 500 kb, then any files larger than 500 kb will be automatically compressed when the personnel record is imported.


Note Only personnel photos in the .jpg format are supported for import.


To set the maximum file size limit, do the following:


Step 1 Select System Configuration from the Admin menu.

Step 2 Select Cisco Settings on the left (Figure 14-5).

Step 3 In the field EDI personnel's photo size limit, enter the maximum file size for the imported file.

Enter a value, in kb, between 50 and 750.

The default value is 250 kb.


Note Any photo file larger than the specified size will be automatically compressed during the EDI import operation. A small loss of image quality may be noticeable in the compressed image.


Figure 14-5 Cisco Settings

Step 4 Click Save to save the changes.

Step 5 Log out and log back in to the Cisco PAM application to activate the changes (select Logout from the Options menu).


Installing the EDI Licence and Desktop Application

To enable EDI database integration, complete the following tasks:

1. Install the EDI license on the Cisco PAM server.

2. Start the EDI driver in the Cisco PAM Hardware module.

3. Install the Cisco EDI Studio desktop software on your PC.


Step 1 Install the EDI license on the Cisco PAM server. Figure 14-6 Shows the EDI license installed on a Cisco PAM server. See Using the Web Admin Menus, Commands and Options for information to view the installed licenses or purchase and install new licenses.

Figure 14-6 Cisco PAM Licenses

Step 2 Create and start the EDI driver, if necessary.

a. Select Hardware from the Doors menu.

b. If the EDI Driver is included in the driver list, continue to Step 3.

c. If the EDI Driver is not included, right-click the Driver Manager and select New EDI Driver.

d. Right-click the EDI Driver and select Start. The driver status should be Started (see Figure 14-7).

Figure 14-7 EDI Driver

Step 3 Download and install the EDI Studio desktop software.

a. Open a Web browser and enter the IP address for the Cisco PAM Server Administration utility.

b. Click Download Cisco EDI Studio on the Login page, as shown in Figure 14-8. You do not need to log on to the utility to download the software. The required version of Java is also installed, if necessary.

Figure 14-8 Download EDI Studio


Tip You can also log in to the Cisco PAM Server Administration utility and select Cisco EDI Studio (JRE Required) from the Downloads menu. See Using the Web Admin Menus, Commands and Options.


c. Save the installation file to your local drive.

d. Double-click the EDI Studio installer file on your local drive to download and launch the installer.

e. Follow the on-screen prompts to install the EDI Studio desktop application. The application opens automatically when the installation is complete.

f. Select Cisco EDI Studio from the shortcut on your desktop or from your Windows Programs menu.


Creating Active Directory Database Integration Projects Using EDI Studio

The EDI desktop application is used to define data integration projects. Once created, the project is imported into the Cisco PAM to begin data synchronization.

This section provides an example to import personnel records from an Active Directory database into the Cisco PAM database. This example does not cover every possible scenario, and the specific records, fields and other data may not match the details for your site. Contact your Active Directory administrator for assistance when performing this process.

Review the following notes before creating and running an Active Directory project:

Cisco PAM supports a single Active Directory project in EDI. You can create multiple AD projects, but only one can run.

The Cisco EDI feature is tested and certified for Active Directory Server 2003.

A user ID and password is required to access user objects from Active Directory schema.

EDI supports photos in the JPEG format (the default is a maximum of 100kb per file).

Users should not make major modifications to the Active Directory schema.

The User Object supports timestamp by default.

If changed timestamp is disabled in Active Directory, EDI project can not run.

Complete the following instructions to create a project for a Microsoft Active Directory database.

 
To do this

Step 1 

Select Cisco EDI Studio on your Windows PC. The Cisco Enterprise Data Integration window opens.

Step 2 

Create a new Workspace.

a. Select New Workspace from the File menu. You can also right-click Root and select New Workspace.

b. Enter the Workspace name and click OK. The new Workspace is created along with a Projects folder.

Tip Root and Workspace help organize your projects. They do not serve any other purpose.

Step 3 

Create a new EDI project.

Highlight the Projects folder and select New from the Project menu.

You can also right-click a Projects folder and select New.

Step 4 

Name the project and enter the project properties:

a. Project name: enter the name of the project.

b. Project template: select a template for Microsoft Active Directory.

c. Source DB: select the source database.

d. Destination DB: select the destination database.

e. Click Next.

Step 5 

Enter the Active Directory database parameters:

a. Host name: enter the IP address of the database server.

Note The Active Directory Hostname must be accessible from the Cisco PAM appliance network. For example, both systems should be on the same network.

b. Port: enter the TCP port for the database server. Port 389 is the default for LDAP.

c. Search base: the Distinguished Name (DN) to use as a base for queries. For example: dc=foobar.

Note Cisco PAM is configured to send the cn= parameter, which must exactly match the cn parameter in Active Directory for the account.

d. Login Name (Full DN): the username required to log in to the database.

e. Password: the database password.

Note The fields Search base, Login name, and Password are provided by your Active Directory administrator.

Step 6 

Click Next or Test Connection to validate the server settings.

If the settings are valid, Test connection successful appears.

If the settings are not valid, Test connection failed appears. One or more of the parameters is incorrect. Work with your Active Directory administrator to obtain the correct settings and test the connection again.

Tip To verify the Active Directory user account attribute for the Cisco PAM login, use the tools described in the following step. Cisco PAM is configured to send the cn= parameter, which must exactly match the cn parameter in Active Directory for the account.

Step 7 

Map the equivalent fields between the Destination Cisco PAM database and the Source AD attributes.

a. Enter the field name, or select an option from the drop-down menu.

Required destination fields are marked with an asterisk (*). The other fields are optional.

You must enter values for the site and govt_id_spec, either in this window, or in the following database properties window. If you enter values in the current window, the individual record data is used (and the default value is ignored). To use default values, leave the fields blank in this window and enter them in the following window (Default/Transform Values).

Map emp_status to the appropriate AD attribute. For example, active or inactive. Consult your Active directory Admin for more info on this attribute.

See also Notes for Mapping the AD and Cisco PAM User Attribute Names.

b. Click Next to verify the settings and continue to the next configuration screen.

Clicking next verifies the settings. If the test is not successful, verify that the prefix cn= is used for the login name in the Active Directory Source Parameters window, as described in .

Tip If the test is not successful, verify that the prefix cn= is used for the login name in the Active Directory Source Parameters window (see ).
 

Notes for Mapping the AD and Cisco PAM User Attribute Names

In the AD structure, a user's name includes an attribute sn for the last name, and another attribute givenName for the first name. For example: of Mike Smith would include:

sn=Smith

givenName=Mike

When you create an AD user log in for the Cisco PAM server, you must also configure a first and last name, or the database mapping will fail.

Two tools can help you determine the Active Directory attribute name that corresponds to a Cisco PAM record. The first is called LDAP Browser/Editor. Although Cisco does not provide this tool and does not document the tool usage, the sample output to the right shows the information you need to obtain for use with the EDI project. In this sample, the cpam user allows the Cisco PAM server to log in to the AD database. The sn attribute defines the lastname, and the givenName attribute defines the first name.

In addition, the Active Directory attribute department is defined. This attribute is mapped to the Cisco PAM field govt_id.

 

You can also extract user data to a CSV (comma separated value) file to view the Active Directory attributes.

For example the following command generates a CVS file with user data.

CSVDE -f onlyusers.csv -r "(&(objectClass=user)(objectCategory=person))"
 
        

This command runs the CSCDE (comma separated value data export) tool and creates a file named onlyusers.csv. Filters are used to limit the output to users and persons.

Tip Your system administrator may have additional knowledge of the CSVDE tool and output limiting filters.

Open the onlyusers.csv file in Excel to view the Active Directory attributes and the fields they map to, as shown in the Excel screen to the right. This screen shows how the fields correspond to the Cisco PAM personnel records fields.

The Cisco PAM Active Directory Personnel Data window is shown with the correct field mappings. Click Next to validate the attribute mappings.

Step 8 

Define the Active Directory default database values.

For example, enter the following in the in the Source Attribute Value column:

a. Enter a site. The site must match the Cisco PAM site name. The site name is shown in the bottom right corner of all Cisco PAM client windows. The site name is also displayed at the top of the Hardware tree.

b. Enter the govt_id_spec value.

Note The entries are ignored if values are also entered in the previous Personnel Data window. You must enter values for these fields in one of the windows.

c. Enter the AD attribute used by your organization for each of the emp_status fields. For example, enter I for emp_status (inactive) or R for emp_status (retired) employees. CPAM supports status for active, inactive, on leave, retired, and terminated.

Tip If your organization has additional employee status codes, such as 544 to indicate that a user is active, but their password is expired, you can manually add those codes to the bottom of the list (as shown in the screen to the right). In the CPAM Attribute Value column, manually enter an existing CPAM value, such as emp_status (active). In the Source Attribute Value column, enter your organization's code. You can also create new employee status attributes, if necessary. See the "Creating Custom Employee Status Values" section.

d. Click Next to continue.

Step 9 

(Optional) Select an EDI Extension file, if necessary.

EDI Extension files use API classes used to extend EDI functionality, including the following:

Transform badge and personnel data received from an AD database. For example, remove the leading 1 from the Badge ID.

Define default mapping. For example, assign Badge Templates based on the badge type.

Provide cross field validation (such as dependency fields, correlation across different attributes or between badge and personnel data).

Extensions are built using a Cisco Systems framework and validated by the EDI Studio. Cisco also provides developer support.

Procedure

a. Click Browse.

b. Select the extension file that will be called when writing data into the personnel and badge interface tables. The extension file is validated by the EDI Studio.

c. Click Next to continue.

Step 10 

Choose a schedule to specify how often data will be synchronized.

every hh:mm: the data synchronization begins once every hour/minute specified.

every day: the data synchronization is conducted once a day.

every week: the data synchronization is conducted once a week.

Scheduling Notes

Schedules are based on the Cisco PAM appliance time and time zone settings (not the AD source database server settings).

The default project schedule is 60 minutes. This setting is configurable.

The EDI (Core) frequency is two minutes. This setting is read-only.

Cisco PAM retrieves records with a 15 minute overlap from the previous run to prevent loss of data; all records will be included even if the Cisco PAM and Active Directory server time settings are a few minutes apart.

Step 11 

Click Finish to create the new database project and return to the main window.

The project is shown in the main window. A .jar file is saved to the following directory on your PC:

C:\Program Files\Cisco Systems\EDI Studio\workspaces\<Project_Folder>\projects\

Tip An error message appears if any fields are incorrect or missing. Use the Back button to navigate to the screen and correct the entry. When you are done, click Finish from the window the correction was made. You do not need to return to the last window. The entries in all windows are preserved.

Step 12 

(Optional) To change the data import rules or settings, select the project from the left window, and click Edit at the bottom of the detail window. Edit the settings as necessary and click Save.

Tip To change the name of a project, highlight the project and select Rename from the Edit menu. To delete a project, highlight the project and select Delete from the Edit menu.

Step 13 

Import the project in Cisco PAM and start the project to begin importing records.

See Importing, Starting, and Monitoring EDI Projects in Cisco PAM

Creating Custom Employee Status Values

The employee status (emp_status) attribute defines if a user is active or inactive. The fields supported by default are:

emp_status (active)—the user account is active.

emp_status (inactive)—the user account is inactive.

emp_status (on leave)—the user account is inactive.

emp_status (retired)—the user account is inactive.

emp_status (terminated)—the user account is inactive.

If necessary, you can create additional employee status values. Each identifies the user account as either active or inactive. For example, an organization uses the value of 512 for Active and 514 for Inactive, but they also use an additional value 544 for an active user with an expired password. You can create this new active user status in cpam, and then enter the definition in EDI.

Procedure


Step 1 Enable the Employee Statuses module (disabled by default).

a. Select Profiles from the Users menu.

b. Double-click the user profile for the user who administers EDI projects.

For example, select Administrators.

You can also select the profile name and click Edit.

c. In the Edit - Profile window, select the Modules tab (Figure 14-9).

d. Expand the Advanced category.

e. Select Employee Statuses to highlight it.

f. Select the Allow access to module check box.

g. Click Save and Close.

Figure 14-9 Modules Available to a User Profile

Step 2 To display the new menu, logout of Cisco PAM and log back in.

a. Choose Logout from the Options menu.

b. Enter a username and password for a user assigned to the profile you just modified.

c. Select Login.

Step 3 Select Employee Statuses from the Admin menu (Figure 14-10).

Figure 14-10 Employee Statuses Window

Step 4 Create a new employee status entry.

a. Click Add.

b. Enter the name of the new entry (Figure 14-11).

c. Select Active if user accounts with this status should be active. Deselect Active if the user accounts should be inactive.

d. Click Save and Close.

Figure 14-11 Employee Statuses Window

e. Verify that the new status appears and that the Active setting is true or false (Figure 14-10).


Creating SQL and Oracle Database Integration Projects Using EDI Studio

Data projects define the source database connection and schedule information for an integration task. Once created, the project can be imported into the Cisco PAM EDI module to begin data synchronization.

This section provides an example to import personnel records into Cisco PAM from one of the following databases:

MySQL version 5.0.4

Oracle versions 10g and 11g

SqlServer 2005 and SqlServer 2000

This example does not cover every possible scenario, and the specific records, fields and other data may not match the details for your site. Contact your database administrator for assistance when performing this process.

Because SQL and Oracle projects are created for organization, personnel, and credential data, you must create separate projects for each data type, and run the projects separately. Each project must be monitored to ensure the data integration is complete and successful before the next project is started.


Step 1 Select Cisco EDI Studio on your Windows PC. The Cisco Enterprise Data Integration window opens, as shown in Figure 14-12.

Figure 14-12 EDI Studio: Cisco Enterprise Data Integration Window

Step 2 Create a new Workspace.

Figure 14-13 EDI Studio: New Workspace

a. Right-click Root and select New Workspace (or highlight Root and select New Workspace from the File menu).

b. Enter the Workspace name and click OK. The new Workspace is created along with a Projects folder.


Tip Root and Workspace help organize your projects. They do not serve any other purpose.


Step 3 To create a new EDI project, right-click a Projects folder and select New (or highlight the folder and select New from the Project menu). The Choose Project Template window opens.

Figure 14-14 EDI Studio: New Project

Step 4 Select a Project Template, as shown in Figure 14-15.

Figure 14-15 EDI Studio: Choose Project Template

a. Project name: enter a name for the project.

b. Project template: select a template that defines the data type (such as SQL credential data)

c. Source DB: select the database source (such as Oracle or MySQL).

d. Destination DB: select the destination database (SQL or MySQL).


Note Oracle databases do not support boolean data types. You must define numeric data types and use them as boolean.


e. Click Next.

Step 5 Enter the source parameters, as shown in Figure 14-16.

Figure 14-16 EDI Studio: Enter Parameters for the Source Database

a. Enter the Database name.

b. Enter the User name required to log in to the database.

c. Enter the Password for the database password.

d. Enter the Server IP address of the database server.

e. Enter the TCP Port for the database server. Use a number between 1000 and 65536.

f. Click Next or Test Connection to validate the server settings.

If the settings are valid, Test connection successful appears.

If the settings are not valid, Test connection failed appears. One or more of the parameters is incorrect. Work with your system administrator to obtain the correct settings and test the connection again.

Step 6 Map the database fields for the Destination [Cisco PAM] database with the database fields for the Source database.

a. Enter the Source table name of the source database.

b. Enter a Source field for all required Destination [Cisco PAM] fields (marked with an asterisk*). The Destination fields are different for the type of data, as described in Table 14-1.

Table 14-1 shows the required fields for each data type:

Table 14-1 Required Fields for Data Mapping

Data Type
Required Fields

Organization

Organization Data

name: (primary key) Name of the organization.

Department Data

name: (primary key) Name of the department.

orgName: (primary key) Organization name

Personnel

site: Site of the personnel record.

firs_name: User's first name.

last_name: User's last name

govt_id: (primary key) Government ID number. If the govt_id is a social security number, the length must be exactly nine digits. The valid values are: I, II, III, Jr., and Sr.

govt_id_spec: a unique id that can identify a personnel record. Valid values are SSN, FIN, and ID#.

emp_status: Employment status. The valid values are: active, inactive, on_leave, retired, and terminated. If your organization has additional employee status codes, such as Active Password Expired, you can manually add those codes to the bottom of the list: enter the CPAM Value in the left column (it must be one of the 5 supported emp_status attributes, as shown), and then enter your organization's code in the right column.

The emp_type is not required, but has the following valid values: contractor, employee, employee_full_time, employee_part_time, intern, other, vendor, and visitor. emp_type is a type of employee.

Note The Region and Nationality fields be values already defined in system.

Credential (Badge Records)

Note The primary keys are badgeId and facilityCode.

badgeId: (primary key) The badge ID.

credTemplateId: Use this field to assign the parameters from a badge template in Cisco PAM to imported badges. This option is used when importing badges into Cisco PAM for the first time.

For example, create or edit a badge template in Cisco PAM as described in Configuring Badge Templates. This template can contain settings for fields such as access policy, facility code, badge type, watch level, and effective date. Enter the name of the badge template in the Source Attribute Value column for credTemplateId. For example: KeyPad_BCD4, 26BitWiegandCT, 26BitWiegandKeyPadCT, etc.

facilityCode: (primary key) The facility code

activationDate: Activation date for the badge.

expirationDate: Date the badge expires. This date must be greater than the activation date.

validity: The valid values are: active, inactive, destroyed, lost, and stolen.

role: The user's role in the organization. The valid values are: employee, contractor, vendor, and temporary.


c. Source: Enter the corresponding field name for the source database. Enter a name for all required Destination fields, and any additional fields, if necessary.

d. Click Next.

e. Organization data only: Enter the additional Department Data settings and click Next again.

Step 7 Define the default database values and click Next to continue.

Step 8 (Optional) Select an EDI Extension file, if necessary (Figure 14-17).

Figure 14-17 EDI Studio: EDI Extension

Step 9 Choose a schedule to specify how often data will be synchronized, as shown in Figure 14-18.


Note EDI actions are conducted according to the Cisco PAM appliance time and time zone settings (not the source database server settings).


every hh:mm: the data synchronization begins once every hour/minute specified.

every day: the data synchronization is conducted once a day.

every week: the data synchronization is conducted once a week.

Figure 14-18 EDI Studio: Choose Schedule

Step 10 Click Finish to create the new database project and return to the Cisco Data Enterprise application window (Figure 14-12).

The project is shown in the main window and the project file is saved to the default EDI project directory on your PC:

C:\Program Files\Cisco Systems\EDI Studio\workspaces\Project_Folder\projects\.


Tip An error message appears if any fields are incorrect or missing. Use the Back button to navigate to the screen and correct the entry. When you are done, click Finish from the window the correction was made. You do not need to return to the last window. The entries in all windows are preserved.


Step 11 Import and start the EDI project in Cisco PAM.

See Importing, Starting, and Monitoring EDI Projects in Cisco PAM.


Importing, Starting, and Monitoring EDI Projects in Cisco PAM

This section includes the following information:

Importing and Starting EDI Projects

Verifying EDI Projects (EDI Monitoring)

Modifying a Running EDI Project

Restarting a Failed EDI Project

Summary of EDI Administration Functions

Importing and Starting EDI Projects

After the EDI projects are created, you must import the .jar project files into the Cisco PAM using the EDI Administration module.

 
To do this

Step 1 

Select EDI Administration from the Admin menu.

Step 2 

Click Upload and select a project created using the EDI Desktop Studio.

The project .jar files are saved in the default EDI project directory on your PC:

C:\Program Files\Cisco Systems\EDI Studio\workspaces\<project_folder_name>\projects\

Step 3 

Once the file is uploaded, click Start.

Step 4 

Select the start time:

Select Start Now (default) to run the project immediately.

Select Start Later to select a date and time to start the EDI project. The project will run at this time, and then at any scheduled time defined in the project file.

(Optional) You can also select a Data sync start time to perform the data synchronization from a particular date and time entered. Click the Data sync start time field to open a pop-up calendar. Double-click the date when the data sync should begin. The date and current time will be entered in the field. Edit the date and/or time if necessary.

Note Active Directory EDI projects restart when the Cisco PAM appliance is stopped and restarted. All other projects will run on their normally scheduled time. If you do not want Active Directory projects to run after a server restart, stop the project(s) before restarting the server.

Step 5 

Verify that the project is started.

Verifying EDI Projects (EDI Monitoring)

Use the following information to verify that the record import is working.


Step 1 Select EDI Monitoring from the Admin menu to open the EDI Monitoring module (Figure 14-19).

Figure 14-19 EDI Monitoring Menu

The following information is displayed for each record

Column
Description

ID

The EDI event ID number.

Project Name

The name of the EDI project that the event as defined in the EDI Desktop Studio.

Project Type

The type of data, such as personnel, badge, or organization records.

Records Succeeded

The number of records successfully updated during the integration event.

Failed Records

The number of records that were not updated by the integration event. Failed record details are stored in the log files.

Extract Type

The type of data extraction including interface or core (see the following step).

Start Time

The date and time when the data integration event began.

End Time

The date and time when the data integration event ended.


Step 2 Review the EDI projects on the EDI monitoring screen. There are two types of Extract Types (see Figure 14-20):

Interface: this occurs when the Cisco PAM server connects to the remote data source and retrieves the records that have been added or modified since the last time the Interface extract was executed.

Core: this occurs when the Cisco PAM server validates the records retrieved by the Interface process, and then edits the Cisco PAM personnel database to make the additions, deletions, or edits.

Figure 14-20 EDI Monitoring Window

If the Interface entry shows success, but the Core does not, something in the extracted record is not compatible with the mapping between the Active Directory and Cisco PAM databases. For example, Figure 14-20 shows the following:

ID 331 shows that the project imported 16 records from Active Directory.

ID 341 shows that when we tried to update the Cisco PAM personnel records with the records extracted in 331, but something was wrong with the records, so all 16 failed.

In ID 351 shows again that 16 records were extracted from the Active Directory.

ID 361 shows that 3 of the 16 records were successfully added to the Cisco PAM personnel database.

Step 3 To troubleshoot the errors and view additional error details, select Error Monitoring from the Admin menu (Figure 14-21).

Figure 14-21 EDI Error Monitoring Menu

Step 4 The Error Monitoring window displays entries for each failed record, as shown in Figure 14-22. The Messages column includes text regarding the cause. For example: "Site is null" messages occur if the site name is not entered on the Default/Transform values screen of the EDI Studio project.

Figure 14-22 EDI Error Monitoring

In addition, the following can occur:

Record updates in AD include a timestamp for the edit. When the Cisco PAM server connects, it compares the timestamp of the last edit in AD with what the last edit is that Cisco PAM knows about. If the AD timestamp is newer, the record is extracted.

Once the record is extracted from AD into Cisco PAM, the fields are checked for validity during the Core extract. For example if the AD last name (attribute sn) contains a number, Cisco PAM should fail to import that record into the personnel database because a valid last name cannot contain a number.

Step 5 Once the cause of the error is determined, modify the project. See Modifying a Running EDI Project. If an EDI data integration project fails, identify and resolve the problem, and then complete the instructions in Restarting a Failed EDI Project.


Modifying a Running EDI Project

To modify an EDI project that is running, do the following:


Step 1 Stop the project:

a. Select EDI Administration from the Admin menu.

b. Select the project and click Stop.

Step 2 Click Export to save the .jar project file. Save the file in the in the default EDI project directory on your PC:

C:\Program Files\Cisco Systems\EDI Studio\workspaces\Project_Folder\projects\.

Step 3 Edit the project in EDI Studio:

a. Open the EDI Studio application on your PC.

b. Select the project from the left window, and click Edit at the bottom of the detail window.

c. Edit the settings as necessary and click Save.

Figure 14-23 Editing EDI Projects

Step 4 Upload the modified project to Cisco PAM:

a. Select EDI Administration from the Admin menu.

b. Click Upload and select the .jar file that was saved in the default EDI project directory on your PC:

C:\Program Files\Cisco Systems\EDI Studio\workspaces\<Project_Folder>\projects\.

Note Files can be saved to and uploaded from other locations.

Step 5 Select the project, click Start, and select the start time (Figure 14-24):

Figure 14-24 EDI Project Start Time

Select Start Now (default) to run the project immediately.

Select Start Later to select a date and time to start the EDI project. The project will run at this time, and then at any scheduled time defined in the project file.

(Optional) You can also select a Data sync start time to perform the data synchronization from a particular date and time entered. Click the Data sync start time field to open a pop-up calendar. Double-click the date when the data sync should begin. The date and current time will be entered in the field. Edit the date and/or time if necessary.


Restarting a Failed EDI Project

If an EDI data integration project fails, identify and resolve the problem before restarting the project.

Resolving Active Directory Issues

If an error in the Active Directory record occurs, update the AD record. The EDI project will run according to the defined schedule. To force the project to run immediately, stop and then start the project. See Summary of EDI Administration Functions.

Resolving Cisco PAM or EDI Studio Issues

If an error occurs in the Cisco PAM database, do the following.


Step 1 Correct the issue. For example:

No organization values exist in the Cisco PAM records.
When organization and department values are included in an imported personnel record, those values must already exist in the Cisco PAM configuration. Before creating the EDI project, add the Organization values by manually creating them or through a data import. See Editing Organization and Department Lists for more information.

The project mapping is incorrect. See Modifying a Running EDI Project to correct mapping issues.

Step 2 Delete the project in the EDI Administration.

a. Select EDI Administration from the Admin menu.

b. Select the project and click Delete.

Step 3 Re-import and start the project. See Importing and Starting EDI Projects.


Summary of EDI Administration Functions

Column Descriptions

EDI Administration Functions

Column Descriptions

Column
Description

Name

The data integration project name, as defined in the EDI Desktop Studio.

Type

The type of data, such as personnel, badge, or organization records.

Recent Start Time

The most recent time that data integration began for the project.

Status

Specifies if the project is running, stopped, or scheduled.

Last Run Date

The date of project was last executed (successful and unsuccessful attempts).

Run Count

The number of times the project has been run (successful and unsuccessful attempts).

Success Run Count

The number of times the project has been successfully run.


The EDI Administration window includes the following columns:

EDI Administration Functions

The following functions are available from the menu at the top of the project list:

Function
Description

Refresh

Refresh the window to display current information.

Upload

Upload a new or modified project from the EDI Desktop Studio. The project .jar files are saved in the default EDI project directory on your PC:

C:\Program Files\Cisco Systems\EDI Studio\workspaces\Project_Folder\projects\

Export

Exports the project in the .jar file format.

Start

Runs a data integration project now, or at a specified time.

Tip To create a recurring schedule for EDI projects, use EDI studio.

Note Active Directory EDI projects restart when the Cisco PAM appliance is stopped and restarted. All other projects will run on their normally scheduled time. If you do not want Active Directory projects to run after a server restart, stop the project(s) before restarting the server.

Stop

Disables the project and stops data integration from running. A project cannot be stopped if currently running an integration. To update a project, you must first stop the project, modify it in EDI Studio, and then upload the revised .jar file. See c.

Delete

Removes the data integration project from Cisco PAM. The project remains in the EDI Desktop Studio.


Accessing the SQL Database

The CPAM SQL database can be accessed by 3rd party Time and Attendance (T&A) systems to view personnel, time and attendance, and user tracking data.

The database views are not visible by default. Use the MySQL Query browser to display the database views.


Caution Do not modify the SQL tables. Use the following instructions to browse the tables only. Changing the tables or data can result in CPAM errors or system failures.

To view the CPAM SQL database, complete the following procedure:


Step 1 Contact Cisco technical support to obtain the database username, password, host and schema, if necessary.

Step 2 Install and launch the MySQL Query Browser, and enter the server and login information supplied by Cisco technical support.

Step 3 In the Schemata pane (right column), expand the vxdb entry and scroll down to the bottom of the list to display the entries for personnel_vw, time_attendance_vw, and user_tracking_vw (Figure 14-25).

Figure 14-25 MySQL Query Browser

Step 4 To view the database entries:

a. Double-click on the table name to enter a query in the Query field.

b. Click the Execute button

The data is shown in the browsing area.


See the following for examples of the SQL data views:

Personnel

Time and Attendance

User Tracking Data

Personnel

The Personnel view (Figure 14-26) provides personnel information such as first name, last name, user id, personnel id, photo image, and the image type.

Figure 14-26 Personnel

Time and Attendance

The Time and Attendance view (Figure 14-27) provides information on user entry and exit through he Cisco Access Control Gateways. The information in this view includes first name, last name, personnel id, user id, door name, door location, reader name, entry or exit reader type, and the entry/exit time for the user.

You can optionally select all or partial data based on first name, last name, reader name, or a combination of these fields.

Figure 14-27 Time and Attendance

User Tracking Data

The User Tracking view (Figure 14-28) provides information regarding a user's most recent use of the access control system, including the first name, last name, personnel id, user id, door name, door location, reader name, entry or exit reader type, and the door entry time.

You can optionally select all or partial data based on first name, last name, personnel id, or a combination of these fields.

Figure 14-28 User Tracking