Upgrade the Ironclad Salesforce Integration – Ironclad

This topic will walk you through how to upgrade your Ironclad Salesforce Integration.

Note: This article is intended for users setting up the Ironclad Salesforce Integration for the first time or for those doing a fresh install of the Ironclad Managed Package.

If you are looking for documentation on package versions 2.1 and below, refer to Salesforce Integration Overview (Legacy).
If you want to upgrade from a version below 2.2 to a version above 2.16, refer to Upgrade the Ironclad Salesforce Integration from 2.13+.
If you installed an early-access package (between version 2.4 and 2.12) and are now switching to the official release package (2.16+), refer to Upgrade Early Access Package to Official Release.

Introduction

This guide is only intended for Salesforce Lightning.

Do versions 2.16 and above have new features?

There are a few additional features available with version 2.16+ (most of these features are only available in Salesforce Lightning):

Launch new workflows directly in Salesforce through an embedded launch experience. This includes fields automatically populating with Salesforce data.
View all of the workflows associated with a Salesforce object in one place. This includes workflows that were launched from related objects.
View contract statuses in Salesforce with visual displays of workflow statuses. This gives sales users insight into the contracting process.

What should I know before I upgrade my Salesforce integration to version 2.16+?

The updated package is fully backwards compatible with existing features. Your in-flight contracts and current workflow configurations should not be impacted by updating your package.
Some aspects of your integration’s data model will be updated. If you have any fields/processes that are dependent on the following fields, make sure you have migrated that data or planned an alternative before beginning the upgrade process:
- The Workflow Step field will no longer available. It is replaced with a new field called Workflow Status. As part of the migration process, you will have the option to populate the new Workflow Status field with Workflow Step data for existing workflows.
- All new workflows created after upgrading will automatically use the Workflow Status field.
- The old Workflow Step field will no longer be visible.
The default lookup relationship direction between Ironclad workflows and Salesforce objects will be changed to many-to-one (from workflows to Salesforce objects) to better support multiple contract situations.
- If you followed this article to set up a related list using Process Builder, you already have this lookup relationship. The updated integration will start overwriting this field. You should remove the process to avoid any conflicts with the managed package.
- We recommend NOT starting the upgrade process until you have verified that overwriting these fields or removing the process will not cause negative impacts in other areas of your Salesforce instance.
- Contact Ironclad Support for additional guidance.

How do I upgrade my Salesforce integration?

To upgrade from a previous version of the Ironclad app, you must:

Install the package update and enable the new path component.
Add new Ironclad Workflow Configuration records, as this is the new format in which the app associates workflow configurations to Salesforce source objects.
Invert the lookup relationship between Ironclad Workflows and your Source Objects.
Update the Salesforce page layouts for the Ironclad Workflow object and any Salesforce source objects that will be launching/syncing workflows.
Backfill the new Workflow Status field for existing workflows.

Prerequisites

Before you upgrade your Salesforce integration, you must:

Contact your Ironclad support representative to request that your account is enabled for access to the new Salesforce integration features.
If you have previously used this article to set up a related list using Process Builder, remove the process that you created. To do this:
- In Salesforce, navigate to Setup > Process Builder. You do not have to remove the lookup relationship you created, only the process.

Install the Ironclad Package Update

In the Salesforce AppExchange, locate the Ironclad Managed Package. Verify that the version number is higher than 2.13. Install the package. We highly recommend that you Install for All Users to make sure that there are no permissions issues.
If you are not already logged into the org you want to install the package to, Salesforce prompts you to log in. For more information on installing packages, refer to Salesforce’s documentation.

Update Salesforce Permissions

To update your permission sets in Salesforce, refer to Manage Salesforce Permissions.

Migrate Existing Workflows

Required Ironclad Permissions: Admin
In package versions 2.1 and below, the state of in-flight workflows were saved in the Workflow Step Salesforce field. To support expanded functionality, in package versions 2.13+, the Workflow Step field was replaced by the new Workflow Status field.

The old Workflow Step was a string field, and the new Workflow Status field is a picklist.
Because all in-flight workflows do not yet have data for the Workflow Status field, we have created a migration tool to automatically populate those values.

Before discussing the steps for accessing and using the tool, it is important to know that this migration consumes a substantial number of Salesforce API calls. If you do not have sufficient calls left within your daily limit, the migration fails and you must re-attempt on another day. The migration tool shows an estimated number of calls needed prior to starting the migration. The call volume is tied to the number of workflows connected to Salesforce in your company.

To check your daily Salesforce API call limit, refer to Salesforce’s documentation. If you have questions related to the daily API call limit, contact your Salesforce representative.

Before starting the migration, keep in mind:

This process only needs to be done once and cannot be paused, undone, or reversed after it has been started.
The migration does not impact the progress of your workflows. You can continue working on these workflows and launching new ones without any interference while the migration runs in the background.
If you have built any automation or tooling that uses the Workflow Step field, such as Salesforce reports, you should update those processes to use the Workflow Status field before starting the migration. You should also confirm that the datatype change (from string to picklist) will not negatively impact your processes.
Depending on the number of active workflows and demand on the tool, the migration process can take anywhere from a few minutes to a few hours. You receive an email with the status of the migration and any required next steps upon completion.
This step can be completed independently of the other steps in this topic. You can work on other parts of the upgrade process and return to this step on a different day, such as when you have more API calls left within your daily limit.

Log in to your account, and then visit the following link.
View the estimated number of Salesforce API calls needed, and verify that your organization has enough calls left in your daily limit. Click Start Migration.
Follow the prompts and begin the migration. At this point, you can navigate away from the page and continue setting up and using the Salesforce integration. The admin who started the migration will receive an email notifying them if the process was successfully completed, or if there are any errors that need to be resolved.
If you have any questions about the migration tool, reach out to the Ironclad Support team. If you have questions related to the daily API call limit, reach out to your Salesforce representative.

Add a New Path Component

You can now add a path component to the Ironclad Workflow object, which provides a visual representation for the workflow’s status. You must first enable this feature in Salesforce, then you must add the standard component to the lightning page of the Ironclad Workflow object.

In the top right corner of Salesforce, click Setup indicated by a gear icon. Navigate to User Interface > Path Settings, and then click Enable.
Verify the Status path for the Ironclad Workflow, which was added through the managed package, is set to Active.
Click the App Launcher icon indicated by a grid of stacked dots. Search for and click on Ironclad Workflows.
Click New. This is a placeholder record you can delete later.
Enter an Ironclad Workflow Name and Workflow ID. Click Save.
Click Setup indicated by a gear icon in the top right corner, and then click Edit Page.
Drag the Path component to the header section of the page.
Select the Hide path update button checkbox and click Save.
If the activation modal does not immediately appear after you click Save, click Activation to activate the page based on your organization’s needs.
Activate the page as Org Default or App Default depending on your organization’s needs. We recommend that you activate this Lightning page for both Sales and Sales Console apps. Click Close.
Verify that the path’s status bare displays on the test Ironclad Workflow object. Once the activation is complete, if you used a test record, delete the record by exiting the page layout editor, clicking the dropdown icon in the top right, and click Delete.

Add New Lookup Field on Ironclad Workflow Object

This steps below walk you through how to add a new lookup relationship from the Ironclad Workflow object to your Salesforce source objects. This allows users to see all related workflows directly from the source object. This instructions below use the Contact object to represent the source object, but you may follow these steps using any source object.

Click Setup indicated by a gear icon in the top right corner, and then click Object Manager. Click the Ironclad Workflow object.
In the left panel, click Fields & Relationships, and then click New.
For the Data Type, select Lookup Relationship and click Next.
In the Related To dropdown, select the object type you want relate to. In this example, we are using the Contact object, so we select Contact. Click Next.
Enter a Field Label and Field Name.
In the Child Relationship Name field, enter Ironclad_Workflows. Verify the Clear the value of this field checkbox is selected. Click Save.
Repeat the steps above for each Salesforce object you have a workflow configured for.

Delete Old Lookup Field on Salesforce Source Object

You will also need to remove the old lookup relationship. Before doing this, verify that there are no other components in your Salesforce instance that depend on this field.

Click Setup indicated by a gear icon in the top right corner, and then click Object Manager > Fields & Relationships.
Locate the Ironclad Workflow field, and then click on the dropdown button located on the right. Click Delete.
Repeat the steps above for each Salesforce object you have a workflow configured for.

Update Page Layouts

Update Ironclad Workflow Page Layout

Click Setup indicated by a gear icon in the top right corner, and then click Object Manager. Click the Ironclad Workflow object.
In the left panel, click Page Layouts, and then click Ironclad Workflow Layout.
Drag the Account and Contact lookup fields into the page layout (and any other objects you want to configure). This may have been done automatically for you after creating the lookup relationship, in which case all you have to do is double-check that the correct fields appear.
Locate the Workflow Step field and click the Remove icon.
Drag the Workflow Status Field to the page layout, and then click Save. This may have been done automatically for you after creating the lookup relationship, in which case all you have to do is double-check that the correct fields appear.

Update Source Object Page Layout

You must add the Ironclad Workflows Related List to the Source Object Page Layout. This allows users to see all related workflows directly from the source object. The instructions below use the Contact object to represent the source object, but you may follow these steps using any source object.

Click Setup indicated by a gear icon in the top right corner, and then click Object Manager. Click the Contact object.
In the left panel, click Page Layouts, and then click Contact Layout.
Click the Related Lists tab, and then drag the Ironclad Workflows related list onto the page layout. we recommend adding it to the top of the list for easy access. This may have been done automatically for you after creating the lookup relationship, in which case all you have to do is double-check that the correct list appears and reorder the lists as needed.
Click the wrench icon above the Ironclad Workflows related list.
From the Available Fields list, add Ironclad Workflow Name, Workflow ID, Workflow Link, and Workflow Status to the list of Selected Fields. Click OK.
Click Save.

[Optional] Add Workflow Configurations to Salesforce for Embedded Launch

Skip this section if your organization does not want to use embedded launch for your launch forms. Your custom buttons will continue to function normally. If you are launching from a Salesforce custom button and/or only using the Pull from Salesforce option in Ironclad, you do not need to complete this section. It is only required to be able to use embedded launch from the Ironclad Workflows component.

There are three ways to launch an Ironclad workflow that syncs with Salesforce data:

Pull from Salesforce Button on Ironclad: When you click the Pull from Salesforce button, you can search objects in Salesforce and automatically fill in the workflow form with values from the Salesforce object you select based on the configuration you created.
Custom Salesforce Button: Add a custom button to Salesforce pages to automatically launch an Ironclad workflow from a Salesforce page.
Ironclad Workflows Component in Salesforce: Launch a new workflow from within your Salesforce window. You can also see all available workflows from one component.

For more information on the benefits and considerations for each method, refer to Launch Workflows from Salesforce.

In this section, you will learn how to set up a workflow for embedded launch in Salesforce using the Ironclad Workflows component. Using embedded launch, you can launch a new workflow from within Salesforce as well as see all available workflows from one component. You can use embedded launch forms in combination with your existing custom buttons, as well as offer the same workflow through both.

If you are launching a new workflow from within Salesforce, we strongly recommend using the new Ironclad Workflows component. However, launching from a custom button is still supported and encouraged in specific situations.

If your company relies on very strict access-control and permissions within Salesforce, we recommend using custom buttons, as this allows you to easily restrict which workflow launch forms each Salesforce user can access, as well as restrict access to workflow launch until after certain CPQ approvals have been collected.

Note: In this section, we integrate an NDA workflow with the Contact object in Salesforce as an example, but you may integrate any workflows with any Salesforce object using the same steps.

In Ironclad, click on your name located in the top right corner. Navigate to Company Settings > Integrations > Salesforce. Copy the Salesforce Custom URL.
In Salesforce, click the App Launcher icon indicated by a grid of stacked dots.
Search for and click Ironclad Workflow Configurations. Click New.
Enter the following information:
1. In the Ironclad Configuration Name field, enter a name for the workflow configuration.
2. In the Source Object field, enter the API name for the source object. To find this, go to Settings > Object Manager and select your source object. Enter the name exactly as it appears here. For example, if the Object Manager says Contact, make sure you enter Contact, not Contacts.
3. In the URL field, enter the launch URL you copied in the first step.
Verify the URL and Source Object fields are correct.
In the Salesforce Sales app, click the object tab you want to launch from. In this example, we click Contacts. Click New.
Fill in the required fields, and then click Save.
Click Setup indicated by a gear icon in the top right corner. Click Edit Page.
Drag the Ironclad Workflows component to the right panel of the page. Click Save.
If the activation modal does not immediately appear after you click Save, click Activation to activate the page based on your organization’s needs.
Activate the page as Org Default or App Default depending on your organization’s needs. We recommend that you activate this Lightning page for both Sales and Sales Console apps. Click Close.
Repeat these steps for each workflow you want to launch using Salesforce data.