Importing Participant Data

This chapter provides an overview of the concepts involved in importing participant data into Resource Finder. It describes Resource Finder participant data import messaging, message definitions, XML schema definition, and message transformations, and discusses how to:

• Configure PeopleSoft Integration Broker to work with Resource Finder participant data import messages.

• Import participant data files.

• Load participant user IDs.

Understanding Importing Participant Data

You load Resource Finder with participant data imported from disparate data sources using the Resource Finder Data Import Service. The repository stores this consolidated data in a format optimal for accessibility using Resource Finder.

To use the Data Import Service to load participant data directly into Resource Finder, you must first format your data to fit the Resource Finder XML schema definition ($PS_HOME/web/integration/epr.xsd). You then feed the formatted data to the Data Import Service using either the PeopleSoft Integration Broker or the File Import Application Engine process (EPX_FILE_IMP). Use the Integration Broker approach if you want to have your source application post participant data XML messages to the Data Import Service by way of Integration Broker. You do not need to format the XML data using this approach, but you may need to adjust your XSL for any customizations that you made. Use the File Import process approach if your participant data XML files reside on disk and you want to have the data fed to the Data Import Service by way of the File Import process.

The PeopleSoft Integration Broker provides messaging middleware that your external applications can use to publish participant data for subscription by the Resource Finder Data Import Service. If your integrating application is capable of publishing its data into a messaging system like PeopleSoft Integration Broker, we recommend using this approach.

See Enterprise PeopleTools 8.48 PeopleBook: PeopleSoft Integration Broker

The File Import process provides support for importing flat-file XML participant data into Resource Finder. The XML data in the flat file must conform to the Resource Finder XML schema definition. If your integrating application is not able to publish its data into a messaging system like PeopleSoft Integration Broker, or you have other technical considerations keeping you from utilizing Integration Broker, export the data in XML format into a flat file and use the File Import process to feed the data to the Data Import Service for loading to Resource Finder. We provide a run control page that you can use to maintain a list of import files and directory references.

If your integrating application does not have a way to express its data in XML, write a custom program in the language of your choice to transform the data into XML. If you write this transformation application in a language such as Java, you may want to consider just having the integrating application post the transformed output XML to Integration Broker, rather than write it to a flat file for loading by the File Import process.

See Importing Participant Data Files.

Resource Finder provides a user interface for mapping external data source entities to Resource Finder participant attributes.

See Setting Up Data Sources.

Note. You should always load new data into Resource Finder using the services and methods we recommend in this PeopleBook. Do not load data directly from an external data source to Resource Finder's underlying database tables because this circumvents the application-level business logic that governs repository data.

Consider the following rules when working with Resource Finder participant data:

• You cannot manually create new participants in Resource Finder. New participants must be loaded by way of the Data Import Service.

• You cannot manually associate participants with new participant types in Resource Finder. New participant type associations must be loaded by way of the Data Import service.

• You cannot manually edit values associated with participant attributes with attribute types set to Image in Resource Finder. Image attribute values must be loaded by way of the Data Import Service.

• Once values are associated with participant attributes with attribute types set to Participant Reference or External Asset Reference, values can be changed, but not deleted. You cannot disassociate a value and leave the participant attribute without a value.

Describing Resource Finder Participant Data Import Messaging

Messages can be structured or unstructured in PeopleSoft Integration Broker. A structured message is one in which the message payload, or all fields in the message, is explicitly defined in the message definition. Message definitions used in PeopleSoft prepackaged integrations, as well as all message definitions generated by PeopleSoft applications, are structured. Other external applications may define unstructured messages, in which case the message definition serves primarily as a unique name that identifies the message type.

From the Resource Finder perspective, a message definition is an Integration Broker-related object that you define in Application Designer to tie the Integration Broker messaging into the external application providing participant data. You must create a separate message definition for each external data source.

See Enterprise PeopleTools 8.48 PeopleBook: PeopleSoft Application Designer, "Using PeopleSoft Application Designer," Working With Definitions

For example, suppose that external application X publishes a message Y to which Resource Finder wants to subscribe and load. You create a message definition Y on both the sending and receiving Integration Broker nodes so that the applications can send and receive Y messages. In the Resource Finder data import scenario, the message Y definition in your PeopleSoft Enterprise Portal database is always the receiving party, or message consumer. Subscription PeopleCode associated with the Resource Finder's message definition Y calls the Data Import Service.

Once you have created a message definition in the Resource Finder Integration Broker node, add the following subscription PeopleCode to the message definition that processes messages of the message type whenever they arrive. The only variable in this PeopleCode from message to message is the reference to the HTML object that contains the transformation XSL, if applicable to the message.

import EPX_SERVICE:EPRDataImportMessageHandler; Local EPRDataImportMessageHandler &EPRDataImportMessageHandler; &EPRDataImportMessageHandler = create EPRDataImportMessageHandler(GetMessageXmlDoc(), GetHTMLText(HTML.XSLT_WORKFORCE_SYNC));

Note. This step is not necessary for delivered messages that interact with PeopleSoft Human Capital Management (HCM) applications. The necessary PeopleCode is already in the delivered message definitions.

See Describing Delivered Resource Finder Message Definitions.

The type of messaging used for the Resource Finder data import is asynchronous. The external application publishes a message, which is saved to a persistent message queue. The Resource Finder Integration Broker node polls persistent message queues for which there are active subscriptions. When the node encounters new messages, it triggers this message PeopleCode in the relevant message definition. This Resource Finder message PeopleCode transforms the published message, if necessary, and then forwards it to the Data Import Service.

Resource Finder Message Sync Setup

You can refer to several other areas of documentation for specific information about the setup of Resource Finder message sync. There are several sources of information on this topic.

See Migrating Data From the Content Provider Using PeopleSoft Integration Broker.

See Enterprise PeopleTools 8.48 PeopleBook: PeopleSoft Integration Broker,

See Understanding Enterprise Integration.

See Also

Setting Up on the Third-Party Side

Describing Delivered Resource Finder Message Definitions

Resource Finder is delivered with sample participant data import message definitions for use with PeopleSoft Human Capital Management (HCM).

These message definitions are delivered with subscription PeopleCode that applies the appropriate XSL transformation logic and stores the message data in the Resource Finder repository. Installing these HCM data sources for use with these message definitions requires running message-specific Data Mover scripts that create attributes in Resource Finder with names corresponding to HCM message field names.

The XSL required to transform these messages is stored in HTML objects in the portal database. The subscription PeopleCode retrieves the XSL from the database, passes it to the EPRDataImportMessageHandler object, which applies the XSL to the incoming message, and then passes the transformed message to the Data Import Service.

The following table contains a listing of the sample HCM participant data import messages mapped to HCM-specific Integration Broker message channels.

When working with applications, such as HCM, which publish messages for import into Resource Finder, you should clear the Create Message Header and Create Message Trailer options on the Full Data Publish Rules page. Message headers and trailers are not supported by Resource Finder's Data Import Service.

Describing the Resource Finder XML Schema Definition

The participant Data Import Service requires that data conform to the Resource Finder's XML schema definition prior to being loaded. This schema is a representation of all Resource Finder data types in XML and provides you with a standardized specification for formatting your data for import into the Resource Finder repository.

The Resource Finder XML schema definition resides in the $PS_HOME/web/integration/epr.xsd file delivered on your installation CD. The epr.xsd file contains definitions for all Resource Finder data structures, not just participant data. However, only participant elements will be processed during data import.

Describing a Resource Finder Sample Participant Message

In this section, we describe a sample message in Resource Finder format. This message represents a participant and conforms to the Resource Finder XML schema definition (epr.xsd). We deliver a sample XML file that conforms to the XML schema definition: $PS_HOME/web/integration/sample.xml

The outermost element is always epr. Import messages should contain one or more nested participant elements. Each participant element should contain one attribute-value-set element for each distinct attribute that it contains values for. attribute-value-set elements must always contain one attribute-definition-ref element that references the associated attribute. They should also contain one or more attribute-value elements (one for each value).

Just as there are different types of attributes that you define in Resource Finder, there are different types of attribute-value elements that you can nest within an attribute-value-set element. In other words, there are different elements that extend the same element type as attribute-value:

• attribute-ref (attribute references).

• participant-ref (participant references).

• component-ref (external asset references).

Following all of a participant element's attribute-value-set elements, there must be at least one participant-type-ref element that designates the participant type view of the participant to which the message corresponds in Resource Finder; there can be more than one. Nested within this element should be one external-key-mapping element for each field required to uniquely identify the participant in its external data source. For example, if two fields are required to establish a unique identifier, there should be two external-key-mapping elements nested within the participant-type-ref element. The value of the field-name attribute should be the same as the key field name defined in the Resource Finder mapping for that data source. The field-value attribute should contain the actual key field value.

Notice that in the sample message below, the participant element's ID attribute is set to 0 (zero), as are all the values of the attribute-value ID attribute. This is because these values will be populated by Resource Finder native ID values while being processed by the Data Import Service. The Data Import Service will utilize the key mapping metadata defined for the data source to either generate new or retrieve existing Resource Finder IDs for participant messages during import.

See Enterprise PeopleTools 8.48 PeopleBook: Security Administration, "Setting Up User Profiles"

<epr xmlns="http://pt-sun13.peoplesoft.com/epr" xmlns:eo_pe=
"http://pt-sun13.peoplesoft.com/eo_pe" xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=
"http://pt-sun13.peoplesoft.com/epr http://pt-sun13.peoplesoft.com/epr/epr.xsd">
	<!-- Participant is the only type of top-level element that should ever 
come in by way of a data feed. -->
	<participant description="participant 1 name" effective-date="1900-01-01"
 id="0" data-privacy-waived="false" activity-status="ACTIVE" data-source=
"" operator-id="">
		<!-- Participants can nest multiple attribute-value-sets, each one 
representing one or more values associated with a distinct attribute. -->
		<!-- The first one contains a simple attribute-value element with one 
value associated with it. -->
		<attribute-value-set>
			<attribute-definition-ref attribute-name="SSN" external-field-name=
"social_sec_nbr"/>
			<attribute-value id="0" activity-status="A" data-source=
"PSFT-HR_WORKFORCE_SYNCH" effective-date="1900-01-01" value="333-22-3423"/>
		</attribute-value-set>
		<!-- This one contains a simple attribute-value element with multiple 
values associated with it, and the values are scored. -->
		<attribute-value-set>
			<attribute-definition-ref attribute-name="SKILLS" 
external-field-name="competency"/>
			<attribute-value id="0" activity-status="A" data-source=
"PSFT-HR_WORKFORCE_SYNCH" effective-date="1900-01-01" value="Java" score="8"/>
			<attribute-value id="0" activity-status="A" data-source=
"PSFT-HR_WORKFORCE_SYNCH" effective-date="1900-01-01" value="C++" score="6"/>
		</attribute-value-set>
		<!-- The next attribute-value-set contains an attribute reference.
The value of the PREFERRED_CONTACT_METHOD attribute is the current value 
of the WORK_PHONE attribute. -->
		<attribute-value-set>
			<attribute-definition-ref attribute-name="PREFERRED_CONTACT_METHOD" 
external-field-name="pref_contact_mthd"/>
			<attribute-ref id="0" value="" attribute-name="WORK_PHONE" 
external-field-name="work_phone" activity-status="A" data-source=
"PSFT-HR_WORKFORCE_SYNCH" effective-date="1900-01-01"/>
		</attribute-value-set>
		<!-- The next attribute-value-set contains a participant reference.  
The data import process will have to resolve the referenced participant 
(either finding them or creating them if they don't exist in the EPR). 
Notice that the referenced participant has its own key mapping info that 
can be used to find its EPR key. -->
		<attribute-value-set>
			<attribute-definition-ref attribute-name="SUPERVISOR" 
external-field-name="supervisor_id"/>
			<participant-ref id="0" value="" referenced-id="0" activity-status="A" 
data-source="PSFT-HR_WORKFORCE_SYNCH" effective-date="1900-01-01">
				<participant-type-ref name="MANAGER"/>
				<external-key-mapping field-name="supervisor_id" field-value="34324"/>
			</participant-ref>
		</attribute-value-set>
		<!-- The next attribute-value-set contains two component references. 
Like participant references, they have their own key mappings and must be 
resolved to external components in the EPR. The difference is, they must 
already exist. The data feed process should not create external components. -->
		<attribute-value-set>
			<attribute-definition-ref attribute-name="ARTICLES_PUBLISHED" 
external-field-name="article"/>
			<component-ref id="0" value="" referenced-id="0" activity-status="A" 
data-source="PSFT-HR_WORKFORCE_SYNCH" effective-date="1900-01-01">
				<component-type-ref name="PSFT_CM_DOCUMENT"/>
				<external-key-mapping field-name="article_id" field-value="342"/>
				<external-key-mapping field-name="article_type" field-value="G"/>
			</component-ref>
			<component-ref id="0" value="" referenced-id="0" activity-status="A" 
data-source="PSFT-HR_WORKFORCE_SYNCH" effective-date="1900-01-01">
				<component-type-ref name="PSFT_CM_DOCUMENT"/>
				<external-key-mapping field-name="article_id" field-value="546"/>
				<external-key-mapping field-name="article_type" field-value="G"/>
			</component-ref>
		</attribute-value-set>
		<participant-type-ref name="EMPLOYEE">
			<external-key-mapping field-name="empl_type" field-value="129"/>
			<external-key-mapping field-name="empl_id" field-value="3333"/>
		</participant-type-ref>
		<participant-type-ref name="MANAGER"/>
	</participant>

Describing Message Transformations

External data sources may or may not support the publication of their data using messaging technology. In a case in which the external data source does not publish its data using messaging, you can build a custom application to extract the data, format it in XML according to the Resource Finder XML schema definition, and post it to Integration Broker.

In a case in which the external data source does publish its data using messaging, the data source is likely to publish its data in an XML format native to representing its data. In this case, you can build logic to transform the external XML format to the Resource Finder XML schema definition. There are different ways to configure this type of message integration requiring transformation.

• Integration Broker.

  You can define relationships in Integration Broker that specify beginning and resulting transaction types for transactions. For transactions that represent inbound asynchronous messages from publishing data sources, a relationship containing InAsync-to-InAsync transaction modifiers tells the Integration Broker to apply transformations to the associated request messages that transform them into XML that fits the Resource Finder XML schema definition. These transformations can be specified in either PeopleCode or Extensible Stylesheet Language (XSL).

• XSL Transformations (XSLT) in subscription PeopleCode.

  You can apply an XSLT to an inbound message in subscription PeopleCode by calling the PeopleTools built-in function TransformEx()). This approach is entirely programmatic and does not involve launching an Application Engine program to transform each message. All message integrations included with Resource Finder use this approach.

  For example, the HCM WORKFORCE_SYNC message has corresponding XSL that transforms the message into a structure that conforms to the Resource Finder XML schema definition. The XSL is stored in an HTML object called XSLT_WORKFORCE_SYNC. The subscription event script associated with the WORKFORCE_SYNC message includes the following code:

  import EPX_SERVICE:EPRDataImportMessageHandler; Local EPRDataImportMessageHandler &EPRDataImportMessageHandler; &EPRDataImportMessageHandler = create EPRDataImportMessageHandler(GetMessageXmlDoc(), GetHTMLText(HTML.XSLT_WORKFORCE_SYNC));

  EPRDataImportMessageHandler is a convenience class that attempts to import the current message into the Resource Finder repository. If XSL is passed to the optional second parameter of its constructor, the subscript event script attempts to apply the transformation to the message before attempting to import it.

See the “Importing and Transforming Data For Use With Resource Finder” documentation located in the Documentation Updates section of the PeopleSoft Customer Connection website

Configuring PeopleSoft Integration Broker to Work With Resource Finder Participant Data Import Messages

While there are a variety of ways in which to implement this configuration, the following list provides a set of high-level checks you should perform when configuring PeopleSoft Integration Broker to enable applications to publish data messages to your established Resource Finder participant data import message definitions.

1. Ensure that publish/subscribe is activated in both the publishing and Resource Finder application servers.

2. Ensure that the Integration Broker gateways have been set up for each node—the node publishing the messages and the subscribing Resource Finder node.

3. Ensure that both nodes can ping each other.

4. Ensure that relevant message channels are set to run on both nodes.

5. Ensure that relevant message definitions are active on both nodes.

6. Log onto the publishing node, go to the Resource Finder node, and add relevant messages as OutBound asynchronous transactions.

7. Log onto the Resource Finder node, go to the publishing node, and add relevant messages as InBound asynchronous transactions.

See Also

Setting Up on the PeopleSoft Side

Importing Participant Data Files

In this section, we discuss how to configure and run the File Import process using the Configure File Import component (EPX_FILE_IMPORT).

Understanding the File Import Process

The File Import process provides an alternative means for external applications to push their messages to Resource Finder. Instead of using Integration Broker, you provide a solution for getting external application data into an XML flat file whose contents conform to the requirements of the Resource Finder XML schema definition. You write this formatted XML data to a file system directory accessible by the Process Scheduler in your Resource Finder installation. The File Import process imports participant data stored in configured XML files into Resource Finder.

Page Used Import Participant Data Files

Importing Files

Access the Configure File Import page.

File/Directory

Enter directory information for XML files you want to include in an update to Resource Finder. To include an individual file, enter its full path information as it resides on the Process Scheduler host, for example Root:\Directory\File.xml. To include all XML files in a folder, enter its full path information as it resides on the Process Scheduler host, for example Root:\Directory. You must manually enter the file and folder path information because these XML files are located on the Process Scheduler host and browse functionality is only available on local file systems. The Process Scheduler kicks off an Application Engine process that searches designated directories for relevant files in an attempt to import them. Naturally, the paths you enter must be accessible to the Application Engine process.

Include

Select for a file or folder to include it in the File Import process.

Loading Participant User IDs

This section provides an overview of the Load Participant User IDs Application Engine process (EPX_LOAD_OPR) and discusses how to run the Load Participant User IDs Process using the Load Participant User Ids component (EPX_LOAD_OPR).

Understanding the Load Participant User IDs Process

The Load Participant User IDs process updates Resource Finder participant definitions with corresponding PeopleSoft user ID values. Making this connection between Resource Finder participant definitions and PeopleSoft user IDs allows the Collaborative Workspaces and Content Management features to display a Resource Finder participant profile for a user, when applicable.

For example, let's say that you have a User Profile Key Field field value of EMPLID and a Key Field Name field value of EMPLID on the Load Participant Users Ids page. If there is a PeopleTools user profile with an EMPLID value of PSMITH and there is a participant profile with an EMPLID value of PSMITH, this process makes a connection between the user profile and the participant profile and in applicable areas of the Collaborative Workspaces and Content Management features, when a user clicks a user ID link, the Resource Finder participant profile can be displayed. If no connection is made between a user profile and a participant profile, when a user clicks a user ID link, the PeopleTools generic user profile information is displayed.

Page Used to Load Participant User IDs

Running the Load Participant User IDs Process

Access the Load Participant User Ids page.

You must save all settings before running the process.

Settings