Using Listening Connectors and Target Connectors

This chapter discusses how to:

• Work with the PeopleSoft connectors.

• Work with the HTTP connectors.

• Work with the PeopleSoft 8.1 connectors.

• Work with the Java Messaging Service (JMS) connectors.

• Work with the simple file target connector.

• Work with the File Transfer Protocol (FTP) target connector.

• Work with the AS2 connectors.

• Work with the Simple Mail Transfer Protocol (SMTP) target connector.

• Work with the Post Office Protocol 3 (POP3) target connector.

Understanding Listening Connectors and Target Connectors

This section discusses listening connectors, target connectors and target connector properties.

Listening Connectors

Listening connectors receive message requests from integration participants, send them to the gateway manager, and deliver responses back to the integration participants. The following diagram shows the flow of an inbound message from an external system into the integration engine through a listening connector:

Message flow through a listening connector

PeopleSoft-Delivered Listening Connectors

PeopleSoft delivers several listening connectors with PeopleSoft Integration Broker that enable integration participants to communicate with the PeopleSoft system using a number of communication formats.

You send messages to a listening connector at a URL address derived from its class location on the gateway web server.

Note. For all connectors in the following table except the service listening connector, the gateway provides a matching target connector. Although this chapter discusses each pair of listening and target connectors in a separate section, the use of a particular listening connector does not obligate you to use the corresponding target connector.

All of the delivered listening connectors that service HTTP requests run as servlets and are configured to run in BEA WebLogic or IBM WebSphere web server environments. These connectors are the PeopleSoft listening connector, the HTTP listening connector, and the PeopleSoft 8.1 listening connector.

Null Characters in Messages

The listening connectors delivered with PeopleSoft Integration Broker do not support null characters (ASCII value 00) as part of message field data. If a third-party application sends a message containing null characters, you must replace each instance of the null character with an acceptable substitute character, such as a space, before sending the message to the PeopleSoft system. Alternatively, you can modify the delivered listening connector to replace the null characters when it receives the message.

Target Connectors

Target connectors generate message requests, send them to integration participants, wait for responses from participants, and deliver the responses back to the gateway manager, as shown in the following diagram:

Message flow through a target connector

The integration gateway invokes target connectors dynamically through the gateway manager. Target connectors adhere to a standard structure by implementing the target connector interface provided by the integration gateway. By implementing this interface, target connectors can take advantage of all gateway manager services.

Each target connector has an internal connector ID that you use when selecting the connector; for example, the connector ID for the simple file target connector is FILEOUTPUT.

PeopleSoft-Delivered Target Connectors

PeopleSoft delivers several target connectors with PeopleSoft Integration Broker that enable you to communicate with integration participants using a wide range of communication formats. The following table describes the delivered target connectors:

Target Connector Properties

Most of the delivered target connectors have required and optional configuration properties that you set to control the connectors' behavior. Depending on the connector, you configure some of these properties in the integrationGateway.properties file or by using the Gateways component. You can specify values for connector properties in the following ways:

• Gateway-level target connector properties always have the same value for a given connector, regardless of which nodes or transactions use the connector.

  You specify the values of these properties in the integrationGateway.properties file.

• Node-level target connector properties can have different values for each default local node that uses a given gateway.

  Each node-level connector property is identified by a property ID and a property name. You specify default values for these properties in the Gateways component of each participating node.

  See Administering Integration Gateways.

When you create a node definition in the local database, you specify which gateway and target connector should be used to send messages to that node. In the node definition, you can supply values for the connector's node-level properties that override the defaults and apply only when sending messages to that node.

See Configuring Nodes.

When you define a transaction for a given node, you can supply values for the connector's node-level properties to override the node definition's values and apply only when sending messages with that transaction.

See Configuring Transactions.

You can set and override target connector properties at runtime using PeopleCode.

See Setting and Overriding Target Connector Properties at Runtime.

Passwords

You must encrypt all required and optional target connector passwords.

See Encrypting Passwords.

Properties for HTTP URLs

The following connectors communicate over HTTP:

• PeopleSoft target connector.

• HTTP target connector.

• PeopleSoft 8.1 target connector.

• AS2 target connector.

For the HTTP target connector you can specify only one primary URL (PRIMARYURL) per node. The primary URL is the URL of the external system that handles the request.

However, you may specify more than one backup URL (BACKUPURL). Upon the failure of a transaction to the primary URL, the message is sent to any backup URLs one at a time. When a transaction that is sent to a URL succeeds, the other URLs are not used. If all URLs fail, the appropriate action and message is relayed to the calling module. The message and the node/URL failure is noted in the database or in the PeopleSoft Integration Broker Monitor.

Note. If the property ID is HEADER, then the target connector retrieves the information from a getHeader method call on the ConnectorInfo object, which resides on the IBRequest object. All other properties can be retrieved from a getFieldValue method call on the ConnectorInfo object.

Properties for Message Compression and Encoding

When the local integration gateway sends messages to a remote gateway, it ensures that they are compressed and base64 encoded. However, by default, when it sends messages directly to any node, it sends them uncompressed and unencoded. You can change this setting for transactions that use the following connectors:

• HTTP target connector.

• JMS target connector.

• FTP target connector.

• AS2 target connector.

• SMTP target connector.

• Simple file target connector.

Use the node-level SendUncompressed property for the appropriate connector. You can change the current value of this property specified for a given node by using the Connectors page of the node definition, or you can override the value for a single transaction by using the Connectors page of the node transaction detail. If you set the property's value to No, it sends messages compressed and base64 encoded.

See Configuring Nodes and Transactions.

Note. If nonrepudiation is in effect for a message, the SendUncompressed property is not used, and the message is always sent compressed and base64 encoded.

Working With the PeopleSoft Connectors

This section provides an overview of the PeopleSoft connectors and discusses how to:

• Use the PeopleSoft listening connector.

• Use the PeopleSoft target connector.

Understanding the PeopleSoft Connectors

The PeopleSoft listening and target connectors establish the primary connection between a PeopleSoft application's integration engine and its designated local gateway. They also support secure HTTPS communications if SSL encryption is configured on the gateway machine.

Using the PeopleSoft Listening Connector

The PeopleSoft listening connector receives requests from integration participants in the PeopleSoft internal messaging format. Like the HTTP listening connector, the PeopleSoft listening connector is implemented as a Java HTTPServlet object. However, it receives requests in PeopleSoft Multipurpose Internet Mail Extensions (MIME) format. A PeopleSoft integration engine sends messages formatted in MIME over HTTP. The PeopleSoft listening connector receives these messages as POSTs (GET requests cannot be made in this way) and immediately converts the MIME input into a Java string object.

The PeopleSoft listening connector logs these requests and then invokes the gateway manager to unmarshall the string into an IBRequest object. The gateway manager invokes the target connector specified in the ConnectorClassName field in the IBRequest, which is derived from the node definition on the source integration engine. The gateway manager returns the responses to the connector, where they are logged and sent back to the original requesting systems, typically integration engines.

The URL for the PeopleSoft listening connector is http://gatewayserver/PSIGW/PeopleSoftListeningConnector, where gatewayserver is the machine name and port, host name, or IP address of the web server hosting the gateway.

Note. Third-party applications and PeopleSoft releases that don't include PeopleSoft Integration Broker should not send messages to this connector unless they can produce a properly MIME-encoded, PeopleSoft formatted message.

Using the PeopleSoft Target Connector

The PeopleSoft target connector initiates conversation with a PeopleSoft application's integration engine over a BEA Jolt connection in the PeopleSoft internal messaging format. The integration gateway sends messages to a specific integration engine based on the destination node specified in an incoming message. Use this connector to send messages only to PeopleSoft applications that use PeopleSoft Integration Broker.

The connector ID for the PeopleSoft target connector is PSFTTARGET.

Gateway-Level Connector Properties

There are no gateway-level connector properties specific to this connector; however, it uses both the node-specific and default BEA Jolt connect string properties in the integrationGateway.properties file to determine where to send the messages.

See Setting General Connection Properties.

Node-Level Connector Properties

There are no node-level connector properties for the PeopleSoft target connector.

Working With the HTTP Connectors

This section provides an overview of the HTTP connectors and discusses how to:

• Use the HTTP listening connector.

• Use the HTTP target connector.

• Comply with message formatting and transmission requirements.

• Run the gateway behind a proxy server.

Understanding the HTTP Connectors

The HTTP listening and target connectors provide a web-standard method for an integration gateway to exchange messages with both PeopleSoft and third-party applications using the HTTP GET and POST methods. They also support secure HTTPS communications if SSL encryption is configured on the gateway machine.

Using the HTTP Listening Connector

The HTTP listening connector monitors specific ports for incoming HTTP messages. It's implemented as a Java HTTPServlet object. The URL for the HTTP listening connector is http://gatewayserver/PSIGW/HttpListeningConnector, where gatewayserver is the machine name and port, host name, or IP address of the web server hosting the gateway.

The HTTP listening connector accepts compressed and based64-encoded data.

PeopleSoft HTTP Message Parameters

You must specify several required parameters in messages that you send to the HTTP listening connector. There are also several optional parameters.

These parameters, also known as credentials, are metadata specific to each message that the HTTP listening connector processes. These parameters supply authentication information and descriptive details about how the message is processed. For each message that you send to the connector, PeopleSoft Integration Broker uses the parameters that you supply to create an IBRequest that it uses to process and service the request internally. The following table describes the parameters:

The PeopleSoft HTTP message parameters can be passed with inbound messages to the HTTP listening connector using several methods, and they are transmitted with outbound messages by the HTTP target connector.

See Complying With Message Formatting and Transmission Requirements.

Using External Message IDs

You can specify an external message ID as a parameter in the HTTP listening connector to uniquely identify a message in PeopleSoft Integration Broker, thus ensuring that no duplicate messages are delivered to the system. The ExternalMessageID parameter is optional, but if you do specify this parameter, it must be unique and contain no more than 70 characters.

The HTTP listening connector can receive an external message ID in:

• Query strings.

• HTTP headers.

• SOAPAction headers.

• PeopleSoft IBRequest XML

The following example shows passing an external message ID in a query string:

http://localhost/PSIGW/HttpListeningConnector?From=QE_UNDERDOG&To=
QE_LOCAL&MessageName=QE_SYNC_MSG&MessageVersion=VERSION_1&
ExternalMessageID=UniqueId0006

The following example shows passing an external message ID in an HTTP header:

ExternalMessageID: UniqueId0006

The following example shows passing an external message ID in a SOAPAction header:

http://peoplesoft.com/QE_SYNC_MSG/QE_UNDERDOG/password/QE_LOCAL/
UniqueId0006

The following example shows passing an external message ID in PeopleSoft IBRequest XML:

<?xml version="1.0"?>
<IBRequest>
    <From>
        <RequestingNode>QE_UNDERDOG</RequestingNode>
        <OrigTimeStamp>2003-09-29T00:37:30.790-0800</OrigTimeStamp>
        <ExternalMessageID>UniqueId0006</ExternalMessageID>
    </From>
    <MessageName>QE_SYNC_MSG</MessageName>
    <MessageType>sync</MessageType>
    <To>
        <DestinationNode>QE_LOCAL</DestinationNode>
    </To>
    <ContentSections>
        <ContentSection>
            <Headers>
            <version>VERSION_1</version>
            </Headers>
            <Data><![CDATA[<?xml version="1.0"?><QE_SYNC_MSG/>]]></Data>
        </ContentSection>
    </ContentSections>
</IBRequest>

Using the HTTP Target Connector

The HTTP target connector enables you to exchange messages with non-PeopleSoft systems using the HTTP protocol. The HTTP target connector uses SSL for all basic security services, including client-side authentication.

The HTTP target connector also supports the Simple Object Access Protocol (SOAP) XML format.

The connector ID for the HTTP target connector is HTTPTARGET.

IBInfo Data Contained in HTTP Headers

A message has two parts—the transaction data and the IBInfo header that is the routing envelope used by PeopleSoft Integration Broker. In the event that a receiving system wants to make use of the IBInfo data, IBInfo header information is included when publishing messages to non-PeopleSoft systems when using the HTTP target connector or the JMS target connector.

When using the HTTP target connector to send messages to non-PeopleSoft systems, the following IBInfo data is contained in the HTTP headers. The content of the message (message body) is not impacted.

• MessageName

• MessageType

• OrigTimeStamp

• NonRepudiation

• To

• From

Gateway-Level Connector Properties

The HTTP target connector provides the option of routing through proxy servers. To enable this capability, you must set the domain name of the proxy server and the port number of the proxy server in the integrationGateway.properties file:

See Running Integration Gateways Behind Proxy Servers.

Node-Level Connector Properties

The HTTP target connector features properties that correspond to standard HTTP 1.1 header fields, as well as several custom properties that are documented in the following table. The World Wide Web Consortium (W3C) web site provides complete documentation for the standard header fields.

See http://www.w3.org/Protocols/rfc2616/rfc2616.html

Using the Content-Type Property

One of the optional gateway-level properties you can set for the HTTP target connector is Content-Type.

When the HTTP target connector property Content-Type is application/x-www-form-urlencoded, the connector converts the content string to MIME format.

Encoding Strings

When encoding a string, the following rules apply:

• The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.

• The special characters ".", "-", "*", and "_" remain the same.

• The space character " " is converted into a plus sign "+".

• All other characters are unsafe and are first converted into one or more bytes. Then each byte is represented by the three-character string "%xy," where xy is the two-digit hexadecimal representation of the byte.

Complying With Message Formatting and Transmission Requirements

This section discusses:

• The PeopleSoft XML message wrapper.

• The PeopleSoft non-XML message element.

• Passing HTTP parameters.

• Specifying message destinations in HTTP headers.

• Adding nonrepudiation signatures.

• Submitting cookies in the HTTP header.

• Responses to inbound request messages.

• Submitting SOAP messages.

This section directly addresses the issue of third parties that format and transmit messages to the HTTP listening connector; third parties should also expect the HTTP target connector to format and transmit outbound messages using the same standards.

The PeopleSoft XML Message Wrapper

At a minimum, when you submit message content to the HTTP listening connector, you submit it—preceded by the following XML version declaration—inside a simple XML wrapper:

<?xml version="1.0"?>
  <![CDATA[your_message_content]]>

Upon receiving the message, the integration gateway strips off the outer elements, leaving the message content with its original XML version declaration to be handled by PeopleSoft Integration Broker:

<?xml version="1.0"?>your_message_content

The message content can comply with the PeopleSoft rowset-based message format, which you can manipulate using the PeopleCode Rowset class. It can also be nonrowset-based XML-DOM-compliant data, which you can manipulate with nonrowset PeopleCode. Both formats are compatible with Application Engine transform programs, in which you can manipulate the message content using both PeopleCode and Extensible Stylesheet Language Transformation (XSLT) code.

The following template shows how a message in PeopleSoft rowset-based message format fits into the XML wrapper (data omitted for readability):

<?xml version="1.0"?>
     <![CDATA[<?xml version="1.0"?>
      <psft_message_name>
         <FieldTypes>
            ...
         </FieldTypes>
         <MsgData>
            ...
         </MsgData>
      </psft_message_name>]]>

Note. Psft_message_name is the name of the message definition in the PeopleSoft database.

The PeopleSoft Non-XML Message Element

If you’re submitting a non-XML message, you must insert the message content into a special element containing its own CDATA tag, as follows:

<?xml version="1.0"?>
   <![CDATA[<?xml version="1.0"?>
      <any_tag psnonxml="yes">
         <![CDATA[your_nonXML_message_content]]>
      </any_tag>]]>

Note. Any_tag can be any tag that you want to use. This is an XML-DOM-compliant method of transmitting non-XML data.

The following restrictions apply to the content of non-XML messages, such as those in comma-separated value (CSV) or PDF format:

• If the message content is non-XML text, it must be encoded as characters that are compliant with Unicode Transformation Format 8 (UTF-8).

• If the message content is non-text (binary), it must be encoded in base64 format.

Upon receiving the message, the integration gateway strips off the outer elements, leaving the non-XML message content inside a valid XML-DOM-compliant wrapper with its original XML version declaration.

Passing HTTP Parameters

You can pass parameters to the HTTP listening connector in:

• The PeopleSoft message wrapper, through an HTTP POST.

• The HTTP header, through an HTTP GET or POST.

• The URL query string, through an HTTP GET or POST.

The only HTTP parameters that you must provide for basic messaging are MessageName and RequestingNode. If you pass them in the PeopleSoft message wrapper, you must embed them in an XML structure along with the CDATA element containing the message content. Following is the minimum wrapper structure required to pass the parameters this way:

<?xml version="1.0"?>
<IBRequest>
   <MessageName>psft_message_name</MessageName>
   <From>
      <RequestingNode>psft_node_name</RequestingNode>
   </From>
   <ContentSections>
      <ContentSection>
         <Data>
            <![CDATA[<?xml version="1.0"?>your_message_content]]>
         </Data>
      </ContentSection>
   </ContentSections>
</IBRequest>

Note. Psft_message_name and psft_node_name are the names of the message definition and the sending system's node definition in the PeopleSoft database.

If you want to pass all of the HTTP message parameters in the PeopleSoft message wrapper, you embed them in the XML wrapper structure as follows (required parameters are shown emphasized, and element values are omitted for readability):

<?xml version="1.0"?>
<IBRequest>
   <MessageName/>
   <MessageType/>
   <From>
      <RequestingNode/>
      <Password/>
      <OrigUser/>
      <OrigNode/>
      <OrigProcess/>
      <OrigTimeStamp/>
   </From>
   <To>
      <FinalDestination/>
      <DestinationNode/>
      <SubChannel/>
   </To>
   <ContentSections>
      <ContentSection>
         <NonRepudiation/>
         <MessageVersion/>
         <Data>
            <![CDATA[<?xml version="1.0"?>your_message_content]]>
         </Data>
      </ContentSection>
   </ContentSections>
</IBRequest>

The following template shows the format for passing HTTP message parameters in the HTTP message header. The optional parameters can be omitted if not needed. The HTTP header format is as follows (required parameters are shown emphasized):

MessageName: MessageName
MessageType: Sync|Async|Ping
From: RequestingNode
Password: Password
OrigUser: OrigUser
OrigNode: OrigNode
OrigProcess: OrigProcess
OrigTimeStamp: OrigTimeStamp
FinalDestination: FinalDestination
To: DestinationNode
SubChannel:  SubChannel
NonRepudiation: Y|N
MessageVersion: MessageVersion

Warning! Whether you send message parameters in the message wrapper or in the HTTP header, those parameters—including the password—aren't secure if you don't encrypt the message. You can secure messages by implementing SSL encryption.

The following template shows the format for passing HTTP message parameters in a URL query string. Include all of the parameter variables, even if you don't supply values for some of them. With only the required parameters, the URL query string looks like the following (required parameters are emphasized):

http://gatewayserver/PSIGW/HttpListeningConnector?&MessageName=MessageName
&MessageType=&From=RequestingNode&Password=&OrigUser=&OrigNode=&OrigProcess=
&OrigTimeStamp=&FinalDestination=&To=&SubChannel=&NonRepudiation=&MessageVersion=

The full URL query string format is:

http://gatewayserver/PSIGW/HttpListeningConnector?&MessageName=MessageName
&MessageType=[Sync|Async|Ping]&From=RequestingNode&Password=Password&OrigUser=OrigUser
&OrigNode=OrigNode&OrigProcess=OrigProcess&OrigTimeStamp=OrigTimeStamp
&FinalDestination=FinalDestination&To=DestinationNode&SubChannel=SubChannel
&NonRepudiation=[Y|N]&MessageVersion=MessageVersion

Warning! URL query strings are always transmitted in clear text, so your parameters are visible to the world. This means that using a query string to send message parameters—such as a password—is highly insecure. Consequently, it is not recommended.

Using an HTTP POST is the only way that you can send message content to PeopleSoft Integration Broker through the HTTP listening connector. However, you can use an HTTP GET when you don't need to post message content. In this case, you pass the HTTP connector properties in the URL query string or in the HTTP header, but you don't insert any message content or XML wrapper. For example, you might have requests for information (queries), such as a request for a customer list. In this case, you need to specify only the message name (for example, CUSTOMER_LIST_REQUEST) and the name of the requesting node in the URL query string or the HTTP header.

Specifying Message Destinations in HTTP Headers

When message credentials are supplied in HTTP headers, the "To:" (destination node) specification is ignored. PeopleSoft Integration Broker uses the Default Application Server node entry in the integrationGateway.properties file as the destination node, not the "To:" entry from the headers. If no default application server entry is specified in the integrationGateway.properties file, the follow error is generated:

<?xml version="1.0"?>
<IBResponse type="error">
<DefaultTitle>Integration Broker Response</DefaultTitle>
<StatusCode>20</StatusCode>
<MessageID>10201</MessageID>
<DefaultMessage>null</DefaultMessage>
</IBResponse>

You can specify destination node information in the SOAPAction field or HTTP query string.

Note. If using SOAP, PeopleSoft Integration Broker takes all IBInfo from the SOAPAction field, not from the HTTP header or HTTP query string.

Adding Nonrepudiation Signatures

If you’re working with a nonrepudiated message, its signature must be located at the same level as the message data.-The message doesn’t need to be formatted with the PeopleSoft rowset hierarchy, as long as it's enclosed in valid XML and has the signature section as specified by the W3C. The following template describes a nonrepudiation signature alongside the PeopleSoft rowset-based format message it represents, within the ContentSection element of the PeopleSoft XML message wrapper (the tags you must add for nonrepudiation are in bold):

<ContentSections>
   <ContentSection>
      <NonRepudiation>Y</NonRepudiation>
      <MessageVersion/>
      <Data>
        <?xml version="1.0"?>
         <any_tag>
            <data>
               <![CDATA[<?xml version="1.0"?>your_message_content]]>
            </data>
            <Signature>
               <SignedInfo>
                <CanonicalizationMethod/>
                <SignatureMethod/>
                <Reference>
                   <DigestMethod>
                      <DigestValue>
                      ...
                      </DigestValue>
                   </DigestMethod>
                </Reference>
               </SignedInfo>
             <SignatureValue>
             ...
             </SignatureValue>
          </Signature>
        </any_tag>
      </Data>
   </ContentSection>
</ContentSections>

Note. Any_tag can be any tag that you want to use, such as My_NR_Message.

You can find more information about the proposed standard for XML signature syntax and processing at the W3C web site.

See http://www.w3.org/TR/xmldsig-core/

Important! In PeopleSoft Integration Broker, all signatures use line feeds for newlines, so the nonrepudiation signature cannot include any carriage return and line feed (CR/LF) pairs. A non-PeopleSoft application must strip out the carriage returns before inserting the signature and sending the message.

Note. To handle nonrepudiated messages, you must install node-based digital certificates on the sending and receiving systems and configure the message and channel definitions to use the nonrepudiation feature.

See Implementing Authentication and Nonrepudiation.

Submitting Cookies HTTP Headers

The HTTP listening connector supports cookies. Cookies that are passed as part of a message request to the HTTP listening connector are processed, read, and manipulated by the receiving PeopleCode in the application. You enter cookies in the HTTP message header. For example:

Cookie: favoritecolor=green; path=/; expires Mon, 09-Dec-2003 13:46:00 GMT

In this example, the header entry would result in a cookie named favoritecolor. The value of favoritecolor is green. This cookie has a path of /, meaning that it is valid for the entire site, and it has an expiration date of December 9, 2003 at 1:46 p.m. Greenwich Mean Time (GMT).

See Handling Cookies.

Responses to Inbound Request Messages

PeopleSoft Integration Broker responds to inbound messages in one of three ways:

• For a successfully received synchronous transmission, the integration gateway passes the request message to the integration engine.

  The integration engine generates and passes back through the listening connector a response message in a format determined by the applicable node, transaction, relationship, and transaction modifier definitions for the request message.

• For a successfully received asynchronous transmission, the integration gateway immediately returns a simple XML acknowledgment message.

  The following example shows a successful asynchronous acknowledgment:

  <?xml version="1.0"?>
  <IBResponse type="success">
     <DefaultTitle>Integration Broker Response</DefaultTitle>
     <StatusCode>0</StatusCode>
     <TransactionID>UNDERDOG.QE_SALES_ORDER_ASYNC_CHNL.20</TransactionID>
  </IBResponse>

• For an unsuccessful transmission, the integration gateway immediately returns a simple XML error message in a standard XML error format for all requests (except SOAP requests), if error handling is invoked in the integration gateway.

  The following is an example of this standard error response:

  <?xml version="1.0"?>
  <IBResponse type="error">
     <DefaultTitle>Integration Broker Response</DefaultTitle>
     <StatusCode/>
     <MessageID/>
     <DefaultMessage/>
     <MessageParameters>
        <Parameter/>
     </MessageParameters>
  </IBResponse>

Submitting SOAP Messages

SOAP messages support a subset of the HTTP message parameters— two required parameters and two optional parameters. You pass them to the HTTP listening connector in a SOAP-specific HTTP header. Concatenate them in a string, with each parameter preceded by a pound sign (#). They must appear in the following order:

#http://peoplesoft.com/MessageName/RequestingNode/Password/DestinationNode

The following example shows where the parameter string belongs in a SOAP HTTP header:

POST /get_BindingDetail HTTP/1.1
Host: www.someOperator.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: http://peoplesoft.com/PURCHASE_ORDER/MY_NODE/PSFT_PASS/PSFT_NODE

Note. The SOAPAction must always be in the HTTP header, not contained within the IBRequest XML.

Because the last two parameters are optional, you can exclude them; however, you must still include the pound signs. This example excludes the password:

SOAPAction: http://peoplesoft.com/PURCHASE_ORDER/MY_NODE//PSFT_NODE

Note. The SOAPAction format for previous PeopleTools releases is still supported. This format had the parameters concatenated in a string separated by pound signs ("#"): SOAPAction: #PURCHASE_ORDER#MY_NODE#PSFT_PASS#PSFT_NODE

Warning! When you send message parameters in the SOAP header, those parameters—including the password—aren't secure if you don't encrypt the message. You can secure messages by implementing SSL encryption.

If an error occurs on the integration gateway during processing, a SOAP-specific XML error is generated instead of a standard XML error. Following is an example of an error in SOAP-specific XML format:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring>Server Error</faultstring>
         <detail>
            <IBResponse type="error">
               <DefaultTitle>Integration Broker Response</DefaultTitle>
               <StatusCode>10</StatusCode>
               <MessageID>10731</MessageID>
               <DefaultMessage></DefaultMessage>
            </IBResponse>
         </detail>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Understanding HTTP Status Codes

This section describes HTTP status codes for non-SOAP and SOAP messages.

Status Codes for Non-SOAP Messages

The following list summarizes HTTP status codes for non-SOAP messages:

• For an asynchronous message, HTTP status codes 200 to 299 indicate a message status of Success.

• For a synchronous message, the HTTP status code 200 indicates a message status of Success.

• HTTP status code 404 indicates that the server has not found anything matching the Request-URI. In this case, an ExternalSystemContactException is generated on the integration gateway and the message status goes to Retry.

• HTTP status code 503 indicates that the server is currently unable to handle the request due to temporary server overload or maintenance. In this case, an ExternalSystemContactException is generated on the integration gateway and the message status goes to Retry.

• All other HTTP status codes generate an ExternalApplicationException. The status of these messages goes to Error.

Status Codes for SOAP Messages

This section summarizes HTTP status codes for SOAP messages.

If you are following SOAP 1.1 standards, the HTTP status code 500 indicates an Error.

If you are following SOAP 1.2 standards, the following HTTP status codes apply:

• HTTP status code 400 can mean any of the following:

  • InvalidMessageException

  • MessageMarshallingException

  • MessageUnmarshallingException

  • Malformed HTTP/XML

• HTTP status code 405 indicates that the method is not POST.

• HTTP status code 415 indicates the content type is not text/xml.

• HTTP status code 500 can mean any of the following:

  • ExternalSystemContactException

  • ExternalApplicationException

  • GeneralFrameworkException

Running Integration Gateways Behind Proxy Servers

When a proxy server is set up for a network on which the integration gateway resides, all HTTP transactions are routed through that proxy server automatically. The HTTP transport layer uses proxy server settings that you specify in the integrationGateway.properties file. The message is routed to the proxy server and then on to the internet. Only the HTTP target connector can use a proxy server.

Inserted in the HTTP message header of each transaction is a Proxy-Authenticate header field containing a user ID and password. The proxy server uses these values to authenticate the message and then passes it on to its target.

Setting Proxy Web Server Properties

To run the integration gateway behind a proxy server:

1. Set the gateway-level properties.

   Uncomment and add values for the properties in the integrationGateway.properties file section labeled Proxy webserver section.

   Property	Description
   ig.proxyHost	Enter the domain name of the proxy web server; for example: proxy.peoplesoft.com
   ig.proxyPort	Enter the port number of the proxy web server; for example: 80

   The HTTP target connector reads these two properties and calls the setProxy function. In an outbound transaction, the request is redirected to the proxy server and the proxy server forwards the request to the destination URL.

2. Set the node-level property.

   You set the user ID and password required by the proxy server in the HEADER, Proxy-Authenticate connector property. The integration gateway encodes the values that you provide, adds the required formatting, and sends it. The format is:

   userid:password

See Also

Using the integrationGateway.properties File

Working With the PeopleSoft 8.1 Connectors

This section provides an overview of the PeopleSoft 8.1 connectors and discusses how to:

• Use the PeopleSoft 8.1 listening connector.

• Use the PeopleSoft 8.1 target connector.

Understanding the PeopleSoft 8.1 Connectors

The PeopleSoft 8.1 listening and target connectors enable communication between PeopleSoft 8.1x applications and an integration gateway using PeopleSoft Application Messaging technology. To the PeopleSoft 8.1x application, the gateway appears to be another PeopleSoft 8.1x application, so no change in the messaging development process is needed. The connectors also support secure HTTPS communications if SSL encryption is configured on the gateway machine.

See Also

Setting Up SSL Encryption

Using the PeopleSoft 8.1 Listening Connector

In PeopleSoft 8.1x systems, PeopleSoft Application Messaging generates highly structured XML messages that are designed to be sent to PeopleSoft 8.1x Application Messaging gateways. The PeopleSoft 8.1 listening connector mimics the role of the Application Messaging gateway by transparently receiving and processing PeopleSoft 8.1x messages. This connector transforms inbound PeopleSoft 8.1x messages into PeopleSoft Integration Broker formatted XML messages that can be processed by the integration gateway and ultimately by the integration engine. This conversion is necessary because the two message formats are distinctly different.

The URL for the PeopleSoft 8.1 listening connector is http://gatewayserver/PSIGW/PS81ListeningConnector, where gatewayserver is the machine name and port, host name, or IP address of the web server hosting the gateway.

This connector automatically handles base64–encoded and compressed messages, as well as uncompressed messages.

Using the PeopleSoft 8.1 Target Connector

This connector enables the gateway to communicate with PeopleSoft 8.1x applications that use PeopleSoft Application Messaging technology. It converts outbound messages to the Application Messaging native format. Messages from the PeopleSoft Integration Broker system reach the PeopleSoft 8.1x system through the Application Messaging gateway on the PeopleSoft 8.1x system.

The PeopleSoft 8.1 target connector uses the HTTP target connector to manage the HTTP communication with the PeopleSoft 8.1x Application Messaging gateway. The PeopleSoft 8.1 target connector focuses on messaging semantics, instead of communication details; it constructs an Application Messaging XML document and sends it using the HTTP target connector. The PeopleSoft 8.1 target connector detects the status of returned responses by the value in the ReturnCode field in the XML response.

The connector ID for the PeopleSoft 8.1 target connector is PSFT81TARGET.

Gateway-Level Connector Properties

The PeopleSoft 8.1 target connector has one gateway-level property, in the section of the integrationGateway.properties file labeled DELIVERED CONNECTOR CONFIGURATION Section. This property specifies where the connector can send messages if a target URL isn't specified in the connector's node-level properties. Specify the URL as follows:

ig.connector.amtargetconnector.url=peoplesoft_8.1x_application_messaging_gateway

You can override this value by specifying a different URL in the node-level connector properties, in the node definition for the PeopleSoft 8.1x target node, or in the transaction definition for the message.

Node-Level Connector Properties

The following table describes the node-level connector properties:

Working With the JMS Connectors

This section provides an overview of the JMS connectors and discusses how to:

• Specify JNDIFactory class names.

• Use the JMS listening connector.

• Use the JMS target connector.

Understanding the JMS Connectors

The JMS listening and target connectors enable communication between JMS provider systems and an integration gateway using standard JMS protocols. PeopleSoft currently supports Java Native Directory Interface (JNDI) only for File System Context [fscontext].

Supported JMS Providers

To use the JMS connectors, you must add specific Java archive (JAR) files to the Java CLASSPATH. The JAR files that you add to the CLASSPATH depend on the JMS provider with which you're communicating. The following JMS providers are supported:

Note. Not only can a gateway running on a BEA WebLogic web server communicate with a WebLogic JMS provider, but both services can run on a single installation of WebLogic. However, the gateway still treats the JMS provider as a separate system, and it must be configured the same way as in any other scenario.

You can also add generic JMS providers for use with PeopleSoft Integration Broker.

See Adding Generic JMS Providers.

Specifying JNDIFactory Class Names

You must set up the JNDIFactory class names for the JMS provider in the section of the integrationGateway.properties file labeled JMS configuration Section.

When you set the JMSProvider property, the provider name that you enter must match the provider in the JNDIFactory class name exactly. You must set this property for both the JMS listening connector and the JMS target connector. This property is case-sensitive.

weblogic.jndi.WLInitialContextFactory

com.sun.jndi.fscontext.RefFSContextFactory

com.sun.jndi.fscontext.RefFSContextFactory

You can also specify a service provider that is not listed. For example, if you are using MSMQ, enter the following value for the property:

ig.jms.JMSProvider.JNDIFactory.MSMQ=com.sun.jndi.fscontext.RefFSContextFactory

Using the JMS Listening Connector

The JMS listening connector has two components: a subscriber and a queue listener. The JMS subscriber subscribes to different topics and the JMS queue listens on queues for new messages.

Note. The JMS listening connector always expects JMS messages in text format.

Receiving Messages

The JMS listening connector retrieves topics and queues from the integrationGateway.properties file. For each topic it starts a topic subscriber, and for each queue it starts a queue listener. When a message arrives either for a queue or topic, the JMS listening connector sends the message to the integration engine.

A parameter called ExternalMessageID is used to ensure that messages are received only once. When the JMS listening connector receives a message, it sets an external message ID in IBInfo and sends this information to the PeopleSoft Integration Broker with the message content. If the external message ID exists in IBInfo, the application server checks for duplicate messages. If a duplicate is found, an error is generated. The external message ID is optional. If specified, it must be unique and not exceed 70 characters.

Error Handling

If an error occurs during message processing, the JMS listening connector publishes the message back to either an error topic or an error queue. All error messages feature a header called ErrorDescription which contains a description of the error.

Note. If the application server returns the status 20, the message is published to the error topic and the response is logged in the integration gateway message log.

To capture errors you must set error topic or error queue properties in the JMS Configuration Section of the integrationGateway.properties file. These properties are discussed later in this section. If both an error topic and an error queue are set up and configured, only the error queue will capture error messages.

JMS Queue Listener Properties

You can configure multiple queues in the section of the integrationGateway.properties file labeled JMS Configuration Section. To configure multiple queues, use the convention, ig.queue1, ig.queue2, ig.queue3, and so on.

JMS Topic Subscriber Properties

You can configure multiple topics, in the section of the integrationGateway.properties file labeled JMS configuration Section. To configure multiple topics, use the convention ig.topic1, ig.topic2, ig.topic3, and so on.

Error Queue Properties

To capture JMS listening connector errors in an error queue, set the following properties in the JMS Configuration Section of the integrationGateway.properties file.

Error Topic Properties

To capture JMS listening connector errors in an error topic, set the following properties in the JMS Configuration Section of the integrationGateway.properties file.

JMS Message Header Properties

For the JMS listening connector to process messages, you must set the following properties. You can set these properties in JMS message headers, the integrationGateway.properties file or in the body of the XML message.

You can specify JMS headers in the integrationGateway.properties file for both queues and topics. However you must be using separate queues or topics per requesting node/message combination.

You must supply the properties listed in the following table in the JMS message header when you publish messages from a JMS provider system to the integration gateway.

The following example shows specifying JMS header properties in the body of an XML message.

<?xml version="1.0" ?> 
   <IBRequest>
      <MessageName>JMS_MessageName</MessageName>
      <MessageType>Async_or_Synch></MessageType>
      <From>
         <RequestingNode>JMS_RequestingNode</RequestingNode>
         <Password>JMS_NodePassword</Password>
         <OrigUser></OrigUser>  
         <OrigNode></OrigNode/>  
         <OrigProcess></OrigProcess> 
         <OrigTimeStamp></OrigTimeStamp > 
      </From>
      <To>
         <FinalDestination>JMS_FinalDestination<FinalDestination>
         <DestinationNode>JMS_DestinationNode</DestinationNode>
      </To>
         <ContentSections>
            <ContentSection>
               <NonRepudiation></NonRepudiation> 
               <MessageVersion></MessageVersion>  
               <Data></Data> 
            </ContentSection>
        </ContentSections>
    </IBRequest>

When the message received specifies synchronous mode, a reference to the temporary queue or topic must be set in the JMS message header for the JMS listening connector to determination the destination of the message response. The JMS listening connector also sets the JMS correlation ID when it sends the response so the requestor can properly associate the response with its corresponding request.

If any of the message header properties are missing, an error is logged and an error is published to an error topic or error queue. The message that the connector publishes to the error topic has a property call error and is set to True. The error message that is published contains the following information: default message, message ID, message set, message parameters, and body of the message sent.

Starting the JMS Listening Connector

You can start the JMS listening connector using the JMSListeningConnectorAdministrator servlet, or you can start it manually.

To start the JMS listening connector using the servlet:

1. Deploy the servlet under the web application PSIGW.

2. To start the servlet on start up of the web server, set the variable Load On Startup.

   When you set the Load On Startup option, the JMS listening connector automatically starts when you start the web server. Refer to the web server documentation for more details about starting the servlet automatically when the web server starts.

To start the JMS listening connector manually:

1. Open a browser and enter the following URL:

   http://localhost/PSIGW/JMSListeningConnectorAdministrator?Activity=Start

2. Press Enter.

Shutting Down the JMS Listening Connector

You can shut down the JMS listening connector by stopping the JMSListeningConnectorAdministrator servlet.

To shut down the JMS listening connector:

1. Open a browser and enter the following URL:

   http://localhost/PSIGW?JMSListeningConnectorAdministrator?Activity=Stop

2. Press Enter.

Note. You must register the JMSListeningConnectorAdministrator servlet object under the web application PSIGW in the web server. The BEA WebLogic or IBM WebSphere documentation should provide instructions about how to register the servlet. The class name is com.peoplesoft.pt.integrationgateway.listeningconnector.JMSListeningConnectorAdministrator.

Using the JMS Target Connector

JMS is an application programming interface (API) for accessing message systems. JMS provides a standard Java-based interface to the message services of message-oriented middleware (MOM) providers. The JMS target connector is an adapter to JMS providers, and it can be used with MOM and JMS providers, such as IBM MQSeries, BEA WebLogic, Sun iPlanet and others. The following diagram illustrates how messages flow through the JMS API:

Message flow through the JMS API

The primary features of JMS are.

• Connection factories that are used to create connections to a specific JMS provider.

• Separate publish, subscribe, and point-to-point messaging domains.

  These are defined by separate interfaces so that a provider does not have to support both.

• Topics for publish and subscribe, as well as queues for point-to-point messaging.

When multiple applications must receive the same message, publish and subscribe messaging is used. In publish and subscribe messaging, all of the subscribers subscribe to a topic and all of the publishers publish messages to a topic. The messaging system distributes messages from the publisher to the subscriber. This domain is mainly used for asynchronous messaging.

When one application must send a message to another application, point-to-point messaging is used. This domain is only for synchronous messaging. There are two basic types of point-to-point messaging systems. One uses a client that directly sends a message to another client. The other, more commonly used implementation uses a message queue.

The JMS target connector either publishes a message to a topic or inserts a message into a queue, based on the node-level properties that you set.

The JMS target connector supports only JNDI file context for the lookup of connection factories, topics, and queue names. (Lightweight Directory Access Protocol (LDAP) is not supported.)

The connector ID for the JMS target connector is JMSTARGET.

Asynchronous and Synchronous Communication

The JMS target connector provides both synchronous and asynchronous modes of communication. When the node level property ReplyTo is set to False, communication is asynchronous. When it is set to True, communication is synchronous.

For asynchronous communication, the JMS target connector publishes messages to MOM or drops messages into a queue and commits the session. It does not wait for a response from the destination system. For synchronous communication, after the connector publishes messages or drops them into a queue, it waits for the temporary topic or queue to respond.

For synchronous communication, the exchanges involve only the publisher and a single subscriber. When a JMS-compliant remote node receives a synchronous request message from PeopleSoft, it must use the value of the message ID of the request message to populate the correlation ID of its response message. When the response is received by the PeopleSoft JMS target connector, it compares the JMS correlation ID of the response message with the JMS message ID of the request. The message is not accepted if these two IDs do not match.

When sending messages either synchronously or asynchronously, the connector sets different string properties in the JMS message header. The properties are used as metadata about the message. The JMS target connector also sets a reference to the temporary queue or topic from which it requires the response.

IBInfo Data Contained in JMS Headers

A message has two parts—the transaction data and the IBInfo header that is the routing envelope used by PeopleSoft Integration Broker. In the event that a receiving system wants to make use of the IBInfo data, IBInfo header information is included when publishing messages to non-PeopleSoft systems when using the JMS target connector or the HTTP target connector.

When using the JMS target connector to send messages to non-PeopleSoft systems, the following IBInfo data is contained in the JMS headers. The content of the message (message body) is not impacted.

• RequestingNode

• FinalDestinationNode

• DestinationNodes

• MessageName

• MessageType

• OrigTimeStamp

• NonRepudiation

Gateway-Level Connector Properties

There are no gateway-level JMS target connector properties that you must set.

Node-Level Connector Properties

You must set either a JMS queue or JMS topic for a given node definition. If both are set or are missing the PeopleSoft Integration Broker generates an invalid message exception.

Note. You must register JMS-administered objects—such as topics, queues, and connection factories—that you include as connector properties. The documentation for specific providers should provide instructions on how to register the topics.

JMS message types can be Text, Map Message, Stream, or Object. However, PeopleSoft provides only text messages. If you need to use other message types, you can write a class that implements the com.peoplesoft.pt.integrationgateway.common.jms.ProcessJMSMessage interface, and you set the class name as a value for JMSMessageTypeClass.

The provider name that you specify for the JMSProvider in the node definition must match the JMSProvider.JNDIFactory property that you specify in the integrationGateway.properties file.

The following table describes the node-level connector properties:

Additional Setup Steps

Before using the JMS target connector, verify that:

1. The JMS messaging system is running.

2. All JMS connection factories, topics, and queues are registered for JNDI lookup.

3. A username and a password are created in the JMS system for use as values for the properties JMSUserName and JMSPassword.

JMS Target Connector Errors and Exceptions

The JMS target connector may generate the following exceptions:

Adding Generic JMS Providers

The JMS providers that PeopleSoft supports are BEA WebLogic, Sun iPlanet and IBM MQSeries. However, to meet your business requirements you can add generic JMS providers.

This section provides lists of configuration tasks to perform on the JMS listening connector and JMS target connector to add a generic JMS provider to PeopleSoft Integration Broker.

Configuring the JMS Listening Connector for Generic JMS Providers

To configure the JMS listening connector for a generic JMS provider:

• Obtain the following information from the provider:

  • JMS jar file.

  • JNDIFactory information

• Determine if messaging will be in topics or queues.

• Determine if error handling will be in topics or queues.

• Update JMS properties in the integrationGateway.properties file:

  • Update the JNDIFactory entry.

    For example if the provider were Tibco the entry might be:

     ig.jms.JMSProvider.JNDIFactory.Tibco=com.tibco.JMSFactory

  • Populate the appropriate messaging topic and queue entries based on how messaging will be handled.

  • Populate the appropriate error topic and queue entries based on how messaging will be handled.

In addition to the information provided in this section, review the JMS Headers Properties section of this chapter which discusses the required information that must be in the headers of each message processed by the JMS listening connector.

Configuring the JMS Target Connector for Generic JMS Providers

To configure the JMS target connector for a generic JMS provider:

• Define a node for the provider.

• Assign the JMS target connector to the provider node and specify the target connector properties.

Working With the Simple File Target Connector

This section discusses the simple file target connector.

Understanding the Simple File Target Connector

With the simple file target connector, you can save PeopleSoft messages as files in XML format. This enables you to verify that:

• You have composed messages correctly.

• The messages contain the content that you want to send.

You can use the Simple File target connector to send messages using the PUT command and receive messages using the GET command.

The connector ID for the simple file target connector is FILEOUTPUT.

Setting File Security

To secure files during processing, set the property ig.fileconnector.password in the integrationGateway.properties file, in addition to the Password property in the connector properties set in the Gateways component.

Setting file security is optional. However, if you use this feature, both passwords must match and be encrypted.

See Encrypting Passwords.

Node-Level Connector Properties

The following table describes the node-level connector properties:

Working With the FTP Target Connector

This section discusses working with the FTP target connector.

Understanding the FTP Target Connector

The FTP target connector enables the gateway to use FTP to send messages to and receive messages from FTP servers. It uses the PUT command to place messages or files from the integration gateway onto remote FTP servers. The GET command is used to receive messages from FTP servers. Outbound messages through the FTP target connector are UTF-8 encoded.

PeopleSoft Integration Broker also supports secure communication with FTP servers using FTPS.

The connector ID for the FTP target connector is FTPTARGET.

Prerequisites for Using the FTP Target Connector

In addition to specifying Java Archive (JAR) files in the web server CLASSPATH and setting node-level connector properties, to use this connector you must also specify the integration gateway URL in the Gateways component. Information about specifying the required JAR files and setting node-level FTP and FTPS connector properties is discussed in this section.

Specifying Required JAR Files

For the FTP target connector to function properly the following JAR files from IBM must reside in the CLASSPATH of the web server running the integration gateway:

• FTPProtocol.jar

• ipworksssl.jar (required for FTPS)

Setting Node-Level FTP Connector Properties

This section describes the required node-level properties you must set to use the FTP target connector.

The following table describes the required node-level connector properties:

Setting Node-Level FTPS Connector Properties

The following table describes properties to use for secure FTPS communication.

Using Directory Lists

One of the optional node-level FTP connector properties is FILENAME. If you do not know the file name of the file you would like to receive but do not know the directory in which it resides, you can use the GETDIRLIST method to retrieve a directory list. The directory list is retrieved in XML format and you must parse the XMLDocument to read its contents. You can then use the GET method to get the actual file. The following example shows the format of a returned directory list.

<DirList>
   <File name="sample.bat">
      <Date></Date>
      <Size>1234</Size>
      <Time></Time>
      <isFile>True</isFile>
   </File>
   <File name="sample2.bat">
      <Date></Date>
      <Size>1234</Size>
      <Time></Time>
      <isFile>True</isFile>
   </File>
   <File name="temp">
      <Date></Date>
      <Size>1234</Size>
      <Time></Time>
      <isFile>False</isFile>
   </File>	
</DirList>	


Date : Date on the file on remote system
Time : Time on the file on remote system
Size : Size of the file
isFile : True if it is a file. False if it is a directory.

Example

The following example shows the code needed to use the FTP connector to get a list of the files in a directory, run through the list of files, select a file, and retrieve it. To use this example, you must know the directory in which the file resides.

If you know the name of the file you wish to receive but do not know the directory, use the FILENAME property and the GETDIRLIST method to retrieve a directory list, as described previously in this section.

See Using Directory Lists.

Local XmlDoc &Output;
Local Message &MSG1, &MSG2, &MSG3;

&MSG = CreateMessage(Message.QE_FLIGHTPLAN_UNSTRUCT);

/* Set ConnectorName and Connector ClassName */
&MSG.IBInfo.IBConnectorInfo.ConnectorName = "FTPTARGET";
&MSG.IBInfo.IBConnectorInfo.ConnectorClassName = "FTPTargetConnector";

/* Set the FTP connector properties in the ConnectorInfo */
/* Mehtod name can be either Get or GetDirlist.  */
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("Method", "GET",%Property);
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("HOSTNAME", 
     "ftp.ftpserver.com",%Property);
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("USERNAME", "sam",%Property);

/*  Encrypt the password */
&pscipher = CreateJavaObject("com.peoplesoft.pt.integrationgateway.common.
     EncryptPassword");
&encPassword= &pscipher.encryptPassword("ftpserverpassword");
 &pscipher = Null;

&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("PASSWORD", 
     encPassword,%Property,);
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("DIRECTORY", 
     "/incoming/tmp",);


/* Do Connector Request */
&MSG2 = ConnectorRequest(&MSG);

/* Get XMLDoc from MSG2*/
&fileListXmlDoc = &MSG2.GetXmlDoc();

/*Parse the XMLDoc. Structure of the DirList Message is 
<DirList>
     <File name="sample.bat">
        <Date></Date>
        <Size>1234</Size>
        <Time></Time>
        <isFile>True/False</isFile>
     </File>
</DirList>*/

&XmlNode = &fileListXmlDoc .DocumentElement.FindNode("File ");

/* Get the file name */
&fileName = &XmlNode.NodeValue

/* Get the file name from the Remote FTPServer */
&MSG = CreateMessage(Message.QE_FLIGHTPLAN_UNSTRUCT);

/* Set ConnectorName and Connector ClassName */
&MSG.IBInfo.IBConnectorInfo.ConnectorName = "FTPTARGET";
&MSG.IBInfo.IBConnectorInfo.ConnectorClassName = "FTPTargetConnector";

/* Set the FTP connector properties in the ConnectorInfo */
/* Mehtod name can be either Get */
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("Method", "GET",%Property);
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("FILENAME", 
     &fileName,%Property);
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("HOSTNAME", 
     "ftp.ftpserver.com",%Property);
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("USERNAME", "sam",%Property);

/*  Encrypt the password */
&pscipher = CreateJavaObject("com.peoplesoft.pt.integrationgateway.common.
     EncryptPassword");
&encPassword= &pscipher.encryptPassword("ftpserverpassword");
 &pscipher = Null;

&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("PASSWORD", 
     encPassword,%Property,);
&yo = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties("DIRECTORY", "/incoming/tmp",);

/* Do Connector Request */
&MSG3 = ConnectorRequest(&MSG);

Working With the AS2 Connectors

This section provides an overview of the Applicability Statement 2 (AS2) specification and discusses how to:

• Work with the AS2 listening connector.

• Work with AS2 response connector.

• Work with the AS2 target connector.

Understanding Using AS2

AS2 is specification for Electronic Data Interchange (EDI) between organizations using the internet. AS2 uses Secure/Multipurpose Internet Mail Extensions (S/MIME), which secures data with authentication, nonrepudiation and encryption. The transportation protocol for this specification is HTTP and HTTPS for real-time communication. S/MIME secures data with authentication, message integrity and nonrepudiation.

PeopleSoft Integration Broker provides three connectors for use with AS2:

You can use the AS2 listening and target connectors to transport any kind of data, including, but not limited to, XML, EDI, text and binary data.

Understanding MDNs

AS2 uses two different message types: the request message containing the data to be integrated and the Message Disposition Notification (MDN) to acknowledge the receipt of the data.

AS2 message exchange can occur over HTTP or HTTPS. The sender must request and MDN from the receiver, that enables the sender to verify that the message has been transferred in an unmodified state and that the receiver has been able to decompress or decrypt the message.

As an option, an MDN may be digitally signed, enabling the recipient to authenticate the sender of the MDN to check the integrity of the incoming message.

MDNs can be delivered synchronously or asynchronously.

Synchronous MDNs

Synchronous MDNs are returned to the sender in the same HTTP connection that sent the message. Processing does not continue until the sender receives the MDN.

Asynchronous MDNs

Asynchronous MDNs are delivered to the sender at a later time after the transmission of the message.

AS2 Requests initiated by the AS2 target connector with an asynchronous MDN Type must send MDN asynchronous responses to the AS2 response connector at the following URL:

http://<SERVER><PORT>/PSIGW/AS2ResponseConnector

The AS2 response connector processes MDNs by verifying them with sent request and publishes a response message to the PeopleSoft Integration Broker.

When a message is published the AS2 target connector stores the information regarding the request (for example, MessageID, signed algorithm, and so forth) for verifying the response on the integration gateway. When the response is received, the AS2 response connector verifies with the request information and publishes a response message to PeopleSoft Integration Broker.

A published asynchronous response is an empty message with the following structure:

<? Xml version="1.0">
<AS2ASyncResponse>
      <ConversationID>123213</ConversationID> 
      <OriginalMessageID>23234<OriginalMessageID>
      <MDN>123123 . . </MDN>
      <ReceiptMessage> <![CDATA[Receipt message.]]></ReceiptMessage> 
      <MDNVerified>True/False<MDNVerified> 
</AS2ASyncResponse>

PeopleSoft Integration Broker generates the conversation ID tag when a message is published. This tag is used to correlate the MDN with the request message.

If the MDNVerified tag is set to True, the integration gateway has successfully verified the MDN.

Note. To provide application the flexibility to take appropriate action with responses and response status information, it is the developer's responsibility to write subscription PeopleCode for processing acknowledgement messages and correlating them with requests. Without subscription PeopleCode to consume the message, an MDN will not be sent back to the source.

PeopleCode Considerations

In outbound messages, always use the &msg.publish () or publisXMLDoc () functions. Using SyncRequest or SyncRequestXMLDoc results in errors.

Understanding the AS2 Listening Connector

The AS2 listening connector can receive inbound asynchronous request messages, and can send synchronous and asynchronous MDNs. This section describes how these messages flow through the AS2 listening connector and how MDNs are created and returned to the senders of messages.

Inbound Asynchronous Request—Synchronous MDN

This section describes the process flow of an inbound asynchronous request message through the AS2 listening connector, with the integration engine generating a synchronous MDN.

1. The AS2 listening connector receives an AS2 message over an open HTTP connection.

2. The connector verifies the digital signature and decrypts the message. If necessary, the connector also decompresses the message.

3. The AS2 listening connector sends the message to the integration engine.

4. The integration engine creates an MDN and sends it back to the integration gateway as part of the HTTP response message.

Inbound asynchronous Request—Asynchronous MDN

This section describes the process flow of an inbound asynchronous request message through the AS2 listening connector, with the integration engine generating an asynchronous MDN.

1. The AS2 listening connector receives a message over HTTP.

2. The AS2 listening connector closes the connection and sends a status code of 200.

3. The connector verifies the digital signature and decrypts the message. If necessary, the connector also decompresses the message.

4. The AS2 listening connector sends the message to the integration engine.

5. The integration engine creates an MDN and sends it back to the sender as an asynchronous transaction, using the AS2 target connector.

Understanding the AS2 Response Connector

When a request is published, PeopleSoft Integration Broker generates a conversation ID in the message ID field of the request message. Then, when an MDN comes back it extracts the conversation ID from the message to correlate the MDN acknowledgement with the request message.

Note. You must write subscription PeopleCode to process acknowledgement messages and to correlate them with requests messages. This provides flexibility for you to specify actions to take based on response status.

When it receives an MDN, the AS2 response connector checks for the conversation ID, constructs the asynchronous response message by setting the conversation ID, MDN, and the message/subject received with the MDN. It then sends the response to the integration engine.

Understanding the AS2 Target Connector

This section describes how messages flow through the AS2 target connector and how the connector processes MDNs.

Note. The AS2 target connector sends message requests in asynchronous mode only. However, the connector can receive MDNs in synchronous or asynchronous mode.

Outbound Asynchronous Request—Synchronous MDN

This section describes the process flow of outbound asynchronous request message through the AS2 listening connector, with the integration engine generating a synchronous MDN.

1. The AS2 target connector receives the request message from the integration engine.

2. The AS2 target connector checks the outbound message to determine if an MDN is required, and if so, whether the MDN is synchronous or asynchronous.

3. The AS2 connector makes an HTTP request to the receiver.

4. The AS2 connector verifies the MDN in the HTTP response if an MDN is requested.

5. Once the MDN is verified, the AS2 connector sends a response to the integration engine indicating whether the message was sent successfully.

Outbound Asynchronous Request—Asynchronous MDN

This section describes the process flow of an outbound synchronous request message through the AS2 listening connector, with the integration engine generating an asynchronous MDN.

1. The AS2 target connector receives the request message from the integration engine.

2. The AS2 target connector checks the outbound message to determine if an MDN is required, and if so, whether the MDN is synchronous or asynchronous.

3. Check for MDNAsynchronousURL and request a Asynchronous Receipt (MDN).

4. The AS2 connector makes an HTTP request to the receiver.

5. The AS2 connector reads the HTTP status code and sends a response to the integration engine indicating whether the message was sent successfully.

6. At a later time, the AS2 listening connector receives an MDN from the receiver. The MDN is then processed.

Using the AS2 Listening Connector

This section describes how to use the AS2 listening connector and discusses how to:

• Set required header parameters.

• Set optional header parameters.

• Set gateway-level properties.

Setting Required Header Parameters

The following HTTP header parameters are require in incoming AS2 requests:

If the AS2From and AS2To node names are not PeopleSoft node names, you must map them in the integrationGateway.properties file.

Setting Optional Header Parameters

When using the AS2 listening connector, you may set the following optional HTTP header parameters:

Setting Gateway-Level Properties

To configure the AS2 listening connector, you must set properties located in the integrationGateway.properties file for each message the connector receives.

Note. Replace text in angle brackets (for example <project_branch>) with the appropriate values.

Using the AS2 Target Connector

This section describes using the AS2 target connector and discusses how to:

• Set node-level connector properties.

• Set gateway-level connector properties.

Setting Node-Level Connector Properties

The following table lists the required and optional AS2 target connector properties you set at the node level. You set these properties in the Gateways component in the PeopleSoft Pure Internet Architecture.

Setting Gateway-Level Connector Properties

This section describes required AS2 target connector properties you set in the integrationGateway.properties file.

The AS2 target connector uses digital certificates for digital signatures, nonrepudiation and encryption.

As a result, you must set up digital certificates to use the connector.

Public keys and signatures are stored in certificates, so there must be a place in the organization to store these keys and certificates.

The place to store keys is the key store. A key store can be a flat file, a database or an LDAP server that can store key material. PeopleSoft keystore is installed with the PeopleSoft Pure Internet Architecture at the following default location: <PS_HOME>\webserver\peoplesoft\keystore. PeopleSoft AS2 connectors will invoke these certificates from JKS. JKS exists on WebServer.

The following properties should be set in the integrationGateway.properties file of the source web server in order to use the AS2 target connector. Use the PSCipher utility to encrypt the password.

Working With the SMTP Target Connector

The SMTP target connector enables the gateway to send messages by email using SMTP. This connector supports plain text and HTML text content types. The connector supports the following fields: To:, From:, cc:, and bcc:. You can send data of any format in the body of the email.

You can include only one email address per type of address in the header. For instance, you can include only one addressee as a destination (DestEmailAddress).

The connector ID for the SMTP target connector is SMTPTARGET.

Gateway-Level Connector Properties

The SMTP target connector has one gateway-level property, in the section of the integrationGateway.properties file labeled DELIVERED CONNECTOR CONFIGURATION Section. This property specifies the SMTP mail server host through which the connector sends messages. Specify the host as follows:

ig.connector.smtptargetconnector.host=SMTP_domain_name

Node-Level Connector Properties

The following table describes the required node-level connector properties:

Working With the POP3 Target Connector

This section provides an overview of the POP3 target connector and discusses how to:

• Work with the default POP3 node definition.

• Pass connector properties as defined.

• Override the defined connector properties.

Understanding the POP3 Target Connector

Use the POP3 target connector to retrieve messages from a POP3 email server. You can use it in two different cases. You can use it when a single user has an account, and you can use it when an application has an account.

Note. The POP3 target connector is a deprecated technology. Its functionality is provided by the GetMail target connector. Existing integrations that use the POP3 target connector will still function without modification. However, PeopleSoft recommends that you develop new integrations to receive email using the GetMail target connector. See the Enterprise PeopleTools 8.46 PeopleBook: Multichannel Framework, “Configuring the Email Channel,” for more information on the GetMail target connector.

The POP3 target connector supports attachments. Before using the attachments feature, you should make sure that the web server and application server have sufficient memory to handle large attachments.

PeopleSoft provides a default node for use with the POP3 target connector, called PT_EMAIL_POP3. More information about this node, including messages and transactions defined for it, is provided later in this section.

The connector ID for the POP3 target connector is POP3TARGET.

POP3 Services

When you use the POP3 target connector, you can execute the following predefined services:

Note. When you use the ReadMessage or DeleteMessage services, you must specify a UIDL value. UIDL is a system used by POP3 servers to uniquely identify a mail message. The UIDL is a fixed string (CHAR, 70) that is unique to the message. The UIDL of a message never changes and is never reused, even when the message has been deleted from the user's mailbox.

Node-Level Connector Properties

The POP3 target connector has the following node-level properties:

The POP3 target connector returns an empty message in addition to the actual message responses for the following MethodName values: ReadAll, ReadDeleteAll, ReadHeaders, ReadHeadersWithAttach, and ReadMessage services.

You must create separate transactions for the POP3 node for each service; for example, ReadAll, ReadAndDelete, MessageCount, and so forth. For single-user accounts, you set values for server, port, account, user, password, and method name in a request message that contains the EMAIL_RES_WRK work record.

Working With the Default POP3 Node Definition

This section discusses how to:

• Configure the POP3 default node.

• Use the PT_EMAIL_POP3 node.

• Retrieve specific messages from the POP3 server.

• Pass node-level connector properties.

Configuring the POP3 Default Node

The POP3 target connector default node, PT_EMAIL_POP3, has a transaction predefined for each method name value (or service). To configure the node, you must edit each transaction and specify the POP3 server name, user name, and password.

You use the Node Definitions - Transactions page to configure the default node:

To set up transactions for PT_EMAIL_POP3:

1. Select PeopleTools, Integration Broker, Integration Setup, Node Definitions.

   The Nodes page appears.

2. Search for and open the POP3 default node, PT_EMAIL_POP3.

3. Select the Transactions tab.

   The predefined transactions for the node appear.

4. Click the Edit link next to the transaction to set up.

   Transaction detail tabs appear.

5. Select the Connectors tab.

   You may have to click View All link to view all properties for a transaction.

6. Specify values for the following properties:

   • Password

   • Port

   • Server

   • User

7. Click Save.

To set up other transactions for the node, click the Return to Transaction List link and repeat steps 4 through 7

Using the PT_EMAIL_POP3 Node

PeopleSoft provides a default node called PT_EMAIL_POP3 for use with the POP3 target connector.

PeopleSoft provides the several message definitions with the PT_EMAIL_POP3 node. The request message name identifies a transaction for the node. The response message name indicates the response returned by the POP3 target connector. For example, when you send the message EMAIL_REQ_MSGCOUNT, it internally executes the service MessageCount and returns the response in the EMAIL_RES_MSGCOUNT message.

Note. The values each message returns depends on the service. The POP3 services are described earlier in this section.

PeopleSoft provides the following message definitions with the PT_EMAIL_POP3 node:

All predefined request messages contain the EMAIL_REQ_WRK record. When a request message passes through the POP3 target connector, it retrieves data from the following fields in the EMAIL_REQ_WRK record:

The POP3 target connector then takes the field values from the EMAIL_REQ_WORK and generates a response. The response is contained in the EMAIL_RES_WRK record. The EMAIL_RES_WRK record contains the field values shown in the following table:

An additional record, EMAIL_ATT_WRK, is returned when there is an attachment. EMAIL_ATT_WRK is a child of EMAIL_RES_WRK. The record EMAIL_ATT_WRK contains the following fields:

Retrieving Specific Messages from the POP3 Server

You can retrieve specific messages if you are using the ReadMessage, DeleteMessage, and ReadMessageWithAttach services. To retrieve specific messages for these services, set the UIDL in the SyncRequest ( ) method to the value of the message that you want to read. The messages that you specify are located in the EMAIL_RES_MESSAGE table.

To retrieve all messages, enter the value New for the UIDL.

Passing Node-Level Connector Properties

Most POP3 requests are performed using the SyncRequest ( ) method, as shown here:

SyncRequest([NodeName])

There are two ways to pass node-level properties to the POP3 target connector:

• Pass the values defined for the node as defined in the node definition.

• Override all the values defined in the node definition at runtime.

  In this case, you pass property values through method field records.

Passing Connector Properties as Defined

The following code examples demonstrate how to populate the UIDL field before the SyncRequest ( ) call to ensure that PeopleSoft Integration Broker provides a message response in structured message format when no field values are set in the request.

The examples also show the code that you need to add to the end of the request to pass property values via method field records.

MessageCount

The following example shows how to execute SyncRequest for MessageCount:

Local Message &MSG;
Local Message &response;

&MSG = CreateMessage(Message.EMAIL_REQ_MSGCOUNT);
&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField
(Field.UIDL).Value = "NEW";

&response = &MSG.SyncRequest(Node.PT_EMAIL_POP3);

If (&response.ResponseStatus = 0) Then
    &str = &response.GetRowset().GetRow(1).GetRecord
    (Record.EMAIL_RES_WRK).GetField(Field.NUMROWS).Value

End-If;

ReadAll

The following example shows how to execute SyncRequest for ReadAll:

Local Message &MSG;
Local Message &response;

&MSG = CreateMessage(Message.EMAIL_REQ_READALL);
&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField
(Field.UIDL).Value = "NEW";

&response = &MSG.SyncRequest(Node.PT_EMAIL_POP3);

If (&response.ResponseStatus = 0) Then
    /* get field values here */

End-If;

ReadMessage

The following example shows how to execute SyncRequest for ReadMessage:

Local Message &MSG;
Local Message &response;

&MSG = CreateMessage(Message.EMAIL_REQ_READMSG);
   &MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_
      WRK).GetField
   (Field.UIDL).Value = &uidl;
   /* UIDL of the message to read */

&response = &MSG.SyncRequest(Node.PT_EMAIL_POP3);

If (&response.ResponseStatus = 0) Then
/* get field values here */

End-If;

DeleteMessage

The following example shows how to execute SyncRequest for DeleteMessage:

Local Message &MSG;
Local Message &response;

&MSG = CreateMessage(Message.EMAIL_REQ_DELMSG);
&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).
   GetField
(Field.UIDL).Value = &uidl;
/* UIDL of the message to delete */

&response = &MSG.SyncRequest(Node.PT_EMAIL_POP3);

If (&response.ResponseStatus = 0) Then
   /* get status of deleted message in NUMROWS field. */
   /* this is 1 if the message was found and deleted. */

End-If;

ReadHeaders

The following example shows how to execute SyncRequest for ReadHeaders:

Local Message &MSG;
Local Message &response;

&MSG = CreateMessage(Message.EMAIL_REQ_READHDR);
&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).
   GetField
(Field.UIDL).Value = "NEW";

&response = &MSG.SyncRequest(Node.PT_EMAIL_POP3);

If (&response.ResponseStatus = 0) Then
   /* get field values here */

End-If;

ReadHeadersWithAttach

The following example shows how to execute SyncRequest for ReadHeadersWithAttach:

Local Message &MSG;
Local Message &response;

&MSG = CreateMessage(Message.EMAIL_REQ_READHDRATT);
&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK).GetField
(Field.UIDL).Value = "NEW";

&response = &MSG.SyncRequest(Node.PT_EMAIL_POP3);

If (&response.ResponseStatus = 0) Then
   /* get field values here */

End-If;

ReadMessageWithAttach

The following example shows how to execute SyncRequest for ReadMessageWithAttach:

Local Message &MSG;
Local Message &response;

&MSG = CreateMessage(Message.EMAIL_REQ_READMSGATT);

/* read value from the page */
&str = GetRecord(Record.EMAIL_RES_WRK).GetField(Field.UIDL)
   .Value;
&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK)
   .GetField
(field.UIDL).Value = &str;

&response = &MSG.SyncRequest(Node.PT_EMAIL_POP3);

If (&response.ResponseStatus = 0) Then
   /* get field values here */
   /* level 0 Rowset */
   &rs = &response.GetRowset();

 /* There is always an empty record, so start from 2 */
   For &i = 2 To &rs.ActiveRowCount

          /* Get each row */
          &row = &rs.GetRow(&i);
          /* level 0 record */
          &rec = &row.GetRecord(Record.EMAIL_RES_WRK);

          &rs1 = &row.GetRowset(Scroll.EMAIL_ATT_WRK);
          &count = &rs1.ActiveRowCount;
          For &j = 1 To &count
             &row1 = &rs1.GetRow(&j);
             &rec1 = &row1.GetRecord(Record.EMAIL_ATT_WRK);
             &str = &rec1.GetField(Field.FILENAME).Value;
             &BI_FILE.WriteLine("Message Part: " | &j);

             /* Do different action based on Content Type */
             &BI_FILE.WriteLine("Content Type:" |
                &rec1.GetField(Field.CONTENT_TYPE).Value);

             &str = &rec1.GetField(Field.FILENAME).Value;
             &BI_FILE.WriteLine("File Name:" | &str);

             /* Found a file name? − do something with */
             /* the file data*/
             If All(&str) Then

                  /* if the file name was not available, */
                  /* Content-Id in the message is used, */
                  /* this has "<" and ">" in it.*/

                  &str = Substitute(&str, "<", "");
                  &str = Substitute(&str, ">", "");
                  &FILE = GetFile("C:\TEMP\download\FILE" |
                     &str,"w", "a", %FilePath_Absolute);

                  &FILE.WriteRaw(&rec1.FILE_DATA.Value);
                  &FILE.Close();
             Else
                  &BI_FILE.WriteLine("File Data: " |
                     &rec1.GetField(Field.EMAIL_TEXTLONG)
                     .Value);
             End-If;
        End-For;

      &BI_FILE.WriteLine("Message " | &i);

      &str = &rec.GetField(Field.EMAIL_FROM).Value;
      &BI_FILE.WriteLine("From : " | &str);

      &str = &rec.GetField(Field.DATE_FROM).Value;
      &BI_FILE.WriteLine("Recv Date: " | &str);

      &str = &rec.GetField(Field.UIDL).Value;
      &BI_FILE.WriteLine("UIDL: " | &str);

      &str = &rec.GetField(Field.WL_SUBJECT).Value;
      &BI_FILE.WriteLine("Subject : " | &str);
      &str = &rec.GetField(Field.EMAIL_TEXTLONG).Value;
      &BI_FILE.WriteLine("Body: " | &str);
      &str = &rec.GetField(Field.ATTACHMENTS).Value;
      &BI_FILE.WriteLine("Attachments list : " | &str);

   End-For;
Else;
   &BI_FILE.WriteLine("Bad Response");
End-If;

Overriding the Defined Connector Properties

You can override all values defined for the POP3 target connector in the node definition at runtime by passing property values via method field records. The code for each service is the same as described in the previous section. However, you must also pass the following information: POP3 server name, user, password and method name.

To pass property values via method field records, you can use the code examples in the previous section and add the following code to the end of each example:

&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK)
.GetField(Field.SERVER).Value = <server name of POP3 
 server to connect>;

&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK)
.GetField(Field.USER).Value = <user name for the mail a/c 
to get emails>;

&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK)
.GetField(Field.PASSWORD).Value = <password for the user 
used>;

&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK)
.GetField(Field.MethodName).Value = <Service name to be 
executed>;

/* must specify the port number */

&MSG.GetRowset().GetRow(1).GetRecord(Record.EMAIL_REQ_WRK)
.GetField(Field.Port).Value= 110;