Notification call back

To get information about the status and changes of a sign order, E-Signing offers a notification service with the possiblity to send XML notification call back messages to the customers.

The notification call back messages are sent using the TrustSignNotification message protocol using the POST method. The messages sent are based on triggers defined in the sign order. Messages are transmitted as XML files of predefined structure and convey a specific type of information to the receiving system.

Here you can find shema defining the XML message structure: E-Signing notification XSD trustnotification (1).xsd.

Note: The E-Signing notification service expects an OK response within 5 seconds. If that is not received, the service will try to resend the message. To avoid resending of messages, it is important that the customer doesn’t implement any functions (e.g GetSDO) prior to sending a response OK.

TrustSignNotification

Name	Description	Constraints
OrderID	The OrderID sent by the customer.	MinLength = 1 MaxLength = 80
MerchantID	This value represents the calling customer. The customer gets this value upon configuration in E-Signing.	NA
Time	The message creation time.	NA
OrderNotification	Read more about OrderNotification.	NA
StepNotification	Read more about StepNotification.	NA
SigningProcessNotification	Read more about SigningProcessNotification.	NA

OrderNotification

A sign order passes through different states during the normal lifecycle. The state of a sign order is indicated by a unique status identifier. For each status change, E-Signing triggers are sent to notify subscribing systems of the associated events. OrderNotification messages always have a trigger whose purpose is to inform the message recipient of the event that caused the notification to be sent.

Name	Description	Constraints
Trigger	Trigger that is the source of notification (details in following table).	NA
Reject text	Optional feedback from the signer. Only included when a signer provides feedback after rejecting a sign process.	NA
Trigger info	Code explaining why the trigger was sent.	NA

The following table details the triggers listeners can subscribe to:

Name	Description
OnOrderCancellation	A sign order has been cancelled by the owning customer.
OnOrderCompletion	Sign order processing is complete.
OnOrderRejection	Sign order has been rejected by a signer (RejectText is optional feedback from signer).
OnOrderExpiration	Sign order deadline has passed.
OnOrderFailed	The sign order has failed, and the sign order status is now Failed.

A typical OrderNotification may look like the following xml example

Copy to clipboard

.xml

CODE

<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification 
   xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <OrderID>b5-4ever</OrderID>
   <MerchantID>xxxx</MerchantID>
   <Time>2093-07-13T21:49:57</Time>
   <OrderNotification>
      <Trigger>OnOrderCompletion</Trigger>
   </OrderNotification>
</TrustSignNotification>

StepNotification

StepNotification messages are published by E-Signing whenever the state of a step changes. For each status change, a trigger is sent and a message is transmitted to all subscribing applications.

The member elements are shown in the following table.

Name	Description	Constraints
Trigger	Trigger that is the souce of notification (details in following table)	NA
StepNumber	The number of the affected Step.	NA
StepReferences	A list of available references in the current step. See details below.	Optional

StepReferences

StepReferences is optional and may only occur in StepNotifications with the OnStepReady trigger.

Name	Description	Constraints
StepReference/LocalSignerReference	A reference identifying the signer bound to the step	NA
StepReference/SignURL	The sign URL to the currently active step.	NA

The following table details the triggers listeners can subscribe to:

Name	Description
OnStepCompletion	A step within a sign order has been completed.
OnStepReady	A step within an order is ready for processing.
OnStepExpiration	A step deadline has passed.

A typical StepNotification may look like the following XML example:

Copy to clipboard

.xml

CODE

<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <OrderID>b5-4ever</OrderID>
   <MerchantID>xxxx</MerchantID>
   <Time>2093-07-13T21:49:57</Time>
   <StepNotification>
      <Trigger>OnStepCompletion</Trigger>
      <StepNumber>1</StepNumber>
   </StepNotification>
</TrustSignNotification>

SigningProcessNotification

SigningProcessNotification messages are published by E-Signing whenever the state of a sign process changes. For each status change, a trigger is sent and a message is transmitted to all subscribing applications.

The following table displays all the elements of a SigningProcessNotification.

Name	Description	Constraints
Trigger	The event whose occurrence caused the creation of this notification.	NA
StepNumber	The step within which the affected sign process is defined.	NA
LocalSignerReference	A reference to indicate the signer that provoked a sign process event (see own details below).	NA
TargetReferences	A reference to the affected document(s) in the notification. See details in TargetReferences below.	NA
RejectText	Optional feedback from the signer. Only included when a signer provides feedback after rejecting a sign process.	NA
Timestamp	The time the event occurred.	NA

TargetReferences

Each defined document is issued in a separate TargetReference.

Name	Description	Constraints
TargetReference/LocalDocumentReference	The reference to the actual document targeted by the notification message.	NA
TargetRefererce/SignURL	Optional sign URL.	NA

A typical SigningProcessNotification may look like the following XML example:

Copy to clipboard

.xml

CODE

<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <OrderID>b5-4ever</OrderID>
  <MerchantID>xxxx</MerchantID>
  <Time>2093-07-13T21:49:51</Time>
  <SigningProcessNotification>
    <Trigger>OnSignProcessCompletion</Trigger>
    <StepNumber>1</StepNumber>
    <LocalSignerReference>LSR_1</LocalSignerReference>
    <TargetReferences>
      <TargetReference>
        <LocalDocumentReference>D_1</LocalDocumentReference>
      </TargetReference>
    </TargetReferences>
  </SigningProcessNotification>
</TrustSignNotification>

SigningProcessNotification messages vary in structure and content. This next example illustrates a message for sign processes in the Active state. Note that the TargetReference element in the message now also contains a SignURL.

Copy to clipboard

.xml

CODE

<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification 
  xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <OrderID>b5-4ever</OrderID>
  <MerchantID>1001</MerchantID>
  <Time>2093-07-13T21:49:51</Time>
  <SigningProcessNotification>
    <Trigger>OnSignProcessReady</Trigger>
    <StepNumber>1</StepNumber>
    <LocalSignerReference>LSR_1</LocalSignerReference>
    <TargetReferences>
      <TargetReference>
        <LocalDocumentReference>D_1</LocalDocumentReference>
        <SignURL>https://host/sign/13579</SignURL>
      </TargetReference>
      <TargetReference>
        <LocalDocumentReference>D_2</LocalDocumentReference>
        <SignURL>https://host/sign/97531</SignURL>
      </TargetReference>
    </TargetReferences>
  </SigningProcessNotification>
</TrustSignNotification>

Here is yet another example, this time for rejected sign processes.

Copy to clipboard

.xml

CODE

<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification 
  xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <OrderID>b5-4ever</OrderID>
  <MerchantID>1001</MerchantID>
  <Time>2093-07-13T21:49:51</Time>
  <SigningProcessNotification>
    <Trigger>OnSignProcessRejection</Trigger>
    <StepNumber>1</StepNumber>
    <LocalSignerReference>LSR_1</LocalSignerReference>
    <TargetReferences>
      <TargetReference>
        <LocalDocumentReference>D_1</LocalDocumentReference>
      </TargetReference>
    </TargetReferences>
    <RejectText>Lorem ipsum</RejectText>
    <Timestamp>2093-07-13T21:49:37</Timestamp>
  </SigningProcessNotification>
</TrustSignNotification>

TrustSignNotification

OrderNotification

StepNotification

StepReferences

SigningProcessNotification​​

TargetReferences

SigningProcessNotification