Introduction

Of all of the drivers for Identity Manager, I have found the PeopleSoft driver to be the hardest to understand and implement. Not because of the policies or rules it contains, but because this driver is, unlike the others, only really a demonstration of what you can do, not a canned solution to do it with.

In order to successfully implement the PeopleSoft driver, you will need a good understanding of Identity Manager, but you will also need a cooperative PeopleSoft Component Interface (CI) developer, and Human Resources contact people that can describe their business processes and how things work in your HR system. This will likely take longer than you expect, even if everybody involves tells you that they know exactly how everything works, as you will find things that they forgot to tell you about, or didn't think mattered, or didn't even know themselves.

On the Identity Management side of things, you will also have to know or decide what you want to do about the various HR events that will be coming down the Publisher channel, and what data you will need. This all has to be communicated with your CI developer.

Why bring all of this up? Because in the description that follows, please keep in mind that these are sample policies. Think of them as being for a sample company. One that is not your company. They are intended to show you what is possible, but unless the needs of your actual company match the sample, you will be doing quite a bit of customizing before you're done.

So, with that caveat, let's get started...

Publisher Channel

Input Transform

Policy Set: pub-itp-AddAssociation

Rule: Add the Association to "operation-data/peoplesoft-src-id" Property

Purpose: If the association value (usually the PeopleSoft EMPLID) is available, this rule adds an <operation-data> element to the document, and squirrels away the association value as "peoplesoft-src-id". This is eventually used to process the Status document on the Output Transform (sub-otp-WritebackCNandDNaftersuccessfulPublisherChannelAdd).

Rule: Transform PeopleSoft 'Manager' value from 'Y' to boolean 'true'

Purpose: This is a simple reformat from 'Y' to 'true' of the 'Manager' value if it is present in the document.

Rule: Transform PeopleSoft 'Manager' value from 'N' to boolean 'false'

Purpose: This is a simple reformat from 'N' to 'false' of the 'Manager' value if it is present in the document.

Schema Mapping

Policy Set: smp-SchemaMapping

This provides a sample mapping of data attributes between eDirectory and PeopleSoft. This will be a major area of work with your Component Interface developer. The fields you see on the right ("application") side of the schema map are those that he will be exposing to you via the CI. Many of these terms are obviously named, others you can probably figure out with little effort. Just remember that when you talk of "Full Name", the CI developer is hearing "FULL_NAME".

Publisher Event Transform

Empty

Filter

As with any Identity Manager driver, the Filter specifies what attributes you are interested in, and what to do with them. The samples here show examples of attributes that should flow only in one direction (CN), some that should flow in both directions (employee status), and one that absolutely must flow only in one direction (isManager).

For the most part, you will be customizing the Filter along with the Schema map. Note, for example, that the CN is a Subscriber Only attribute. Any attempt to set the CN from PeopleSoft will be dropped by the Filter. That makes sense to us as Identity Manager afficianados. But look at the Employee Status attribute. This is used to track the current employment status (active, terminated, etc.), and it is very unlikely that your HR system is going to allow this to be updated from Identity Manager. The isManager attribute is much more likely to reflect your eventual implmentation, where any change to this from eDirectory will not only be ignored, but will be actively reset back to its correct value from the HR system.

You may have some other data attributes, like email address, that do need to be sent back to HR, once the other system that is the authoritative source for that attribute has filled it in.

Publisher Matching Rule

Policy Set: pub-mp-PublisherMatching

Rule: Match on WorkforceID

Purpose: In PeopleSoft, every person is identified with a unique number, referred to as the EMPLID. The default configuration here maps the EMPLID to eDirectory attribute workforceID (see the Schema Map). Then when a User is created in eDirectory, the EMPLID from PeopleSoft is saved on it for later use. Normally at this point the Association would have taken care of finding the correct object to modify, but in cases where a resync is happening and Association values are not to be trusted, or as part of an initial migration, this rule can be handy for associating the correct eDirectory User object with the right PeopleSoft person entry. As a migration strategy, you might get a list of everybody with their EMPLID value, and manually update their User object with the workforceID value. Then the migrate from PeopleSoft proceeds smoothly through this rule.

Rule: Match on Surname and Given Name

Purpose: This Matching Rule does exactly what it says. Assuming that the match on EMPLID (workforceID) did not work, then this rule will attempt to find the correct eDirectory User object based on their Given Name and Surname. That might work, in a very small tree, but with more than a few dozen people, you are likely to find at least two John Smiths. This is another area where customization depending on the data you have to work with will be needed. A detailed examination of the eDirectory data will be necessary.

Publisher Create Rule

Policy Set: pub-cp-PublisherCreate

Rule: Check Required Attributes for User Creation

Purpose: A minimal list of attributes, without which an object cannot or should not be created in eDirectory. This rule only checks for Given Name and Surname. For eDirectory, that is sufficient, but for an actual implementation it is likely that far more will be needed.

Rule: Create CN for user if not available

Purpose: This rule checks to see if a CN is available in the current document (it will never be, because the Filter would have thrown it away), then goes and creates one. The default naming scheme combines Given Name, Surname, and a counter digit. It is likely that you will have some other needs here in naming your User objects.

Publisher Placement Rule

Policy Set: pub-pp-PublisherPlacement

Rule: Active User Placement

Purpose: This is an interesting demonstration of handling an "active" (vs. "inactive") employee. If the object to be created has an Employee Status of "A", which presumably stands for "Active", then the user is to be created in the "Active Users Container". This, in turn, is fetched from a Global Configuration Value, allowing more than one Identity Manager driver to be told where to look for, or place, "active" users.

If the user is active, though, the rather unfriendly "A" is stripped, and replaced by the word "active", in the eventual employeeStatus attribute that reaches eDirectory.

Rule: Inactive User Placement

Purpose: An obvious corrolary rule to the "Active User Placement", this rule has similar logic to decide what to do with a User object to be created for a person with an "I" in his Employee Status. Interestingly, though, the Global Configuration Value used is the same, so all Active and Inactive users will actually be created in the same container in eDirectory.

As with "Active", the "I" is stripped and replaced with the word "inactive". This is probably only useful if people are reading this attribute for something. Identity Manager and eDirectory obviously do not care what value is stored here.

Another area for customization presents itself here. In PeopleSoft, many possible Employee Status values are possible. You will need to find out which ones are being used, and what they mean to your organization. Not all "inactive" status codes necessarily need to be handled as though the person is being terminated ("on leave" for example may indicate inactive employment, but not necessarily a termination of access or duties).

Rule: Default User Placement (Inactive)

Purpose: If the Employee Status is neither "A" nor "I", then the first two rules in this Policy Set will not execute. This rule then does, and assumes that "not active" (ie: Employee Status is not "A") is the same as "Inactive" and acts accordingly. Good error case handling here, so if HR sets up somebody with an Employee Status that is unexpected, at least something will happen, even if it is not quite what HR was expecting. Your needs may vary, but we wary of any test that only applies to specific values, as unexpected values may show up some day.

Publisher Command Transform

Policy Set: pub-ctp-EmployeeStatus

Rule: set employeeStatus to inactive

Purpose: This duplicates the logic of the Publisher Create Rule that replaces "I" in the Employee Status with the word "inactive".

Rule: set employeeStatus to active

Purpose: This duplicates the logic of the Publisher Create Rule that replaces "A" in the Employee Status with the word "active".

Sadly, there is no error case handling here, so if HR changes somebody from "A" to "R", the result in eDirectory will be a User object with "R" as the employeeStatus. This will stand out in a sea of "active" and "inactive" values, but still looks wrong. If you are using the "active" and "inactive" logic on the Publisher Create Rule, you should add a third rule to this policy set to handle error cases.

Better yet might be to remove the logic from the Publisher Create Rule that does this and have it only on the Publisher Command Transform. That way the rules are only in one Policy Set, not in two. This is good programming practice.

Policy Set: pub-ctp-CheckPasswordGCV

Policy Set: pub-ctp-PublishDistributionPassword

Policy Set: pub-ctp-PublishNDSPassword

Policy Set: pub-ctp-AddPasswordPayload

These are four of the standard Policy Sets for Password Synchronization based on Universal Password. Geoffrey Carman's article (Password Transformation Rules in the Publisher Channel) describes these already, so I won't repeat them here.

Subscriber Channel

Subscriber Event Transform

Policy Set: sub-etp-EventTransformation

Rule: Transform Delete event to Modify to remove CN, DN, Internet Email Address, and Description

Purpose: This sample configuration writes back several eDirectory attribute values to the PeopleSoft system. This rule takes a Delete event and uses it to remove those values, since presumably they are no longer relevant to the person that this User object represents. It has, after all, been deleted.

Rule: Transform Rename event to Modify of CN and DN

Purpose: In eDirectory, changing the name of an object modifies its CN and its DN. Since these two data values are being provided back to the PeopleSoft system, this rule updates them in PeopleSoft when they change. PeopleSoft does not have a concept of "rename", though, so this must be done as a Modify event. It will then, via the Component Interface, update the CN and DN values in the database.

Rule: Transform Move event to Modify DN

Purpose: Similarly to the handling of Rename events, if an object is moved in eDirectory that will change its DN. This rule updates PeopleSoft with the new value.

Subscriber Matching Rule

Policy Set: sub-mp-SubscriberMatching

Rule: Match on WorkforceID

Purpose: This is identical to the rule on the Publisher Matching Rule. It will attempt to match an eDirectory User object with a PeopleSoft person based on the workforceID (EMPLID) value. If you have workforceID values populated on your eDirectory User objects, this works well and quickly.

Rule: Match on Given Name and Surname

Purpose: Better than nothing at all, this will attempt to match on Given Name and Surname. You will likely want to customize this one, along with the similar rule on the Publisher Matching Rule.

Subscriber Create Rule

Policy Set: sub-cp-SubscriberCreate

Rule: User Required Attributes

Purpose: This rule describes the minimum data necessary to create an object. But since we are on the Subscriber here, this is the list of attribute data needed to create a new Person in the PeopleSoft system. At least in theory, this is possible, but in the real world of HR systems it is unlikely that your HR department will be allowing new eDirectory objects, even if they have all of the required data, to actually create new People in their HR system. There is even specifically a Subscriber Option on this driver to prevent Add events from being sent to PeopleSoft. So this rule could easily be replaced by a single veto() and nobody would ever notice.

Subscriber Placement Rule

Empty

Subscriber Command Transform

Empty

Output Transform

Policy Set: sub-otp-employeeStatus

Rule: Set PS employeeStatus to 'A'

Purpose: The inverse of the Publisher channel, where 'A' is mapped to the word 'active' in two policies, here a change in the employeeStatus attribute to 'active' is written to the PeopleSoft system as 'A'.

Rule: Set PS employeeStatus to 'I'

Purpose: The inverse of mapping 'I' to 'inactive' on the Publisher Channel, here 'inactive' is mapped to 'I'.

Policy Set: sub-otp-TransformManager

Rule: Transform PeopleSoft 'Manager' values from boolean 'true/false' to 'Y/N'

Purpose: The Manager (isManager) attribute in eDirectory is multi-valued, so here a nodeset of its current values is built, then transformed to what PeopleSoft expects the values to be. Since the default Filter has isManager configured as "Reset", this rule is only going to apply to <query> documents, and is a really interesting demonstration of XPath and nodeset processing.

Policy Set: sub-otp-WritebackCNandDNaftersuccessfulPublisherChannelAdd

Rule: Writeback CN and DN after successful Publisher Channel Add

Purpose: If the status of an event that was processed on the Publisher Channel is Success, then the CN and DN of the processed (created or modified) object are written back to the PeopleSoft system in to a staging table. This uses the operation-data / peoplesoft-src-id that was set up on the Input Transform to get the EMPLID of the Person to modify, since Status documents don't contain Association values.

Policy Set: sub-otp-WritebackDNvalueduring"from-merge"Modifyevents

Rule: Writeback DN during "from-merge" Modify events

Purpose: When the Publisher processed an Add event that uses the Matching Rule to find and update an object that already exists in eDirectory, the Modify event is tagged as being "from-merge=True" so that it can be distinguished from other Modify events. When the Status of that Modify is processed here, the DN of the modified object is then written back to PeopleSoft.

Policy Set: sub-ot--AddDNvaluetoAddevents

Rule: Add DN value to Add events

Purpose: If an Add event is being submitted to PeopleSoft by the Subscriber channel (unlikely), then the DN of the added object is added to the event.

Policy Set: sub-otp-EmailOnFailedPasswordPublication

This is another of the standard Policy Sets for Password Synchronization based on Universal Password. Geoffrey Carman's article (Password Transformation Rule Sets ) describes these already, so I won't repeat them here.

Driver Configuration

Authentication

Authentication ID In this driver, this parameter specifies the account that will be used by the driver to log in to the PeopleSoft system. Your DBA will need to create the account and configure PeopleSoft security as needed for this account.

Connection Information //host:port This specifies the host and port of the application server that the driver to connect to. Check with your DBA. Ask about the "Jolt" port.

Driver Parameters

Driver Options

Schema CI Name Your Component Interface programmer will specify a Schema CI Name as part of building the CI. The default name, DIRXML_SCHEMA01, works with the default CI supplied with this driver, but you will probably use a different name in your actual deployment.

Data Record ID Field Also part of your CI development. This parameter specifies what field will be used to identify a person. The default, ASSOC_ID, works with the default CI supplied with the driver. You may or may not be changing this, again depending on your CI developer.

Use Case Sensitive Search Yes or no. The default, No, seems reasonable unless you know you need case sensitive searching (in PeopleSoft).

Subscriber Options

Allow Subscriber channel 'add' events This configuration option (default is 'No') prevents the driver from attempting to add new people to the PeopleSoft system. Unless you have a really unusual HR system, you will probably be leaving this option disabled.

Allow Subscriber channel 'delete' events This configuration option prevents (or allows) the driver to remove people from the HR system. As with 'add' events, it is very unlikely that you will be enabling this option.

Publisher Options

Transaction CI Name This is another option that you will be negotiating with your CI developer. It specifies the name of the staging table that the driver will be polling for events.

Driver Subset Identifier The name of the field in the CI (Data) that uniquely identifies a PeopleSoft object.

Publisher Polling Option This driver can be configured to poll every X seconds (see the Queue Poll Interval, below), or on a schedule based on a crontab type format.

Queue Poll Interval (seconds) How often the publisher thread should poll the staging table (DIRXML_TRANS01) for available transactions.

Publisher Heartbeat interval If the publisher is configured to send 'Heartbeat' status messages, they will be sent every 1 (default) seconds when the publisher is otherwise idle.