Managing Signers’ Attachments

.withSigner(newSignerWithEmail("[email protected]")
.withFirstName("John")
	.withLastName("Doe")
	.withCustomId("Signer1")
	.withAttachmentRequirement(newAttachmentRequirementWithName("Driver's license")
		.withDescription("Please upload a copy of your driver’s license.")
		.isRequiredAttachment()
		.build()))

DocumentPackage myPackage = client.getPackage(packageId);
		
List<AttachmentRequirement> signer1Attachments = myPackage.getSigner("[email protected]").getAttachmentRequirements();
		
for(AttachmentRequirement attachment : signer1Attachments){
      System.out.println(attachment.getName() + " " + attachment.getStatus() + " " + attachment.getId());
}

//Download individual attachment
DownloadedFile downloadedAttachment = client.getAttachmentRequirementService().downloadAttachmentFile(packageId, attachmentId);
Files.saveTo(downloadedAttachment.getContents(), downloadedAttachment.getFilename());
//Download all attachments in package	    
DownloadedFile downloadedAllAttachmentsForPackage = client.getAttachmentRequirementService().downloadAllAttachmentFilesForPackage(packageId);
Files.saveTo(downloadedAllAttachmentsForPackage.getContents(), "downloadedAllAttachmentsForPackage.zip");
//Download all attachments for signer in package         
DownloadedFile downloadedAllAttachmentsForSigner1InPackage = client.getAttachmentRequirementService().downloadAllAttachmentFilesForSignerInPackage(myPackage, signer1);
Files.saveTo(downloadedAllAttachmentsForSigner1InPackage.getContents(), "downloadedAllAttachmentsForSigner.zip");

client.getAttachmentRequirementService().rejectAttachment(packageId, signer1, "Driver's license", "Expired driver's license");

DocumentPackage myPackage = client.getPackage(packageId);
		
myPackage.setStatus(PackageStatus.COMPLETED);
		
client.updatePackage(packageId, myPackage);

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

OneSpan Sign offers the ability for signers to upload attachments during the signing workflow. Senders can review the provided attachment and mark the transaction as complete. This topic describes how a sender can require the signer to upload an attachment to the transaction.

Creating an Attachment Request

The following code describes how to edit your signer block to request a file attachment.

The withDescription() method allows you to provide a description to the signer about the file upload you are requesting. The isRequiredAttachment() method defines that the attachment is required. Neither of these are mandatory when building your AttachmentRequirement object.

.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
    .WithFirstName("John")
    .WithLastName("Doe")
    .WithCustomId("Signer1")
    .WithAttachmentRequirement(AttachmentRequirementBuilder.NewAttachmentRequirementWithName("Driver's license")
        .WithDescription("Please upload a copy of your driver’s license.")
        .IsRequiredAttachment()
        .Build()))

Attachment Status

You may want to query the status of each attachment in your transaction. The following code will loop through each AttachmentRequirement object and print out the name, status, and id of each requested attachment for the specified signer.

DocumentPackage myPackage = client.GetPackage(packageId);
IList<AttachmentRequirement> signer1Attachments = myPackage.GetSigner("[email protected]").Attachments;
foreach (AttachmentRequirement attachment in signer1Attachments)
{
     Debug.WriteLine(attachment.Name + " " + attachment.Status + " " + attachment.Id);
}

Downloading Attachments

Attachments can be downloaded in the following ways:

• As a single attachment. This requires the attachment id.
• In a package that includes all attachments.
• In a package that includes all attachments from a specified signer.

The following code will do this:

//Download individual attachment
DownloadedFile downloadedAttachment = client.AttachmentRequirementService.DownloadAttachmentFile(packageId, attachmentId);
System.IO.File.WriteAllBytes(downloadedAttachment.Filename, downloadedAttachment.Contents);
//Download all attachments in package
DownloadedFile downloadedAllAttachmentsForPackage = client.AttachmentRequirementService.DownloadAllAttachmentFilesForPackage(packageId);
System.IO.File.WriteAllBytes("downloadedAllAttachmentsForPackage.zip", downloadedAllAttachmentsForPackage.Contents);
//Download all attachments for signer in package
DownloadedFile downloadedAllAttachmentsForSigner1InPackage = client.AttachmentRequirementService.DownloadAllAttachmentFilesForSignerInPackage(myPackage, signer1);
System.IO.File.WriteAllBytes("downloadedAllAttachmentsForSigner.zip", downloadedAllAttachmentsForSigner1InPackage.Contents);

Reviewing Attachments

After reviewing the attachment, you can then either refuse or accept it. If you refuse the attachment, you can calso include a small feedback message explaining why the attachment was refused. The following code will do this:

client.AttachmentRequirementService.RejectAttachment(packageId, signer1, "Driver's license", "Expired driver's license");

It is important to note that transactions that require attachments will not auto-complete. This gives the sender the opportunity to review the attachment, and either accept or reject it.

If all the required attachments have been uploaded and approved, you can complete the package by updating the status of your package to COMPLETED. The following code will do this:

DocumentPackage myPackage = eslClient.GetPackage(packageId);
myPackage.Status = DocumentPackageStatus.COMPLETED;
eslClient.UpdatePackage(packageId, myPackage);

Results

Once you have completed this procedure, the required documents will be listed with each recipient.

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

OneSpan Sign offers the ability for signers to upload attachments during the signing workflow. Senders can review the provided attachment and mark the transaction as complete. This topic describes how a sender can require the signer to upload an attachment to the transaction.

Creating an Attachment Request

The following code describes how to add a recipient with an attachment requirement.

HTTP Request

POST /api/packages/{packageId}/roles

HTTP Headers

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

Request Payload

{
  "id": "client",
  "type": "SIGNER",
  "index": 1,
  "attachmentRequirements": [
    {
      "description": "Please upload a scanned copy of your driver's license.",
      "required": true,
      "id": "lD6p5QnWk905",
      "status": "INCOMPLETE",
      "comment": "",
      "name": "Driver's license"
    }
  ],
  "signers": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "email": "[email protected]"
    }
  ],
  "name": "client"
}

For a complete description of each field, see the Request Payload table below.

Response Payload

{
    "id": "client",
    "data": null,
    "emailMessage": null,
    "attachmentRequirements": [
        {
            "status": "INCOMPLETE",
            "description": "Please upload a scanned copy of your driver's license.",
            "required": true,
            "id": "1JMGfs9xRDoD",
            "comment": "",
            "name": "Driver's license",
            "data": null
        }
    ],
    "locked": false,
    "reassign": false,
    "specialTypes": [],
    "index": 1,
    "type": "SIGNER",
    "signers": [
        {
            "group": null,
            "language": "en",
            "signature": null,
            "id": "fe666c24-c18d-4d93-bbb7-2b1a6ce8332e",
            "auth": {
                "scheme": "NONE",
                "challenges": []
            },
            "data": null,
            "title": "",
            "external": null,
            "updated": "2017-10-19T18:18:37Z",
            "company": "",
            "email": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "phone": "",
            "professionalIdentityFields": [],
            "userCustomFields": [],
            "knowledgeBasedAuthentication": null,
            "delivery": {
                "provider": false,
                "email": false,
                "download": false
            },
            "address": null,
            "created": "2017-10-19T18:18:37Z",
            "name": "",
            "specialTypes": []
        }
    ],
    "name": "client"
}

Downloading Attachments

Attachments can be downloaded in the following ways:

• As a single attachment. This requires the attachment id.
• In a package that includes all attachments.
• In a package that includes all attachments from a specified signer.

To download an individual attachment, you will need the package and attachment ID. The following code will do this:

HTTP Request

GET /api/packages/{packageId}/attachment/{attachmentId}

HTTP Headers

Accept: application/octet-stream
Content-Type: application/octet-stream
Authorization: Basic api_key

Response Payload

[document.pdf]

You can also download all attachments as a zip file in a package. The following code will do this:

HTTP Request

GET /api/packages/{packageId}/attachment/zip

HTTP Headers

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

Response Payload

[document.zip]

To download all attachments as a zip file for a particular signer, you will make your request to:

HTTP Request

GET /api/packages/{packageId}/attachment/zip/{roleId}

HTTP Headers

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

[document.zip]

Reviewing Attachments

After reviewing the attachment, you can then either refuse or accept it. If you refuse the attachment, you can calso include a small feedback message explaining why the attachment was refused. The following code will do this:

HTTP Request

PUT /api/packages/{packageId}/roles/{roleId}

HTTP Headers

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

Request Payload

{
  "attachmentRequirements": [
    {
      "id": "q66CYiDrxTU1",
      "status": "REJECTED",
      "comment": "Invalid copy."
    }
  ]
}

It is important to note that transactions that require attachments will not auto-complete. This gives the sender the opportunity to review the attachment, and either accept or reject it.

If all the required attachments have been uploaded and approved, you can complete the package by updating the status of your package to COMPLETED. 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" : "COMPLETED"
}

Results

Once you have completed this procedure, the required documents will be listed with each recipient.

JSON Properties Table

Property	Type	Editable	Required	Default	Sample Values
id	string	Yes	No	n/a	client
type	string	Yes	No	SIGNER	SIGNER / SENDER
index	integer	Yes	No	0	0 / 1 / 2 ...
name	string	Yes	No	n/a	client
attachmentRequirements
description	string	Yes	No	n/a	Please upload a scanned copy of your driver's license
required	boolean	Yes	No	false	false / true
id	string	Yes	No	n/a	lD6p5QnWk905
status	string	Yes	No	INCOMPLETE	INCOMPLETE / COMPLETE / REJECTED
comment	string	Yes	No	n/a	wrong driver license
name	string	Yes	No	n/a	Driver's license
signers
firstName	string	Yes	No	n/a	John
lastName	string	Yes	No	n/a	Smith
email	string	Yes	No	n/a	[email protected]

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

OneSpan Sign offers the ability for signers to upload attachments during the signing workflow. Senders can review the provided attachment and mark the transaction as complete. This topic describes how a sender can require the signer to upload an attachment to the transaction.

Creating an Attachment Request

The following code describes how to edit your signer block to request a file attachment.

ESignLiveAPIObjects.Role role = new ESignLiveAPIObjects.Role();
ESignLiveAPIObjects.Signer signer = new ESignLiveAPIObjects.Signer();
signer.firstName = 'firstName';
signer.lastName = 'lastName';
signer.email = '[email protected]';
signer.name = 'signer1';
signer.id = 'signer1';
role.signers = new List<ESignLiveAPIObjects.Signer>{signer};
role.id = 'signer1';
role.attachmentRequirements = new ESignLiveAPIObjects.AttachmentRequirement(null, 'Please upload a copy of your driver\'s license.','attachment1','driver\'s license' ,true,null,null);

Additional, there are two encapsulated functions in the code share:

public ESignLiveAPIObjects.AttachmentRequirement createAttachmentRequirement(String id, String name, String description, Boolean isRequired)
public ESignLiveAPIObjects.Role createRoleWithAttachmentRequest(String id, String firstName, String lastName, String email, List attachmentRequirements)

The withDescription() method allows you to provide a description to the signer about the file upload you are requesting. The isRequiredAttachment() method defines that the attachment is required. Neither of these are mandatory when building your AttachmentRequirement object.

The createAttachmentRequirement() function allows you to provide a description to the signer about the file upload you are requesting and if that attachment is required. The createRoleWithAttachmentRequest() function provides an easier way to create role with a list of attachment requirements.

Attachment Status

You may want to query the status of each attachment in your transaction. The following code will loop through each AttachmentRequirement object and print out the name, status, and id of each requested attachment for the specified signer.

ESignLiveSDK sdk = new ESignLiveSDK();
//retrieve attachments' status
ESignLiveAPIObjects.Role retrievedRole1 = sdk.getRole(packageId,roleId);
for(ESignLiveAPIObjects.AttachmentRequirement attachment: retrievedRole1.attachmentRequirements){
     System.debug('Attachment: ' + attachment.id+ ' : ' + attachment.name + ' : ' + attachment.status);        
}

The code snippet is encapsulated in this function:

public void retrieveAttachmentsStatus(String packageId, String roleId)

Downloading Attachments

Attachments can be downloaded in the following ways:

• As a single attachment. This requires the attachment id.
• In a package that includes all attachments.
• In a package that includes all attachments from a specified signer.

The following code will do this:

//Download individual attachment
Blob downloadAttachmentFile = downloadAttachmentFile('packageId','attachmentId');
//Download all attachments in package	    
Blob downloadAttachmentFilesForPackage = downloadAllAttachmentFilesForPackage('packageId');
//Download all attachments for signer in package         
ESignLiveSDK sdk = new ESignLiveSDK();
String downloadAllAttachmentForSigner = sdk.downloadAllAttachmentFilesForSignerInPackage('packageId','roleId');

Reviewing Attachments

After reviewing the attachment, you can then either refuse or accept it. If you refuse the attachment, you can calso include a small feedback message explaining why the attachment was refused. The following code will do this:

public void acceptAttachment(String packageId, String roleId, String attachmentName)
public void rejectAttachment(String packageId, String roleId, String attachmentName, String senderComment)

It is important to note that transactions that require attachments will not auto-complete. This gives the sender the opportunity to review the attachment, and either accept or reject it.

If all the required attachments have been uploaded and approved, you can complete the package by updating the status of your package to COMPLETED. The following code will do this:

ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);
pkg.status = ESignLiveAPIObjects.PackageStatus.COMPLETED;
sdk.updatePackage(pkg,packageId);  

Results

Once you have completed this procedure, the required documents will be listed with each recipient.