Integration Server 10.3 | Publish-Subscribe Developer’s Guide | Publishing Documents | Replying to a Published or Delivered Document | How to Create a Service that Sends a Reply Document
 
How to Create a Service that Sends a Reply Document
The following describes the general steps you take to code a service that sends a reply document in response to a received document.
1. Declare a document reference to the publishable document type. In the input signature of the service, declare a document reference to the publishable document type for the received document. The name of the document reference must be the fully qualified name of the publishable document type.
If you intend to use the service to reply to documents that satisfy a join condition (a condition that associates multiple publishable document types with a service), the service’s input signature must have a document reference for each publishable document type. The names of these document reference fields must be the fully qualified names of the publishable document type they reference.
2. Create a document reference to the publishable document type that you want to use as the reply document. You can accomplish this by:
*Declaring a document reference in the input signature of the replying service
-OR-
*Inserting a MAP step in the replying 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.
Note:
If the publishing service requires that the reply document be an instance of a specific publishable document type, make sure that the document reference variable refers to this publishable document type.
3. Add content to the reply document. You can add content to the reply document by linking fields to the document reference or by using the Set Value modifier to assign values to the fields in the document reference.
4. Assign values to fields in the envelope (_env field) of the reply document. When a service or adapter notification publishes a document, Integration Server and Broker automatically assign values to fields in the document envelope. When you create a service that sends a reply document, Integration Server uses the field in the envelope of the received document to populate the reply document envelope. However, you can manually set some of these fields. Integration Server and Broker do not overwrite fields that you set manually. For more information, see Setting Fields in the Document Envelope.
5. 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.
6. Invoke pub.publish:reply to publish the reply document. This service takes the reply document you created and delivers it to the client specified in the envelope of the received document.
The pub.publish:reply 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 reference for the document you want to publish to document.
In addition to the document reference that you map into document, you must provide the following parameters to the pub.publish:reply service.
Name
Description
documentTypeName
A String specifying the fully qualified name of the publishable document type for the reply document. The publishable document type must exist on Integration Server.
Important:
Services that publish or deliver a request and wait for a reply can specify a publishable document type to which reply documents must conform. If the reply document is not of the type specified in receiveDocumentTypeName parameter of the pub.publish:publishAndWait or pub.publish:deliverAndWait service, the publishing service will not receive the reply. You need to work closely with the developer of the publishing service to make sure that your reply document is an instance of the correct publishable document type.
You may also provide the following optional parameters.
Name
Description
receivedDocumentEnvelope
A document (IData object) containing the envelope of the received document. By default, Integration Server uses the information in the received document’s envelope to determine where to send the reply document.
If the service executes because two or more documents satisfied an All (AND) join condition, Integration Server uses the envelope of the last document that satisfied the join condition. If you want Integration Server to always use the envelope from the same document type, link the envelope of that publishable document type to receivedDocumentEnvelope. If you want each document publisher to receive a reply document, you must invoke the pub.publish:reply service for each document in the join.
Important:
If the replying service executes because a document satisfied an Any (OR) or Only one (XOR) join condition, do not map or assign a value to the receivedDocumentEnvelope. It is impossible to know which document in the Any (OR) or Only one (XOR) join will be received first. For example, suppose that an Only one (XOR) join condition specified document types documentA and documentB. Integration Server uses the envelope of whichever document it received first as the receivedDocumentEnvelope value. If you map the envelope of documentA to receivedDocumentEnvelope, but Integration Server receives documentB first, the reply service will fail.
Name
Description
delayUntilServiceSuccess
A String specifying that Integration Server will delay publishing the reply document until the top-level service executes successfully. If the top-level service fails, Integration Server will not publish the reply document.
Set to...
To...
true
Delay publishing until after the top-level service executes successfully.
false
Publish the document when the pub.publish:reply service executes. This is the default.
7. Build a trigger. For this service to execute when Integration Server receives documents of a specified type, you need to create a trigger. The trigger needs to contain a condition that associates the publishable document type used for the request document with this reply service. For more information about creating a trigger, see webMethods Service Development Help.