Modify Status Of A Package

The following guide demonstrates how to modify the status of a package.

Once you have created your package (transaction in the UI), your package starts its lifecycle from “DRAFT” status. Below is a state machine diagram that shows you all possible statuses in OneSpan Sign and two actions regarding to the package lifecycle management.

Capture

Briefly explanation of all statuses:

  • DRAFT: The package has not yet been sent.
  • SENT: The package has been distributed for signatures but has not yet been completed.
  • COMPLETED: The package has been signed by all recipients.
  • OPTED_OUT/DECLINED: The package has at least one recipient who has opted out of signing the document(s) electronically or declined to sign the document(s).
  • EXPIRED: The package has expired (its expiry date is in the past).
  • ARCHIVED: The package has been archived.

Two package lifecycle management actions:

  • Trash Action: The Trash action is used to move a selected package to the Trash Folder. Trashed packages will be kept for two weeks and be permanently deleted afterwards.
  • Delete Action: Your package will be permanently deleted and cannot be reinstated.

The Code

1. DRAFT <--> SENT
After you have fully baked your package and you are ready to send to your signers, you can do so by calling the below function:

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

If you wish to make some edits to “SENT” packages, change the status of your package to draft through:

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

2. SENT –> COMPLETED
By default, a package signed by all its recipients changes automatically to COMPLETED status. OneSpan Sign also gives you the capability to put a pause on this automatic status change, giving you time to review a package before marking it complete, manually. To toggle this option, first create your package in the below manner:

DocumentPackage pkg1 = PackageBuilder.newPackageNamed("Example Package " + System.currentTimeMillis())
        .autocomplete(false)
        ......
        .build();

Once received the “Recipient completed signing” callback event or you actively polling the package status and find it is ready to review, you can use the below function to mark the package complete.

eslClient.getPackageService().markComplete(packageId); 		//sent to complete

3. COMPLETED <--> ARCHIVED
The Archive action 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 signing ceremony view anymore. When they click the signing URL link or download link from email, an “Access Denied” page will appear.
As a sender, archiving a package won’t affect your access. You can still fully control and manipulate the package through the UI or API.
The below function shows you how to archive a package:

eslClient.getPackageService().archive(packageId); 		//completed to archived

To cancel archiving, simply move the package back to completed status:

eslClient.getPackageService().markComplete(packageId); 		//archived to completed

4. OPTED_OUT/DECLINED –> SENT
If a signer has opted out of the signing electronically or has declined to sign the document(s), you may want to modify the package according to their reasons and resend it. To resend, simply call the below function:

eslClient.sendPackage(packageId);				//opted_out/declined to sent

Also check our Opt-out and Declined Messages guide to learn how to retrieve the opt-out and declined messages.

5. EXPIRED –> DRAFT
Depending on your requirement, if a package was already in “EXPIRED” status, but you still want to extend the expiry date for your signers. Simply update the package with a future expiration date, and the package will automatically convert to “DRAFT” status:

DocumentPackage package1 = eslClient.getPackage(packageId);
package1.setExpiryDate(newDate);
eslClient.updatePackage(packageId, package1);

Next, you can modify the package, if necessary, and resend it.

6. Trash Action
If you have all the documents and info you need from a package and don’t want to archive your transactions inside of OneSpan Sign, or you are wanting to get rid of an unneeded package, you can move a package to your trash folder:

eslClient.getPackageService().trash(packageId);     //trash action

A package in your trash folder can still be accessed by the Sender (via the UI or API), for 2 weeks, before permanent deletion. If a package needs to be recovered, you can do so by calling the below function:

eslClient.getPackageService().restore(packageId);   //restore trash

7. Delete Action
The delete action will permanently delete your package. Therefore, you (nor OneSpan Sign) will not be able to recover this package at a later point.

eslClient.getPackageService().deletePackage(packageId);     //delete action

Get the Code

Once you have created your package (transaction in the UI), your package starts its lifecycle from “DRAFT” status. Below is a state machine diagram that shows you all possible statuses in OneSpan Sign and two actions regarding to the package lifecycle management.

Capture

Briefly explanation of all statuses:

  • DRAFT: The package has not yet been sent.
  • SENT: The package has been distributed for signatures but has not yet been completed.
  • COMPLETED: The package has been signed by all recipients.
  • OPTED_OUT/DECLINED: The package has at least one recipient who has opted out of signing the document(s) electronically or declined to sign the document(s).
  • EXPIRED: The package has expired (its expiry date is in the past).
  • ARCHIVED: The package has been archived.

Two package lifecycle management actions:

  • Trash Action: The Trash action is used to move a selected package to the Trash Folder. Trashed packages will be kept for two weeks and be permanently deleted afterwards.
  • Delete Action: Your package will be permanently deleted and cannot be reinstated.

The Code

1. DRAFT <--> SENT
After you have fully baked your package and you are ready to send to your signers, you can do so by calling the below function:

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

If you wish to make some edits to “SENT” packages, change the status of your package to draft through:

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

2. SENT –> COMPLETED
By default, a package signed by all its recipients changes automatically to COMPLETED status. OneSpan Sign also gives you the capability to put a pause on this automatic status change, giving you time to review a package before marking it complete, manually. To toggle this option, first create your package in the below manner:

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

Once received the “Recipient completed signing” callback event or you actively polling the package status and find it is ready to review, you can use the below function to mark the package complete.

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

3. COMPLETED <--> ARCHIVED
The Archive action 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 signing ceremony view anymore. When they click the signing URL link or download link from email, an “Access Denied” page will appear.
As a sender, archiving a package won’t affect your access. You can still fully control and manipulate the package through the UI or API.
The below function shows you how to archive a package:

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

To cancel archiving, simply move the package back to completed status:

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

4. OPTED_OUT/DECLINED –> SENT
If a signer has opted out of the signing electronically or has declined to sign the document(s), you may want to modify the package according to their reasons and resend it. To resend, simply call the below function:

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

Also check our Opt-out and Declined Messages guide to learn how to retrieve the opt-out and declined messages.

5. EXPIRED –> DRAFT
Depending on your requirement, if a package was already in “EXPIRED” status, but you still want to extend the expiry date for your signers. Simply update the package with a future expiration date, and the package will automatically convert to “DRAFT” status:

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

Next, you can modify the package, if necessary, and resend it.

6. Trash Action
If you have all the documents and info you need from a package and don’t want to archive your transactions inside of OneSpan Sign, or you are wanting to get rid of an unneeded package, you can move a package to your trash folder:

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

A package in your trash folder can still be accessed by the Sender (via the UI or API), for 2 weeks, before permanent deletion. If a package needs to be recovered, you can do so by calling the below function:

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

7. Delete Action
The delete action will permanently delete your package. Therefore, you (nor OneSpan Sign) will not be able to recover this package at a later point.

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

Get the Code

Once you have created your package (transaction in the UI), your package starts its lifecycle from “DRAFT” status. Below is a state machine diagram that shows you all possible statuses in OneSpan Sign and two actions regarding to the package lifecycle management.

Capture

Briefly explanation of all statuses:

  • DRAFT: The package has not yet been sent.
  • SENT: The package has been distributed for signatures but has not yet been completed.
  • COMPLETED: The package has been signed by all recipients.
  • OPTED_OUT/DECLINED: The package has at least one recipient who has opted out of signing the document(s) electronically or declined to sign the document(s).
  • EXPIRED: The package has expired (its expiry date is in the past).
  • ARCHIVED: The package has been archived.

Two package lifecycle management actions:

  • Trash Action: The Trash action is used to move a selected package to the Trash Folder. Trashed packages will be kept for two weeks and be permanently deleted afterwards.
  • Delete Action: Your package will be permanently deleted and cannot be reinstated.

The Code

1. DRAFT <--> SENT
After you have fully baked your package and you are ready to send to your signers, you can do so by calling the below API:

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
   "status": "SENT"
}

If you wish to make some edits to “SENT” packages, change the status of your package to draft through:

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
   "status": "DRAFT"
}

2. SENT –> COMPLETED
By default, a package signed by all its recipients changes automatically to COMPLETED status. OneSpan Sign also gives you the capability to put a pause on this automatic status change, giving you time to review a package before marking it complete, manually. To toggle this option, first create your package in the below manner:

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 received the “Recipient completed signing” callback event or you actively polling the package status and find it is ready to review, you can use the below API to mark the package complete.

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
   "status": "COMPLETED"
}

3. COMPLETED <--> ARCHIVED
The Archive action 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 signing ceremony view anymore. When they click the signing URL link or download link from email, an “Access Denied” page will appear.
As a sender, archiving a package won’t affect your access. You can still fully control and manipulate the package through the UI or API.
The below API shows you how to archive a package:

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 package back to 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. OPTED_OUT/DECLINED –> SENT
If a signer has opted out of the signing electronically or has declined to sign the document(s), you may want to modify the package according to their reasons and resend it. To resend, simply call the below API:

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
   "status": "SENT"
}

Also check our Opt-out and Declined Messages guide to learn how to retrieve the opt-out and declined messages.

5. EXPIRED –> DRAFT
Depending on your requirement, if a package was already in “EXPIRED” status, but you still want to extend the expiry date for your signers. Simply update the package with a future expiration date, and the package will automatically convert to “DRAFT” status:

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"
}

Next, you can modify the package, if necessary, and resend it.

6. Trash Action
If you have all the documents and info you need from a package and don’t want to archive your transactions inside of OneSpan Sign, or you are wanting to get rid of an unneeded package, you can move a package to your trash folder. To do so, simply set true to the “trashed” attribute at package level:

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
   "trashed": true
}

A package in your trash folder can still be accessed by the Sender (via the UI or API), for 2 weeks, before permanent deletion. If a package needs to be recovered, you can do so by calling the below API:

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
   "trashed": false
}

7. Delete Action
The delete action will permanently delete your package. Therefore, you (nor OneSpan Sign) will not be able to recover this package at a later point.

HTTP Request
DELETE /api/packages/{packageId}

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

Get the Code

JSON Properties

Property Type Editable Required Default Sample Value(s)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
due string Yes Yes null 2017-02-13T21:18:40Z
trashed boolean Yes No false true / false

If you have sent your package (transaction in the UI) for signing and wish to make some edits, you can do so by changing the status of your package to draft.

The Code

Changing the package status to draft is done using the Apex SDK client and passing your package ID as a parameter. The package ID is returned to you during package 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.

Running Your Code

Once you’ve run your code, if you login to your OneSpan Sign account, you will find your package in the DRAFT tab, as shown in the screenshot below.

Capture

Get the Code