Working With the AS2 Connectors
This section discusses how to:
Work with the AS2 listening connector.
Work with AS2 response connector.
Work with the AS2 target connector.
Electronic Data Interchange (EDI) is a standard means of exchanging data between companies so that they can transact business electronically.
PeopleSoft supports the Applicability Statement 2 (AS2) specification for EDI. However, the Oracle SOA Suite B2B component supports AS2 and additional EDI formats and protocols, and provides a full-feature EDI integration solution.
Note: PeopleSoft recommends using the Oracle SOA Suite B2B component for all EDI integrations, including those based on the AS2 specification.
PeopleSoft provides generic integration capabilities with Oracle SOA B2B. Use Oracle Mediator-based services to integrate with Oracle SOA B2B.
Consult the Oracle SOA Suite documentation for EDI specifications supported.
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:
|
Field or Control |
Definition |
|---|---|
| AS2 listening connector |
Use the AS2 listening connector to receive request messages in AS2 format. |
| AS2 response connector |
The AS2 response connector sends acknowledgements for data you receive from the AS2 listening connector. |
| AS2 target connector |
Use the AS2 target connector to send messages in AS2 format. |
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.
The AS2 target connect is segment-aware and you may use it to send message segments to integration partners.
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/AS2ResponseConnectorThe 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.
The AS2 connectors implement correlation IDs in MDNs. The AS2 target connector saves the outbound message ID as a correlation ID in the directory defined in the ig.AS2.AS2Directory in the integrationGateway.properties file .
When the response arrives later, the AS2ResponseConnector checks the conversationID from the response message with the one saved by early. If they don’t match, the transaction fails.
In outbound messages, always use the %Intbroker.publish () function. Using %IntBroker.SyncRequest results in errors.
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.
The AS2 listening connector receives an AS2 message over an open HTTP connection.
The connector verifies the digital signature and decrypts the message. If necessary, the connector also decompresses the message.
The AS2 listening connector sends the message to the integration engine.
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.
The AS2 listening connector receives a message over HTTP.
The AS2 listening connector closes the connection and sends a status code of 200.
The connector verifies the digital signature and decrypts the message. If necessary, the connector also decompresses the message.
The AS2 listening connector sends the message to the integration engine.
The integration engine creates an MDN and sends it back to the sender as an asynchronous transaction, using the AS2 target 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.
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.
The AS2 target connector receives the request message from the integration engine.
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.
The AS2 connector makes an HTTP request to the receiver.
The AS2 connector verifies the MDN in the HTTP response if an MDN is requested.
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.
The AS2 target connector receives the request message from the integration engine.
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.
Check for MDNAsynchronousURL and request a Asynchronous Receipt (MDN).
The AS2 connector makes an HTTP request to the receiver.
The AS2 connector reads the HTTP status code and sends a response to the integration engine indicating whether the message was sent successfully.
At a later time, the AS2 listening connector receives an MDN from the receiver. The MDN is then processed.
See Understanding MDNs.
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 required in incoming AS2 requests:
|
HTTP Header Parameter |
Description |
|---|---|
|
AS2From |
Specify the name of the sending node. |
|
AS2To |
Specify the name of the receiving node. |
|
MessageName |
Specify the name of the incoming operation or message. Note: You can specify the message name in the HTTP header, HTTP query string or in the integrationGateway.properties file. The value is in the form Message.Version. For example: UserProfile.Version_84 |
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:
|
HTTP Header Parameter |
Description |
|---|---|
|
Password |
(Optional.) Specify an encrypted password for node authentication. |
|
OrigUser |
(Optional.) Specify the username of the originating user. |
|
ExternalMessageID |
(Optional.) Specify a unique ID that identifies the message. If two messages are published with the same external message ID, the first message is processed and the second messages is marked as a duplicate. |
Setting Gateway-Level Properties
To configure the AS2 listening connector, you must set properties located in the AS2 Connector Properties of the integrationGateway.properties file for each message the connector receives.
Note: Replace text in angle brackets (for example <project_branch>) with the appropriate values.
A property is required unless denoted as “(Optional.)” in the description.
|
Property |
Description |
|---|---|
|
ig.AS2.LogDirectory |
(Optional.) Specify the directory to log all incoming and outgoing AS2 requests and responses. For example: ig.AS2.LogDirectory = c://temp//as2//logs |
|
ig.AS2.KeyStorePath |
Specify the path to the Java keystore. For example: C://pt853 //webserv//peoplesoft//keystore//pskey |
|
ig.AS2.KeyStorePassword |
Specify the encrypted password to the Java keystore. |
|
ig.AS2.AS2ListenerMap.From.<from alias> |
(Optional.) If a sending or receiving node is not a PeopleSoft node, you must map it in the integrationGateway.properties file. Use this property if the sending system is not a PeopleSoft node. Replace the information in brackets with an alias of the sending system and set it equal to the remote node name in the PeopleSoft application database. For example: ig.AS2.AS2ListenerMap.From.QE_SOURCE= PT_LOCAL |
|
ig.AS2.AS2ListenerMap.To.<to alias> |
(Optional.) If a sending or receiving node is not a PeopleSoft node, you must map it in the integrationGateway.properties file. Use this property if the receiving system is not a PeopleSoft node. Replace the information in brackets with an alias of the receiving system and set it equal to the remote node name in the PeopleSoft application database. For example: ig.AS2.AS2ListenerMap.To. QE_IBTGT= AS2TARGETNODE |
|
ig.AS2.<source>.<target>.CertificateAlias |
Specify the certificate (target) alias name. Replace <source> and <target> with the source and target PeopleSoft node names used in the AS2FROM and AS2TO HTTP headers, or those mapped in the properties above. For example: ig.AS2.PT_LOCAL.AS2TARGETNODE.CertificateAlias=JFRANCO030204 |
|
ig.AS2.<source>.<target>.SignerCertificateAlias |
Specify the certificate alias (source) used for signing the certificate. For example: ig.AS2.PT_LOCAL.AS2TARGETNODE.SignerCertificateAlias=JRICHAR2030104 |
|
ig.AS2.<source>.<target>.MessageName |
(Optional.) Specify the name of the incoming message. Replace <source> and <target> with the source and target PeopleSoft node names used in the AS2FROM and AS2TO HTTP headers, or those mapped in the properties above. For example: ig.AS2. PT_LOCAL.AS2TARGETNODE.MessageName=EXAMPLE_REQUEST_MSG Note: You can specify the message name in the HTTP header, HTTP query string or in the integrationGateway.properties file. |
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.
A property is required unless denoted as “(Optional.)” in the description.
|
Property ID |
Property |
Description |
|---|---|---|
|
AS2PROPERTY |
AS2From |
Specify the name of the sending node. |
|
AS2PROPERTY |
AS2To |
Specify the name of the receiving node. |
|
AS2PROPERTY |
AsynchronousMDNRecipientURL |
Specify a URL that indicates how and where the MDN is delivered. For example: http://<source webserver>:<http port>/PSIGW/AS2ResponseConnector By specifying a valid URL you can request asynchronous delivery instead. The URL indicates the destination for the reply, and may use any appropriate protocol, such as HTTP or HTTPS. If this property is set to an empty string (Default), the receipt is returned synchronously within an HTTP reply. |
|
AS2PROPERTY |
Compression |
Specify whether to compress outbound AS2 messages. Options are:
|
|
AS2PROPERTY |
EDIType |
Specify the content type of the message. Options are:
|
|
AS2PROPERTY |
EnableCRLF |
(Optional.) PeopleSoft Integration Broker automatically removes carriage returns in messages and retains line feeds. Use this property to specify whether to add a carriage return (CR) back to the end of a line feed (LF). Options are:
|
|
AS2PROPERTY |
EncryptingAlgorithm |
(Optional.) Specify the algorithm used to encrypt data. The default value is 3DES. Use of this algorithm is highly recommended. When you specify an encrypting algorithm, you must set the RecipientCertAlias to a valid certificate. The data is encrypted using the RecipientCertAlias value you define with the algorithm you specify here. |
|
AS2PROPERTY |
FirewallHost |
(Optional.) If connecting through a firewall, specify the firewall hostname or IP address. |
|
AS2PROPERTY |
FirewallPassword |
(Optional.) If connecting through a firewall, specify an encrypted password if authentication is to be used when connecting through the firewall. |
|
AS2PROPERTY |
FirewallPort |
(Optional.) If connecting through a firewall, specify the port of the firewall to which to connect. See the description for the FirewallType property for guidelines on how the default setting is made. |
|
AS2PROPERTY |
FirewallType |
(Optional.) If connecting through a firewall, specify the type of firewall. Options are:
You can overwrite port numbers in the FirewallProperty field. |
|
AS2PROPERTY |
Firewall User |
(Optional.) If connecting through a firewall, specify the firewall username if authentication is to be used connecting through a firewall. |
|
AS2PROPERTY |
Http Password |
(Optional.) Specify the HTTP username if HTTP authentication is to be used. |
|
AS2PROPERTY |
HttpUser |
(Optional.) Specify the HTTP username password if HTTP authentication is to be used. |
|
AS2PROPERTY |
MDNSecurityType |
(Optional.) Specify the algorithm to use for signing the MDN. Options are:
|
|
AS2PROPERTY |
MDNType |
Specify whether to generate an MDN, and if so the type to generate. Options are:
|
|
AS2PROPERTY |
ProxyPassword |
(Optional.) Specify the proxy user password. |
|
AS2PROPERTY |
ProxyPort |
(Optional.) Port of the proxy server to which to connect. |
|
AS2PROPERTY |
ProxySSL |
(Optional.) Options are:
|
|
AS2PROPERTY |
ProxyServer |
(Optional.) Specify the proxy server name or IP address. |
|
AS2PROPERTY |
ProxyUser |
(Optional.) Specify the username if authentication is to be used to connect through a proxy. |
|
AS2PROPERTY |
RecipientCertAlias |
(Optional.) Specify the alias name of the recipient's certificate. Note: This property is required if the EncryptingAlgorithm property is set. |
|
AS2PROPERTY |
SecurityType |
Specify the security type of the request message. Options are:
|
|
AS2PROPERTY |
SignersCertificateSubject |
Specify the alias name of the signing certificate. This property is required if the SecurityType property is set to SignedOnly or Signed-Encrypted. |
|
AS2PROPERTY |
TimeOut |
(Optional.) Specify the timeout for the connector in seconds. When this value is set to 0, all operation will run uninterrupted until successful completion, or an error condition is encountered. The default value is 60. |
|
AS2PROPERTY |
User Agent |
(Optional.) Specify the name of the user agent or email address. |
|
BACKUPURL |
URL |
(Optional.) Specify the backup URL to use to send messages if delivery to the primary URL fails. |
|
PRIMARYURL |
URL |
Specify the URL to which messages are sent using this connector. |
|
HEADER |
sendUncompressed |
Specify whether to send messages decompressed. Options are: Y: Send messages decompressed and decoded. (Default.) N: Send messages compressed and base64 encoded. Note: Do not change the default value. |
|
PRIMARYURL |
URL |
Specify the URL to which messages are sent using this connector. For example: http://<target webserver>:<http port>/PSIGW/AS2ListeningConnector |
Setting Gateway-Level Connector Properties
This section describes required AS2 target connector properties you set in the integrationGateway.properties file.
A property is required unless denoted as “(Optional.)” in the description.
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: <PIA_HOME>\webserver\<DOMAIN>\keystore. PeopleSoft AS2 connectors will invoke these certificates from JKS. JKS exists on the web server.
The following properties should be set in the AS2 Connector Properties section 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.
|
Property |
Description |
|---|---|
|
ig.AS2.KeyStorePath |
Specify the path to the Java keystore. For example: C://pt854//webserv//peoplesoft//keystore//pskey |
|
ig.AS2.KeyStorePassword |
Specify the encrypted password to the Java keystore. |
|
ig.AS2.AS2Directory |
Specify the directory to log MDN responses. This property is required for asynchronous MDNs. For example: c://temp//as2 |
|
ig.AS2.LogDirectory |
(Optional.) Specify the directory to log all incoming and outgoing AS2 requests and responses. For example: c://temp//as2//logs |