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.

​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 

 TrustNotification[1].png

 

​Name​Description​Constraints
​OrderID

​​​The OrderID sent by the customer.

​MinLength = 1

MaxLength = 80

​MerchantIDThis 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
​StepNotificationRead more about StepNotification.​NA
​SigningProcessNotificationRead 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.

OrderNotification[1].png 

​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

<?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.

StepNotification[1].png 


 

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[1].png 

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
​OnStepCompletionA 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:

<?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.

SigningProcessNotification[1].png 

The following table displays all the elements of a SigningProcessNotification.

​Name​Description​Constraints
​TriggerThe event whose occurrence caused the creation of this notification​.​NA
StepNumber​​The step within which the affected sign process is defined.​​NA
​LocalSignerReferenceA 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.

TargetReferences[1].png 

​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:

<?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.

<?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.

<?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>