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 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.
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.
-
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.)
-
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.
-
-
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 customer details in 10Duke Enterprise apart from the B2B 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.
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.
-
Go to the Salesforce setup and the installed packages.
-
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.
-
Go to the Salesforce setup and the object manager.
-
First, create the new custom object.
-
Use the option to create a custom object using a spreadsheet. Log in when prompted, and upload the spreadsheet.
-
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.
-
-
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.
-
-
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
, andQuantity
, and some automatically added fields.You still need to add a few Salesforce-specific fields required by the integration.
-
-
Go back to the object manager, open the new license grant object, and go to fields & relationships.
-
Edit the 10Duke-specific fields.
-
Change the record name from
LicenseGrant
toName
. -
For
StartDate
,ProductCode
, andQuantity
, 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.
-
-
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 toQuoteLine
. -
Leave the other settings to the default values.
-
-
-
Go back to the object manager, open the new license grant object, and go to validation rules.
-
Create validations rules for the
StartDate
andEndDate
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:
-
Go to the Salesforce setup and the app manager.
-
Create a new connected app.
The following steps highlight the settings required by the integration.
-
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.
-
-
Enable the OAuth settings.
-
Set the callback URL to
https://eu-west-1.console.aws.amazon.com/appflow/oauth
. -
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
)
-
-
Disable the PKCE extension for supported authorization flows.
-
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:
-
Still in the app manager, open the new connected app’s details.
-
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.
-
Use the verification code in the email to verify your identity to Salesforce and access the consumer details.
-
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.
-
Go to the Salesforce setup and Change Data Capture settings.
-
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.