Build an Envelope Handler Service
The WmMarketConnectExample package contains sample envelope handler services.
![*](icon_task_xpe.png)
To build an envelope handler service
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 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:
b. Call the
getDocumentHeader service to get the xCBL request document's header information. d. 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.
You can also have the handler service call custom services to process the document and attachments. (For instructions on writing custom services, see the 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.
![*](chapterTOC_bullet.png)
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.
7. Return the reply envelope to the
receiveEnvelope service to return to MarketSite.
![*](chapterTOC_bullet.png)
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 webMethods Service Development Help for your release.)