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 and update your B2B and B2C customers

• Grant and update licenses for one-time orders

• Grant and update 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.

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.

See how to set up the custom license grant object in Salesforce.

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.

Optionally, you can configure customer creation in 10Duke Enterprise to only be triggered for certain Salesforce account types. This enables you to, for example, create a Salesforce account for a potential lead already early on, but delay the customer creation in 10Duke Enterprise to the point when the customer relationship has been established.

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.

• If the account type configuration is in use, select a suitable account type for the customer.

  • If the selected account type is included in the configuration, the customer is created in 10Duke Enterprise.

  • If you select any other account type, customer creation is triggered later when you update the account to use one of the configured account type values.

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

Update an account

When an account is updated in Salesforce, Salesforce sends update events that can trigger the following actions in 10Duke Enterprise:

• If the optional account type configuration is in use, the update can trigger the first-time creation of the customer in 10Duke Enterprise (see more on account creation).

  This happens if customer creation hasn’t been triggered yet for the Salesforce account, and you change the account to use one of the configured account type values.

  Important: While the account only exists in Salesforce, you can modify the account data there as needed. The only exception is that when customer creation is later triggered in 10Duke Enterprise, the user account created in 10Duke Enterprise will always use the contact that was initially created for the account in Salesforce, and more importantly, it will use the email address that contact was initially created with.

  To prevent the future invitation from being sent to the wrong person, we recommend that you create a new account with the new contact email address, instead of changing the email address in Salesforce, or deleting the initial contact from the account and adding a new one.

  Otherwise, to prevent the wrong person from accessing the customer’s licenses and accessing OrgAdmin, you can delete the invitation in SysAdmin before it’s accepted, or delete the user’s account, or just remove the user’s access to the organization’s licenses and their OrgAdmin administrator role.

• After a B2B customer has been created in 10Duke Enterprise, updating the account name in Salesforce updates the organization’s name in 10Duke Enterprise. Changes to the other organization details and to the B2B administrator’s user account are not supported.

  No updates are supported for B2C customers.

  If the account type configuration is in use, it’s good to note that changing the account type back to a value that is not included in the configuration doesn’t revert the customer creation in 10Duke Enterprise. Changes to the account type are ignored by the integration at this stage.

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.

Update licenses

When a license grant for a one-time order or a subscription is updated for a registered customer in Salesforce, Salesforce sends update events that trigger the following actions in 10Duke Enterprise:

• The existing licenses are updated.

• If the name of the product package included in the received event has changed, new licenses are granted to the customer (a B2C user or a B2B organization) that are valid until the new end date.

  Like when granting licenses, the event specifies the products to be used for granting them.

  This may result in a different set of licenses than at the time of the order creation. This may happen if the Salesforce products specified in the order are different, or if the licensed items included in the 10Duke Enterprise product packages have changed.

Note: When the licenses are granted through the Graph API new licenses are granted to the customer (a B2C user or a B2B organization) that are valid until the end of the new subscription period, and the old licenses are deleted. If there were seat reservations for the old licenses, those are also deleted.

Updating a license grant requires providing the same information in Salesforce as when granting licenses.

Note the following:

• This information on license updates only applies to orders that have been activated. If you haven’t activated your draft order yet, you can make any changes in Salesforce as needed, as licenses have not yet been created in 10Duke Enterprise.

• You cannot add any new license grants to the order. However, if you change Product Code to point to another product package, you effectively replace the old licenses with new licenses for the other product.

• We recommend that you don’t edit the order itself, nor change its status back to “draft”. Changing the order or its status has no effect on the licenses in 10Duke Enterprise, and your information in the two systems won’t be in sync.

• As a general rule, we also recommend that you don’t change the start date for a license grant, as this has no effect on licenses in 10Duke Enterprise. The only use case where you can change it is when changing also Product Code, in which case it will be used as a start date for the new licenses created with the new product package.

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 an update to the validity of the licenses associated with the license grant in 10Duke Enterprise. The valid until date is set to the current instant (now) making the licenses invalid with immediate effect.

In the same way, if you delete the whole order in Salesforce, Salesforce sends a delete event that triggers an update to the validity of all the licenses associated with the order’s license grants in 10Duke Enterprise. The valid until date is set to the current instant (now) making all the licenses invalid with immediate effect.

Note: If you delete a license grant from an order (a one-time order or a subscription) or the whole order in Salesforce, and the licenses are granted through the Graph API, the delete event triggers the deletion of the licenses associated with the license grant or 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 customer details in 10Duke Enterprise apart from the B2B account (organization) name 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.

• With B2B customers’ subscriptions, take into account that if you move granted licenses to other entitlements, updating a subscription’s licenses may affect how the organization’s users and devices can access those licenses in 10Duke Enterprise. See more information on authorizing access to licenses.

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.

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.

If users with other user profiles than the Salesforce administrator profile need to work with license grants, make sure those user profiles have access to viewing and managing the custom object.

• In the user profile’s setup, make sure that:

  • In custom tab settings, the profile has access to the license grant tab.

  • In custom object permissions, the profile has read, create, edit, and delete permissions to the license grant.

  • In general user permissions, the profile has the activate orders and activate contracts permissions.

• In the object manager in the license grant object, go to fields & relationships and field-level security settings, and make sure the optional EndDate field is visible to the user profile.

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)

Setup in 10Duke Enterprise

After all the setup steps in Salesforce have been completed, the 10Duke Integration Support team will help to complete the setup at the 10Duke Enterprise end and activate connectivity between Salesforce and 10Duke Enterprise.

The setup 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 SysAdmin, and setting up the account type configuration if needed (see below).

Account type configuration

With the optional account type configuration, you can limit customer creation in 10Duke Enterprise to only be triggered for certain Salesforce account types.

Provide the 10Duke Integration Support team with the Salesforce Account Type values that should trigger customer creation.

When the configuration is in place, creating an account in Salesforce with any other account type value will not trigger the customer to be created in 10Duke Enterprise.

Only when you change the account type in Salesforce to one of the configured values, B2C or B2B customer creation is triggered in 10Duke Enterprise as described in account creation.