Embedding the Document into XML

Similar to data web notifications, configuring document embedded notifications is done in a wizard-style user interface where you specify information about:

  • Your service endpoint

  • The XML to be passed

  • The expected response

To start configuring a document transmission web notification, go to the “Administration” tab, and click on “DocumentTRAK” under the “Notifications” heading. The “Completed Document Transmission” table allows you to create a new notification or copy an existing one. When creating a new document transmission, select “Embed in a web notification” as the Document Transmission Type.

General Information for Embedded Notification

The interface for specifying the endpoint for a web notification with embedded document is the same as for a data only web notification. Provide a unique name for your service that will help you identify it properly when selecting it later on a template workflow instance. Consider avoiding overly generic names such as “WebService 1” which could cause debugging difficulties later on.

Specify the URL of your service. This will be the working location of your service, for example

Copy 
https://www.assuresign.net/webservices/documentresult.asmx

or

Copy 
http://www.mydomain.com/whathappened.svc

You may specify whether HTTP authentication is to be used, in which case you may either use account-level credentials (specified in your Nintex eSign account settings) or specific credentials for the web service. All such configuration is stored encrypted in the Nintex eSign system. If the communication is to a SOAP based service then you are asked to enter the SOAP action.

Request Message XML for Embedded Notification

The interface for specifying the request message XML for a web notification with embedded document is the same as for a data only web notification. The form of the XML to be passed may be specified by:

  • Manually entering or pasting an XML string

  • Generating the XML from either an online source or a file in the form of:

    • XSD (XML Schema Definition)

    • WSDL (Web Service Definition Language)

While you may enter a non-functioning URL in the end point configuration in the General Information section, it may be beneficial to use a live location that also publishes the WSDL or XSD to save time typing and avoid errors. When specifying the XML from either an online or file source, you will then specify the specific operation to be called (in the case that multiple operations are defined).

In either case (manual entry or dynamic creation), you may then edit the XML to be passed. Nintex eSign web notifications could be used in a limited fashion to merely pass back static responses, but this would be of very limited use. In order to return document-specific information you must modify the XML string to include merge fields.

Two types of merge fields are available for your use:

  • Globally available merge fields

  • Template-specific parameter merge fields

Merge fields may be manually typed into your XML, or the globally available merge fields may be entered by highlighting the section of the XML where they should be inserted and clicking on the merge field name.

Response Validation Method

The returned response may be parsed or confirmed via a variety of mechanisms. Available methods of validation are.

Accept Any Non-Error Response

Any response with HTTP status code 200 will be handled as a success.

Compare Response to Expected XML String

Similar to the Request Message XML builder, you may generate the XML by:

  • Manually entering or pasting an XML string

  • Loading from either an online source or a file in the form of:

    • XSD (XML Schema Definition)

    • WSDL (Web Service Definition Language)

As with the Request Message XML builder, you may insert merge fields whose dynamically populated values will replace the bracketed captions. At run time a case insensitive string comparison will occur (including any merge field values) and the transaction will be considered successful if there is a match.

Note: Comparing the response to an XML string is a literal comparison: all formatting such as tabs and line breaks that will not actually be returned should be removed from your comparison string. If this is a SOAP service the XML declaration and SOAP envelope should be included in your string if they exist in the response XML.

Evaluate XPath expression

XPath – an expression language for parsing XML documents – may be used to search for the presence of specific element or attribute values in the response XML. Enter an XPath expression that will return the element or attribute containing the value to be checked, and enter the required value in “Expected Value”. If the value of the searched-for item matches at runtime the response will be considered successful. See the example provided in the XPath validation section under Data Only Web Notifications.

Example of Embedding a Document

We will show concepts via a simple web service using C# and .NET. Our web service will simply receive the document ID, a completed flag, and the embedded document. Our C# web service code contains

Copy 
[WebMethod] 
public string ReceiveDocument(
 string orderID, string docID, bool completed, byte[] docContents) 
{ 
     If(Completed) 
     { 
         // update the record based on the orderID returned
     }   
     // now save the file somewhere 
     System.IO.BinaryWriter writer = new System.IO.BinaryWriter(System.IO.File.OpenWrite( string.Format(@"C:\temp\{0}.pdf", docID))); 
     writer.Write(docContents); 
     writer.Flush(); 
     writer.Close(); 
     return true.ToString(); 
}

In the Completed Document Transmission user interface in Nintex eSign, we start by clicking “New”. We name our design “Successful embedded document transmission”, we enter the location of our web service, indicate it is a SOAP-based service and set the SOAP action to the appropriate string. In this case, the SOAP action is:

Copy 
http://assuresign.net/webservices/ReceiveDocument

Point the interface to the location of our WSDL, and modify it to include the merge fields “DocumentID” and “Completed Document”.

We set the Response Validation Method to “Accept any non-error response”. After all of this is configured we can save our design and click “Test” from the Completed Document Transmission list. From the pop up window, click “Begin Test”. If all is successful we should receive a message “Web notification sent and received successfully”.

Testing Embedded Document Web Notifications

After you have saved your configuration you may click the “Test” link on your notification. A pop-up interface will be displayed and you may select “Begin Test”. Sample data will be populated in any merge fields you have entered into the request message design. The returned response XML will be displayed along with an indicator of success or failure; standard error messages such as authentication and access errors will be displayed. Additionally, success will be based on the type of response validation you have selected when configuring the notification. You should also confirm that you have received the document through your application, and that your application has received all merge field values you may have included when building your standard request message.

Note: When testing an embedded document web notification a sample PDF document will be passed. You should confirm both that data is passed properly and that your application is properly converting the Base64 encoded byte array to a readable format.