Connect to Salesforce

This article provides instructions on the steps required from you (the vendor), when you’re integrating 10Duke Enterprise with Salesforce using Salesforce Change Data Capture events in combination with a Salesforce connected app. See information on Change Data Capture events and connected apps in Salesforce’s documentation.

When you create customers and orders (one-time orders or subscriptions) in the Salesforce UI, Salesforce generates and sends events to 10Duke Enterprise to trigger actions accordingly.

The following actions are supported:

  • Set up your B2B and B2C customers

  • Grant licenses for one-time orders

  • Grant licenses for subscriptions

  • Delete licenses

The integration requires an optional 10Duke Integration Service component that is purchased separately.

Contact the 10Duke Integration Support team to get started with the integration and get support with the setup needed in Salesforce.

The integration also requires setup and configurations at the 10Duke Enterprise end, which are handled by the 10Duke Integration Support team. This includes enabling the Integration Service component for your deployment, and defining the connection between the component and 10Duke Enterprise as an OAuth client application, which you will see in the 10Duke SysAdmin tool.

Custom license grant object

The integration requires the implementation of a custom “license grant” object in Salesforce, which will hold the information for granting licenses for both one-time orders and subscriptions.

A custom license grant object contains information on a single product package to be used for granting licenses. One or more license grants can be associated with the standard Salesforce object Order, which can be a one-time order or a subscription.

Contact the 10Duke Integration Support team to set up the custom license grant object.

Supported actions

When you create accounts and orders in the Salesforce UI, Salesforce sends Change Data Capture events for the created objects (such as an Account or Order object), which then trigger actions in 10Duke Enterprise.

See the following sections for information on the supported actions.

Create an account

When an account is created for a customer in Salesforce, Salesforce sends create events that trigger the following actions in 10Duke Enterprise:

  • For a B2C customer, this creates a user account.

  • For a B2B customer, this creates:

    • A new organization in 10Duke Enterprise.

    • A user account for the organization’s first administrator, with access to the 10Duke OrgAdmin tool (if you’re providing it for your B2B customers).

    • A default entitlement to hold the organization’s licenses.

    • An “employees” user group where the first administrator user is added, and which is granted access to the default entitlement.

  • For both customer types, an email is sent to the created user, who needs to activate their user account by setting a password.

In Salesforce, make sure to enter all the information required by the integration.

  • When you start creating an account in Salesforce, first select whether the account is for a B2C (person) or B2B customer.

  • For a B2B customer:

    • Provide an account name. This is set as the name of the organization in 10Duke Enterprise.

    • Create a contact and link it to the account. Enter the contact’s first name, last name, and email address: these are set as the name and email address of the B2B customer organization’s first administrator user in 10Duke Enterprise. The email address must be unique across users in 10Duke Enterprise.

  • For a B2C customer, enter the customer’s first name, last name, and email address. These are set as the name and email address of the B2C customer’s user account in 10Duke Enterprise. The email address must be unique across users in 10Duke Enterprise.

See detailed information in Salesforce’s documentation on creating records (in this case an account and a contact). See also guidelines for creating accounts.

If needed, you can update a B2B account’s name in Salesforce, and the new organization name is updated to 10Duke Enterprise.

Grant licenses

When an order (a one-time order or a subscription) is created for a registered customer in Salesforce, Salesforce sends create events that trigger the following actions in 10Duke Enterprise:

  • New licenses are granted to the customer (a B2C user or a B2B organization).

    The event specifies one or more Salesforce products, which map to 10Duke Enterprise product packages that are used for granting the licenses.

  • For a B2C customer, granting licenses also automatically creates an entitlement if they don’t have one yet.

  • For a B2B customer, the licenses are always created in the organization’s default entitlement.

In Salesforce, make sure to enter all the information required by the integration.

  1. Create an order in Salesforce for the appropriate customer account. Make sure to keep the order in “draft” status.

    (To be able to proceed, the Salesforce UI requires you to define a product and a quantity. These settings are not used by the integration.)

  2. In the order, add the license grants.

    For each license grant, define the data needed by the integration:

    • Order: If you’re creating the license grant within the order, the order ID is prefilled here. Otherwise select the correct order.

    • Subscription (optional): A Salesforce-specific identifier, only supported in Salesforce CPQ. If this field is included, the license grant is considered as a subscription, and otherwise as a one-time order.

    • Product Code: The name of the product package in 10Duke Enterprise that is used for granting the licenses.

    • Quantity: The number of product packages used to grant licenses, used for calculating the final license credit. This number is effectively a multiplier for the credit amount defined for the licensed item in the product package.

    • Start Date: The start date of the license validity.

    • End Date (optional): The end date of the license validity. An empty value means granting perpetual licenses.

  3. When you have defined all the necessary license grant objects, you can change the order status to “activated”.

After completing an order, don’t change it back to status “draft” nor add any new license grants.

See Salesforce’s documentation for guidelines on creating orders.

Delete licenses

If you delete a license grant from an order (a one-time order or a subscription) in Salesforce, Salesforce sends a delete event that triggers the deletion of the licenses associated with the license grant in 10Duke Enterprise.

In the same way, if you delete the whole order in Salesforce, Salesforce sends a delete event that triggers the deletion of all the licenses associated with the order’s license grants in 10Duke Enterprise.

See detailed information in Salesforce’s documentation on order management and deleting orders.

Limitations

  • Granting and managing licenses for subscriptions is only supported with Salesforce CPQ.

  • The integration only supports granting seat-based licenses.

  • Updates to customers apart from the account (organization) name are not supported.

  • Updates to licenses are not supported.

  • You can only grant licenses to Salesforce accounts that have been created as customers (users or organizations) in 10Duke Enterprise through the integration. If the Salesforce account was created before the integration, or the user or organization was created in 10Duke Enterprise using some other means, licenses cannot be granted for that account through the integration.

  • The transaction-based SysAdmin features cannot be used together with the Salesforce integration, which doesn’t create transactions for the licenses. Contact the 10Duke Integration Support team to make sure the legacy UI that doesn’t use transactions is enabled in your deployment.

Requirements

  • Support for customer creation and granting licenses to B2C customers requires that person accounts are enabled in Salesforce. See instructions on enabling person accounts in Salesforce’s documentation.

  • In your Salesforce B2B customer creation flow, make sure you first create the account and then add the contact for it. If you link an existing contact to the account, the customer won’t be created in 10Duke Enterprise.

  • Make sure that in your Salesforce order fulfillment flow (for a one-time order or a subscription), you add the necessary license grants to an order before changing the order status from “draft” to “activated”. After completing an order, don’t change it back to status “draft” nor add any new license grants.

Setup in Salesforce

Complete the steps below for the integration setup in Salesforce.

After all the setup steps have been completed, the 10Duke Integration Support team can support with completing the setup at the 10Duke Enterprise end, and activate connectivity between Salesforce and 10Duke Enterprise.

Step 1: Edit Salesforce CPQ settings

If you’re using Salesforce CPQ and need support for subscriptions in your integration, enable the settings required by the integration. Otherwise you can ignore this step.

  1. Go to the Salesforce setup and the installed packages.

  2. Edit the following Salesforce CPQ configurations:

    • In the line editor settings, enable “validate large quotes”.

    • In the quote settings, enable “primary quote keeps opportunity products”.

    • In the subscriptions and renewals settings, enable “legacy amend/renew service”.

See detailed information on CPQ package settings in Salesforce’s documentation.

Step 2: Create the custom license grant object

Create the custom license grant object in Salesforce.

To facilitate this step, 10Duke provides a spreadsheet (.xlsx) for importing the object with the 10Duke-specific fields. Contact the 10Duke Integration Support team to get the spreadsheet.

  1. Go to the Salesforce setup and the object manager.

  2. First, create the new custom object.

    1. Use the option to create a custom object using a spreadsheet. Log in when prompted, and upload the spreadsheet.

    2. In the worksheet details, use the following settings:

      • In field label source, select to detect from row.

      • Set field labels row to 1.

      • In record name field, let Salesforce create a default record name.

      Note: Make sure to select the “No, skip import” option so that the data in the fields is not imported.

    3. Next, edit the object properties.

      • We recommend that you change the labels to an easily readable form: License Grant and License Grants.

        Note: Do not change the API name, it’s used by the integration.

      • Make sure all the advanced settings are enabled.

    4. Finish the creation of the object. Processing the new custom object may take a while.

    At this point, the custom object contains the 10Duke-specific fields LicenseGrant, StartDate, EndDate, ProductCode, and Quantity, and some automatically added fields.

    You still need to add a few Salesforce-specific fields required by the integration.

  3. Go back to the object manager, open the new license grant object, and go to fields & relationships.

  4. Edit the 10Duke-specific fields.

    • Change the record name from LicenseGrant to Name.

    • For StartDate, ProductCode, and Quantity, make sure that “always require a value in this field in order to save a record” is set to required. The integration requires that these fields are always filled in for a license grant. EndDate is an optional field.

      We also recommend that you edit the UI labels to an easily readable form: Start Date, End Date, and Product Code.

      Note: Do not change the field names, they are used by the integration.

  5. Add the following Salesforce-specific custom fields to the object.

    These are the settings required by the integration:

    • Order:

      • Set data type to “master-detail relationship” and set the related object to Order.

      • Set both the field label and name to Order.

      • Set the sharing setting to read-write.

      • Leave the other settings to the default values.

    • Subscription (only available in Salesforce CPQ):

      • Set data type to “lookup relationship” and set the related object to Subscription.

      • Set both the field label and name to Subscription.

      • Leave the other settings to the default values.

    • QuoteLine (only available in Salesforce CPQ):

      • Set data type to “lookup relationship” and set the related object to Quote Line.

      • Set the field label to Quote Line and the field name to QuoteLine.

      • Leave the other settings to the default values.

  6. Go back to the object manager, open the new license grant object, and go to validation rules.

  7. Create validations rules for the StartDate and EndDate fields with the following settings:

    • For the StartDate validation rule:

      • Set the rule name to StartDate.

      • Set the rule to active.

      • Use this error condition formula: TODAY()-1 >= StartDate__c

      • Use this error message: The start date must be set to the current date or later.

      • Set the error location to the top of the page.

    • For the EndDate validation rule:

      • Set the rule name to EndDate.

      • Set the rule to active.

      • Use this error condition formula: StartDate__c-1 >= EndDate__c

      • Use this error message: If provided, the end date cannot be earlier than the start date.

      • Set the error location to the top of the page.

Now the custom license grant object is ready for the integration. The license grant tab should be displayed when you’re creating a new order or subscription.

It may take a while for Salesforce to process the changes. If the Salesforce UI doesn’t show the license grant object after 10 minutes, contact the 10Duke Integration Support team for help.

See detailed information on creating custom objects in Salesforce’s documentation.

Step 3: Create a connected app

Create a connected app in Salesforce to connect Salesforce to the 10Duke Enterprise. This enables the Integration Service component to subscribe to Change Data Capture events sent by Salesforce. The connected app type must be an OAuth client that uses the client credentials flow.

To create the connected app:

  1. Go to the Salesforce setup and the app manager.

  2. Create a new connected app.

    The following steps highlight the settings required by the integration.

  3. In the basic information:

    • Set the API name to tenduke_connected_app.

    • Set the contact email to your Salesforce administrator’s email address. The verification code that you need in the later steps will be sent to this email address.

  4. Enable the OAuth settings.

  5. Set the callback URL to https://eu-west-1.console.aws.amazon.com/appflow/oauth.

  6. Select the Oauth scopes required by the integration:

    • Access custom permissions (custom_permissions)

    • Access the identity URL service (id, profile, email, address, phone)

    • Access unique user identities (openid)

    • Manage user data through APIs (api)

    • Perform requests at any time (refresh_token, offline_access)

  7. Disable the PKCE extension for supported authorization flows.

  8. Enable the following:

    • Require secret for web server flow

    • Enable client credentials flow

    • Enable authorization code and credentials flow

After saving the settings for the new connected app, it may take a while for Salesforce to process and create it.

See detailed information on creating a connected app in Salesforce’s documentation.

Step 4: Copy the consumer key and secret

Copy the consumer key and consumer secret that Salesforce automatically created for your new connected app:

  1. Still in the app manager, open the new connected app’s details.

  2. In consumer key and secret, click to manage the consumer details of the connected app.

    This sends a verification code email to the email address that you defined for the connected app.

  3. Use the verification code in the email to verify your identity to Salesforce and access the consumer details.

  4. In the consumer details of the connected app, copy the consumer key and consumer secret.

See detailed information on managing consumer details in Salesforce’s documentation.

Provide the consumer key and secret to the 10Duke Integration Support team. Make sure to use a secure method to communicate this, such as GNU Privacy Guard (GPG) encryption.

Note: To keep the integration working, we recommend that you don’t rotate the consumer key and secret of the connected app in Salesforce.

If the consumer key and secret are changed, you must repeat this step 4 as a whole.

Step 5: Enable the events sent to 10Duke Enterprise

Enable the Change Data Capture events that Salesforce must send to 10Duke Enterprise for the integration.

  1. Go to the Salesforce setup and Change Data Capture settings.

  2. In the available entities, make sure the following are selected:

    • Order (Order)

    • Account (Account)

    • Contact (Contact)

    • LicenseGrant (LicenseGrant__c)

    • Subscription (SBQQ__Subscription__c)

On this page