Note: As of Salesforce Winter '17, the CreateSDoc method is no longer supported. In this document, all instances of the CreateSDoc method have been replaced with the newer CreateSDocSync method. This method still uses the same parameters as the old CreateSDoc method, and works exactly the same as the old method; the only difference is that you now must call CreateSDocSync rather than CreateSDoc to guarantee proper functionality with Winter '17 and subsequent releases. If you have existing code that uses CreateSDoc calls, please replace all instances of CreateSDoc with CreateSDocSync.
To use the CreateSDocSync method, you will need to be on version 2.266 or later. For instructions on upgrading, please see our guide on upgrading S-Docs to the latest version.
- If you are looking for a way to generate multiple S-Docs (in batch) from an object list view, or you want a document to be automatically generated and emailed when a field value has changed or a date has passed, this article will help you configure S-Docs to meet your requirements.
- For example, when a user changes an opportunity stage field to “send quote” you can configure S-Docs to generate a PDF quote along with a customize cover letter and email it to the opportunity contact. Users would not need to click on any buttons, or choose any templates. Whenever the field value is changed, even from a mobile device, the process is invoked and the documents are generated and optionally emailed.
- When using the S-Docs API in batch mode, a user can select multiple records at once from a list view and send each record a custom invitation email to an event. The possibilities to further automate and distribute your documents are unlimited.
The S-Docs REST API is leveraged to invoke document generation programmatically. This powerful feature means that documents can be created in the background (synchronously) without any user involvement whenever defined criteria are met.
Both use cases work on the same principle –
1) A workflow rule, time-based workflow rule, or mass update button changes a field value that acts as a trigger to generate an S-Doc.
2) The document is created (and optionally emailed) by adding a line of code to an APEX trigger that invokes the S-Docs REST API
3) The trigger field is reset
SETUP QUICK OVERVIEW
- Add your Salesforce domain to the list of remote sites (within Setup).
- Add a field to your object that controls when the S-Doc is generated (e.g. Create_Welcome_Letter__c)
- Add a small trigger on the object that generates the doc whenever that field is set
- Option A: Add a custom list button that updates the field in step 1 in bulk (and therefore generates/emails docs in bulk).
- Option B: Use a workflow rule that has a field update action – (and therefore generates/emails the doc whenever the workflow rule is tripped)
- The S-Docs templates used in this automation need to be completely defined, meaning they must have all the needed merged fields to generate properly without user input. This won't work on any S-Docs template that prompts for user input during the generation process. For example, if you intend to email a document based on a workflow rule, then you need to use an S-Doc HTML template that defines the email body along with the “to”, “cc”, “subject” fields in order to form a valid email. Without all the field values defined, the document won’t be able to generate correctly. These fields can be set dynamically, but must be defined in the S-Docs HTML template.
- Since S-Docs runs on the Salesforce platform, it is subject to Salesforce governor limits. To help prevent reaching those limits, we suggest batch document creation is limited to 50 records per invocation. You can generate many more documents, but you should group them into batches of 50 or less records per invocation.
We’re excited about this feature and welcome your questions, suggestions and feedback.
S-Docs REST API
The S-Docs API method (CreateSDocSync) can be called from within a Salesforce trigger or an APEX class. It needs to be preceded by the namespace “SDOC.” and the class name “SDBatch”. The method can be called with 2 or 3 parameters depending on the use case.
API Call Signatures:
Option 1: Context User: This is the simpler call and can be used for basic workflow and batch processing. It requires a valid session id at time of invocation.
SDOC.SDBatch.CreateSDocSync(STRING sessionid, STRING createURL)
Option 2: As User: This signature allows for time-based workflow, or where you need to specify that the invocation run under a specific user id. It leverages JWT Bearer Assertion flow and therefore requires some additional admin setup. Click here to read about this setup.
SDOC.SDBatch.CreateSDocSync(STRING sessionid, STRING username, STRING createURL)
Call parameter details:
Sessionid: A valid session id is used to generate and send documents. In APEX, you can use UserInfo.getSessionId() to retrieve the current user’s session id. The document and email will be generated and sent from the given user context. NOTE: This may not work for time-based workflow, as the user may have logged out or the sessionid has expired when the invocation occurs. For time based workflow, you should leverage the second call method in which you specify the username parameter.
Username: (used in 2nd call signature only) The Salesforce username (not record id) that you want to use to generate and email the documents. The username is a unique identifier and is in the form of an email. Additional setup steps (described below) are needed to leverage this feature. User needs to be an active Salesforce user and have been granted API access in their user profile. S-Docs will create a new session whenever invoked in this manner.
CreateURL: This is in a querystring form (separated by &) that includes:
|Id=||(required) the Salesforce id of the record used to generate the S-Docs|
|Object=||(required) the API name of the object (for custom records it will end in __c)|
|doclist=||(required) comma delimited list of Salesforce ids. These are the S-Docs template ids. Note, they will change from sandbox to production.|
|Sendemail=||(optional) If set to 1, then the generated documents will be emailed. If you are using this option, one of the templates included in the doclist parameter should have the “Template Format” field set to “HTML”. This document will then comprise the email body of the outbound email. This template should also set the “to”, “cc”, “subject” fields. This is found under the “set advanced properties” button on the template editor.|
|Aid=||(optional). Comma delimited list of Salesforce record Ids for any attachments to be included in the outbound email.|
|Did=||(optional). Comma delimited list of Salesforce record Ids for any Documents to be included in the outbound email.|
Option 1: Method and Code Examples:
The following can be used in your code with an immediate workflow action or a batch update process. In this example, we will send an email (with no attachments) for a given lead.
The following would generate a document on account (without email). This could be used as part of your trigger when a field is updated.
Option 1: Setup Instructions: Generating and emailing S-Docs in bulk
Here are detailed steps if you wanted to send introductory emails to leads in bulk:
- Salesforce requires a remote site to be authorized for the REST callout, even if it’s in the same instance. Therefore, you need to go to Setup > Security Controls > Remote Site Settings and add an entry for your own server (eg. https://na1.salesforce.com ). Make sure the Active checkbox is checked. If you are using my domains, it is critical that you add the exact my domain registered (it is case sensitive. Go to Setup > Domain Management > My Domain and copy/paste the exact domain into the remote site setting.
- You need to add a field (checkbox or other) to your object that controls when an S-Doc is generated, such as SDocs_Send_Intro__c. It would also be helpful to add a timestamp field called SDocs_Intro_Sent_Date__c that would record when the generation occurred.
- A simple trigger would use the SDOCS REST api to generate and optionally email the documents you specify. You can pass in multiple S-Doc template ids into the doclist parameter. You can also include attachment ids, and/or Salesforce document ids if needed. In your code, you can dynamically set the template used based on any criteria (e.g., language preference), you would need to update the trigger below accordingly.
Option 2: Method and Code Examples
The next example can be used with a time-based workflow, or if you want to specify the user who will be used to generate (and optionally email) the document. In this case, we pass a blank sessionid and a valid username. If you were to pass both paramaters, the session id would be used unless it's null, in which case the specified user would be used.
Note: Additional configuration steps are needed (described below) prior to being able to leverage this method.
Specifying running user or invocation from time-based workflow (Setup Instructions)
This option requires setting a few things up in order to work without any preauthorization (as required by Salesforce). Click here to read about this setup.