Export (0) Print
Expand All

Microsoft BizTalk Adapters for PeopleSoft

Overview

Large companies today are filled with disparate systems containing overlapping functionality. Companies frequently support separate systems to handle manufacturing, financials, human resources (HR), and customers. Those companies that are disciplined enough to run on a single vendor’s line of business (LOB) applications are not necessarily better off than those running on applications from multiple vendors. It is likely that the vendor gained the application suite through acquisitions, and supports only custom integration between the individual applications.

Even companies that run on a single Enterprise Resource Planning (ERP) system that also handles HR and Customer Relationship Management (CRM) data are rarely able to handle the custom requirements of each organization. The result is that millions of dollars are spent on customizing the LOB application or developing an entirely separate application (a satellite system) to handle the custom functionality. (The advantage of creating a satellite system is that it is significantly easier than dealing with the LOB version upgrade problems that accompany the modification of source code in an LOB application.) Regardless—whether a company has multiple LOB applications, a plethora of satellite systems, or both—the data between systems needs to be sourced from a single master and synchronized across each application. Otherwise, the data becomes stale and worthless. Data synchronization is one of the problems that Microsoft® BizTalk® Server is designed to address, and with the addition of the LOB adapters in BizTalk Server 2006, applications such as PeopleSoft, JD Edwards, and Siebel can be smoothly integrated.

ERP Systems

ERP systems are a type of LOB system. In their early form, they were sold as a “magic bullet” solution to integrating an enterprise’s business, people, and processes. ERP systems were popularized in the 1980s and 1990s with the intention of integrating multiple business functions into a single application platform. Built by the likes of Oracle, PeopleSoft, JD Edwards, Siebel, SAP, and Baan, these ERP systems created application silos bounded by each vendor’s proprietary application technology. Inevitably there was a need to integrate ERP systems with each other or with other systems that provided additional functionality.

Figure 1: Typical LOB system integration scenario (partial integration)
Bb820917.c1cd4677-1e4f-4de4-b0a0-41cbe4746fa1(en-US,BTS.10).gif

Figure 1 depicts typical scenarios in which LOB system integration occurs with seemingly ad-hoc integration links needed to keep data synchronized. These include mergers and acquisitions that result in two companies, running two different ERP systems that must share data through synchronization or real-time exchange. Another scenario where such integration occurs is when new systems are introduced with functionality not available within the ERP systems. For example, the implementation of a custom e-commerce system introduces the need for the customer to enter a sales order into the corporate Order Management System (OMS) in near-real time. Still another example is when there is no centralized organizational application strategy (due perhaps to “political boundaries” or to improper management), resulting in departments within the same company using different systems.

Integration and Interoperability

The need for integration prompted the need for external, or integration-based, APIs from ERP vendors. However, the APIs produced were clunky, proprietary, and required very specialized skill sets. The need for standards-based adapters based on a common pattern was apparent, and several vendors went to work to create adapter frameworks that would allow a developer to learn a single API for creating software to integrate with multiple ERP platforms. Some adapter vendors took this a step further to create adapters that were ready to use with integration platforms such as BizTalk Server 2006.

Figure 2: Typical integration scenario designed by using BizTalk Server and LOB adapters
Bb820917.35466ec2-2a36-4684-b982-a14cdc0b2a61(en-US,BTS.10).gif

This allows BizTalk Server to be used as a centralized integration broker, as shown in Figure 2, reducing the need for point-to-point or custom integrations between two systems. BizTalk Server 2006 provides a diverse set of LOB adapters to facilitate the exchange of information between a variety of ERP systems, and other external data repositories, through the use of a common technology. We will summarize important high-level technical points about the LOB adapters throughout this white paper.

Purpose and Advantages

The purpose of the LOB adapters is to enable companies to leverage their existing investments in their enterprise application infrastructure while mitigating risks inherent to integrating business systems. The following paragraphs discuss some advantages of using the adapters.

Reuse of Existing Business Logic

A common integration challenge faced by companies today is that much of their investment in the design and development of business logic cannot be leveraged when interfacing directly with the underlying databases. Use of a data transformation utility such as Data Transformation Services (DTS) or SQL Server™ Integration Services (SSIS) can often lead to data exchanges that violate critical business rules because these rules are implemented in application logic, and not in the databases. This also undermines the investment made in the LOB system’s business logic. By communicating directly with the LOB system at the database level, it is possible to introduce data that will be misinterpreted by the LOB system.

“Application adapters” allow integration platforms to interface with the “business logic layer” of the LOB system using each system’s proprietary interface mechanisms. By using application adapters, IT departments can create integrations that will exchange data while still adhering to the critical business rules that have been programmed into the business logic layer.

Specifically with BizTalk Server 2006, the Adapters for Enterprise Applications (the “LOB adapters”) enable run-time application integration while also providing key design-time functionality. BizTalk Server ports are configurable for connections to multiple instances of the LOB systems. “Wizards” are used in the Microsoft Visual Studio® .NET development environment to browse business object metadata and generate XSD schemas and orchestrations that can be consumed as part of the BizTalk Server development cycle.

Reduced Development Cost

Because the BizTalk Server LOB adapters communicate directly with the existing business logic layer on the LOB system, additional components that would otherwise be duplicated as part of an integration effort are not needed. Companies can avoid having to develop components for their integration projects that mimic the logic that already exists on the LOB systems.

Lower Change Management Risk

Eliminating the need for duplicated business logic greatly reduces the risks associated with managing changes to the LOB systems and any dependent systems. For example, if you have seven different processes all using distinct versions of the same business logic, a change in one could necessitate a change in all. However, it is possible that not all seven processes would be modified correctly or at all. Even if the changes were properly completed, imagine the resources expended in making the same change repeatedly or inaccurately.

Component/Package View of LOB Adapters

The LOB adapters consist of several components. You will find many of these processes running in Task Manager as you use the design-time and run-time components of the adapters:

  • Adapter Framework – The adapters are built on the BizTalk Server Adapter Framework. The Adapter Framework is a set of extensible APIs that enable developers to take advantage of relevant services of BizTalk Server when building adapters and connectors that integrate third-party applications. For more information, see How the Adapter Is Designed: The Adapter Framework.
  • Java Runtime – The Adapter Framework, which is used by the LOB adapters, is dependent upon the Java Runtime (version 1.4.3 or later).
  • Browser Agent – This process is used by the Adapter Framework and invoked by Visual Studio .NET. It retrieves and formats metadata from the LOB systems into XSD files that the BizTalk Server development environment can then consume and use. After five minutes of inactivity, it automatically shuts down to release any resources, such as memory, that may have been used. This process appears in Task Manager as browsingagent.exe.
  • Runtime Agent – This process is used by the Adapter Framework and is invoked by the BizTalk Server runtime (BtsNtSvc.exe) to call business functions on the LOB systems. Unlike the Browser Agent, the Runtime Agent does not shut down after a period of inactivity. This process appears in Task Manager as runtimeagent.exe.
  • Connectors, JAR files – JAR files contain the set of Java classes specific to the LOB system. The Adapter Framework exposes these classes as Java interfaces, which are used to communicate with the BizTalk Server design-time and run-time executables.

Figure 3 shows the high-level architecture of both the design-time and run-time components and how they interface with the LOB adapters and the LOB system.

Figure 3: LOB adapter process flow
Bb820917.ef291557-9aaf-462c-87f8-0ff148f9bcb2(en-US,BTS.10).gif

The PeopleSoft architecture closely follows a client/server architecture. However, there are multiple integration points into the PeopleSoft architecture that you should consider when designing your integration infrastructure.

PeopleSoft Architecture

Given PeopleSoft’s client/server architecture, there are many different types of clients, including thin clients such as Files, Java, and the Web browser (see Figure 4).

Figure 4: PeopleSoft client/server architecture
Bb820917.78a69c9b-40c7-4381-9faa-2780e40ad5a9(en-US,BTS.10).gif

But PeopleSoft is not only built with client access in mind. It also includes a variety of integration capabilities. Figure 5 shows the integration channels offered by the PeopleSoft application server.

Figure 5: PeopleSoft integration channels
Bb820917.f4bbb435-a69b-451c-a117-d2543fe6d69d(en-US,BTS.10).gif

As this figure shows, several connection mechanisms are offered, and with the exception of Java Beans, these mechanisms are readily available from BizTalk Server 2006.

Bb820917.note(en-US,BTS.10).gifNote
One additional integration option is the PeopleSoft Integration Broker. The PeopleSoft Integration Broker was introduced with PeopleSoft PeopleTools 8.45 as one of the preferred integration methods. Prior releases relied on stand-alone integration methods, such as Component Interfaces for inbound traffic and Application Messaging for synchronous/asynchronous traffic.

Like BizTalk Server, the Integration Broker provides a middleware technology to facilitate synchronous and asynchronous messaging with other PeopleSoft applications and with third-party systems. It communicates with PeopleSoft through a subset of the communication protocols identified in Figure 5, while also managing message structure, message content, and transport disparities.

The PeopleSoft LOB Adapter

The BizTalk PeopleSoft LOB adapter communicates with the PeopleSoft application servers by using the PeopleSoft Component Interfaces, and does not interact directly with the PeopleSoft Integration Broker. Instead, the PeopleSoft Component Interfaces are exposed as Web services. The PeopleSoft LOB adapter receives an XML message from BizTalk Server. This message is encapsulated in a SOAP request that is sent to the LOB application server by using the PeopleSoft psjoa classes (see Figure 6). The result is a PeopleSoft connection from BizTalk Server using the standard integration LOB development paradigm, which can generate the API schemas and use them within BizTalk Server 2006 mapping and orchestration facilities at design time and run time.

Figure 6: BizTalk Server 2006 PeopleSoft LOB adapter process flow
Bb820917.8cc0b7c7-ed21-4560-a24f-d090df03da67(en-US,BTS.10).gif

At design time, the PeopleSoft LOB adapter evaluates the PeopleSoft Component Interfaces and exposes a listing of these APIs within the BizTalk Server 2006 Add Adapter Wizard (see Figure 7), which should more appropriately be called the Add Generated Items Wizard.

Figure 7: Generating PeopleSoft schemas using the Add Adapter Wizard
Bb820917.5da937e0-06e7-4c2d-a87b-59ce0cd371aa(en-US,BTS.10).gif

Although BizTalk Server 2006 is built on the Microsoft .NET Framework, the connection of the PeopleSoft LOB adapter into the PeopleSoft application uses Java. This is especially evident when configuring the port because it is necessary to reference several JAR file locations in addition to the PeopleSoft connection information.

Figure 8: PeopleSoft LOB adapter architecture
Bb820917.b55c9e01-a8c6-47bf-9f87-eec4e28f26e2(en-US,BTS.10).gif

A key limitation in the PeopleSoft LOB adapter architecture (see Figure 8) is that it facilitates only calls into PeopleSoft (send handlers). It does not also receive notifications directly out of PeopleSoft into BizTalk Server (receive handlers). The adapter can retrieve data from PeopleSoft through calls that are initiated from outside the PeopleSoft application. It cannot, however, receive or listen to events from PeopleSoft. However, as long as the calling application has the necessary lookup information when calling the PeopleSoft Component Interface, the adapter is well suited for requesting data from PeopleSoft.

Unfortunately, the adapter is not suited for notifications out of the PeopleSoft application. There simply is not a receive handler within the PeopleSoft LOB adapter. As a result, if a user alters data inside the PeopleSoft application, it is not possible for the PeopleSoft LOB adapter to receive a callback from PeopleSoft and push the updated information into another system such as an ERP system. The infrastructure for solving this problem does not rely on the PeopleSoft LOB adapter, but rather works through one of the other connection mechanisms shown in Figure 5—namely File, FTP, Web Services, or HTTP. Alternatively, a connection could be set up directly with the database using the PeopleSoft audit tables, or custom-built staging tables that are populated from the PeopleSoft application through the use of triggers. BizTalk developers could employ a database adapter but extreme care will be needed to avoid data integrity violations. Another obstacle with this approach may be inappropriate access to confidential information.

Integration Strategies

The goal is to communicate with the PeopleSoft application. As with many ERP systems, it is necessary for bidirectional data to flow. Options for importing data into, as well as exporting data out of, PeopleSoft are provided below.

Design Pattern: Receive Handler—from PeopleSoft to BizTalk Server

Since the PeopleSoft LOB adapter does not provide an option to extract data directly out of PeopleSoft though the standard receive port process, the use of an alternative adapter is required. Fortunately, BizTalk Server offers a variety of other adapters that can assist in this process, including file-based adapters, database adapters, and Web service adapters. While the PeopleSoft LOB adapter does not handle retrieving data from PeopleSoft directly, the send handler can be used to initiate a request for information provided that the appropriate requesting parameters are available.

File-Based Integration

PeopleSoft offers automated processes that generate flat files. A PeopleSoft developer will be required to assist in the setup and scheduling of this effort, but once the file generation events are established, either the BizTalk Server File or FTP adapter can be used to monitor for these file-based messages (see Figure 9).

Figure 9: Receiving PeopleSoft files
Bb820917.2c6d1fbc-cfb3-453d-8e82-1670de0a9c3b(en-US,BTS.10).gif
Database-Level Integration

PeopleSoft can be installed on a variety of database servers: Oracle, IBM DB2, Microsoft SQL Server, and HP-UX to name a few. BizTalk Server comes with many database adapters, as shown in Figure 10, which can communicate with these DBMS platforms, and third-party adapters are available for others.

The BizTalk Server Oracle database, Host Integration Server DB2, and SQL Server adapters provide options to execute SQL statements, call stored procedures, or monitor tables for specific changes. One of the advantages of this option is that developers are familiar with database structures and development regardless of the particular DBMS platform. This familiarity can reduce the reliance on the availability of a PeopleSoft developer. However, there are some security concerns to keep in mind when using this approach. It is recommended that a limited-access database account be created specifically for integration. This database account should have access to only those tables and objects necessary for integration. While read-only access is preferred, it is often impractical due to the requirement to change the state of the data to reflect integration.

Figure 10: Database extraction
Bb820917.148823ad-9a9e-41df-b2b5-74a1b28e3aa0(en-US,BTS.10).gif
Web Services-Based Integration

PeopleSoft provides a variety of Web services that BizTalk Server can interface with by using the HTTP or SOAP adapters. To establish a receive handler using Web services, a PeopleSoft developer will be required to create code that calls out to BizTalk Server (see Figure 11).

Figure 11: Receiving Web service requests
Bb820917.5972b1ad-215d-46fb-b243-196abdcdb35f(en-US,BTS.10).gif

Design Pattern: Send Handler—from BizTalk Server to PeopleSoft

In contrast to receiving data from PeopleSoft, the BizTalk PeopleSoft LOB adapter does allow you to push data to the PeopleSoft application server. While this may be the most practical approach, it is not the only option available. You can also use other BizTalk adapters to facilitate integration with PeopleSoft.

PeopleSoft LOB Adapter

BizTalk Server provides the PeopleSoft LOB adapter specifically for communicating with the PeopleSoft Component Interfaces. As Figure 12 shows, this allows interaction directly with the PeopleSoft application servers while requiring minimal involvement from a PeopleSoft developer. After the PeopleSoft server has been properly configured for BizTalk Server, you are ready to begin integration development. (See the Adapter Configuration and Interface Development section for more information about how to configure your send port.)

Figure 12: Use of Component Interfaces
Bb820917.878a420b-c968-4bd8-a9e5-637c92730eb7(en-US,BTS.10).gif
File-Based Integration

Probably the most basic method of integration with PeopleSoft is through files. The PeopleSoft Application Engine accepts files in a variety of formats: positional, comma separated, XML, etc. By using the BizTalk Server File and/or FTP adapters (see Figure 13), you can transport files in the predefined format for integration. After the PeopleSoft configuration is complete, you can monitor directories for the existence of these files. PeopleSoft will process these files in a batch mode. The only disadvantage is that a PeopleSoft developer will be required to assist in the setup and scheduling of this effort. By harnessing the power of BizTalk Server message manipulation, BizTalk Server can easily extract data from an external system, convert it to the predefined format, and send it to PeopleSoft for processing.

Figure 13: Use of the Application Engine
Bb820917.9b28a6e7-1ca2-4da3-b050-6a79483229b4(en-US,BTS.10).gif
Web Services-Based Integration

As mentioned above, Web services can be used for publishing data to PeopleSoft. The BizTalk Server HTTP or SOAP adapter can easily be configured to communicate with PeopleSoft in this fashion. Once again, the assistance of a PeopleSoft developer may be required (see Figure 14).

Figure 14: Use of Web services
Bb820917.c7b4aede-b704-47fe-837d-2eeeed13ec25(en-US,BTS.10).gif
Database-Level Integration

Similar to extracting data from PeopleSoft, you can theoretically use the BizTalk Server database adapters to insert or update data directly on the PeopleSoft database server (see Figure 15). It is recommended that you use a database account created specifically for integration. However, unlike with data extraction, you will be modifying the data directly and there are many dependencies associated with relational databases. Simply inserting an employee record may seem to be a trivial step, while in reality, PeopleSoft creates multiple records across multiple tables to perform this process. Developers should take this approach only as a last resort and should employ extreme caution when altering the underlying data directly.

Figure 15: Database connection to PeopleSoft
Bb820917.1f020c55-c54c-492a-af3b-96eeb6a3c8dd(en-US,BTS.10).gif

This section provides development-oriented instructions for configuring the PeopleSoft adapter and generating the schema for the send port.

Installation and Configuration of the PeopleSoft LOB Adapter

For the BizTalk PeopleSoft LOB adapter to communicate with the PeopleSoft application server, you must configure the PeopleSoft application server. Additionally, you need to create new Application Designer objects and alter PeopleSoft Security. You must perform these steps on each PeopleSoft instance that is targeted. In this section, we will identify the necessary modifications at a high level.

Complete instructions are available online at: http://go.microsoft.com/fwlink/?LinkId=56392.

A PeopleSoft developer and/or administrator will be required to perform the necessary installation and configuration procedures.

Creating the GET_CI_INFO Custom Component Interface in PeopleSoft

The GET_CI_INFO Component Interface allows the BizTalk PeopleSoft LOB adapter to retrieve the list of PeopleSoft Component Interfaces to which it has access, and also generates the necessary metadata information for the PeopleSoft Component Interfaces. The configuration is required for each instance with which you wish to integrate using the PeopleSoft LOB adapter.

To begin, you must use a Component Interface that does not contain keys. This may be accomplished using the following code snippet:

SELECT DISTINCT BCNAME FROM PSBCITEM BC1 WHERE NOT EXISTS(SELECT 1 FROM PSBCITEM BC2 WHERE BC1.BCNAME = BC2.BCNAMEAND BC2.BCTYPE IN (1, 2))

Create the new GET_CI_INFO Component Interface by cloning an existing Component Interface that does not contain keys. Replace the existing PeopleCode, if any, with the contents of <install_directory>\config\PeopleSoft\get_ci_info.pc and save your changes.

After you have created the GET_CI_INFO PeopleSoft Component Interface, you must set the security for the GetCINamespace, GetDetails, and GetCollections methods. All methods must be granted Full Access. Finally, test your configuration. Ensure that the GET_CI_INFO Component Interface does not contain any keys.

After you have successfully configured one PeopleSoft instance, you may choose to migrate the project definition to a subsequent instance instead of configuring each instance individually.

Additional details are outlined in the appendix under Configuring the PeopleSoft Application Server.

Send Port Configuration

To connect successfully to PeopleSoft by using the BizTalk PeopleSoft LOB adapter, you must configure the send port with configuration properties that determine how messages will be processed. Although several properties are common across all send ports; some are uniquely defined based on the type of adapter being used. For the PeopleSoft LOB adapter, it is necessary to configure the transport properties as well as the pipelines before the adapter will work either at design time or at run time.

Configuring Transport Properties

The adapter uses transport properties (see Table 1) to connect to PeopleSoft. One important characteristic to note about these transport settings is that the values are case sensitive. Take care when specifying the properties.

Table 1: Required Properties

Transport Property Description / Example

Application Server Path

The name of the computer and port on which the PeopleSoft application server is running and listening. The syntax of the URL path to the PeopleSoft 8 application is //<machine_name>:<port>.

The <port> value is the JOLT protocol Listener port, not the App Server port. The default JOLT port is 9000.

JAVA_HOME

The location where the JDK was installed.

For example: C:\j2sdk1.4.2_08.

This value is required only if you do not include this value in your PATH environment variable. For instructions on this process, see Updating Environment Variables in the appendix.

Password

The user’s password used to access the PeopleSoft system. The characters do not appear but are represented by asterisks (*).

This is required only if you are not using Enterprise Single Sign-On (SSO).

PeopleSoft 8x JAR Files

The location of the psjao.jar file. Additionally, to use the Component Interfaces in PeopleSoft 8 only, you must update your CLASSPATH environment variable to include the PeopleSoft Component Interface JAR file.

For example: C:\PeopleSoft\psjoa.jar or \\<PeopleSoft Server>\web\psjoa\psjoa.jar

The psjoa.jar file is unique to each version and installation of PeopleSoft. This file is typically located at <PeopleSoft_Home>\web\PSJOA\psjoa.jar.

The CLASSPATH environment variable on the BizTalk server can be updated to include the location of the psjoa.jar file. For instructions on this process, see Updating Environment Variables in the appendix. Updating the CLASSPATH is optional, however, if you decide not to set this value you must populate the PeopleSoft 8x JAR Files parameter of your send port’s transport properties. The recommended approach is to populate the value in the transport properties.

User Name

The user’s login name used to access the PeopleSoft system.

This is required only if you are not using SSO.

In addition to the required parameters, there are several other transport type options that you can modify based on your communication needs. The database date format is specific to the PeopleSoft adapter while the others are common to BizTalk send ports.

Table 2: Transport properties

Transport Property Description / Example

Database date format

When a date is used as a key value, it has a different format. The default format is YYYY-MM-DD.

Max Concurrent Calls

This value specifies the maximum number of concurrent calls that can be made on this send port. If the number of calls exceeds this value, the additional requests will become dehydrated until processing threads become available. –1 indicates an unlimited number of calls.

Maximum number of sessions

This determines the maximum number of sessions that can be connected to the server at one time.

Event Log Level

This is the level of events that are to be recorded as they are encountered. The default value is Error. Possible values are Info, Warning, and Error.

Refresh Agent

When Yes is selected, the runtimeagent.exe and the browsingagent.exe processes will be restarted automatically as required.

Affiliate Application

This value is created by Enterprise Single Sign-On tools and is used to represent an external application. The user credentials are stored in the SSO Credential database.

Use SSO – This value determines whether SSO is to be used or not.

Sessions relate to the way in which a client connects to the server. For example, if the login credentials are the same, they use the same session. Concurrent calls relate to the number of simultaneous connections that can be made to a server at a time. You may need to limit the number of sessions based on the number of client licenses, whereas the number of concurrent calls impacts performance and is determined by back-end processing capabilities.

Setting Pipelines

The PeopleSoft adapter requires that the send and receive pipelines use the default XML pipelines of XML Transmit and XML Receive respectively.

Component Interfaces

The PeopleSoft LOB adapter contains a set of standard methods used to communicate with the PeopleSoft Component Interfaces. The methods are Get, CreateEx, Find, DeleteOnly, and UpdateEx.

CreateEx

The CreateEx method is available whenever the Create and Save functions of the PeopleSoft Component Interface are enabled. This method creates a new record based on a set of keys and properties. The syntax for this method is CreateEx(key1, key2, key3, …, keyn, interactivemode, properties).

  • keyn parameters: The keys are the in or out parameters defined by the Component Interface. The values placed into key parameters represent values within the database that will uniquely identify records in the database.
  • interactivemode is used primarily for error handling. The PeopleSoft LOB adapter executes a variety of API calls that interact with the Component Interface. However, instead of calling each API individually, the psjoa.jar file packages all the calls inside a single transaction. When the interactive mode is set to TRUE, each call is executed individually. This allows a more granular level of detail when an error occurs. The error indicates exactly which field caused the error to occur.
  • properties represents a single collection of values that contains all of the property information for a specific PeopleSoft Component Interface. As the record is created, these properties are created along with the record.

You may not always know the specific key values when executing the CreateEx method. In some cases, you will create the record without knowing the next sequential number to provide. Instead, you can pass a value of NEXT and receive the value generated in one of the out keys.

DeleteOnly

The DeleteOnly method removes items from a collection. The syntax for this method is DeleteOnly(key1, key2, key3, …, keyn, correctionmode, interactivemode, properties).

  • keyn parameters: These keys are used to uniquely identify an item as defined by the PeopleSoft Component Interface. The key’s values must exist in the database.
  • correctionmode, when set to TRUE, allows you to remove data that has an effective date on or before the current effective date. Otherwise, any attempts to delete these records will result in an error.
    Bb820917.note(en-US,BTS.10).gifNote
    It is recommended that correctionmode be set to FALSE in the production environment to preserve the audit trail.

  • interactivemode and properties act similarly as described above.

UpdateEx

The UpdateEx method is available whenever the Get and Save functions of the PeopleSoft Component Interface are enabled. This method is used to update property values for a given set of keys. The syntax for this method is UpdateEx(key1, key2, key3, …, keyn, correctionmode, interactivemode, properties).

  • keyn parameters: These keys are used to uniquely identify an item as defined by the Component Interface. The key’s values must exist in the database.
  • correctionmode and interactivemode act similarly as described above.
  • properties represents a single collection of values that contains all of the property information for a specific PeopleSoft Component Interface. The properties used when calling this method actually replace the existing values. In essence, the current values are deleted from the record and the new values are associated.

Find

The Find method is available when the Get function of the PeopleSoft Component Interface is enabled. The Find method is used to return a list of keys based on the value of the partial key. The syntax for this method is Find(partialkey, keylist).

  • partialkey is a value used to match against existing keys. This allows for wildcard search capabilities similar to those in the PeopleSoft application. For example: “AB” would return a list of keys beginning with “AB” and “%AB” would return a list of keys containing “AB”.
  • keylist is simply a list of keys that match the partial key’s search criteria.

It is important to note that any search resulting in more than 300 keys will return an error. This is a limitation of the PeopleSoft server.

Get

The Get method is available when the Get function of the PeopleSoft Component Interface is enabled. The Get method is used to return the properties of a record for a particular set of keys. The syntax for this method is Get(key1, key2, key3, …, keyn, properties) or Get(key1, key2, key3, …, keyn, gethistoryitems, properties).

  • keyn parameters: These keys are used to uniquely identify an item as defined by the PeopleSoft Component Interface. The key’s values must exist in the database.
  • properties acts similarly as described above. These values are returned by the call.
  • gethistoryitems, when set to TRUE, causes all items, regardless of effective date, to be returned. If the value is FALSE, only items with current and future effective dates are returned.

Custom Component Interfaces

In addition to the PeopleSoft Component Interfaces and their predefined methods, the PeopleSoft LOB adapter also supports the ability to execute user-defined methods of a PeopleSoft Component Interface. The syntax for this call is myRet=myCI.myMethod(parameter1, parameter2, parameter3, …, parameter), where myRet is the return value and the parameters are the input values.

When this option is used, only a scalar value can be returned from the method. To invoke the custom method, the Get function must be enabled on the Component Interface. Furthermore, custom methods will not work if the Component Interface has keys. There is a potential workaround if your target Component Interface has keys and you require a custom method. One way is to create a new Component Interface to accept the necessary parameters. Next call the target method.

Metadata Generation

After a PeopleSoft LOB adapter send port has been created and configured, and the necessary PeopleSoft Component Interfaces have been identified, you can use the Add Adapter Wizard to add the necessary schema(s) to your BizTalk project. Metadata defines the structure in which data will be interfaced with PeopleSoft. The Add Adapter Metadata Wizard generates the XML schema for a given PeopleSoft Component Interface.

From within your BizTalk project, you can access the Add Adapter Metadata Wizard by clicking Add Generated Items on the Project menu. From here, you select the Add Adapter Metadata schema files node on the left side of the dialog box (Figure 16) and the Add Adapter Metadata option on the right side of the dialog box. After you are prompted with the Add Adapter Wizard screen (Figure 17), you select the PeopleSoft Enterprise® adapter from the list provided. The SQL Server and Database values are specific to your BizTalk configuration. The Port list displays only a list of ports configured to use the registered adapter you selected, in this case the PeopleSoft Enterprise® adapter, which appears only after you configure the send port as described in the previous section.

Figure 16: Add Generated Items
Bb820917.b1231fd4-23c7-468b-998a-976d61c2eae8(en-US,BTS.10).gif

If you determine you need to alter (or add) the configuration of the send port, you must exit the wizard before changes will take effect.

Figure 17: Add Adapter Wizard – adapter selection
Bb820917.b857fe67-8d8c-4c28-ac92-87191eb53124(en-US,BTS.10).gif

After you have selected the necessary adapter and port information, you will be presented with a list of PeopleSoft Component Interfaces, as shown in Figure 18. The Add Adapter Wizard refers to the PeopleSoft Component Interfaces as “services” because this wizard is used for multiple LOB adapters. You can select as many PeopleSoft Component Interfaces as required (you must select at least one).

Figure 18: Add Adapter Wizard - Component Interface selection
Bb820917.5da937e0-06e7-4c2d-a87b-59ce0cd371aa(en-US,BTS.10).gif

After the PeopleSoft Component Interfaces have been selected, the Add Adapter Metadata Wizard begins generating XML schemas that define the format for data interchange.

Typically, for each PeopleSoft Component Interface selected, two schema files are created—object-level definition and API metadata definition.

The object-level definition XSD (for example, USER_PROFILEService_obj.xsd) is a schema that contains any object-level definitions and is referenced in the import collection of the primary schema.

Figure 19: Object-level definition schema
Bb820917.7c529e60-4dab-47da-930b-b6634693b57e(en-US,BTS.10).gif

The API metadata definition XSD (for example, USER_PROFILEService_USER_PROFILE_x5d.xsd) is the primary schema for the Component Interface, and contains multiple root-level nodes that expose the various APIs and methods available to the PeopleSoft Component Interface.

Figure 20: API metadata schema
Bb820917.76563993-268d-4822-a750-4aeeed8429c6(en-US,BTS.10).gif

Orchestrations vs. Content-Based Routing

Due to the nature of the PeopleSoft Component Interfaces, it is common for multiple synchronous transactions to be executed for a single integration. For best performance, it is recommended to use Content-Based Routing (CBR) to avoid the overhead produced by orchestrations. CBR allows you to transmit messages based solely on the properties of the message or ports. However, when using CBR it becomes difficult to encapsulate the complete integration inside a single transaction. Without the use of transaction-based integration, you lose a level of error handling that is required to ensure data is properly sent and received, possibly multiple times, during the interface.

By using orchestrations, you can better control the flow of data and easily capture and handle any errors that may occur. Orchestrations also provide the ability to use a Scope shape, which simulates a try/catch block. As shown in Figure 21, scopes can have multiple exception handlers that allow you to take a specific course of action based on the error encountered.

Figure 21: Sample orchestration with multiple exception handlers
Bb820917.63bf8452-6e29-4a49-a2a0-bfbae1dae145(en-US,BTS.10).gif

Integration Example

This example attempts to demonstrate a simple process that uses the PeopleSoft LOB adapter to update a user’s profile. This process is roughly outlined in Figure 22.

The Component Interface used is PeopleSoft’s User Profile service. In addition to the standard methods, the Component Interface provides the ability to set a user’s description, set a user’s password, and reset a user’s password. In this example, the orchestration receives a PeopleSoft user ID, an updated e-mail address, and effective dates in the form of an XML file. The orchestration transforms the inbound message to a valid Get request and sends it to a send port configured for the PeopleSoft LOB adapter. The send port executes the request and returns a response from the method. The response message is evaluated to ensure the requested data change is different and outside the current effective dates. If the comparison is successful, the inbound message is transformed to a valid UpdateEx request and sent to the send port. Once more, the send port executes the request and returns a response from the method. The response message is then written to an archive file. If the comparison is unsuccessful, the process is stopped.

Figure 22: Process flow chart
Bb820917.e315244a-419e-453f-8c5b-a1f4865120de(en-US,BTS.10).gif

This example requires the use of an orchestration because both the embedded business logic and the need for error handling occur. By implementing a Scope shape, we can catch and manage any exceptions that may occur. It is also possible for both of the PeopleSoft-bound messages to use the same send port by using multiple send port operations. This allows messages of multiple types to be processed by using a single send port configuration. Furthermore, any message faults that may occur will be handled by the scope’s exception block. In this example, the errors will be written to an error file.

Figure 23 shows the orchestration for the example.

Figure 23: Sample orchestration
Bb820917.a153e942-d540-4db4-aef3-b1518c3aba33(en-US,BTS.10).gif

Integration with and between ERP systems is commonplace in today’s businesses, especially with the proliferation of acquisitions. The power of BizTalk Server can be harnessed to accomplish this task.

Throughout the course of this white paper we have discussed various topics from general ERP system integration practices to a specific integration solution using the PeopleSoft LOB adapter. The PeopleSoft ERP system provides multiple integration points that are available via BizTalk Server, including File, FTP, HTTP, SOAP, Database, and of course the PeopleSoft LOB adapter. The benefits of using the PeopleSoft LOB adapter include direct communication with the PeopleSoft application server, execution of the Component Interfaces, and limited dependency on an LOB expert. When choosing an integration strategy, it is important not to force a common solution onto all scenarios regardless of requirements. Some integrations are better suited for the “out-of-the-box” adapters while others require the PeopleSoft LOB adapter. In some cases, you will use a combination of these adapters. Furthermore, a majority of integrations will require the use of transactional processes. In these cases, the use of an orchestration is necessary. However, in the rare event that a transaction is not needed, CBR can be used.

For more information about using the PeopleSoft LOB adapter, visit the MSDN® Web site at http://go.microsoft.com/fwlink/?LinkId=101312.

Glossary of Terms

Term Definition

Line of Business (LOB) system

An application used in business.

Enterprise Resource Planning (ERP) system

A software package used by a company to manage important parts of its business. An ERP package can be considered a type of LOB system.

Content-Based Routing (CBR)

CBR is a mechanism for routing messages based solely on their properties. By using this publish/subscribe model, messages can be delivered to any number of send ports without requiring the additional overhead and resources used by orchestrations.

Common Errors

The following table lists common errors for Microsoft® BizTalk® Adapter v1.0 for PeopleSoft Enterprise®.

Error Number and Message (in Event Log) Resolution

E-JNI0004 - No psjoa.jar.

A Java exception occurred.

The adapter was unable to locate the PeopleSoft psjoa.jar file.

See Updating Environment Variables in the appendix.

E-PSFT0030 No psjoa.jar.

Failed to instantiate Component Interface Beans.

The Adapter was unable to locate the PeopleSoft psjoa.jar file.

See Updating Environment Variables in the appendix.

E-PSFT0019 Wrong server name.

Connection to PeopleSoft Application Server failed.

Check to ensure the proper PeopleSoft host, port, and credentials are being used.

Bb820917.note(en-US,BTS.10).gifNote
These values are case-sensitive.

E-PSFT0024 Wrong User Name and Password.

Connection failed. Error Message: JavaClient is an Invalid User name, or you typed the wrong password.

Check to ensure the proper PeopleSoft user name and password are being used.

Bb820917.note(en-US,BTS.10).gifNote
These values are case-sensitive.

E-PSFT0040: Missing key in metadata for

Collection XX.

A key must exist for a collection (to index different members of the collection). You can verify your data by looking at the XSD; if you see a collection, for example, XX contains only YY, which is not a key—an error message is generated.

Null Date Output format differs in

Get.xml for Job data. The Date output defaults to

"0001-01-01" when there is no input from the User.

The adapter is hard coded for null dates.

Use BizTalk Mapper to replace 0001-01-01 date with Null.

Limitations

  • The APIs associated to the PeopleSoft Component Interfaces provide limited functionality and often require multiple API calls to perform even basic data transactions.
  • Most of the API calls allow you to insert or update only a single record at a time, requiring even more transactions to be performed.
  • It is not likely that a BizTalk Server expert would also be proficient in PeopleSoft. Therefore, you will find that in order to successfully communicate and integrate with PeopleSoft, a PeopleSoft system developer and/or administrator will be required.
  • The Find method can only return up to 300 results. Any query resulting in more than 300 keys will return an error. This is a known limitation of the PeopleSoft server.

Known Issues

There is a known issue for PeopleSoft version 8.17.02. Although the adapter can read data from the PeopleSoft server without issue, the adapter cannot create or update properties with collections. PeopleSoft expects this problem to be resolved in version 8.18.

Updating Environment Variables

Use the following procedure to update environment variables.

To update your environment variables on Windows® XP or Windows 2000
  1. Open Control Panel.

  2. Click the System icon.

  3. Click the Advanced tab.

  4. Click Environment Variables.

  5. To update the Path variable:

    1. Find the Path variable in the list of System Variables.
    2. Click Edit.
    3. Append the desired value to the existing Variable value. Values should be separated by a semicolon (;).
      Example: C:\j2sdk1.4.2_08
  6. To update the CLASSPATH variable:

    1. Find the CLASSPATH variable in the list of System Variables.
    2. Click Edit.
    3. Append the desired value to the existing Variable value. Values should be separated by a semicolon (;).
      Example: C:\PeopleSoft\psjoa.jar or
      \\<PeopleSoft Server>\web\psjoa\psjoa.jar

Configuring the PeopleSoft Application Server

The following sections provide step-by-step instructions for performing the necessary configuration of the PeopleSoft server.

Creating a PeopleSoft Component Interface

Use the following procedure to create a PeopleSoft Component Interface.

To create a PeopleSoft Component Interface
  1. Sign in to Application Designer.

  2. Select File, New in Application Designer.
    The New dialog box appears.

  3. Select Component Interface and click OK.

  4. Click Select.

    A list of all components appears.

  5. Select the Component Interface that contains no keys, for example, INSTALLATION_RS.

  6. Click Select.

    You have now loaded a component.

  7. Select File, Save As.

  8. Enter GET_CI_INFO in the input box and click OK.

  9. Right-click any method of your new Component Interface.

    A menu appears.

  10. Select the View PeopleCode item.
    A window appears.

  11. Copy and paste the content of <install_directory>\config\PeopleSoft\get_ci_info.pc into that window.

  12. Select File, Save.

  13. Close Application Designer.

Setting the PeopleSoft Component Interface Security

Use the following procedure to set the PeopleSoft Component Interface security.

To set the PeopleSoft Component Interface security
  1. Sign in to PeopleSoft Internet Architecture.

  2. Select PeopleTools, Security, Permissions & Roles, Permission Lists.

  3. Click Search, select the relevant Permission List, and click the appropriate list hyperlink.

    The Permission List pane opens on the right.

  4. Click the right arrow next to the Sign-on Times tab to display the Component Interfaces tab.

  5. Click the Component Interfaces tab.

  6. Click the + button to add a new row to the Component Interfaces list.

  7. Select the GET_CI_INFO component interface and click Edit.

  8. Click Full Access (All) to set the methods to Full Access.

  9. Click OK.

  10. Scroll down to the bottom of the Component Interfaces window and click Save.

  11. Select PeopleTools, Security, Permissions & Roles, Roles.

  12. Click Search, select the relevant Role and click the appropriate list hyperlink.

  13. The Role pane opens on the right.

  14. Click the Permission List tab.

  15. Click the + button to add a new row to the Permission List.

  16. Select the GET_CI_INFO Permission List.

  17. Scroll down to the bottom of the Roles window and click Save. [Save as GET_CI_ROLE]

  18. Select PeopleTools, Security, User Profiles, User Profiles.

  19. Click Add New Value, type BizTalk into the text box, and click Add to display the General tab

  20. Select a Symbolic ID in the drop-down box.

  21. Type a Password and Confirm Password.

  22. Choose an appropriate Navigator Homepage.

  23. Choose an appropriate Process Profile.

  24. Choose an appropriate Primary Permission List for the Primary field.

  25. Choose an appropriate Row Security Permission List for the Row Security field.

  26. Click the Roles tab.

  27. Click the + button to add a new row to the Roles list.

  28. Select the GET_CI_INFO Role.

  29. Select the PeopleSoft User Role.

  30. Select the Standard Non-Page Permissions Role.

  31. Scroll down to the bottom of the User Profile window and click Save.

Testing the PeopleSoft Component Interface

Use the following procedure to test the PeopleSoft Component Interface.

To test the PeopleSoft Component Interface
  1. Start Application Designer.

  2. Click File, Open and select Definition = Component Interface.

  3. Select GET_CI_INFO CI from the list of Component Interfaces.

  4. After opening GET_CI_INFO, right-click anywhere in the right pane of your Component Interface definition and select Test Component Interface.

    The Component Interface Tester dialog box appears.

  5. GET_CI_INFO should not contain any keys. If keys are present, you need to return to Application Designer and remove them.

Brian Jones is a solutions architect for HCL EAI Services, Inc. He holds a BS in Computer Information Systems from Troy University. Brian has been in the Information Technology industry for 12 years and has been working with BizTalk Server 2004 and 2006 since the beginning.

Jay Lee is a Partner and Chief Technologist at Anaheim-based eBI Solutions, LLC where he and his team help customers succeed in their business and IT initiatives in Enterprise Application Integration (EAI), Business-to-Business Integration (B2Bi), Business Process Management (BPM), and Business Intelligence. Jay holds a BA in Physics from UCLA and is pursuing an MBA at the Marshall School of Business at USC. He is a member of the Microsoft BizTalk Virtual Technical Specialist team. He speaks, writes, and trains regularly on topics related to BizTalk Server architecture, development, and administration. Jay lives with his wife Emily in Orange County, CA.

Mark Michaelis is the owner of intelliTechture, a small business dedicated to training and consulting in Microsoft technologies as well as the IDesign architect specializing in WCF and VSTS. Mark was recognized by Microsoft as a Microsoft MVP for Visual Studio Team System and he wrote the official courseware for VSTS for Microsoft. Mark holds an MS in Computer Science from the Illinois Institute of Technology and he serves on several Microsoft Software Design Review teams including WCF, C#, and VSTS. Mark speaks at developer conferences both nationally and internationally and has written several articles and books, in addition to maintaining a blog (http://mark.michaelis.net/blog). His recent book is Essential C# 2.0 (Addison-Wesley, 2006).

Show:
© 2014 Microsoft