This guide will require you to have a Salesforce and a Youtrust organization. If you only wish to try it out, you can create a Salesforce Developer account and a Youtrust Trial Account for free.

Install the Salesforce toolbox package

This is the most technical part, we are here to guide you through it step by step.

We made this toolbox to ease the Youtrust API integration inside Salesforce and for you to focus on your specific business cases. As such, the first step is to import it in your own Salesforce organization.

You can find all the sources and the steps to do so here.

Use the Youtrust API in Salesforce

Are you still with us and done with the package deployment? Well, there is good news, if you have code phobia and wondered if this would give you nightmares tonight, rest assured: now, only admin tasks are needed.

Creation of the API key

1. Log into your Youtrust web application
2. Go to the Integration > API tab. If you are in a trial version, start your API trial.
3. Create an API Key.
   1. Description Salesforce - Sandbox Full Access
   2. Environment Sandbox
   3. Permissions Full-Access

Now that it is created, you can now copy the API key value; we will use it right after.

Configure Youtrust access in Salesforce

You can now log into Salesforce but do not close the Youtrust application yet: (spoiler) we will still need it afterward.

1. Go to Setup > Security > Named Credentials then click on the External Credentials tab.

2. Select the YS - Sandbox external credential

   

3. Edit the Principal called Authorization Token and create a new value with the name API_KEY and paste the API key value you got from the Youtrust Application previously.

   

4. In the setup, go to Users > Permission Sets and select the YS_Sandbox (it might not be on the first page).

   

5. Go to Manage Assignments and assign the permission set to yourself.

6. Do the same with the YS_ObjectsPermissions permission set: select it and manage assignments to assign the permission set to yourself.

Now you have access to use the API! You can test that in the following way:

1. Open the developer console

   

2. Press Ctrl + E (on windows) or Command + E (on mac) to open an anonymous code window

3. Clear what is inside the anonymous window if there is something.

4. Copy + Paste inside the following code. It will get your Youtrust user info.

   Apex

   // We use the Named Credential we previously configured
   String credential = 'YS_Sandbox';
   String basePath = '/v3'; 
   // Youtrust endpoint for the test call
   String endpoint = '/users';
   String method = 'GET';
   Integer timeout = 10000;
   
   // construct HTTP request
   HttpRequest request = new HttpRequest();
   request.setMethod(method);
   request.setEndpoint('callout:' + credential + basePath + endpoint);
   request.setTimeout(timeout);
   
   try
   {
   		// send HTTP request
       HttpResponse response = new Http().send(request);
   		// treat HTTP response
       System.debug('🤞');
       Integer statusCode = response.getStatusCode();
       System.debug('Status Code 👉 ' + statusCode);
       if (statusCode == 200)
       {
           System.debug('🙌'); // SUCCESS! You want to see this
           System.debug(response.getBody());
       }
       else
       {
           // You don't want to see this
           System.debug('😭'); // You managed to call the API but there was an error during the call (ex: 405 if you made POST instead of GET)
           System.debug('[' + statusCode + '] ' + response.getStatus());
       }
   }
   catch (Exception e)
   {
       // You want to see this even less 😱
       // Error on SF side. The probable causes are
       // - The name of the credential doesn't match your Named Credential name.
       // - You haven't assigned yourself the permission set.
       // - There is an error on the on the principal API_KEY value (name or value)
       System.debug('🌋');
       System.debug(e);
   }

5. Tick the Open Log checkbox then click Execute.

   

6. In the opening tab, tick Debug Only.

7. In the debug log you want to see 🙌 and do not want to see 😭 nor 🌋. Hopefully your debugs logs will look like this:

   

Before continuing, let's have a quick look at what we did earlier:

• we imported a package inside our salesforce organization, containing means to access and use the Youtrust API
• we configured access for our Salesforce user using a new API key generated in Youtrust
• we are now able to use the Youtrust API to query or send information

But this is not the end, we can make better usage of Youtrust's API

If we are able to send or query information through Youtrust's API when we want, sometimes Youtrust wants to notify you of important updates that happened inside the application like when a Signer signed a Document.

Allow Youtrust to notify Salesforce

Create a public site

Domain configuration

1. Go to Setup > Company settings > My domain.
2. Choose a domain name, check for availability then register the domain.
3. Once it is ready, click on Log in then on Deploy to Users.

Public site creation

As for the previous step, you might experience small differences from one salesforce edition to another. The principle stays the same.

1. Go to Setup > User Interface > Sites and Domains > Sites.

2. Choose a site name, check for availability, accept the Sites Terms of Use then register it.

3. Click on the button New:

   1. Site Label YS webhooks
   2. Site Name yswebhooks
   3. Put a System Administrator as the Site Contact & Default Record Owner
   4. Suffix Default Web Address by yswebhooks
   5. Tick Active
   6. Active Site Home Page InMaintenance

4. Click Save

   

Public site access settings

1. Click on the Public access settings button.
   (if you already closed or change the page from the last step, can access it by going back to Setup > User Interface > Sites and Domains > Sites then selecting the previously created one)

2. Click on the Edit button near Enabled Apex Class Access.

3. Add the YS_WebhookListener class then hit Save.

   

4. Once back on the Profile page for the public access settings, on the top of the page, click the Edit button (next to the View Users one).

5. Scroll down to the Platform Event Permissions and grant Read and Create accesses to the YS Events object. Click Save afterward.

   

Tell Youtrust where to notify Salesforce

In the previous step, we created an endpoint that Youtrust can contact freely to send Salesforce some notifications. Now, we need to tell Youtrust where we want to be notified.

Create a webhook

1. First let's copy your site url (the endpoint mentioned above). Go to Setup > User Interface > Sites and Domains > Sites and copy the Site Url next to your YS Webhooks site.

2. Go to your Youtrust account

3. Go to the Integration > Webhooks section. Then hit Add a webhook.

   1. Endpoint: paste the value you copied at step one and suffix it with /services/apexrest/ys/webhooks.
      It should look something like https://XXXXXXX.my.salesforce-sites.com/yswebhooks/services/apexrest/ys/webhooks

   2. Description Salesforce - Sandbox

   3. Environment Sandbox

   4. Subscribed events Trigger on all events

      

4. Click Create Webhook.

5. Click the 3 dots under Actions and select Copy secret key.

6. In Salesforce go to Setup > Custom Code > Custom Settings and click on YS configuration.

7. Click New (the one above the section Default Organization Level Value).

   1. Tick Is Sandbox.

   2. Paste the Secret key in the YS Encoding Key field.

   3. Click Save.

      

Going to Production

To use the toolbox in Salesforce production environment, you will need to redeploy the package into this organization. Please follow the steps available here.

To connect Salesforce to the Youtrust production API follow the same steps as previously. This are the only differences.

1. Create an API in Youtrust but select Production as environment. Refer to the Creation of the API key section of this guide for more details).

2. Add this API Key in Salesforce in the SF - Prod external credentials and assign it to yourself or needed users through the YS_Prod permission set (also add the YS_ObjectsPermissions permission set for needed users). Refer to the step Configure Youtrust access in Salesforce of this guide for more details.

3. Create Webhook for Youtrust Production but select Production as environment. Do not tick Is Sandbox in SalesforceYS Configuration custom setting. Check the Create a webhook section for more details.

4. Switch the credentials used by the External Service to the Production ones.

   1. Go to Setup > Integrations > External Services click on the YS External Service.

   2. Click Edit. Change the Named Credentials to YS_Prod.

      

   3. Click Save & Next then Next then Next again and finally Finish.