Integration Server 10.5 | Publish-Subscribe Developer’s Guide | Publishing Documents | Delivering a Document and Waiting for a Reply | How to Deliver a Document and Wait for a Reply
 
How to Deliver a Document and Wait for a Reply
The following describes the general steps that you take to code a service that delivers a document to a specific destination and waits for a reply.
1. Create a document reference to the publishable document type that you want to deliver. You can accomplish this by:
*Declaring a document reference in the input signature of the publishing service
-OR-
*Inserting a MAP step in the publishing service and adding the document reference to Pipeline Out. You must immediately link or assign a value to the document reference. If you do not, the document reference is automatically cleared the next time the Pipeline view is refreshed.
2. Add content to the document reference. You can add content by linking fields to the document reference or by using the Set Value modifier to assign values to the fields in the document reference.
3. Assign values to fields in the envelope (_envfield) of the document reference. When a service or adapter notification publishes a document, Integration Server and the messaging provider automatically assign values to fields in the document envelope. However, you can manually set some of these fields. Integration Server and the messaging provider do not overwrite fields that you set manually. For more information about assigning values to fields in the document envelope, see Setting Fields in the Document Envelope.
Important:
When you create a service that delivers a document and waits for a reply, do not set the value of the replyTo field in the document envelope. By default, Integration Server uses the publisher ID as the replyTo value. If you set the replyTo value, responses may not be delivered to the waiting service.
4. Set values for custom header fields. When publishing a document to Universal Messaging, you can add custom header fields to the document by assigning values to a _properties document variable in the publishable document type. Integration Server adds the contents of _properties as name=value pairs to the header. Subscribers of the publishable document type can register filters that indicate which documents the subscriber wants to receive based on the custom header field contents. When Universal Messaging receives the published document, it applies the filter and only routes the document to the subscriber if the filter criteria is met.
5. Invoke pub.publish:deliverAndWait to publish the document. This service takes the document you created and publishes it to the messaging provider.
The pub.publish:deliverAndWait service expects to find a document (IData object) named document in the pipeline. If you are building a flow service, you will need to use the Pipeline view to map the document you want to publish to document.
In addition to the document reference you map into document, you must provide the following parameters to pub.publish:deliverAndWait.
Name
Description
documentTypeName
A String specifying the fully qualified name of the publishable document type that you want to publish. The publishable document type must exist on Integration Server.
Note:
Instances of publishable document types that use the IS_LOCAL_CONNECTION messaging connection alias cannot be delivered.
destID
A String specifying the ID for the destination to which you want to deliver the document. You can specify the ID for an individual trigger or the default client of an Integration Server as the destination. When you deliver a document to the default client of Integration Server, Integration Server routes the delivered document to any subscribers on that Integration Server.
If you specify an invalid client ID, the Integration Server delivers the document to the messaging provider, but the messaging provider never delivers the document to the intended recipient and no error is produced.
You may also provide the following optional parameters:
Name
Description
receiveDocumentTypeName
A String specifying the fully qualified name of the publishable document type expected as a reply. This publishable document type must exist on your Integration Server.
If you do not specify a receiveDocumentTypeName value, the service uses the first reply document it receives from the client specified in destID.
Important:
If you specify a document type, you need to work closely with the developer of the subscribing trigger and the reply service to make sure that the reply service sends a reply document of the correct type.
waitTime
A String specifying how long the publishing service waits (in milliseconds) for a reply document. If you do not specify a waitTime value, the service waits until it receives a reply. Integration Server begins tracking the waitTime as soon as it publishes the document.
async
A String indicating whether this is a synchronous or asynchronous request.
Set to...
To...
true
Indicate that this is an asynchronous request. Integration Server publishes the document and then executes the next step in the service.
false
Indicate that this is a synchronous request. Integration Server publishes the document and then waits for the reply. Integration Server executes the next step in the service only after it receives the reply document or the wait time elapses. This is the default.
6. Map the tag field to another pipeline variable. If this service performs a publish and wait request in an asynchronous manner (async is set to true), the pub.publish:deliverAndWait service produces a field named tag as output. The tag field contains a unique identifier that Integration Server uses to match the request document with a reply document.
If you create a service that contains multiple asynchronous requests, make sure to link the tag output to another field in the pipeline. Each asynchronously published request produces a tag field. If the tag field is not linked to another field, the next asynchronously published request (that is, the next execution of the pub.publish:publishAndWait service or the pub.publish:deliverAndWait service) will overwrite the first tag value.
Note:
The tag value produced by the pub.publish:deliverAndWait service is the same value that Integration Server places in the tag field of the request document’s envelope.
7. Invoke pub.publish:waitForReply to retrieve the reply document. If you configured the pub.publish:deliverAndWait service to publish and wait for the document asynchronously, you need to invoke the pub.publish:waitForReply service. This service retrieves the reply document for a specific request.
The pub.publish:waitForReply service expects to find a String named tag in the pipeline. (Integration Server retrieves the correct reply by matching the tag value provided to the waitForReply service to the tag value in the reply document envelope.) If you are building a flow service, you will need to use the Pipeline view to map the field.
8. Process the reply document. The pub.publish:deliverAndWait (or pub.publish:waitForReply) service produces an output parameter named receivedDocument that contains the reply document (an IData object) delivered by a subscriber.
If the waitTime interval elapses before Integration Server receives a reply, the receivedDocument parameter contains a null document.