Data Only Web Notifications

Data only DocumentTRAK web notifications are used to communicate without sending the document; they may be sent on any trigger-ready event in the lifecycle of a document.
Configuring data web notifications is done in a wizard-style user interface where you specify information about:

• Your service endpoint
• The body to be passed (for example, as JSON or XML)
• The expected response

To start configuring a web notification, go to the “Administration” tab, and click on “DocumentTRAK” under the “Notifications” heading. The “Web Notifications” table allows you to create a new notification or copy an existing one.

Note: Copying an existing web notification may save you time when a single end point can handle multiple values of data. Consider a case where you would like to create a single URL and method and pass a different value depending on whether a document completed or was expired. You could create an AssureSign notification with a fixed “true” boolean string as a method argument, copy the notification to a new instance and merely modify the fixed argument value to “false”. The first web notification could be assigned to Document Completed events. The copied web notification returning false could then be used as a handler for the Document Expired event.

Now you will define the various parts of the web notification.

General Information

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

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

or

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 AssureSign account settings) or specific credentials for the web service. All such configuration is stored encrypted in the AssureSign system. If the communication is to a SOAP based service then you are asked to enter the SOAP action.

Request Message Content

The form of the content to be passed may be specified by:

• Manually entering or pasting a JSON or XML string
• Generating 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. One important point to remember is that any imports or includes must be qualified appropriately in order for them to be parsed. For example: a local XSD or WSDL document file can only reference fully qualified (and publically accessible) import URLs; online XSD or WSDL can reference either fully qualified or relative import URLs. 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. AssureSign 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 and
• Template Specific 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.

It is also possible to perform advanced manipulation of merge fields using javascript.

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.

Validate Response against XSD Schema

A specific XSD schema may be loaded from a file or from an online source. At run time the XML response will be validated against the XSD schema (note that this differs from a simple string comparison whereby XSD could be used merely to generate a comparison string).

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.

Example: You are calling a web service which updates data in your system. If the update is successful, the service returns a “True” string. The expected XML returned is:

<?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <DocumentUpdateResponse xmlns="http://assuresign.net/webservices/">
                <DocumentUpdateResult>True</DocumentUpdateResult>
            </DocumentUpdateResponse>
        </soap:Body>
    </soap:Envelope>

Enter the XPath expression:

//*[local-name()='DocumentUpdateResponse']/*[local-name()='DocumentUpdateResult']

At runtime, the first DocumentUpdateResult node will be found. Note that this expression was built to be namespace agnostic, thus the special “local-name()” handling. Enter “True” as the Expected Value. If the value of DocumentUpdateResult comes back as False then the response will not be considered successful.

When a Communication Fails

You are responsible for configuring additional settings that govern failure condition processing. More information on how failures are handled is available here.

Testing Data Only 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 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. Success or failure will be assigned on the type of response validation you have selected when configuring the notification. You should also confirm that your application has properly received all merge field values you may have included when building your standard request message.