Changing a Transaction’s Status

To download the full code sample see our Code Share site.

OneSpan Sign transactions follow a predefined lifecycle, defined by the following lifecycle states:

• Draft: The transaction has not yet been sent.
• In progress: The transaction has been distributed for signatures, but has not yet been completed.
• Completed: The transaction has been signed by all recipients.
• Opted out: The transaction has at least one recipient who has opted out of signing the transaction electronically. Note: The opt-out option has been removed from the Signer Experience.
• Declined: The transaction has at least one recipient who has declined to sign the transaction.
• Expired: The transaction has expired (i.e., its expiry date is in the past).
• Archived: The transaction has been archived.

The following diagram outlines the flow a transaction normally goes through. In addition, included in this diagram or two possible actions that you can take during this lifecycle process.

• Trash Action: The Trash action is used to move a selected transaction to the Trash folder. Transactions in the trash folder are not automatically deleted, unless there is a specific retention policy set for that account. Transactions that are manually deleted from this folder are recoverable for two weeks after deletion. To recover these transactions you must contact our Support Team.
• Delete Action: Your package will be permanently deleted and cannot be reinstated.

1. Moving from DRAFT to SENT

The following code will do this:

eslClient.SendPackage(packageId);				//draft to sent

Conversely, if you need to make some changes to a transaction that you have already SENT, use the following code to move the transaction back into DRAFT:

eslClient.ChangePackageStatusToDraft(packageId);		//sent to draft

2. Moving from SENT to COMPLETED

By default, if a transaction has been signed by all recipients, its status will automatically change to COMPLETED. However, if you do not want this automatic change to happen you can do so, and then manually mark the transaction as Completed later.

First though, you must create a transaction that does not automatically change to COMPLETED once all recipients have signed. The following code will do this:

DocumentPackage pkg1 = PackageBuilder.NewPackageNamed("Example Package " + System.DateTime.Now)
        .WithoutAutomaticCompletion()
        ......
        .Build();

Once you have received the Recipient completed signing callback event, or after you actively poll the transaction status and find that it is ready for review, you can use the following code to mark the transaction as COMPLETED.

eslClient.PackageService.MarkComplete(packageId); 		//sent to complete

3. Moving from COMPLETED to ARCHIVED

Archiving moves the selected transactions from your Inbox to the Archived folder. This action is only available for COMPLETED transactions. Once a package is archived, your signers cannot access the completed Signer Experience anymore. When they click the signing URL link or download link from email, an Access Denied page will appear.

Archiving a transaction does not affect access for the sender. Senders can still fully control and manipulate the transaction through the UI or API.

The following code shows you how to archive a transaction:

eslClient.PackageService.Archive(packageId); 		//completed to archived

To cancel archiving, simply move the transaction back to a COMPLETED status:

eslClient.PackageService.MarkComplete(packageId); 		//archived to completed

4. Moving from DECLINED to SENT

If a signer has declined to sign a document, you may want to modify the transaction and resend it. The following code will do this:

For information on how to retrieve Declined messages, see Retrieving Reasons for Declining.

eslClient.SendPackage(packageId);				//declined to sent

5. Moving from EXPIRED to DRAFT

Even though a transaction has expired, you can still change its expiration date. Simply update the transaction with the new expiry date, and the transaction's status will automatically change back to DRAFT. You can then modify the transaction (if necessary), and resend it. The following code will do this:

DocumentPackage package1 = eslClient.GetPackage(packageId);
package1.ExpiryDate = new DateTime(2019, 3, 12, 1, 0, 0);
eslClient.UpdatePackage(packageId, package1);

6. Trashing a Transaction

The following code will move a transaction to the Trash folder:

eslClient.PackageService.Trash(packageId);     //trash action

A transaction that is in the Trash folder can still be accessed by the Sender, for two weeks. After two weeks the transaction will be permanently deleted. Before that happens though, you can recover the transaction by using the following code:

eslClient.PackageService.Restore(packageId);   //restore trash

7. Deleting a Transaction

Deleting a transaction is permanent. A deleted transaction cannot be recovered.

The following code will permanently delete a transaction:

eslClient.PackageService.DeletePackage(packageId);     //delete action

To download the full code sample see our Code Share site.

OneSpan Sign transactions follow a predefined lifecycle, defined by the following lifecycle states:

• Draft: The transaction has not yet been sent.
• In progress: The transaction has been distributed for signatures, but has not yet been completed.
• Completed: The transaction has been signed by all recipients.
• Opted out: The transaction has at least one recipient who has opted out of signing the transaction electronically. Note: The opt-out option has been removed from the Signer Experience.
• Declined: The transaction has at least one recipient who has declined to sign the transaction.
• Expired: The transaction has expired (i.e., its expiry date is in the past).
• Archived: The transaction has been archived.

The following diagram outlines the flow a transaction normally goes through. In addition, included in this diagram or two possible actions that you can take during this lifecycle process.

• Trash Action: The Trash action is used to move a selected transaction to the Trash folder. Transactions in the trash folder are not automatically deleted, unless there is a specific retention policy set for that account. Transactions that are manually deleted from this folder are recoverable for two weeks after deletion. To recover these transactions you must contact our Support Team.
• Delete Action: Your package will be permanently deleted and cannot be reinstated.

1. Moving from DRAFT to SENT

The following code will do this:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "status": "SENT"
}

Conversely, if you need to make some changes to a transaction that you have already SENT, use the following code to move the transaction back into DRAFT:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "status": "DRAFT"
}

2. Moving from SENT to COMPLETED

By default, if a transaction has been signed by all recipients, its status will automatically change to COMPLETED. However, if you do not want this automatic change to happen you can do so, and then manually mark the transaction as Completed later.

First though, you must create a transaction that does not automatically change to COMPLETED once all recipients have signed. The following code will do this:

HTTP Request

POST /api/packages

HTTP Headers

Authorization: Basic api_key
Accept: application/json
Content-Type: multipart/form-data

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="testDocumentExtraction.pdf"
Content-Type: application/pdf
%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
   "roles":[
      ......
   ],
   "documents":[
      ......
   ],
   "name":"Example Package",
   "type":"PACKAGE",
   "language":"en",
   "emailMessage":"",
   "description":"New Package",
   "autocomplete":false,
   "status":"SENT"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--

Response Payload

{
    "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI="
}

Once you have received the Recipient completed signing callback event, or after you actively poll the transaction status and find that it is ready for review, you can use the following code to mark the transaction as COMPLETED.

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "status": "COMPLETED"
}

3. Moving from COMPLETED to ARCHIVED

Archiving moves the selected transactions from your Inbox to the Archived folder. This action is only available for COMPLETED transactions. Once a package is archived, your signers cannot access the completed Signer Experience anymore. When they click the signing URL link or download link from email, an Access Denied page will appear.

Archiving a transaction does not affect access for the sender. Senders can still fully control and manipulate the transaction through the UI or API.

The following code shows you how to archive a transaction:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "status": "ARCHIVED"
}

To cancel archiving, simply move the transaction back to a COMPLETED status:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "status": "COMPLETED"
}

4. Moving from DECLINED to SENT

If a signer has declined to sign a document, you may want to modify the transaction and resend it. The following code will do this:

For information on how to retrieve Declined messages, see Retrieving Reasons for Declining.

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "status": "SENT"
}

5. Moving from EXPIRED to DRAFT

Even though a transaction has expired, you can still change its expiration date. Simply update the transaction with the new expiry date, and the transaction's status will automatically change back to DRAFT. You can then modify the transaction (if necessary), and resend it. The following code will do this:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "due": "2019-03-13"
}

6. Trashing a Transaction

The following code will move a transaction to the Trash folder:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "trashed": true
}

A transaction that is in the Trash folder can still be accessed by the Sender, for two weeks. After two weeks the transaction will be permanently deleted. Before that happens though, you can recover the transaction by using the following code:

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload

{
   "trashed": false
}

7. Deleting a Transaction

Deleting a transaction is permanent. A deleted transaction cannot be recovered.

The following code will permanently delete a transaction:

HTTP Request

DELETE /api/packages/{packageId}

HTTP Headers

Accept: application/json
Content-Type: application/json
Authorization: Basic api_key

Request Payload Table

To download the full code sample see our Code Share site.

If you have sent your transaction for signing and wish to make some edits, you can do so by changing the status of the transaction back to DRAFT.

Changing the transaction status to DRAFT is done using the Apex SDK client and by passing your package ID as a parameter. The package ID is returned to you during transaction creation.

ESignLiveSDK sdk = new ESignLiveSDK();
sdk.setStatus('packageID', ESignLiveAPIObjects.PackageStatus.ARCHIVED); // complete --> archive
sdk.setStatus('packageID', ESignLiveAPIObjects.PackageStatus.COMPLETED); // sent/archive --> completed
sdk.setStatus('packageID', ESignLiveAPIObjects.PackageStatus.DRAFT); // sent --> draft
sdk.setStatus('packageID', ESignLiveAPIObjects.PackageStatus.SENT); // draft --> sent

Similarly, this function can also be used to ARCHIVE and undo archive (COMPLETE) a package.

Results

Here is an example of what you can expect to see once you have run your code.