Application Integration Framework

Accessing Maps Using Web Services

This chapter provides an overview of Application Integration Framework web services and discusses:

EOTF_DVM Service.
EOTF_XREF Service.
Cross-Reference lookup web service example.

Understanding Application Integration Framework Web Services

Application Integration Framework web services provide external applications a web-service-based means of accessing Application Integration Framework map information. Web services are implemented by means of the PeopleTools Integration Broker (IB) framework. The Integration Gateway web application receives all the web service requests and forwards them to the Integration Engine (application server) for processing.

This diagram illustrates an external application using the cross-reference lookup web service to look up values in an Application Integration Framework cross-reference map.

Using Application Integration Framework web service with an external application

The external application invokes one of the web service operations.
PeopleSoft Integration Broker receives the service operation and validates the WS security credentials.
The request is passed to the application server for processing. The application server authenticates the service operation and routes it to the respective handler. The handler runs the PeopleCode and sends the response to the Integration Gateway.
Integration Broker sends the response to the external application.

EOTF_DVM Service

This section describes the Service Operations available as web services for DVM:

EOTF_DVM_LOOKUP
EOTF_DVM_IMPORT.v2
EOTF_DVM_IMPORT.v1

EOTF_DVM_LOOKUP

This service operation is used to lookup values from a DVM.

Alias: dvmLookupValue

Type: Synchronous

Request Message: EOTF_DVM_LOOKUP_REQ.V1

This is an example of the soap body for the request:

<soapenv:Body>
      <dvm:dvmLookupValue>
         <dvm:mapname>?</dvm:mapname>
         <!--2 or more repetitions:-->
         <dvm:Values>
            <dvm:domain>?</dvm:domain>
            <!--1 or more repetitions:-->
            <dvm:element name="?"/>
         </dvm:Values>
         <dvm:Values>
            <dvm:domain>?</dvm:domain>
            <!--1 or more repetitions:-->
            <dvm:element name="?"/>
         </dvm:Values>
         <dvm:targetDomain>?</dvm:targetDomain>
      </dvm:dvmLookupValue>
   </soapenv:Body>

Element Name	Description
mapname	The name of the domain value map to lookup values in.
Values	This element holds the elements and values to be found in the DVM.
domain	The name of the target domain provided on the lookup request.
element	Represents a DVM element and its value.
targetDomain	The name of the domain the lookup request should return values for.

Response Message: EOTF_DVM_RESPONSE.V1

Element Name	Description
status	The status of the operation. Returns Success or Exception.
reason	If there is an exception, the reason will be returned.
requestValues	This element hold the reference values used for a lookup operation. For partially qualified lookups these values may differ from the values provided in the request.
domain	The name of the reference domain provided on the lookup request.
element	The DVM element and its value.
responseValues	The values returned for the lookup operation.
domain	The name of the target domain provided on the lookup request.
element	The DVM element in the target domain and its value.

EOTF_DVM_IMPORT.v2

Use this service operation to import a Domain Value Map definition and values into the Enterprise Transformation Framework, based on the PeopleSoft schema.

Type: Asynchronous-One Way.

Alias: import_dvm

Default: Yes

Request Message: EOTF_DVM.V2

This is an example of the soap body for an import request using PeopleSoft schema:

<soapenv:Body>
      <dvm:dvm>
         <dvm:name>?</dvm:name>
         <!--Optional:-->
         <dvm:description>?</dvm:description>
         <!--Optional:-->
         <dvm:comments>?</dvm:comments>
         <dvm:elements>
            <!--2 or more repetitions:-->
            <dvm:element name="?" order="?" dataType="string" dataLength="?"⇒
 isCommon="false"/>
            <dvm:element name="?" order="?" dataType="string" dataLength="?"⇒
 isCommon="false"/>
         </dvm:elements>
         <dvm:domains>
            <!--1 or more repetitions:-->
            <dvm:domain name="?">
               <!--1 or more repetitions:-->
               <dvm:element name="?" qualifier="false"/>
            </dvm:domain>
         </dvm:domains>
         <!--Optional:-->
         <dvm:rows>
            <!--1 or more repetitions:-->
            <dvm:row>
               <!--2 or more repetitions:-->
               <dvm:cell>?</dvm:cell>
               <dvm:cell>?</dvm:cell>
            </dvm:row>
         </dvm:rows>
      </dvm:dvm>
   </soapenv:Body>

Element Name	Description
description	The DVM description. Optional
comments	Comments about the DVM. Optional
elements	This element holds the DVM's element list.
element	Represents a DVM element.
domains	This elements holds the DVM's domain list.
domain	This element represents a domain in a DVM.
element	This represents an element in the DVM domain.
rows	This represents all the rows of data in the DVM.
row	Each DVM row of values.
cell	This is the value for this row and the for each element in the same order as defined in elements.

EOTF_DVM_IMPORT.v1

Use this service operation to import a Domain Value Map definition and values into the Enterprise Transformation Framework, based on the FMW schema.

Type: Asynchronous-One Way.

Alias: import_dvm

Default: No

Request Message: EOTF_DVM.V1

This is an example of the soap body for an import request using FMW schema:

<soapenv:Body>
      <dvm:dvm name="?">
         <!--Optional:-->
         <dvm:description>?</dvm:description>
         <dvm:columns>
            <!--2 or more repetitions:-->
            <dvm:column name="?" qualifier="false" order="?"/>
            <dvm:column name="?" qualifier="false" order="?"/>
         </dvm:columns>
         <!--Optional:-->
         <dvm:rows>
            <!--1 or more repetitions:-->
            <dvm:row>
               <!--2 or more repetitions:-->
               <dvm:cell>?</dvm:cell>
               <dvm:cell>?</dvm:cell>
            </dvm:row>
         </dvm:rows>
      </dvm:dvm>
   </soapenv:Body>

Element Name	Description
description	The DVM description. Optional
columns	This element holds the DVM's column list.
column	Represents a DVM column.
rows	This represents all the rows of data in the DVM.
row	Each DVM row of values.
cell	This is the value for this row and the for each column in the same order as defined in columns.

EOTF_XREF Service

This section lists the service operations available for cross references:

EOTF_XREF_ADD
EOTF_XREF_LINK
EOTF_XREF_UPDATE
EOTF_XREF_DELETE
EOTF_XREF_LOOKUP
EOTF_XREF_IMPORT.v2
EOTF_XREF_IMPORT.v1

EOTF_XREF_ADD

Use this service operation to add values to a cross-reference map.

Alias: add_xref_value

Type: Synchronous

Request Message: EOTF_XREF_ADD_REQ.V1

This is an example of the soap body for the request:

<soapenv:Body>
      <xref:xrefAddValue>
         <xref:mapname>?</xref:mapname>
         <!--2 or more repetitions:-->
         <xref:Values>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?"/>
         </xref:Values>
         <xref:Values>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?"/>
         </xref:Values>
      </xref:xrefAddValue>
   </soapenv:Body>

Element Name	Description
mapname	The name of the cross-reference map to add values to.
Values	This element holds the cross-reference elements and values to be populated.
domain	The name of the domain the elements are a part of.
element	This represents an element and its value.

Response Message: EOTF_XREF_RESPONSE.V1

Element Name	Description
status	The status of the operation. Returns Success or Exception.
reason	If there is an exception, the reason will be returned.
responseValues	The values returned for the lookup operation.
domain	The name of the target domain provided on the lookup request.
element	Represents an element in the target domain and its value.

EOTF_XREF_LINK

Use this service operation to link values to a cross-reference map.

Alias: link_xref_value

Type: Synchronous

Request Message: EOTF_XREF_LINK_REQ.V1

This is an example of the soap body for the request:

<soapenv:Body>
      <xref:xrefLinkValue>
         <xref:mapname>?</xref:mapname>
         <xref:ReferenceValues>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?"/>
         </xref:ReferenceValues>
         <!--1 or more repetitions:-->
         <xref:TargetValues>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?"/>
         </xref:TargetValues>
      </xref:xrefLinkValue>
   </soapenv:Body>

Element Name	Description
mapname	The name of the cross-reference map to add values to.
ReferenceValues	This element holds the existing elements and values in a cross-reference to link target values with.
domain	The name of the domain the reference elements are a part of.
element	This represents a cross-reference element and its value.
targetValues	This element holds the cross-reference elements and values to be added.
domain	The name of the domain the target elements are a part of.
element	This represents a cross-reference element and its value.

Response Message: EOTF_XREF_RESPONSE.V1

Element Name	Description
status	The status of the operation. Returns Success or Exception.
reason	If there is an exception, the reason will be returned.
responseValues	The values returned for the lookup operation.
domain	The name of the target domain provided on the lookup request.
element	Represents an element in the target domain and its value.

EOTF_XREF_UPDATE

Use this service operation to update values in a cross-reference map.

Alias: update_xref_value

Type: Synchronous

Request Message: EOTF_XREF_UPDATE_REQ.V1

This is an example of the soap body for the request:

<soapenv:Body>
      <xref:xrefUpdateValue>
         <xref:mapname>?</xref:mapname>
         <xref:ReferenceValues>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?"/>
         </xref:ReferenceValues>
         <!--1 or more repetitions:-->
         <xref:TargetValues>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?"/>
         </xref:TargetValues>
      </xref:xrefUpdateValue>
   </soapenv:Body>

Element Name	Description
mapname	The name of the cross-reference map to update values to.
ReferenceValues	This element holds the existing cross-reference elements and values to locate the row to be updated.
domain	The name of the domain the reference elements are a part of.
element	This represents a cross-reference element and its value.
targetValues	This element holds the cross-reference elements to be updated and the new values.
domain	The name of the domain the target elements are a part of.
element	This represents a cross-reference element and its value.

Response Message: EOTF_XREF_RESPONSE.V1

Element Name	Description
status	The status of the operation. Returns Success or Exception.
reason	If there is an exception, the reason will be returned.
responseValues	The values returned for the lookup operation.
domain	The name of the target domain provided on the lookup request.
element	Represents an element in the target domain and its value.

EOTF_XREF_DELETE

Use this service operation to delete values from a cross-reference map.

Alias: delete_xref_value

Type: Synchronous

Request Message: EOTF_XREF_DELETE_REQ.V1

This is an example of the soap body for the request:

<soapenv:Body>
      <xref:xrefDeleteValue>
         <xref:mapname>?</xref:mapname>
         <!--2 or more repetitions:-->
         <xref:Values>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?"/>
         </xref:Values>
         <xref:Values>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?"/>
         </xref:Values>
      </xref:xrefDeleteValue>
   </soapenv:Body>

Element Name	Description
mapname	The name of the cross-reference map to delete values from.
Values	This element holds the cross-reference elements and values to be deleted.
domain	The name of the domain the elements are a part of.
element	This represents an element and its value.

Response Message: EOTF_XREF_RESPONSE.V1

Element Name	Description
status	The status of the operation. Returns Success or Exception.
reason	If there is an exception, the reason will be returned.
responseValues	No response values are returned.

EOTF_XREF_LOOKUP

Use this service operation to lookup values from a cross-reference map.

Alias: lookup_xref_value

Type: Synchronous

EOTF_XREF_LOOKUP_REQ.V1

This is an example of the soap body for the request:

<soapenv:Body>
      <xref:xrefLookupValue needFault="true">
         <xref:mapname>?</xref:mapname>
         <xref:Values>
            <xref:domain>?</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="?">?</xref:element>
         </xref:Values>
         <xref:targetDomain>?</xref:targetDomain>
      </xref:xrefLookupValue>
   </soapenv:Body>

Element Name	Description
mapname	The name of the cross-reference map to lookup values in.
Values	This element holds the cross-reference elements and values to lookup.
domain	The name of the domain the reference elements are a part of.
element	This represents a cross-reference element and its value.
targetDomain	The name of the domain the lookup request should return elements and values for.

Response Message: EOTF_XREF_RESPONSE.V1

Element Name	Description
status	The status of the operation. Returns Success or Exception.
reason	If there is an exception, the reason will be returned.
responseValues	The values returned for the lookup operation.
domain	The name of the target domain provided on the lookup request.
element	Represents an element in the target domain and its value.

EOTF_XREF_IMPORT.v2

Use this service operation to import a cross-reference map definition and values in using PeopleSoft schema.

Alias: xref

Type: Asynchronous - One Way

Default: Yes

Request Message: EOTF_XREF.V2

This is an example of the soap body for the request:

<soapenv:Body>
      <xref:xref>
         <xref:name>?</xref:name>
         <!--Optional:-->
         <xref:description>?</xref:description>
         <!--Optional:-->
         <xref:comments>?</xref:comments>
         <xref:elements>
            <!--2 or more repetitions:-->
            <xref:element name="?" order="?" dataType="string" dataLength="?"⇒
 isCommon="false"/>
            <xref:element name="?" order="?" dataType="string" dataLength="?"⇒
 isCommon="false"/>
         </xref:elements>
         <xref:domains>
            <!--1 or more repetitions:-->
            <xref:domain name="?">
               <!--1 or more repetitions:-->
               <xref:element name="?"/>
            </xref:domain>
         </xref:domains>
         <!--Optional:-->
         <xref:rows>
            <!--1 or more repetitions:-->
            <xref:row>
               <!--2 or more repetitions:-->
               <xref:cell>?</xref:cell>
               <xref:cell>?</xref:cell>
            </xref:row>
         </xref:rows>
      </xref:xref>
   </soapenv:Body>

Element Name	Description
description	The cross-reference description. Optional
comments	Comments about the cross-reference. Optional
elements	This element holds the cross-reference element list.
element	Represents a cross-reference element.
domains	This elements holds the cross-reference domain list.
domain	This element represents a domain in a cross-reference map.
element	This represents an element in the cross-reference domain.
rows	This represents all the rows of data in the cross-reference map.
row	Each cross-reference row of values.
cell	This is the value for this row and the for each element in the same order as defined in elements.

EOTF_XREF_IMPORT.v1

Use this service opertaion to import a cross-reference map definition and values in using PeopleSoft schema.

Alias: xref

Type: Asynchronous - One Way

Default: No

Transform: To v2

Request Message: EOTF_XREF.V1

This is an example of the soap body for the request:

<soapenv:Body>
      <xref:xref>
         <xref:table name="?">
            <!--Optional:-->
            <xref:description>?</xref:description>
            <!--Optional:-->
            <xref:columns>
               <!--1 or more repetitions:-->
               <xref:column name="?"/>
            </xref:columns>
            <!--Optional:-->
            <xref:rows>
               <!--1 or more repetitions:-->
               <xref:row>
                  <!--1 or more repetitions:-->
                  <xref:cell colName="?"/>
               </xref:row>
            </xref:rows>
         </xref:table>
      </xref:xref>
   </soapenv:Body>

Element Name	Description
table	This element hold the table elements.
description	The DVM description. Optional
columns	This element holds the DVM's column list.
column	Represents a DVM column.
rows	This represents all the rows of data in the DVM.
row	Each DVM row of values.
cell	This is the value for this row and the for each column in the same order as defined in columns.

Cross-Reference Lookup Web Service Example

The service operation EOTF_XREF_LOOKUP.v1 is used by external systems to look up a cross-reference value. For the external system to have access to the web service, it must be published on the PeopleSoft application.

See Enterprise PeopleTools PeopleBook: Integration Broker, Providing Services.

Example: Cross-Reference Map Definition

In this example, the third-party system requests a cross-reference lookup for payment terms. This page shows elements in the value map PaymentTermsGUID:

Three elements are defined: UniqueGUID, SETID, and PYMNT_TERMS_CD.

This page shows the domains that are defined for the domain value map:

Two domains are defined for this map:

UinqueGUID is the domain used by the third party; it contains the UniqueGUID element.
PSFT represents the PeopleSoft application which contains the elements SETID and PYMNT_TERMS_CD.

Example: Web Service Request and Response

This is a sample request to obtain the PeopleSoft values for a common GUID value:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:⇒
xref="http://xmlns.oracle.com/Enterprise/tools/schema/xrefLookupValue.v1">
   <soapenv:Header/>
   <soapenv:Body>
      <xref:xrefLookupValue needFault="true">
         <xref:mapname>PaymentTermGUID</xref:mapname>
         <xref:Values>
            <xref:domain>UniqueGUID</xref:domain>
            <!--1 or more repetitions:-->
            <xref:element name="UniqueGUID">9d266732-90e2-11dd-a062-96c8921a7858<⇒
/xref:element>
         </xref:Values>
         <xref:targetDomain>PSFT</xref:targetDomain>
      </xref:xrefLookupValue>
   </soapenv:Body>
</soapenv:Envelope>

This is the response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:⇒
soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org⇒
/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <xrefResponse xmlns="http://xmlns.oracle.com/Enterprise/tools/schema/xref⇒
Response.v1">
         <status>Success</status>
         <responseValues>
            <domain>PSFT</domain>
            <element name="SETID">SHARE</element>
            <element name="PYMNT_TERMS_CD">CD01</element>
         </responseValues>
      </xrefResponse>
   </soapenv:Body>
</soapenv:Envelope>