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.

By default, adding a recipient to a transaction will give that recipient visibility to all documents. As a best practice, we recommend that you set document visibility after all documents and recipients have been added to the transaction. If you need to add a recipient after you have set document visibility, be sure to verify the document visibility of the recipient you have just added.

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 " + new SimpleDateFormat("HH:mm:ss").format(new Date()))
    .describedAs("This is a package created using the OneSpan Sign SDK")
    .withSigner(SignerBuilder.newSignerWithEmail("mail31@example.com")
        .withCustomId(SIGNER1_ID)
        .withFirstName("John1")
        .withLastName("Smith1"))
    .withSigner(SignerBuilder.newSignerWithEmail("mail32@example.com")
        .withCustomId(SIGNER2_ID)
        .withFirstName("John2")
        .withLastName("Smith2"))
    .withDocument(DocumentBuilder.newDocumentWithName("Document1")
        .withId(DOC1_ID)
        .fromFile(DOC_FILE_PATH_1)
        .withSignature(SignatureBuilder.signatureFor("mail31@example.com")
            .onPage(0)
            .atPosition(100, 100)))
    .withDocument(DocumentBuilder.newDocumentWithName("Document2")
        .withId(DOC2_ID)
        .fromFile(DOC_FILE_PATH_2)
        .withSignature(SignatureBuilder.signatureFor("mail32@example.com")
            .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 have created your transaction, you will need to create your DocumentVisibility object and add configurations for the visibility of each

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

com.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:

com.silanis.esl.sdk.DocumentVisibility visibility = newDocumentVisibilityBasedOnSigner()
    .addConfiguration(
        newDocumentVisibilityConfigurationBasedOnSigner(SIGNER1_ID)
            .withDocumentIds(Arrays.asList(DOC1_ID))
    )
    .addConfiguration(
        newDocumentVisibilityConfigurationBasedOnSigner(SIGNER2_ID)
            .withDocumentIds(Arrays.asList(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:

List<Signer> signersForDocument1 = eslClient.getSigners(packageId, DOC1_ID);

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

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

By default, adding a recipient to a transaction will give that recipient visibility to all documents. As a best practice, we recommend that you set document visibility after all documents and recipients have been added to the transaction. If you need to add a recipient after you have set document visibility, be sure to verify the document visibility of the recipient you have just added.

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("mail31@example.com")
        .WithCustomId(SIGNER1_ID)
        .WithFirstName("John1")
        .WithLastName("Smith1"))
    .WithSigner(SignerBuilder.NewSignerWithEmail("mail32@example.com")
        .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("mail31@example.com")
            .OnPage(0)
            .AtPosition(100, 100)))
    .WithDocument(DocumentBuilder.NewDocumentNamed("Document2")
        .WithId(DOC2_ID)
        .FromFile("C:/Users/hhaidary/Desktop/PDFs/cleaning_contract.pdf")
        .WithSignature(SignatureBuilder.SignatureFor("mail32@example.com")
            .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.

By default, adding a recipient to a transaction will give that recipient visibility to all documents. As a best practice, we recommend that you set document visibility after all documents and recipients have been added to the transaction. If you need to add a recipient after you have set document visibility, be sure to verify the document visibility of the recipient you have just added.

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', 'signer1@example.com', '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', 'signer2@example.com', '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();
document1.name = document1Name;
document1.id = document1Name;

ESignLiveAPIObjects.Document document2 = new ESignLiveAPIObjects.Document();
document2.name = document2Name;
document2.id = document2Name;

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) {
    // Initialize the list to hold the roles
    List<ESignLiveAPIObjects.Role> signers = new List<ESignLiveAPIObjects.Role>();

    // Fetch the package using the packageId
    ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);

    // Iterate through the roles in the package
    for (ESignLiveAPIObjects.Role role : pkg.roles) {
        // Check if the role is associated with the specified document
        for (ESignLiveAPIObjects.Document doc : role.documents) {
            if (doc.id == documentId) {
                signers.add(role);
                break;
            }
        }
    }

    return signers;
}

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

public List<ESignLiveAPIObjects.Document> getDocuments(String packageId, String roleId) {
    // Initialize the list to hold the documents
    List<ESignLiveAPIObjects.Document> documents = new List<ESignLiveAPIObjects.Document>();

    // Fetch the package using the packageId
    ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);

    // Iterate through the roles in the package
    for (ESignLiveAPIObjects.Role role : pkg.roles) {
        // Check if the role matches the specified roleId
        if (role.id == roleId) {
            // Add all documents associated with the role to the list
            documents.addAll(role.documents);
            break;
        }
    }

    return documents;
}

Setting Visibility and Sending the Transaction

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

// Configure document visibility
configureDocumentVisibility(packageId, documentVisibility);

// Set the package status to SENT
sdk.setStatus(packageId, ESignLiveAPIObjects.PackageStatus.SENT);

Results

Each recipient will only see the document assigned to them.