Configuring Document Visibility

To download the full code sample see our Code Share site. You can also see this feature in our Interactive Demo.

During a Signer Experience, by default all recipients can view all documents in a transaction. However, you can configure your transactions so that certain documents can only be seen by specific recipients. This can save recipients from having to process documents they don’t need to see, and it can ensure that documents with sensitive information are viewed only by their intended recipients.

Defining Document Signing By Recipient

For this example, a transaction is setup such that Signer1 is only required to sign Document 1 and Signer2 is only required to sign Document 2, as shown below:

 DocumentPackage superDuperPackage = PackageBuilder.NewPackageNamed("DocumentVisibilityExample " + DateTime.Now)   .DescribedAs("This is a package created using the OneSpan Sign SDK")   .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")   .WithCustomId(SIGNER1_ID)   .WithFirstName("John1")   .WithLastName("Smith1"))   .WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")   .WithCustomId(SIGNER2_ID)   .WithFirstName("John2")   .WithLastName("Smith2"))   .WithDocument(DocumentBuilder.NewDocumentNamed("Document1")   .WithId(DOC1_ID)   .FromFile("C:/Users/hhaidary/Desktop/PDFs/sample_contract.pdf")   .WithSignature(SignatureBuilder.SignatureFor("[email protected]")   .OnPage(0)   .AtPosition(100, 100)))   .WithDocument(DocumentBuilder.NewDocumentNamed("Document2")   .WithId(DOC2_ID)   .FromFile("C:/Users/hhaidary/Desktop/PDFs/cleaning_contract.pdf")   .WithSignature(SignatureBuilder.SignatureFor("[email protected]")   .OnPage(0)   .AtPosition(100, 100)))   .Build(); 

Defining Document Visibility By Recipient

You can configure each document so that only a specified signer can see that document.This can ensure that documents with sensitive information are viewed only by their intended recipients.

After you've created your transaction, you will need to create your DocumentVisibility object using the OneSpan Sign DocumentVisibilityBuilder.Then you would set the visibility for each document using the custom ids set in the previous section.For example, withId(DOC1_ID).

 Silanis.ESL.SDK.DocumentVisibility visibility = DocumentVisibilityBuilder.NewDocumentVisibility()   .AddConfiguration(DocumentVisibilityConfigurationBuilder.NewDocumentVisibilityConfiguration(DOC1_ID)   .WithSignerIds(signerIdsList1))   .AddConfiguration(DocumentVisibilityConfigurationBuilder.NewDocumentVisibilityConfiguration(DOC2_ID)   .WithSignerIds(signerIdsList2))   .Build(); 

You can also configure document visibility based on specific signers:

 Silanis.ESL.SDK.DocumentVisibility visibility = DocumentVisibilityBuilder.newDocumentVisibilityBasedOnSigner()   .AddConfiguration(DocumentVisibilityConfigurationBasedOnSignerBuilder.NewDocumentVisibilityConfigurationBasedOnSigner(SIGNER1_ID)   .WithDocumentIds(new List{ DOC1_ID })) .AddConfiguration(DocumentVisibilityConfigurationBasedOnSignerBuilder.newDocumentVisibilityConfigurationBasedOnSigner(SIGNER2_ID)   .WithDocumentIds(new List{ DOC2_ID })) .Build(); 

Retrieving a List of Signers Per Document

Once you have set these configurations, you can then retrieve a list of signers who can view a document:

 IList<Signer> signersForDocument1 = eslClient.GetSigners(packageId, DOC1_ID); 

Similarly, you can retrieve a list of documents for which a signer can view:

 IList<Document> documentsForSigner1 = eslClient.GetDocuments(packageId, SIGNER1_ID); 

Setting Visibility and Sending the Transaction

Finally, you set the visibility of your documents and send your transaction using the OneSpan Sign client:

 eslClient.ConfigureDocumentVisibility(packageId, visibility);   eslClient.SendPackage(packageId); 

Results

Each recipient will only see the document assigned to them.

To download the full code sample see our Code Share site. You can also see this feature in our Interactive Demo.

During a Signer Experience, by default all recipients can view all documents in a transaction. However, you can configure your transactions so that certain documents can only be seen by specific recipients. This can save recipients from having to process documents they don’t need to see, and it can ensure that documents with sensitive information are viewed only by their intended recipients.

Defining Document Signing By Recipient

For this example, a transaction is setup such that Signer1 is only required to sign Document 1 and Signer2 is only required to sign Document 2, as shown below:

HTTP Request

 POST /api/packages 

HTTP Headers

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

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"   {   "autocomplete": true,   "description": "This is a package created using the OneSpan Sign REST API",   "documents": [   {   "approvals": [   {   "fields": [   {   "extract": false,   "height": 50,   "left": 100,   "page": 0,   "subtype": "FULLNAME",   "top": 100,   "type": "SIGNATURE",   "width": 200   }   ],   "role": "Signer1"   }   ],   "extract": false,   "id": "doc1",   "index": 0,   "name": "DocumentA"   },   {   "approvals": [   {   "fields": [   {   "extract": false,   "height": 50,   "left": 100,   "page": 0,   "subtype": "FULLNAME",   "top": 100,   "type": "SIGNATURE",   "width": 200   }   ],   "role": "Signer2"   }   ],   "extract": false,   "fields": [],   "id": "doc2",   "index": 0,   "name": "DocumentB",   "pages": []   }   ],   "name": "DocumentVisibilityExample REST API",   "roles": [   {   "id": "Signer1",   "index": 0,   "name": "Signer1",   "signers": [   {   "email": "[email protected]",   "firstName": "John1",   "id": "Signer1",   "lastName": "Smith1"   }   ]   },   {   "id": "Signer2",   "index": 0,   "name": "Signer2",   "signers": [   {   "email": "[email protected]",   "firstName": "John2",   "id": "Signer2",   "lastName": "Smith2"   }   ]   }   ],   "type": "PACKAGE",   "visibility": "ACCOUNT"   }   ------WebKitFormBoundary1bNO60n7FqP5WO4t-- 

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

Response Payload

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

Defining Document Visibility By Recipient

You can configure each document so that only a specified signer can see that document.This can ensure that documents with sensitive information are viewed only by their intended recipients.

After you've created your transaction, you will need to make a POST https://sandbox.esignlive.com/api/packages/{packageId}/documents/visibility with the following JSON payload:

HTTP Headers

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

 {   "configurations": [   {   "documentUid": "doc1",   "roleUids": [   "Signer1"   ]   },   {   "documentUid": "doc2",   "roleUids": [   "Signer2"   ]   }   ]   } 

You can add a configurations for each document's visibility using the custom ids set in the previous step (e.g. "id": "doc1").Once you've configured your document visibility, you can retrieve your document visibility as such:

Setting Visibility and Sending the Transaction

Finally, you set the visibility of your documents and send your transaction using the OneSpan Sign client:

 {   "status": "SENT"   } 

Results

Each recipient will only see the document assigned to them.

Request Payload Table

To download the full code sample see our Code Share site. You can also see this feature in our Interactive Demo.

During a Signer Experience, by default all recipients can view all documents in a transaction. However, you can configure your transactions so that certain documents can only be seen by specific recipients. This can save recipients from having to process documents they don’t need to see, and it can ensure that documents with sensitive information are viewed only by their intended recipients.

Defining Document Signing By Recipient

For this example, a transaction is setup such that Signer1 is only required to sign Document 1 and Signer2 is only required to sign Document 2, as shown below:

  ESignLiveSDK sdk = new ESignLiveSDK();   //Create package   ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();   pkg.name = 'Test Document Visibility - ' + Datetime.now().format();   pkg.status = ESignLiveAPIObjects.PackageStatus.DRAFT;   //Create Roles   String roleId1 = 'Signer1';   ESignLiveAPIObjects.Role role1 = new ESignLiveAPIObjects.Role();   role1.signers = sdk.createRolesSigner('sigenr1_firstname', 'signer1_lastname', '[email protected]', 'CEO', 'ABC Bank');   role1.id = roleId1;   role1.name = roleId1;   String roleId2 = 'Signer2';   ESignLiveAPIObjects.Role role2 = new ESignLiveAPIObjects.Role();   role2.signers = sdk.createRolesSigner('sigenr2_firstname', 'signer2_lastname', '[email protected]', 'Applicant', 'ABC Company');   role2.id = roleId2;   role2.name = roleId2;   pkg.roles = new List<ESignLiveAPIObjects.Role>{role1,role2}; //add role   //Prepare Documents Blob   //use single document twice, just for test   String document1Name = 'documentA';   String document2Name = 'documentB';   StaticResource sr = [SELECT Id, Body FROM StaticResource WHERE Name = 'testdoc1' LIMIT 1];   Map<String,Blob> documentBlobMap = new Map<String,Blob>();   documentBlobMap.put(document1Name, sr.Body);   documentBlobMap.put(document2Name, sr.Body);   //Create Document Metadata   ESignLiveAPIObjects.Document document1 = new ESignLiveAPIObjects.Document();   documentA.name = documentAName;   documentA.id = documentAName;   ESignLiveAPIObjects.Document documentB = new ESignLiveAPIObjects.Document();   documentB.name = documentBName;   documentB.id = documentBName;   pkg.documents = new List<ESignLiveAPIObjects.Document>{document1,document2}; //add document   //Send package One Step   String packageId = sdk.createPackage(pkg,documentBlobMap);   System.debug('PackageId: ' + packageId); 

Defining Document Visibility By Recipient

You can configure each document so that only a specified signer can see that document.This can ensure that documents with sensitive information are viewed only by their intended recipients.

After you have created your transaction, you will need to create your DocumentVisibility object and add configurations for the visibility of each using the Role IDs set in the previous section.For example, role1.id = roleId1.

  //configure documentVisibility   DocumentVisibility documentVisibility = new DocumentVisibility()   .addConfiguration(new DocumentVisibilityConfiguration('document1')   .addRole('Signer1'))   .addConfiguration(new DocumentVisibilityConfiguration('document2')   .addRole('Signer2')); 

Retrieving a List of Signers Per Document

Once you have set these configurations, you can then retrieve a list of signers who can view a document:

  public List<ESignLiveAPIObjects.Role> getSigners(String packageId, String documentId) 

Similarly, you can retrieve a list of documents for which a signer can view:

  public List<ESignLiveAPIObjects.Document> getDocuments(String packageId, String roleId) 

Setting Visibility and Sending the Transaction

Finally, you set the visibility of your documents and send your transaction using the OneSpan Sign client:

  configureDocumentVisibility(packageId, documentVisibility);   sdk.setStatus(packageId , ESignLiveAPIObjects.PackageStatus.SENT); 

Results

Each recipient will only see the document assigned to them.