Keeping Integration Simple
DocuSign Integration with e-Builder
The Product
e-Builder is a construction program management solution that manages capital program cost, schedule, and documents through a world-class workflow and business intelligence. e-Builder is a complete solution designed at its core to deliver control and reduce surprises for owners of capital program.
The Challenge
e-Builder has been around for years and while it solves several problems in the owner space, it can be challenging to navigate and control. When users want to integrate DocuSign in order to streamline creating and sending envelopes, they are required to jump back and forth with DocuSign and copy information they may not necessarily understand, leaving room for user error.
Part One
Understanding the Problem
Passing the Torch
There was another designer assigned to this issue who had put together a solution and due to unforseen circumstances, it was transferred over to me to complete delivery.
“What is an API?”
The original process was very complex and required the end user (admins) to reference and input information from DocuSign. The information required included:
User ID
Username
API Account ID
Account base URI (optional)
BrandID (optional)
Selection to Trace or not Trace API Calls (optional)
It was safe to assume that the average administrator didn’t always know what they were looking for. This left a lot of room for user error and opened the door for a lot of contact with our support team to understand what exactly they needed to find.
Product Request
Originally the design was to be left unchanged with the exception of removing a field (specifically the Account base URI).
Although from a UX perspective, this didn’t solve the issue that users had no simple way of integrating with DocuSign. We needed to get more information.
Meeting with DocuSign
I wasn’t the only one that was hesistant with the existing solution. Our developers knew that we had a lot of user information stored in our system already and this meant there was likely an easier way to authenticate with DocuSign without needed all the manual input.
We scheduled a call with our DocuSign representative who elaborated further on possible options.
They explained that most of their clients implement an Authorization Code Grant. Essentially the users would construct a URL, log into DocuSign, exhange a token on the backend, grant consent and complete authentication.
In simpler terms, it’s a “social” log in, not very different from sites that allows a user to “Log in through Gmail” or “Log in through Facebook”.
Still Requires Manual Input
While this solution was significantly easier than what existed currently, we still had to get a JWT (JSON Web Token). The easiest solution was to have the users copy it from DocuSign but our developers were confident that we could likely cache the GUID’s.
From a UX point of view, I was concerned about the number of steps our users had to take. After digesting all the information we had up to this point, the solution was less about removing “clicks” and more about getting it right.
There was another concern about the process that was brought to my attention and this was that we had a lot of accounts that share a User ID and authenticating/authorizing the integration would go accross the board rather than just e-Builder.
Security First
We knew we could at least simplify the process significantly to integrate DocuSign and we were confident our engineers would put together a console to cache GUID’s to eliminate the copy/paste method for JWT’s.
The next step was to establish some security around the process. Knowing that several accounts share a User ID, we decided to hide certain characters after authenticating.
We also needed to implement an account selection so the admins can only authorize e-Builder and no other accounts. This wouldn’t eliminate an incorrect selection, but it would trigger an error if they selected anything other than e-Builder.
Confirming the Details
The input fields would be broken down by User ID, Username, and in a later phase, Brand ID (for logo).
The Brand ID would let the user know which logo is currently being added but they can only swap this out in e-Builder. There is also no visual indicator for what logo is currently selected and this was a limitation from DocuSign specifically.
If the user was changing the User ID, the username would be left as-is until the authorization was complete.
There would be a new page to grant consent and ideally, DocuSign would also provide the accounts to select from.
User ID’s could not be visible in any capacity but username could be. We agreed to partially mask the email to increase security while still providing enough detail to the user should they need the reference.
Modernizing the Look
e-Builder was acquired by our parent company Trimble Inc. in 2018 and Trimble had their own style guide that we were asked to slowly implement.
The idea was to implement it where the risk was low and standardize wherever/whenever we could.
My initial designs used all of these new components and only further simplified the user journey.
There was some pushback from developers as this would be the first time this particular team would code with the new components but ultimately our product team agreed to move forward.
Part Two
High-Fidelity Designs & Delivery
Accessibility
It was important to keep the process accessible, especially because the components were new to our developers. There were several conversations throughout the delivery to make sure the final product was “pixel"-perfect”.
When it came to ARIA labels for screen readers, this actually led to minor button changes in the design in order to improve ease of use and consistency with the way the labels would be read out loud.
Part Three
Looking Back
This project was a lot of hard work. In general, there was a lot of discovery needed from the technical side and making sure we had a clear understanding of the constraints and limitations. The initial handoff to me came with little to no intent of changing the design so this meant establishing a problem with product with the hope of prioritizing the improvements. This all worked out rather well, given the concern didn’t only come from me and with proper communication, we were able to move forward as needed.
Accessibilty was reviewed prior to delivery but ARIA labeling came up later than it should have. Fortunately, collaboration was efficient and several decisions/design changes were made in less than a day.
Overall, our users would now have the ability to integrate with DocuSign without making them think too much. The most important takeaway was that while simple is better, nothing trumps doing it the right way the first time.