I still remember my first big project using OutSystems back in 2007. It was a document management system for a water regulatory agency. I wish I had Box back then.

Sooner or later, if you’re dealing with documents, this use case will show up. Sales contracts, NDA’s, employee onboarding… There are plenty of opportunities to implement an online document signing feature in your app or company.

Typically, folks send a PDF, which gets printed, then manually signed, scanned and sent back as an email attachment. Sound’s inefficient, right? But there is an easier way.

Several companies offer this service as a complete app and most also provide APIs you can use in your app. If you look on the Forge, you’ll find quite a selection of electronic signature related components.

Box is a fairly popular component amongst OutSystems developers and recently launched their Sing API. So if you integrate Box into your app, this feature is already available to you.

Adding Box E-Signature Component to an App

If you search in the Forge for “Box”, you’ll find at least three components:

Box Forge components 

The Box API Token is a wrapper to get a JWT Authorization token to use the API (thanks Hari). If you choose JWT you can use this one or the generic JWT component.

The Box Connector, which implements the bulk of Box APIs, is still using the traditional stack, so some creativity is required.

I ended up creating a service to manage the JWT authorization tokens and another one to handle the Box Sign API agnostic of the type of application.

Box API: JWT Authorization

This service handles the JWT Authorization and application configuration.

The idea is to make it simple for the developer. All you need is to upload the configuration JSON file you get from setting up the app on the Box console and you're done.

Box API: JWT Authorization 

Sensitive information, such as the client secret, private key, and passphrase are being encrypted in the database.

The service method is being protected by an “App Manager” specific permission.

The BoxAPI_AccessToken_Get service method handles the request of a new token if it is about to expire, or it’ll reuse an existing one. This method is also protected by an “API User” permission.

Box API: JWT Authorization 

Box API: Sign

Compared to other Box APIs, you’ll find this one to be simple and easy to use. They only have 5 entry points (list, get, create, cancel and resend).

Box API: Sign request

The minimal info you need to create a sign request is a document ID, the folder ID, and the email of the signer.


{
"signers": [
{
"role": "signer",
"email": "example_email@box.com"
}
],
"source_files": [
{
"type": "file",
"id": "123456789"
}
],
"parent_folder":
{
"type": "folder",
"id": "0987654321"
}
}

From this point, Box takes over.

Box will send the document to the email, provide the app interface for the user to sign, and return the signed document to the requester. No printing, no paper, no scanning, done.

It does have an impressive set of features (although I didn’t test all of them) such as:

  • Automatic reminders for users who haven’t signed the document yet (an explicit resend is also available);
  • Two-factor authentication (besides a document password);
  • Prefill signing related information to allow you to contextualize the workflow, person, or document;
  • Multiple signers with a specific order of signing and roles (requester, approver, signer).

The Sample App

To serve as a demo app, I need to restrict the usage, otherwise, my developer account is going to have a very short life.

So I have prepared a simple document which will be the only document that can be signed. Users can send this sample to their email as a signature request.

App demo 

Once you enter your email address and create a request, you should expect the request in your inbox in just a few seconds, and follow the instructions.

Email requesting to sign document online 

Box also handles the signature capture.

Box API sign demo 

The Code

Once you have the Box API working, coding this app is a straightforward process.

For the Home screen, a simple list widget shows the current sign requests and their state.

Coding the app 

The method to create a new request grabs the hardcoded folder and document ID, the list of signers' emails, and calls the API.

Coding the app

Coding the app

Finally, there is also a detail screen that is using the Sign Request Get API method.

Coding the app 

Check out the Box related components on the forge for more details.

Box Forge components 

And give a test drive to this demo here.

By now you already know what you need to do…

Go build some apps!