Example 5: Using the AS2 Connectors

This section discusses using the AS2 listening and AS2 target connectors.

The purpose of the AS2 protocol is to allow the secure exchange of EDI data over the internet with trading partners. In the simplest case of an AS2 Message exchange, a sender packages data into an AS2 message structure and sends the message to trading partner over HTTP. Any kind of data can be transferred using AS2, including XML, EDI, text and binary.

The examples in this section demonstrate using the AS2 target connector to send an XML message to an external trading partner and using the AS2 listening connector to receive an XML message from a trading partner.

To use the examples in this section, security certificates must be setup and registered in the keystore on the source and target machines. Take note of the certificate alias name for both the source or signer and the target or recipient servers, as you will need this information to set connector properties.

Verify that messages can be sent to and received from the AS2 external trading partner over HTTP before proceeding with the examples.

For the AS2 target connector example, you will need a third-party application to consume and view the messages created. For the AS2 listening connector example, you will need a third-party application to create and deliver the messages.

In this example PeopleSoft Integration Broker will generate an AS2 message and send it to a trading partner using HTTP. The external trading partner consumes the message. This example shows the tasks to perform to receive an MDN response message back synchronously or asynchronous.

To use the AS2 target connector:

In PeopleSoft Application Designer open the EXAMPLE_WORKREC record and add the following PeopleCode to the FieldChange event for the TEST field:

/*create an XML document */
Local string &xmldata;
Local XmlDoc &xmlDoc;
Local XmlNode &rootNode, &descNode;
Local boolean &result;

&xmldata = "<AS2ConnectorTest/>";

&xmlDoc = CreateXmlDoc("");
&rootNode = &xmlDoc.CreateDocumentElement("AS2ConnectorTest");
&rootNode = &xmlDoc.DocumentElement;

/* add text to the document */
&descNode = &rootNode.AddElement("TestNode");
&descNode.NodeValue = "Sending a AS2 message.";

&MSG = CreateMessage(Operation.EXAMPLE_SERVICE_ASYNC_OPR);
&MSG.SetXmlDoc(&xmlDoc);

/* and send it out in an async request */
%IntBroker.Publish(&MSG);

MessageBox(0, "", 0, 0, "AS2 Message sent.");

In the PeopleSoft Pure Internet Architecture, open the node definition for TARGETNODE. Set the Connector ID to AS2TARGET. Set the values for the following required properties:

Property Name	Value
URL	Specify the URL to which messages are sent using this connector.
AS2To	Specify the name of the sending node.
AS2From	Specify the name of the receiving node.
RecipientCertAlias	Specify the alias of the receiving certificate.
SignersCertificateAlias	Specify the alias of the signing certificate.

Add an outbound asynchronous transaction on the AS2TARGETNODE, to identify that the message EXAMPLE_MESSAGE, VERSION_1 will be sent to the URL location.

Set the following properties in the integrationGateway.properties file. Use PSCipher.bat utility located at <PIA_HOME>\webserv\peoplesoft to encrypt the keystore password.

#AS2 Log Directory, logs all incoming and outgoing AS2 request and responses.
#Uncomment and specify the correct directory name to enable logging.
ig.AS2.LogDirectory = c://temp//as2

#AS2 Properties
#Uncomment the following two lines to specify your keystore and AS2 properties
ig.AS2.KeyStorePath=KeyStore Location (use // for windows path)
ig.AS2.KeyStorePassword=EncryptedKeyStorePassword  
ig.AS2.AS2Directory=Location of AS2 Certificates  (required for Async MDN Type)
ig.AS2.LogDirectory=Path to store AS2 Log Files (optional)

Examples
ig.AS2.KeyStorePath=C://pt846-112-R2//webserv//peoplesoft//keystore//pskey
ig.AS2.KeyStorePassword=*** Encrypted password ***
ig.AS2.AS2Directory=c://temp//as2
ig.AS2.LogDirectory = c://temp//as2//logs

If the MDN response is synchronous, go to step 8.
If the MDN response is asynchronous, verify the delivered node named ASYNC_MDN exists.
Verify that the node ASYNC_MDN has an active incoming asynchronous routing for the service operation ASYNC_MDN_RESPONSE. VERSION_1.
Verify that the delivered queue AS2_CHANNEL is not in Pause mode.
Test the connector.
1. Open the test page, and click on the Test button.
2. Verify that the message was sent to the recipient. The exact mechanism for doing so depends on the AS2 trading partner you are using.
3. Verify that the MDN response was sent back to the source. The exact mechanism for doing so depends on the AS2 trading partner you are using.
If the MDN type is set to Async, verify that the ASYNC_MDN_RESPONSE was received.

In this example, you will use the AS2 listening connector to receive a message sent by the AS2 trading partner, and return an MDN synchronous or asynchronous response. Perform all tasks on the target machine. PeopleSoft Integration Broker will consume the message.

To use the AS2 listening connector:

In the PeopleSoft Pure Internet Architecture, choose the node that corresponds to the AS2 trading partner sending the message.
Insert an inbound asynchronous routing corresponding to the service operation EXAMPLE_REQUEST_ASYNC_OPR.VERSION_1 expected.
Insert an outbound asynchronous routing corresponding to the service operation EXAMPLE_RESPONSE_ASYNC_OPR.VERSION_1 as a reply.

In PeopleSoft Application Designer, create an application package and application class, and provide a method OnNotify with the following PeopleCode:

Local XmlDoc &xmlDoc;
   Local File &theFile;
   Local Message &msg;
  Local XmlDoc &MsgXmlDoc,  &xmlDoc;
   Local XmlNode &rootNode, &descNode;
   
   /* get the body of the incoming message */
   &MsgXmlDoc = &MSG.GetXmlDoc(); /* and write it to a file */
   &theFile = GetFile("AS2Request.txt", "W");
   &theFile.WriteString(&MsgXmlDoc.GenXmlString());
   &theFile.Close();
   
   &xmlDoc = CreateXmlDoc("");
   
   &rootNode = &xmlDoc.CreateDocumentElement("ConnectorTest");
   &rootNode = &xmlDoc.DocumentElement; /* add text to the document */
   
   &descNode = &rootNode.AddElement("ResponseMessage");
   &descNode.NodeValue = "This was generated in the OnRequest event."; 
   /* send the response message */
   
   &msg = CreateMessage(Operation.EXAMPLE_RESPONSE_ASYNC_OPR);
   
   &msg.SetXmlDoc(&xmlDoc);
   
   /* and send it out in an async request */
   %IntBroker.Publish(&msg);

In the PeopleSoft Pure Internet Architecture, open the handler tab on the service operation EXAMPLE_RESPONSE_ASYNC_OPR, and set the application package, class name and method.

In the integrationGateway.properties file, set the following properties to the values indicated:

#AS2 Properties
#Uncomment the following two lines to specify your keystore and AS2 properties
ig.AS2.KeyStorePath=KeyStore Location (use // for windows path)
ig.AS2.KeyStorePassword=EncryptedKeyStorePassword  
ig.AS2.LogDirectory=Path to store AS2 Log Files (optional)

#example:
ig.AS2.KeyStorePath=C://pt846-112-R2//webserv//peoplesoft//keystore//pskey
ig.AS2.KeyStorePassword=*** Encrypted password ***
ig.AS2.LogDirectory = c://temp//as2//logs

In the following required properties, replace the <SOURCENODE> with the name of the AS2 trading partner source node, and <TARGETNODE> with the name of the local target node. Continue to set the value of the property.

# CertificateAlias is the certificate of AS2 Listening Node.
# SignerCertificateAlias is the certificate of AS2 trading partner of Listening Node.
ig.AS2.QE_<SOURCE>.<TARGET>.CertificateAlias= Target Machine Alias
ig.AS2. <SOURCE>.<TARGET>.SignerCertificateAlias=Source Machine Alias

#example:
ig.AS2.PSFT_SRC_NODE.PSFT_TGT_NODE.CertificateAlias=<GeneratedAS2certificatealias>
ig.AS2.PSFT_SRC_NODE.PSFT_TGT_NODE.SignerCertificateAlias=<GeneratedAS2certificatealias>

The following values only need to be set if the incoming data does not contain the appropriate AS2To and AS2From values in the header of the message. It is best to leave these values in the request message header and leave these properties commented out.

#This map translate AS2From and AS2To to a different node name. 
#This property is not required if you would use AS2FROM and AS2TO http header.
ig.AS2.AS2ListenerMap.From.<SOURCEALIAS> = Specify the Source Node Name
ig.AS2.AS2ListenerMap.To.<TARGETALIAS> = Specify the Target Node Name

#example:
ig.AS2.AS2ListenerMap.From.QE_SOURCE= PT_LOCAL
ig.AS2.AS2ListenerMap.To. QE_IBTGT= AS2TARGETNODE

Test the connector:
1. Send a text message to the example AS2 queue. Name the message EXAMPLE_REQUEST_MSG.
2. Set the text of the message to:
```
<?xml version="1.0"?>
<ConnectorTest>
<TestNode>Sending a message to the AS2 Listening Connector.</TestNode>
</ConnectorTest>
```
3. Check the file named in the subscription PeopleCode. The default location for this file is <PS_CFG_HOME>\appserv\<DOMAIN_NAME>\Files. The message contents should be present.
4. If the MDN type is asynchronous, verify that the AS2 trading partner received the ASYNC_MDN_RESPONSE.

Example 5: Using the AS2 Connectors

Understanding the AS2 Connector Examples

Prerequisites

Using the AS2 Target Connector

Using the AS2 Listening Connector