Adapter for PeopleSoft CRM CIC

Requirements

How the Adapter for PeopleSoft CRM CIC Works

Use the Adapter for PeopleSoft CRM CIC to read or write data to your PeopleSoft CRM CIC system. Your customer input XML document specifies the operation and the field or record on which you want to operate, and the Adapter for PeopleSoft CRM CIC translates this to PeopleSoft CRM CIC requests.

For example, you have customer information stored in PeopleSoft CRM CIC. To provide the marketing department with the customer address information from the PeopleSoft CRM CIC system, you can access the information within a business process in Sterling B2B Integrator using the Adapter for PeopleSoft CRM CIC to read this information and return it in the form of an XML output file.

Data Structure and the Adapter for PeopleSoft CRM CIC

The Adapter for PeopleSoft CRM CIC operates on data and records contained in objects on a PeopleSoft CRM CIC server. Do not use the adapter to change the underlying structure of those objects.

The Adapter for PeopleSoft CRM CIC operates on the logical view of the PeopleSoft CRM CIC data as supplied by the VanAPI-Java Technology Edition (JTE). The VanAPI library contains public C-style functions that establish a connection to the PeopleSoft CRM CIC server and manipulate the data in a PeopleSoft CRM CIC application database.

Object Hierarchy

The following figure shows an example of object relationships in the PeopleSoft CRM CIC client: One main object, company, contains one related object, contact. Company contains two child objects, address and territory coverage. In addition, contact contains one related object, opportunity, and two child objects, address and category. Opportunity contains one child object.

Object Type

An object type represents a real world entity or logical concept that is essential for a business organization. An object type can be an account or company. All records in the PeopleSoft CRM CIC system have an associated object type.

Record Set or Record

A record set contains instances of an object type. A record is accessed through a record set, and is one instance of an object type (main, related, or child). For example, an instance of the object type company is a record that could contain the data for Acme, Inc. The data contained by this record is in fields.

Field

A field is the lowest container of data in the hierarchy, and represents a single element. A record can contain one or more fields. For example, in the Acme, Inc. record, one field might contain the number of employees. The Adapter for PeopleSoft CRM CIC enables creating, reading, updating, or deleting values in the fields.

Adapter for PeopleSoft CRM CIC Operations

The operations supported by the Adapter for PeopleSoft CRM CIC are create, read, update, and delete (CRUD). To operate on an object type, you need to specify an object path. In the object path, specify all object types by their labels, which correspond to the labels in the PeopleSoft CRM CIC client interface. For example, if you want to update a customer address record, you must specify the customer object and the address object.

The object element maps to the model hierarchy. Element object.1 is always a main object, and the nested object elements can be either child or related objects. If an element represents a child object, then it cannot have an object element as its child.

Field Tag – Defines the fields to be created, searched (read), updated, or deleted. Field tags are included on only the lowest-level object.

XML tags that occur multiple times in a document must be unique if they require fixed data from the DTD. To make the tags unique, append a period (.) and a number after the tag.

Create

The create operation creates a record, which can be a main, related, or child object. The operation attribute of the request element must be Create. The create operation creates records on only one object type at a time. For example, in the following XML, although you can specify both Customer and Addresses, you can create records only on the lowest level object, in this case, Addresses. If you want to create a customer, which has customer addresses, you must perform separate operations for these object types.

The name attribute represents the display label of the columns to write data to. You can write more than one field from the lowest-level object in each create operation.

The following XML example shows a create operation for a Customer Address record. The Customer object has search criteria that specify on which customer object or objects the address record will be added. The Customer search criteria set the phone number to 799-4721.

<PS_CRMAdapter>
   <request operation="Create">
       <object.1 label="CUSTOMER">
    	<search.1 field="Phone" operator="=">799-4721</search.1>
           <object.2 label="Addresses">
               <field.1 name="Type">Ship To</field.1>
     		   		<field.2 name="City">Aspen</field.2>
     		   <field.3 name="State/Province">CO</field.3>
           </object.2>
         </object.1>
   </request> 
</PS_CRMAdapter>

The response for the create operation does not have result records. The status attribute indicates whether the operation succeeded or failed. The statusText attributes provide the number of records created if the operation succeeded or a detailed error message if the operation failed.

The following XML shows a create response:

<PS_CRMAdapter>
	<results status="success" statusText="2 Record(s) Created."/> 
</PS_CRMAdapter>

Read

The operation attribute of the request element must be Read. The read operation reads data from the field level and one object type at a time. For example, in the following XML example, you cannot read data for both Customer and Addresses; you can read data only for the lowest-level object, which is Addresses.

The name attribute represents the display label of the columns to read data from. You can read more than one field from the lowest-level object in each read operation.

The following XML example shows a read operation for the city and state/province information of the Mail To address from the customer whose phone number is 555-1234.

<PS_CRMAdapter>
	<request operation="Read">
		<object.1 label="CUSTOMER">
			<search.1 field="Phone" operator="=">555-1234</search.1>
			<object.2 label="Addresses">
				<search.2 field="Type" operator="=">Mail To</search.2>
				<field.1 name="City"/>
				<field.2 name="State/Province"/>
			</object.2>
		</object.1>
	</request> 
</PS_CRMAdapter>

The following XML example shows the status attribute report for a successful read operation. Each of the result elements is a record returned from the read operation. The field elements are the same as those in the request XML, except the values are the data returned from the read operation.

<PS_CRMAdapter>
	<results status ="success" statusText="2 Record(s) Read.">
		<result>
			<field.1 name="City">Dublin</field.1>
			<field.2 name="State/Province">OH</field.2>
		</result>
		<result>				
			<field.1 name="City">Denver</field.1>
			<field.2 name="State/Province">CO</field.2>
		</result>
	</results> 
</PS_CRMAdapter>

Update

The update operation enables you to modify fields in a record. The operation attribute of the request element must be Update. Provide search criteria to select the records on which you want to operate.

The update operation updates data for only one object type at a time. For example, in the following XML, although you can specify search criteria for both Customer and Addresses, you can update data on only the lowest-level object, which is Addresses.

The name attribute represents the display label of the columns to update data. The user can update more than one field from the lowest-level object in each update operation.

The following XML example shows an update operation for the city and state/province information of the Mail To address for the customer whose phone number is 555-1234 and who has an address type set to Mail To.

<PS_CRMAdapter>
	<request operation="Update">
		<object.1 label="CUSTOMER">
			<search.1 field="Phone" operator="=">555-1234</search.1>
			<object.2 label="Addresses">
					<search.2 field="Type" operator="=">Mail To</search.2>
				<field.1 name="City">Aspen<field.1>
				<field.2 name="State/Province">CO</field.2>
			</object.2>
		</object.1>
	</request> 
</PS_CRMAdapter>

The response for the update operation does not have any result records and is the same as a response from the create and delete operation.

Delete

The delete operation enables you to delete PeopleSoft CRM CIC records. You provide the search criteria to select the records to delete. The operation attribute of the request element must be Delete.

The following XML example shows a delete operation for address records. Each address record is a child of a customer with the phone number 799-4721 and an address type set to Mail To. The address records are deleted in this operation.

<PS_CRMAdapter>
	<request operation="Delete">
	<object.1 label="CUSTOMER">
	<search.1 field="Phone" operator="=">799-4721</search.1>
		<object.2 label="Addresses">
 	 <search.2 field="Type" operator="=">Mail To</search.2>
	</object.2>
	</object.1>
	</request> 
</PS_CRMAdapter>

The response for the delete operation does not have any result records.

Building Adapter for PeopleSoft CRM CIC DTDs

You must create DTDs for your operations if you want to use the Translation service. There are five different types of DTDs, one for each operation (create, read, update, and delete) and one for the response document. Create a DTD for each object type you want to operate on, because only one object type can be operated on at a time. For example, you might have one DTD for customer (main object), but if you want to operate on customer address (child object), you need to create a separate DTD.

Input DTDs

A DTD is required for the Translation service to translate the Adapter for PeopleSoft CRM CIC input XML document to and from other documents.

<?xml version='1.0' encoding='UTF-8'?>
<!ELEMENT PS_CRMAdapter (request)> 
<!ELEMENT request (object.1)> 
<!ATTLIST request operation CDATA #FIXED "Read"> 
<!ELEMENT object.1 (search.1, object.2)> 
<!ATTLIST object.1 label CDATA #FIXED "CUSTOMER">
<!ELEMENT search.1 (#PCDATA)> 
<!ATTLIST search.1 field CDATA #FIXED "Name" operator CDATA #FIXED "=">
<!ELEMENT object.2 (field.1, field.2?)> 
<!ATTLIST object.2 label CDATA #FIXED "ADDRESSES">
<!ELEMENT field.1 EMPTY> 
<!ATTLIST field.1 name CDATA #FIXED "Street1">
<!ELEMENT field.2 EMPTY> 
<!ATTLIST field.2 name CDATA #FIXED "Street2"> 
Output DTDs 
The results tag contains the results for the operation being performed. For more 
information, see Error Messages. The following XML example shows an output
DTD for reading fields on a child object, customer address. 
The result returns one to many records, each containing two fields, Street 1 and
Street 2. 
<?xml version='1.0' encoding='UTF-8' ?>
<!ELEMENT PS_CRMAdapter (results)> 
<!ELEMENT results (result*)> 
<!ATTLIST results status CDATA #IMPLIED
      	      statusText CDATA #IMPLIED > 
<!ELEMENT result (field.1, field.2)> 
<!ELEMENT field.1 (#PCDATA)> 
<!ATTLIST field.1 name CDATA #FIXED "Street1">
<!ELEMENT field.2 (#PCDATA)> 
<!ATTLIST field.2 name CDATA #FIXED "Street2">

Error Messages

The response XML returns a status message in the form of success or failure. In some cases, an advanced status message (called statusText in DTD) is returned. The following table describes the advanced status messages:

Implementing the Adapter for PeopleSoft CRM CIC

Installing the Adapter for PeopleSoft CRM CIC

To install the Adapter for PeopleSoft CRM CIC, run the install3rdParty.sh script to install the required PeopleSoft CRM CIC .jar file (vanjavi.jar) and shared libraries.

The Adapter for PeopleSoft CRM CIC requires operating system-specific shared libraries. The supported operating systems are Solaris™, HP-UX, and AIX.

Contact IBM® Customer Support for a custom installation of the Adapter for PeopleSoft CRM CIC for your platform version.

Pass the absolute path for the library files to the install3rdParty.sh script.

For the PeopleSoft CRM CIC .jar files, run the following script from the folder where you have Sterling B2B Integrator installed:

./install3rdParty.sh <Vendor> <Version> -j <location of 
         the .jar>

The following figure shows an example of the script for the PeopleSoft CRM CIC .jar files:

./install3rdParty.sh PeopleSoftCRM 9.0 -j /home/PeopleSoftCRM/vanjavi.jar

For the PeopleSoft CRM CIC shared libraries, run:

./install3rdParty.sh <Vendor> <Version> -l <location of 
         the lib>

The following figure shows an example of the script for the PeopleSoft CRM CIC shared libraries:

./install3rdParty.sh PeopleSoftCRM 9.0 -l /home/PeopleSoftCRM/solaris
                                                  /vanjavi.so

Configuring the Adapter for PeopleSoft CRM CIC for Sterling B2B Integrator

The following table describes the fields used to configure the Adapter for PeopleSoft CRM CIC in Sterling B2B Integrator:

Connection Management

The PeopleSoft CRM CIC system cannot handle multiple users with the same login parameters accessing PeopleSoft CRM CIC simultaneously. The Adapter for PeopleSoft CRM CIC uses a connection management component that operates on the premise that each Adapter for PeopleSoft CRM CIC should connect to a different PeopleSoft CRM CIC system. If a connection to PeopleSoft CRM CIC is in use for the specified login name and password combination, a new request is delayed until the business process using the existing connection is finished. The Adapter for PeopleSoft CRM CIC returns an error if the business process has not finished using the connection before the connection wait timeout period has expired.

Both trusted and default connections are opened when requested, if not already open. An open connection is closed after the idle timeout period has expired, or when the connection is idle and a new connection needs to be opened.

Business Process Examples

The Adapter for PeopleSoft CRM CIC can be invoked from a business process, as shown in the following example:

<operation name="PeopleSoft CRM "> 
      <participant name="PSCRMTestAdapter"/> 
     <output message="outputMessage"> 
         <assign to="." from="*"></assign> 
     </output> 
      <input message="inputMessage"> 
         <assign to="." from="*"></assign> 
     </input> 
</operation> 

You can also pass in values for login and password to overwrite the default login and password to conduct operations that require more privileges. Following is an example of a business process document with user specified login and password:

<process name="PSCRMAdapter_Joe"> 
  <sequence> 
   <operation name=" PeopleSoft CRM "> 
     <participant name=" PSCRMTestAdapter "/> 
     <output message="outputMessage"> 
       <assign to="Login">Joe</assign> 
       <assign to="Password">12345</assign> 
       <assign to="." from="*"></assign> 
     </output> 
      <input message="inputMessage"> 
       <assign to="." from="*"></assign> 
     </input> 
    </operation> 
 
 </sequence> 
</process>