Guides
Status PageRoadmapTestimonies

Getting Started

Discover how to configure and use the Salesforce toolbox for Yousign's API.

Suggest Edits

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

💡

Note

We strongly encourage you to check the Yousign API quick start guides before. That way you will gain insights on its key concepts.

For the following steps you will need an admin access to the Yousign webapp and setup rights in Salesforce.

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 Yousign 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 Yousign 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 Yousign 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 Yousign access in Salesforce

You can now log into Salesforce but do not close the Yousign 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 Yousign 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 Yousign user info.

    // We use the Named Credential we previously configured
String credential = 'YS_Sandbox';
String basePath = '/v3'; 
// Yousign 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:

👍

You got the high-five 🙌

Congratulation you made your first Yousign API call with Salesfore, well done!

❗️

You did not get the high-five but 😭 or 🌋

Please refer to the following and check you completed all the previous steps. The devil is in the details...

  • You got 😭: this means that you managed to call the API but there was an error during the call (ex: 405 if you made POST instead of GET)
  • You got 🌋: there was an error on Salesforce side... here are a few probable causes:
    • 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 principal API_KEY value (name or value)

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 Yousign API
  • we configured access for our Salesforce user using a new API key generated in Yousign
  • we are now able to use the Yousign API to query or send information

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

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

Allow Yousign to notify Salesforce

📘

This could help you!

If you are not familiar with webhooks, this is not an issue and you can proceed forward without it but we kindly advise you to check the dedicated section to understand the base principles (not more than 5 min required).

Create a public site

Domain configuration

🚧

This step might be unnecessary for your organization

In developer edition, this step is already done by default. Also, in production organization, you might already have configured a domain for another business need before.

  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 Yousign where to notify Salesforce

In the previous step, we created an endpoint that yousign can contact freely to send Salesforce some notifications. Now, we need to tell Yousign 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 Yousign 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.

    1. Tick Is Sandbox.

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

    3. Click Save.

📘

Encryption Key

This security layer is directly implemented in the Yousign Toolbox. It makes sure that the webhooks Salesforce received comes from Yousign.

👍

Good job!

You are now done with the toolbox installation

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 Yousign production API follow the same steps as previously. This are the only differences.

  1. Create an API in Yousign 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 Yousign access in Salesforce of this guide for more details.

  3. Create Webhook for Yousign Production but select Production as environment. Do not tick Is Sandbox in Salesforce YS 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.

Updated 6 months ago

What’s Next

After all the hard work comes the reward: sending document to sign directly from Salesforce! You can also find more about the functionalities offered by the toolbox.