How to Publish a Request Document and Wait for a Reply
The following describes the general steps you take to code a service that publishes a request document and waits for a reply.
1. Create a document reference to the publishable document type that you want to publish. 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 link or assign a value to the document reference
immediately. 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 (_env field) of the document reference. When a service or adapter notification publishes a document, Integration Server and the messaging provider (Broker or Universal Messaging) automatically assign values to fields in the document envelope. However, you can manually set some of these fields. Integration Server, Broker, and Universal Messaging do not overwrite fields that you set manually. For more information about assigning values to the document envelope, see
Setting Fields in the Document Envelope. Important:
When you create a service that publishes 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 change the replyTo value, responses will 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:publishAndWait to publish the document. This service takes the document you created and publishes it.
The pub.publish:publishAndWait 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:publishAndWait.
Name | Description |
documentTypeName | A String specifying the fully qualified name of the publishable document type that you want to publish an instance of. The publishable document type must exist on Integration Server. If the publishable document type in documentTypeName is associated with a Universal Messaging connection alias, the Enable Request/Reply Channel and Listener check box must be selected for the alias. When this check box is selected, Integration Server ensures that a request/reply channel exists for the Universal Messaging connection alias on the Universal Messaging server and that Integration Server has a listener that subscribes to the alias-specific request/reply channel. If the check box is cleared, there will be no channel in which Universal Messaging can collect replies and no listener with which Integration Server can retrieve replies. The pub.publish:publishAndWait service will end with a ServiceException if the he Enable Request/Reply Channel and Listener check box is not selected for the Universal Messaging connection alias. |
You may also provide the following optional parameters:
Name | Description |
receiveDocument TypeName
| 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 that it receives for this request. 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. |
local | A String indicating whether you want to publish the document locally. When you publish a document locally, the document remains on the publishing Integration Server. Integration Server does not publish the document to the Broker. Only subscribers on the same Integration Server can receive and process the document. The local parameter applies only when the publishable document type specified for documentTypeName uses the Broker connection alias. A publishable document type that specifies Universal Messaging as the messaging provider cannot be published locally. A publishable document type that specifies the IS_LOCAL_CONNECTION alias can be published locally only. Integration Server uses the local value only if the publishable document type uses a Broker connection alias. |
| Set to... | To... |
| true | Publish the document locally. |
| false | Publish the document to the configured Broker. This is the default. |
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:publishAndWait 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:publishAndWait service is the same value that Integration Server places in the tag field of the request document envelope.
7. Invoke pub.publish:waitForReply to retrieve the reply document. If you configured the pub.publish:publishAndWait 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 containing the tag value of the asynchronously published request to tag.
8. Process the reply document. The pub.publish:publishAndWait (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.
If the pub.publish:publishAndWait service provides a value for receiveDocumentTypeName, the reply document must be of the type specified in the receiveDocumentTypeName field.
Note:
A single publish and wait request might receive many response documents. The publishing Integration Server uses only the first reply document it receives from the messaging provider. Integration Server discards all other replies. First is arbitrarily defined. There is no guarantee provided for the order in which the messaging provider processes incoming replies. If you need a reply document from a specific client, use the pub.publish:deliverAndWait service instead.