Publishing Templates
Publishing templates improves document generation performance by taking referenced clauses in a template and 'publishing' them before the template is used to generate a document. This takes the content of the clause and enters it into the template body as static text as if it was another part of the main template. Auto-publishing enhances this by enabling you to schedule a batch job, which will automatically complete the publishing task that previously needed to be completed manually.
About Auto-Publishing
Auto-publishing requires an apex scheduled job and then entering a username and password and selecting the Enable Auto Publish option on the Publish Template page to work. After that the system automatically handles the process. Even when you have auto publish enabled, you can always manually publish templates on an ad hoc basis. Auto Publishing automates an administrative task, that previously must have been completed manually. There are a number of new fields added to the Template object for this feature that you may or may not want to add to the templates page layout when upgrading. With new installations, by default, the publish fields will be included on the page layout.
The fields are automatically updated by the actions you take in X-Author Contracts and Contract Management, so there is no need to display them for the functionality to work as expected. Including them may actually hinder the functionality. For instance, someone could manually uncheck the Needs Publishing flag for an updated template.
You may want the fields visible and editable for system admin users for troubleshooting and for testing in a sandbox org; however, for typically business users there is no need to display these fields.
The new fields are:
- Needs Publishing - this Checkbox field is automatically selected whenever the referenced clause of a template has been changed and a new version is checked in, since the template was last published. This serves as a flag, which will add the template to the list of templates to be auto-published.
- Number of Clauses - this Roll up Summary field indicates how many referenced clauses are associated with the template.
- Published Date - this Date/Time field indicates the last time the template was published.
- Publish Status - this Picklist field indicates the status of the template in relation to going through the publishing process. The available values are Pending, Published, and Submitted.
- Published Doc ID - This is a unique identifier field, cons assigned to the published template automatically after it is published. You can search for the details of the published template in Salesforce using this ID.
A scheduled apex job is used to set the frequency of your auto-publish jobs, while the Publish Templates page is where you can initiate publishing.
From Contract Management and X-Author Contracts February 2015 release onwards, auto-publishing can be done from the X-Author Templates in Microsoft Word by clicking any of the following ribbons:
- Publish
- Check-In
Configuring Auto-Publishing
To manually publish templates using the Publish Templates tab
- Click + and select Publish Template and a list of templates that have changed or had their associated clauses change, resulting in their Needs Publishing flag being checked, are displayed.If you are going to manually publish a template it does not matter if the Auto-publish option is checked.The manual template publish process does not store the credentials. The credentials are retained in memory and passed to the merge service which uses it to login and establish a session with Salesforce.
- Select the templates you want to publish and click Publish. The status for the template changes to Submitted and an entry is added to the Batch Jobs list for each selected template that is published.
If the job failed, the Batch Jobs list will provide a message you can use to troubleshoot.
If a job failed, you can try publishing the template again. If it published successfully, you can use the template with its updated clause references, for generating agreement documents.
Using Merge Service
Merge Service and the Contract Management package work together as follows, to auto-publish templates.
- A username and password must be provided each time you publish, whether you are initiating an Auto (scheduled) or Manual run. The current session ID is not used, so the user may choose to log out during the process.
- Contract Management uses the AES-256 (Advanced Encryption Standard with a 256-bit key length) protocol.
- When the publish job is submitted, Contract Management calls Merge Service to initiate the publishing process.
- Merge Service does a complete cycle of publishing within each session. This includes fetching the template document and referenced clauses from Contract Management, in-lining the referenced clauses within the Template, and saving the published template document to the Contract Management template record.
- As each template publish cycle is completed, Contract Management updates the Auto publish job status regarding the template as completed, and initiates the next Merge Service template publish cycle. There is never any persistent data retained by Merge Service.
- Each template publish cycle is executed as a separate session with its own unique Session ID.
- When the last template has been published, Contract Management updates the job complete status.
SSO does not work for auto-publishing. The process requires specific login credentials for a user with access to publish documents.
Handling Auto Publishing Security Considerations
Merge Service is hosted in the Amazon EC2 cloud, where service instances may be brought online dynamically to handle demand loads. This means their IP address may change, which precludes the ability to add a static IP address to a whitelist and instead requires the use of a security token.
The template publish process is run through Merge Service, outside the customer’s firewall. The initial service action is to call back into Salesforce to initiate the publish process and pull data from Salesforce. For this, a mechanism is needed to initiate a Salesforce session by providing user credentials to the org, which includes a user name, password, and security token.
In a Single Sign-On (SSO) environment, the user logs into the environment once and passes the token to other applications seamlessly. But in the SSO environment, the security token link is hidden, which then requires additional steps to get a security token for publishing. The SSO token is not available to jobs scheduled to run in the future. Both the current Manual and Auto publishing processes are treated in this way.
Security Handling Options
The typical solution for Salesforce integration jobs is to have a specific profile assigned to a small number of system administrator users, to carefully control who has access to the objects required to complete tasks. So there are three possible ways to approach this security challenge if running a publishing job is desired:
- It is recommended that you create a specific API user profile, with the minimum privileges required to publish templates. Then create a specific API user and assign the profile to this user for all template publishing tasks. For more details, see this Salesforce help topic .
- Another option is to enable Two Factor Authentication for the user profile, which makes the security token link available. After the security token is secured, the Two Factor Authentication may be turned off. The security token will remain valid until the password is changed.
- This additional option is suggested for those who do not want to use a Salesforce license, which is required for our recommended option. You can bypass auto-publishing and use the current user session to manually publish the templates. This would be set up similarly to the method used by Salesforce for Workflow Outbound Messaging, that allows a remote web service to call back into Salesforce, as described in this Salesforce help topic .
