Receiving and Sending Envelopes

Build an Envelope Handler Service

About this task

The WmMarketConnectExample package contains sample envelope handler services.

To build an envelope handler service

Procedure

  1. Open Designer and create a new package. Declare that the package is dependent on the Integration Server package WmMarketConnect. For more information, see the IBM webMethods Service Development Help for your release.
  2. In the new package, create a service that represents an envelope handler service.
  3. If the handler service is to process both incoming envelopes sent synchronously and incoming envelopes sent asynchronously, but you want to process the envelopes differently based on their request mode, have the handler service call the getRequestMode service. Then use a branching flow statement to set up separate logic for processing synchronous and asynchronous requests.
  4. In the handler service, call services to get information from each incoming envelope, as follows:
    1. Call the getEnvelopeHeader service to get the envelope header information.
    2. Call the getDocumentHeader service to get the xCBL request document's header information.
    3. Call a service such as getDocumentAsNode to get the xCBL request document.
    4. In your C1 OnRamp configuration, you specified whether to validate all incoming xCBL documents. If you want to override that default setting, specify the validate parameter on the getDocument service you call.
    5. Call a service such as getAttachmentList to get attachments, if any.

    You can also have the handler service call custom services to process the document and attachments. (For instructions on writing custom services, see the IBM webMethods Service Development Help for your release).

  5. Handle the reply to each incoming envelope. This step varies based on the incoming envelope's request mode.
    • If the incoming envelope's request mode is synchronous, your custom services return an xCBL response document to the handler service. In the handler service, call services to create a reply envelope to return to MarketSite, as follows:
      1. In your C1 OnRamp configuration, you specified whether to validate all outgoing xCBL documents. If you want to override that default setting, call the parseString service.
      2. If your back-end system cannot handle DDIDs, call the getDDID service to get the DDIDs that correspond to the sender ID and recipient IDs provided by your back-end system. You must call the service twice, once to get the DDID for the sender ID and once to get the DDID for the recipient ID.
      3. Call a service such as the createEnvelopeFromRecord service to create a reply envelope that contains the xCBL response document).
      4. In the header of the reply envelope, use the correlationId from the header of the incoming envelope. If you want to specify non-standard fields in the reply envelope header, insert the name/value pairs in the customProperties envelope header record.
      5. Call a service such as the createBinaryAttachment service to create any necessary attachments. If you want to create an attachment from a string, use the Integration Server service pub.string:bytesToString.
      6. Call the addAttachmentToEnvelope service to add the attachments to the envelope.
      7. Return the reply envelope to the receiveEnvelope service to return to MarketSite.
    • If the incoming envelope's request mode is asynchronous, the handler service typically does not have to create a reply envelope. By default, when no errors occur during processing, C1 OnRamp returns a reply envelope to MarketSite that contains a default acknowledgement. If you want to create a custom acknowledgement, call the createAcknowledgement service; this service creates a reply envelope containing your custom acknowledgement and returns the reply envelope to the receiveEnvelope service to return to MarketSite. In the header of the reply envelope, use the correlationId from the header of the incoming envelope.

    For either request mode, when errors occur during processing, C1 OnRamp by default returns a reply envelope to MarketSite that contains a default error. If you want to create a custom error, call the createError service; this service creates a reply envelope containing your custom error and returns the reply envelope to the receiveEnvelope service to return to MarketSite. In the header of the reply envelope, use the correlationId from the header of the incoming envelope.

    You can also have the handler service call custom services to create reply envelopes. (For instructions on writing custom services, see the IBM webMethods Service Development Help for your release).

Build a Send Service

About this task

The WmMarketConnectExample package contains sample send services.

To build a send service

Procedure

  1. Open Designer.
  2. Create a service that represents the send service in either of two locations, depending on the purpose of the send service:
    • If the send service is to create and send envelopes containing xCBL response documents to MarketSite in reply to asynchronous requests, create the service in the package containing the envelope handler that processes the asynchronous requests.
    • If the send service is to create and send envelopes containing xCBL request documents to MarketSite, create a new package, declare that the package is dependent on the Integration Server package WmMarketConnect, and create the send service in that package.
  3. In the send service, call services that create and send envelopes, as follows:
    1. In your C1 OnRamp configuration, you specified whether to validate all outgoing xCBL documents. If you want to override that default setting, call the parseString service.
    2. If your back-end system cannot handle DDIDs, call the getDDID service to get the DDIDs that correspond to the sender ID and recipient IDs provided by your back-end system. You must call the service twice, once to get the DDID for the sender ID and once to get the DDID for the recipient ID.
    3. Call a service such as the createEnvelopeFromRecord service to create an envelope that contains the xCBL document.
    4. If you want to specify non-standard fields in the envelope header, insert the name/value pairs in the customProperties envelope header record.
    5. If you are creating a reply envelope, use the correlationId from the header of the incoming envelope in the header of the reply envelope.
    6. Call a service such as the createBinaryAttachment service to create any necessary attachments. If you want to create an attachment from a string, use the Integration Server service pub.string:bytesToString.
    7. Call the addAttachmentToEnvelope service to add the attachments to the envelope.
    8. If necessary, call the pub.security:clearKeyAndChain service or the pub.security:setKeyAndChain service (see Communicate as a Client for more information).
    9. Call the sendEnvelope service to send the envelope to MarketSite.

    You can also have the send service call custom services to create envelopes. (For instructions on writing custom services, see the IBM webMethods Service Development Help for your release).

Build a Startup Service

About this task

When the C1 OnRamp receiveEnvelope service receives an envelope from MarketSite, the service uses a lookup table to route the envelope to the proper registered envelope handler service. You must create a startup service that runs each time you start Integration Server to register the envelope handler services you want to use in the lookup table.

The WmMarketConnectExample package contains a sample startup service.

To build a startup service

Procedure

  1. Open Designer.
  2. In any C1 OnRamp package, create a startup service.
  3. In the startup service, call the setDocumentHandler service once for each handler service you want to register in the envelope handler service lookup table.