Cisco Physical Access Manager Appliance User Guide, Release 1.1.0
System Integration
Downloads: This chapterpdf (PDF - 4.94MB) The complete bookPDF (PDF - 36.19MB) | 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)

Synchronizing Data Using Enterprise Data Integration (EDI)

Before You Begin

Installing the EDI Licence and Desktop Application

Creating Active Directory Database Integration Projects Using EDI Studio

Importing, Starting, and Monitoring EDI Projects in Cisco PAM

Importing and Starting EDI Projects

Verifying an EDI Project is Importing Records Correctly

Modifying a Running EDI Project

Restarting a Failed EDI Project

Summary of EDI Administration Functions

Creating SQL and Oracle Database Integration Projects Using EDI Studio

Accessing the SQL Database

Personnel

Time and Attendance

User Tracking


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

Installing the EDI Licence and Desktop Application

Creating Active Directory Database Integration Projects Using EDI Studio

Importing, Starting, and Monitoring EDI Projects in Cisco PAM

Creating SQL and Oracle Database Integration Projects Using EDI Studio

Accessing the SQL Database

Configuring URL Actions

URL actions provide access control integration with Cisco and third-party products. For example, URL actions can trigger the following in other systems:

Energywise Integration: 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
Use this display

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 the present a client certificate, and accept all secure certificates.

e. Enter the URL base. 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. URLs 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
Use this display

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 matching the defined filter occurs. Select Event and then click Edit Filter to define the filter.

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, page 13-12.

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, page 12-3 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, page 12-7 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, page 4-2.

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 Performing Additional Configuration, Administration, and Monitoring Tasks, page 4-11 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 Performing Additional Configuration, Administration, and Monitoring Tasks, page 4-11 for instructions to restart the server.

Synchronizing Data Using Enterprise Data Integration (EDI)

Synchronizing Data Using Enterprise Data Integration (EDI)

EDI is used to automatically synchronize records from an Active Directory personnel 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

Installing the EDI Licence and Desktop Application

Creating Active Directory Database Integration Projects Using EDI Studio

Importing, Starting, and Monitoring EDI Projects in Cisco PAM

Importing and Starting EDI Projects

Verifying an EDI Project is Importing Records Correctly

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, page 2-21 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.

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, page 8-13 for more information.

All EDI projects run when the Cisco PAM appliance is stopped and restarted. If you do not want the projects to run after a server restart, stop the projects before restarting the server. See Importing and Starting EDI Projects.

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, page 13-16.

Stop any running EDI projects before upgrading the Cisco PAM appliance software. After the upgrade, re-import the project to EDI Administration and start it again. 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.

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-5 Shows the EDI license installed on a Cisco PAM server. See Obtaining and Installing Optional Feature Licenses, page 2-21 for information to view the installed licenses or purchase and install new licenses.

Figure 14-5 Cisco PAM Licenses

Step 2 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-6).

Figure 14-6 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-7. 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-7 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 Performing Additional Configuration, Administration, and Monitoring Tasks, page 2-12.


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 release 1.1 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 (default 100kb).

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

The User Object supports timestamp by default.

Manually remove the attribute to disable it.

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

 
To do this
Use this display

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.

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

c. Base name: 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: the username required to log in to the database.

e. Password: the database password.

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

Step 6 

Click 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 database.

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

Click Test attributes to verify the settings.

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 ).

Note 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).

 

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's 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=pers
on))"

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. Use the Test attributes button to validate the attribute mappings.

When the mappings are successful, click Next to continue.

Step 8 

Define the default database values.

The site field 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 on the Hardware tree.

Note Enter values for the site and govt_id_spec fields to use default values. 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.

Click Next to continue.

Step 9 

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 10 

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 11 

To run the project, continue to Importing, Starting, and Monitoring EDI Projects in Cisco PAM

Step 12 

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.

For field descriptions, refer to Creating Active Directory Database Integration Projects Using EDI Studio.

After the modifications are complete, continue to Importing and Starting EDI Projects.

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.

Importing, Starting, and Monitoring EDI Projects in Cisco PAM

This section includes the following information:

Importing and Starting EDI Projects

Verifying an EDI Project is Importing Records Correctly

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
Use this display

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\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.

Note All EDI projects run when the Cisco PAM appliance is stopped and restarted. If you do not want the projects to run after a server restart, stop the project(s) before restarting the server.

Step 5 

Verify that the project is started.

Verifying an EDI Project is Importing Records Correctly

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-8).

Figure 14-8 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-9):

Interface: this occurs when the Cisco PAM server connects to the Active Directory server 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-9 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-9 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-10).

Figure 14-10 EDI Error Monitoring Menu

Step 4 The Error Monitoring window displays entries for each failed record, as shown in Figure 14-11. 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-11 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-12 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-13):

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.

Figure 14-13 Select the Project Start Time


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, page 8-13 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 All EDI projects also run when the Cisco PAM appliance is stopped and restarted. If you do not want the 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.


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.

The supported databases are:

MySQL version 5.0.4

Oracle 10g and 9.X versions.

SqlServer 2005 and SqlServer 2000


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

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

Step 2 Create a 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.

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

Figure 14-15 EDI Studio: Choose the Project Template

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

b. Project template: Select a template that defines the data type (such as personnel data), and the database source (such as Oracle or MySQL).


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


c. 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. Database name: name of the database.

b. User name: The username required to log in to the database.

c. Password: The database password.

d. Server IP: The IP address of the database server.

e. Port: the TCP port for the database server. Use a number 1000-65536.

Step 6 Map the database fields for the Destination [Cisco PAM] database with the database fields for the Source database, using the Enter Data window. Figure 14-17 is an example of a window for a Personnel project. The Destination fields are different for the type of data, as described in the following sub-steps.

Figure 14-17 EDI Studio: Example to Map Data Fields

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

b. Source updated timestamp: This field is populated by the remote application or database and can be left blank.

c. Source created timestamp: This field is populated by the remote application or database and can be left blank.

d. Destination [Cisco PAM]: Displays the data fields for the Cisco PAM database. Enter a Source field for all required Destinations fields (marked with an asterisk*).

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.

Note 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: Badge template. The values must already be defined in the system. for example: KeyPad_BCD4, 26BitWiegandCT, and 26BitWiegandKeyPadCT.

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.


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

f. Click Next.

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

Step 7 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 8 Click Finish to create the new database project and return to the Cisco Data Enterprise application window (Figure 14-14).

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.



Accessing the SQL Database

Use the command line to access the SQL database for personnel, time and attendance and user tracking data. Run the following file located on the Cisco PAM server:

/opt/cisco/cpam/import/MySQL_Views.sql

The username and password are:

username: cpamuser1

password: *******

Use the MySQL Query browser to view the following tables:

Personnel

Time and Attendance

User Tracking

Personnel

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

Figure 14-19 Personnel

Time and Attendance

The Time and Attendance view (Figure 14-20) 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-20 Time and Attendance

User Tracking

The User Tracking view (Figure 14-21) 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-21 User Tracking