OneSpan Sign Developers: Virtual Room – Part 2

OneSpan Sign Virtual Room (VR) is a virtual meeting room in which a host and signers from different locations can collaborate through a video conference call and sign documents within a co-browsing session.

In the last blog, we introduced the highlights of the OneSpan Sign Virtual Room and outlined the basic steps to create a VR transaction. Picking up where we left off, we will demonstrate how to create a Virtual Room transaction with SDK code and showcase two ways to access a virtual room transaction. Without further delay, let’s get started!

Virtual Room in SDK

Previously, we walked through the steps to create a Virtual Room transaction with REST API, and the good news is that the Virtual Room feature is also fully supported by our SDK. If you are integrating OneSpan Sign services with either Java or .NET SDK, make sure your SDK version is above 11.41, and you are ready to leverage the Virtual Room feature in a simple 3-steps approach:

Step 1: Create a Transaction

Different from the normal transaction creation flow, we’ll make sure the code has explicitly added the Virtual Room host and specified the role ID as shown in the sample code below:

DocumentPackage documentPackage = PackageBuilder.newPackageNamed("Example Virtual Room Transaction") 
      .withSigner(SignerBuilder.newSignerWithEmail("sender_email")
                  .withCustomId("Owner")
                  .withFirstName("Duo")
                  .withLastName("Liang"))
            .withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
                  .withCustomId("Signer1")
                  .withFirstName("Patty")
                  .withLastName("Galant"))
    .withDocument(DocumentBuilder.newDocumentWithName("Document1") 
            .fromFile("path_to_file") 
            .withSignature(SignatureBuilder.signatureFor("sender_email") 
                .onPage(0) 
                .atPosition(100, 140))
            .withSignature(SignatureBuilder.signatureFor("[email protected]")
                .onPage(0) 
                .atPosition(100, 205)))
        .build();

PackageId packageId = eslClient.createPackageOneStep(documentPackage);

Step 2: Set Up Virtual Room Settings

Once we have the transaction created, we’ll utilize the functions exposed by VirtualRoomService class to configure Virtual Room settings: 

SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
simpleDateFormat.setTimeZone(TimeZone.getTimeZone("America/Toronto"));
Date vrDate = simpleDateFormat.parse("2022-04-23T09:30:00Z");
VirtualRoom virtualRoom = VirtualRoomBuilder.newVirtualRoom()
        .withHostUid("Owner")
        .withVideo(true)
        .withVideoRecording(true)
        .withStartDateTime(vrDate)
        .build();
eslClient.getVirtualRoomService().setVirtualRoom(packageId, virtualRoom);

Step 3: Send the Transaction

You can optionally retrieve the Virtual Room configuration and make sure all the information is correct before sending out the transaction:

VirtualRoom vrConfig2 = eslClient.getVirtualRoomService().getVirtualRoom(packageId);
System.out.println(String.format("Virtual Room Config - Host ID: %s; Start Date: %s; Enable Video: %s; Enable Recording: %s.", 
    vrConfig2.getHostUid(),
    vrConfig2.getStartDatetime(),
    vrConfig2.getVideo(),
    vrConfig2.getVideoRecording()
    ));
eslClient.sendPackage(packageId);

Access via Email Notifications

After the transaction has been sent out for signing, recipients receive an email notification containing all the necessary information about the conference and an access link to the signing ceremony.

The email template behind the scenes is the “email.activate.virtual.room”. For a Virtual Room transaction, this particular email template will kick in and replace the regular “email.activate” template. Similarly, if you resend the signing invitation, a new email template “email.notify.virtual.room” will be triggered instead of the regular notification email.

Both email templates can be customized if you download the default HTML template, modify the wording and layout, and send it back to our support team with your request.

Access via Signing Links

Besides accessing through the invitation email, it’s also possible to programmatically generate the signing link and redirect from your integrated application.

Option 1: You can retrieve a signer authentication and build this formula:

https://{oss_instance_url}/access?sessionToken={signer_auth_token} 

Option 2: Alternatively, you can directly generate a signing URL.

The main differences between these two options are:

• Signing URL never expires, whereas the authentication token is only valid for 30 minutes
• If you want to authenticate the signer (e.g. SMS, Q&A, KBA, etc.) before allowing them to review and sign the documents, you can only use Signing URL in this case.

There it is. In this blog, we have demonstrated how to create a Virtual Room transaction with the SDK code and introduced two ways to access the signing ceremony. If you have any questions regarding this blog or anything else concerning the integration of OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!