Note: Nintex Apps data centers are located in West US and Australia (AUS). In-region processing of Nintex Apps data is only available in these regions.

Salesforce

Salesforce is an enterprise-level cloud computing platform used for customer relationship management and other "big data" needs. By using Nintex Apps in conjunction with Salesforce data, it is possible to create intuitive user interfaces that pull in an organization's data—perhaps while pulling in data from other services as well. It is the default connection available in any Nintex Apps for Salesforce instance, but additional connections can be configured to connect to Salesforce orgs.

For Salesforce users working in larger organizations, there may be multiple orgs, with different types of data, that need to be accessed at various times. Accessing different orgs and modifying data in each can be cumbersome, requiring different login credentials and (sometimes) different platforms.

With Nintex Apps's Salesforce connector, accessing multiple Salesforce orgs is far simpler. In Nintex Apps, creating a Salesforce connection for each external org does not require copying data or cloning objects between orgs. , Nintex Apps authenticates to an external org (or orgs) using a configured authentication provider and connection in a process similar to other external data connections. Once your connections are in place, end users will be directly reading, creating, and updating data on multiple orgs, all from the same app page.

What's an "external org?"

If you're using Nintex Apps, all your connections, including Salesforce, are "external" to your Nintex Apps site and are accessed via connections you create.

If you are using Nintex Apps for Salesforce, however, you are working within a specific Salesforce org, on which Nintex Apps was installed as a managed package. Perhaps you're in sales at Acme Industries, so the Salesforce org where you work within your Nintex Apps pages might be https://acmesales-dev-ed.my.salesforce.com/. If you want to pull data into those pages from another Acme Salesforce org (for example, to get invoice data from the Accounting Department's org, https://acmeaccounts-dev-ed.my.salesforce.com ), you must create a connection that connects to this "external" org—external to the Salesforce org hosting your Nintex Apps pages. You must also create the connected app (see below) in that external org to facilitate this connection.

Connecting to more than one external Salesforce org from your Nintex Apps site? You'll need to create a connected app within each external org, as well as a connection for each within your Nintex Apps site.

Just remember: everything described below is about connecting to an external org from your Nintex Apps site, whether that Nintex Apps instance is on Platform or Salesforce.

Set up a Salesforce connection

To use the Salesforce connector with Nintex Apps, you'll need to complete the following three steps for each external org you want to access:

1. On the external Salesforce org: Create a Salesforce connected app on the external org
2. On Nintex Apps: Create a Salesforce authentication provider that uses the credentials from the connected app created in the external Salesforce org.
3. On Nintex Apps: Create a Salesforce connection—which uses the authentication provider to authenticate—to facilitate a connection to the external Salesforce org.

Best Practices

Before you start

• You must have the latest version of Nintex Apps installed in each external Salesforce org you will be accessing.
• You must have licensed Nintex Apps user credentials for each external Salesforce org you will be accessing. These user credentials must match the credentials used to pull the data; use the same Salesforce/ Nintex Apps credentials throughout this process.

Note:  Within the Salesforce universe, the term " Nintex Apps license" refers to a user's ability to interact with Nintex Apps. While the Nintex Apps UI reflects this terminology to avoid confusion, the "number of Nintex Apps licenses" you have refers to purchased Nintex Apps subscriptions.

• My Domain must be enabled on any Salesforce Org you will be accessing. While the org's instance-based URL (e.g. https://na30.salesforce.com/ ) will technically work, using it is not recommended since this URL is subject to change when Salesforce performs instance migrations. My Domain is free and available on all Salesforce orgs that can run Nintex Apps. Configure your org's My Domain settings by navigating to Setup > Domain Management > My Domain. To learn more, see Salesforce's My Domain documentation.
• Nintex Apps models and pages can not be retrieved using this connector. If you wish to use pages across orgs, you'll need to recreate the pages, use Page Packs, or use skuid-grunt (a developer tool for distributing Nintex Apps pages). These step are not necessary for your Salesforce connections to work.

A few caveats

• Salesforce permissions are retained in all connection; an end user can only see and edit data they have access to in the associated orgs. Ensure that Salesforce user permissions are appropriately set in each external org being accessed.
• If two people are simultaneously editing an external Salesforce org's data, the last edit wins.

Important:  To prevent errors, do not set up multiple connections pointing to the same external Salesforce org while within your current Salesforce org.

Configuration

In the external Salesforce org

Set up a Salesforce connected app

To connect to an external Salesforce org using OAuth (or any other method), you need to create a connected app within that org that functions as a configurable gateway to your data. You'll need to do this only once.

If you have already configured a connected app, you may use that one if its settings match those listed below. If so, proceed to Create the authentication provider.

Note:  To connect to multiple Salesforce orgs, repeat the steps below for each external org.

Create a Connected App:

1. In your external Salesforce org, from the Salesforce Setup pane, navigate to Build > Create > Apps.

2. Under Connected Apps, click New.

3. In the New Connected App page, enter the app's basic information:

   • A unique Connected App Name.
   • A Contact Email.

4. Check Enable OAuth Settings. Once you've done this, additional fields appear:

   • Be sure that your callback URL points to the Nintex Apps Site that will be accessing the data. See the Callback URLs section below.

   Note:  If you'll be accessing this external Salesforce org from multiple instances of Nintex Apps, enter each Nintex Apps site callback URL on a new line, without commas.

   • Selected OAuth Scopes: Click and add the following OAuth scopes to facilitate Nintex Apps interacting with the Salesforce external org's data:
     • Access and manage your data (api): While appearing as a sort of "belt-and-suspenders" approach, including the api scope in addition to the full scope is recommended to avoid OAuth scope errors.
     • Perform requests on your behalf at any time (refresh_token, offline_access): This scope allows end users to login to the org once, as opposed to every several minutes.

5. Click Save.

Note:  It may take a few minutes for Salesforce to create the app.

Callback URLs

Callback URLs tell the connected app in the external Salesforce org where in Nintex Apps to send data. Because of this, the callback URL listed in the external org connected app should point to your Nintex Apps site. Without the proper callback URL, the external org cannot send data to the proper location.

See the examples for your platform of choice below:

For Nintex Apps sites, append /auth/oauth/callback to your Nintex Apps site's domain URL.

Some examples:

• For https://example-us-trial.skuidsite.com/, use https://example-us-trial.skuidsite.com/auth/oauth/callback
• For https://gui-construction.skuidsite.com/, use https://gui-construction.skuidsite.com/auth/oauth/callback
• For https://asgard-talent-management.skuidsite.com/, use https://asgard-talent-management.skuidsite.com/auth/oauth/callback

User access settings

With the connected app configured, you must now grant the appropriate end users access.

If you wish to grant access to all end users:

1. In the Salesforce sidebar, click Manage Apps > Connected Apps.
2. Click the master label of the connected app.
3. Click Edit Policies.
4. Set the Permitted Users field to All users may self-authorize.

If you wish to specify the end users who will be accessing data through the connected app, give them the following permissions:

• Assign users the Connect to this org's data using Nintex Apps permission set:

  1. Navigate to Manage Users > Permission Sets > Connect to this Salesforce org's data using Nintex Apps.

     Note:  This permission set's API name is Connect_to_this_Salesforce_orgs_data_using_Skuid .

  2. Click Manage Assignments.

  3. Click Add Assignments.

  4. Select the appropriate users.

  5. Click Assign.

• Ensure users are API Enabled, either through their profiles or a permission set.

  • Profiles

    Note:  You cannot update the administrative permissions for standard profiles. If you do not wish to use custom or cloned profiles, the use of permission sets is recommended.

    1. Navigate to Manage Users > Profiles.
    2. Click Edit beside the profile that requires access.
    3. Check the API Enabled box under the Administrative Permissions pane.
    4. Click Save.

  • Permission sets

    First, create a permission set with the API Enabled setting.

    1. Navigate to Manage Users > Permission Sets.
    2. Click New.
    3. Enter an appropriate label for the permission set, such as API Enabled.
       • The API Name field will be generated from the label.
    4. (Optional) Add a description for the permission set.
    5. (Optional) If you are certain that only a specific license type will be accessing data through the connected app, you may select that in the License field. Otherwise, leave the value as --None--.
    6. Click Save.
    7. Click System Permissions.
    8. Click Edit.
    9. Check the API Enabled box.
    10. Click Save.

    With the permission set configured, assign it to all appropriate end users. If you have not assigned permission sets before, please refer to Salesforce's documentation.

• Finally, grant end users access to the connected app itself either through their profiles or a permission set.

  • Profiles

    1. Navigate to Create > Apps.
    2. Click Manage beside the connected app.
    3. Click Manage Profiles in the Profiles pane.
    4. Select which profiles should have connected app access.
    5. Click Save.

  • Permission sets

    First, create the permission set for the connected app.

    1. Navigate to Manage Users > Permission Sets.
    2. Click New.
    3. Enter an appropriate label for the permission set.
       • The API Name field will be generated from the label.
    4. (Optional) Add a description for the permission set.
    5. (Optional) If you are certain that only a specific license type will be accessing data through the connected app, you may select that in the License field. Otherwise, leave the value as --None--.
    6. Click Save.
    7. Click Assigned Connected Apps.
    8. Click Edit.
    9. Click the connected app you've created to select it.
    10. Click Add fa-caret-right to assign the connected app to the permission set.
    11. Click Save.

    With the permission set configured, assign it to all appropriate end users. If you have not assigned permission sets before, please refer to Salesforce's documentation.

Credentials

With the settings saved, retrieve the credentials needed for a Nintex Apps authentication provider.

1. From Salesforce Setup pane, navigate to Build > Create > Apps.
2. Under Connected Apps, click the app you just created.
3. Under API (Enable OAuth Settings), find:
   • The consumer key
   • The consumer secret (click to reveal)

If you need to find these later, navigate in Salesforce's Setup pane to Build > Create > Apps, and open the connected app's page.

In Nintex Apps site

With the connected app setup in the external Salesforce org, you've completed all the external configuration. All that's left is creating an authentication provider and connection within your Nintex Apps site.

Note:  As above, you'll need to complete these steps for each external org you connect to.

Create the authentication provider

1. Navigate to Configure > Connections > Authentication Providers.
2. Click New Authentication Provider.
3. Fill out the necessary fields:

• Name: Enter a unique name, such as SalesforceAuth.

Note:  If using more than one org, for the sake of clarity, make sure this identifier also indicates which org is being accessed.

• Authentication Method: OAuth 2.0/OpenID
• Provider Type: Salesforce
• Grant type: Select Authorization code if you would like end users to authenticate using their own Salesforce org credentials.

Note:  You can also share or use credentials stored within Nintex Apps, which we'll cover below.

• Authorize Endpoint URL & Token Endpoint URL: Enter the org's My Domain for the external Salesforce org in the appropriate area. For example, if your Salesforce external org's My Domain is "externalorg-dev-ed," then the endpoint URLs would be:

• https://externalorg-dev-ed.my.salesforce.com/services/oauth2/authorize
• https://externalorg-dev-ed.my.salesforce.com/services/oauth2/token

• Default Scopes: If not auto-populated, insert the following:

• API,refresh_token,offline_access

  Note:  Do not add spaces.

• Client ID: Enter the connected app's consumer key.
• Client Secret: Credentials: Enter the connected app's consumer secret.

4. Click Save.
5. If Nintex Apps asks to create a Remote Site Setting, click Ok.

Create the connection

Now that your authentication provider is configured, create a data connection that uses it to authenticate to the external org.

1. Navigate to Configure > Connections > Connections.
2. Click fa-plus-circle New Connection.
3. Select the Salesforce connector.
4. Enter a unique, easily recognizable name for your connection.
5. Click Next Step.
6. Enter the My Domain name for the external org, and the Salesforce API URL will auto-populate.
7. Click Next Step.
8. Select the authentication provider you created in the previous step.
9. Click Save New Connection.
10. If Nintex Apps asks to create a Remote Site Setting, click Ok.

Share credentials or use credentials stored within Nintex Apps (Optional)

In addition to authenticating using OAuth, you may also use the Resource Owner Password Credential flow instead. While OAuth is the recommended authentication flow, this authentication method allows you to share credentials org-wide/per-profile, or use other stored credentials.

Note:  When using this grant type, you may need to relax IP restrictions in the external org's connected app.

1. Navigate to Configure > Connections > Authentication Providers.
2. Click Details fa-wrench beside your authentication provider.
3. Change the Grant Type to Resource Owner Password Credentials.
4. Navigate to Configure > Connections.
5. Click fa-sliders Advanced Settings beside your connection.
6. Select the Credential Source that fits your use case. For more information, see the Basic HTTP Authentication section of Authentication.
7. Click Save.

Note:  Each user credential entered must have a Nintex Apps subscription within the external orgs they will be accessing. If a user's account on that external org is not assigned a Nintex Apps subscription, they will not be able to access data from that org.

Update Scopes

If you are sharing credentials or using stored credentials, remove refresh_token from the scopes in both the connection and the connected app(s). Nintex Apps won't be able to get refresh tokens using this method, but receiving them is also not necessary since users will be providing credentials with each request.

Metadata Caching

Metadata explains the structure of your data to Nintex Apps. And because it's such an essential part of the data model, metadata is unlikely to change after initial set up. However, Nintex Apps must still query for metadata at every page load.

As an alternative, it is possible to cache, or save, metadata for future use instead of downloading it on each page load. Doing so can lead to noticeable performance improvements.

Enable metadata caching

1. Navigate to Configure > Connections > Connections.
2. Beside any the desired connections, click fa-cogs Configure Connection.
3. Within the connection's detail page, click Enable Metadata Cache fa-history.

With metadata caching enabled, Nintex Apps will store the metadata for that particular connection—greatly improving load times on any pages that use it.

Refresh the metadata cache

Nintex Apps cannot detect that a connection's metadata has changed—such as when a new object or field is created—and it will not automatically re-cache the metadata.

To ensure the cached metadata is up-to-date—or if you know the connection's metadata has changed recently—you'll need to refresh the cache:

1. Navigate to Configure > Connections > Connections.
2. Beside any cached connections, click Refresh Metadata fa-refresh.

Doing this will cause Nintex Apps to re-download the metadata from that connection, grabbing the most recent updates in the process.

Note:  As with enabling metadata caching, ensure that a fully permissioned user refreshes the cache in Nintex Apps. If the Nintex Apps admin does not have access to a previously cached metadata object, that object will be deleted when the cache is refreshed.

Disable metadata caching

To disable and delete Nintex Apps's metadata cache for a connection:

1. Navigate to Configure > Connections > Connections.
2. Beside the cached connections, click Disable Metadata Cache fa-chain-broken.

This will clear Nintex Apps's cache of any stored metadata. You can re-enable caching at anytime by clicking Enable Metadata Cache fa-history.

Using the Salesforce connection in Nintex Apps

When you have configured the connected app in Salesforce, as well as an authentication provider and connection in Nintex Apps, you can freely connect to the external org's data within Nintex Apps pages. To do so, select the external Salesforce org's connection for the models within Nintex Apps pages:

1. Navigate to an existing Nintex Apps page or create a new one.
2. Create a new model.
3. For Connector, select Salesforce.
4. Select the connection you configured for your external org.
5. In the Salesforce Object Name field, enter the name of the Salesforce object the model should access.

Note:  This field is only searching the selected external org —objects from your current org will not appear or be accessible from this particular model!

And with that, data from the external Salesforce org functions just like any other connection.

Model Properties

The following model properties are unique to the Salesforce connector:

• General

  • Model Behavior: Determines whether a model will function as a basic model ( the default Nintex Apps behavior) or as an aggregate model, which summarizes multiple rows of data into aggregations.

• Advanced

  • Clone data returned by Model query: When checked, all records queried by the model are cloned and treated as brand-new records. Any record updates are not applied to currently existing records, but saved as totally separate records.

    Can be useful for testing but not typically recommended for production applications or mission-critical data.

  • Query Deleted / Archived records: Overrides the standard functionality of the Deleted and Archive features of Salesforce objects to retrieve all records, including those that have been deleted or archived. This option adds the "ALL ROWS" clause to a SOQL query submitted by the model. By default, this clause is not added to the query.

  • Update Salesforce "Recently Viewed" info: When checked, the LastViewedDate field will be updated whenever a record is changed within the model, meaning the record will show in the Recently Viewed or Recent Items sidebar on a typical Salesforce page.

  • Auto-sync with other Lightning Components: When checked, the model will send out and respond to events that update Salesforce data. This automatic synchronization works between models on app pages in the Skuid Page component and standard Lightning components.

Using File Upload with the Salesforce connection

The File Upload component has specific properties that are only available when used with a Salesforce connector.

Salesforce currency field support

• Parenthetical Currency Conversion is supported within Nintex Apps.

• Advanced Currency Management (ACM): Nintex Apps does support data entry while ACM is enabled within an org, and entered data will be converted to the org's base currency. However Nintex Apps cannot display existing opportunity amounts using dated exchange rate rules at runtime., Nintex Apps uses the first conversion rate available for a currency.

  If you choose to enable this feature be aware that users may see conflicting historical data that does not match what resides in the database.

Salesforce date functions

Nintex Apps models on Salesforce objects with date/time fields use Salesforce's own date function logic in areas like model conditions.

Connector actions

Use connector actions to add more functionality to applications. Nintex Apps supports both standard Salesforce invocable actions and custom actions (which depend on the existence of custom metadata in the Salesforce org). Nintex Apps also provides Nintex Apps -defined options (such as some of the Approval Process actions) for additional customization.

Note:  Each time a Salesforce connector action is called, a Salesforce API call is made—even when using Nintex Apps for Salesforce in the same org. If API usage limits are a concern for your org, balance the use of these action types and the API limits of your org. For information on API usage limits, see the Salesforce Developer Limits Quick Reference.

The Salesforce connector includes the following connector actions.

Standard actions

• Post to Chatter: Posts a message at runtime to a specified Chatter feed.

• Enable Folder Support for Content Workspace (Library): Enables folders in SF Content library.

  Note:  To use this action, you must have the ID for a ContentWorkspace on Sales-Cloud.

• Send Email: Sends an email in which you specify the recipients, sender, subject, and body.

Depending upon which release your org is using, you may have access to other Salesforce actions. See Salesforce's Invocable Actions for more information.

Custom actions

Important:  There must be custom metadata in the Salesforce org for Custom Salesforce connector actions to function.

• Apex: Invokes Apex methods within Nintex Apps.

  Note:  To be used with this action type, Apex code must contain InvocableMethods, as well as InvocableVariables for fields within those methods.

• Flow: Invokes an active auto launched flow or invocable process. (This flow or process must already exist within the org.) The flow action allows Salesforce Administrators to declaratively develop invocable processes.

• Email Alert: Sends emails from flows by reusing pre-configured workflow email alerts.

• Quick Action: Creates a task or case; can be used to create or update records or log calls.

• Load All Remaining Records: Loads all remaining records for a model's object by querying in batches.

  • Batch Size: The number of records to query for in each batch. Should be a low enough number to avoid hitting query limits.
  • Step Message: The message displayed while Nintex Apps queries each batch. Several merge variables can be used denote progress in this message property.
  • Finish Message: The message displayed after Nintex Apps has queried all records for the model. Several merge variables can be used denote progress in this message property.
  • Cancel Model Changes: Determines whether or not any unsaved changes are discarded once the action begins.

• Send HTML Email: Sends an email in which you specify the recipients, sender, subject, and plain text or HTML body.

Approval Process actions

Note:  For the connector actions below, an Approval Process must be defined for the object.

• Submit for Approval: Submits a Salesforce record for approval.

• Approve: Approves a submitted record. (Only an assigned approver or a Salesforce admin can approve a record.)

• Reject: Rejects a record that has been submitted for approval. (Only an assigned approver or a Salesforce admin can reject a record.)

• Recall: Recalls a record that has been submitted for approval. (Only the submitter or a Salesforce admin can recall a record.)

• Unlock Record: Unlocks a record for editing after the record has been submitted for approval. (Only Salesforce admin can unlock a record.)

  Note:  When records are submitted for approval, they are locked for edits. The Unlock action allows a record to be edited while in the approval process.

  Important:  To use the Unlock action, record locking/unlocking must be enabled in the Salesforce org.

Using the Apex action

All properly-annotated invocable methods will appear within the Apex Action field picklist; the first method that Nintex Apps detects will likely be selected automatically. If you do not see your method, try refreshing the Page Designer.

As with other Nintex Apps fields, invocable variables can point to various fields with the use of merge syntax.

Note:  Only authenticated Salesforce end users may access invocable methods and run Apex actions. Using this action type within a Nintex Apps page on a public-facing Force.com site or community is not recommended, as guest users will not have the permissions for proper functionality.

Merge variables for Apex action information

There are two merge variables unique to the Apex action that allow you to utilize information returned by current and previous actions.

{{$CurrentAction.error}} displays any error message returned by the current Apex action as a string. This error message may not display within Nintex Apps, so it can be helpful to use this merge variable in an on-error action, perhaps in a Show message and block UI action.

$PreviousAction is used for retrieving information from a previous Apex action in the current script of actions. Apex actions typically output a list of objects, and Nintex Apps can retrieve data from the first object in that list with {{$PreviousAction.result.variableName}} . Some examples include:

• An Apex class returns a custom Apex object type with a message invocable variable defined. That invocable variable could be accessed on the first object with {{$PreviousAction.result.message}} .
• An Apex class returns a list of sObjects. The first sObject's fields can be accessed with {{$PreviousAction.result.<fieldApiName>}} , where <fieldApiName> represents the field's name as expected by Salesforce's SOAP API. So {{$PreviousAction.result.FirstName}} could be used retrieve the First Name field of a Contact record returned by Apex.

Note:  Keep in mind that even though an Apex class may return a list of custom Apex objects or a list of sObjects, only the first object is accessible from this merge variable.

Because this merge variable depends entirely on the context of a previous action, it should only be used in a script of actions after an Apex action. If there is more than one Apex action in the script, $PreviousAction will display results from the most recent Apex action.

Using $PreviousAction requires knowledge of what Apex is returning. Because of this, it can be helpful to see what Nintex Apps receives at runtime:

1. Preview the Nintex Apps page.
2. Open the Network inspector within your browser of choice:
   • Chrome
   • Firefox
   • Safari
   • Edge
   • Opera
3. Initiate the Apex action.
4. Click the network request for the Apex action. The request will typically be named after the Apex class containing the invocable method.
5. Preview the network response.
6. Investigate the outputValues node to see what Nintex Apps receives. You can use each of these fields with $PreviousAction .

Merge variables for Load All Remaining Records

The following merge variables may be used within the message properties of the Load All Remaining Records action to illustrate the progress of the action.

• $CurrentAction.nextStartRecord : States the first record in the range of the current batch. E.g., if Nintex Apps is working through its second batch of 50 records at a time, this value would be 51.
• $CurrentAction.nextFinishRecord : States the last record in the range of the current batch. E.g., if Nintex Apps is working through its second batch of 50 records at a time, this value would be 100.
• $CurrentAction.totalRecords : States the total amount of records loaded by a Load All Records action. Can only be used in the Finish Message property.

More about Salesforce connector actions

For more information on using these connector actions, visit the Force.com REST API Developer Guide Invocable Actions and Introducing Actions sections, or review the Force.com Actions Developer Guide.

If your connector actions do not seem to be working see this troubleshooting section.

Troubleshooting