Connect to Salesforce

This article provides instructions on the steps required from you (the vendor), when you’re integrating 10Duke Scale 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 Scale to trigger actions accordingly.

The following actions are supported:

Set up 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 10Duke 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 Scale end, which are handled by 10Duke.

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 configuration 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 Scale.

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 Scale:

A customer is created, and a default license container to hold the customer’s licenses.
For a B2C customer, this also creates a license consumer of type person. (Note that currently the integration only supports key-based licenses, which are consumed using a license key.)

See more information on customers, license containers, and license consumers in 10Duke Scale.

Optionally, you can configure customer creation in 10Duke Scale 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 Scale 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 customer in 10Duke Scale.
- Create a contact and link it to the account. Enter the contact’s last name and email address: the email is set as the email address of the customer in 10Duke Scale. The email address must be unique across users in 10Duke Scale. Note that you need to enter the contact’s last name in Salesforce when creating the contact, but the last name is not used in 10Duke Scale.
For a B2C customer, enter the customer’s first name, last name, and email address in their person account. These are set as the name and email address of the B2C customer’s user account in 10Duke Scale. The email address must be unique across users in 10Duke Scale.
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 Scale.
- 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 Scale:

If the optional account type configuration is in use, the update can trigger the first-time creation of the customer in 10Duke Scale (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 Scale, the user account created in 10Duke Scale 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.
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 Scale. 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 issuing of new licenses to the B2C or B2B customer in their default license container.

The event specifies one or more Salesforce products, which map to 10Duke Scale product configurations that are used for issuing the licenses.

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 configuration in 10Duke Scale that is used for granting the licenses.
- Quantity: The quantity granted in a license, if the associated configuration has license consumption set to enforced. If the quantity type is seats, the maximum quantity is 1000.
- 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.

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 Scale:

The old licenses are deleted.
New licenses that are valid until the new end date are issued.
If the name of the product configuration included in the received event has changed, new licenses are issued to the B2C or B2B customer that are valid until the new end date.

Like when granting licenses, the event specifies the product configurations to be used for issuing 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 features included in the 10Duke Scale product configurations have changed.

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 Scale.
You cannot add any new license grants to the order. However, if you change Product Code to point to another product configuration, 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 Scale, 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 Scale. 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 configuration.

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 Scale.

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 Scale.

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.
You can only grant licenses to Salesforce accounts that have been created as customers in 10Duke Scale through the integration. If the Salesforce account was created before the integration, or the customer was created in 10Duke Scale 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 license containers, updating a subscription’s licenses may affect how the customers’s license consumers can access those licenses in 10Duke Scale. See more information on granting 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 Scale.
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.

Before you start:

Download the spreadsheet (.xlsx) for importing the object with the 10Duke-specific fields:

License grant spreadsheet

To create the custom license grant object:

Go to the Salesforce setup and the object manager.
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.
5. Delete all pre-existing LicenseGrant records used as a template for creating the custom license grant object.
When the fields for the custom object have been created, you can edit the field labels by clicking on the name of the field and clicking Edit. The field names must not be changed.

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.
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 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.
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.
Go back to the object manager, open the new license grant object, and go to validation rules.
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 10Duke 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 10Duke Scale. This enables the Integration Service component to subscribe to Change Data Capture events sent by Salesforce. Your Salesforce environment needs to be subscribed to the following Change Data Capture entities: Account, Contact, Order, and License Grant. The connected app type must be an OAuth client that uses the client credentials flow.

The steps below give you an overview of how to create the connected app:

You (the vendor) will receive a certificate for the OAuth registration.
You (the vendor) will prepare the connected app and the OAuth client registration in the Salesforce account.
You (the vendor) will approve the client application by logging into Salesforce by a Salesforce user in the Salesforce account.
You (the vendor), together with 10Duke, will set up the integration connection between Salesforce and 10Duke. (10Duke recommends scheduling a short online meeting to apply the required settings during the meeting.)

When creating the connected app, use the URL https://login.salesforce.com in the production environment, and the URL https://test.salesforce.com in the sandbox environments.

Note: All the below steps must be completed by the same Salesforce user who originally creates the connected app.

Before you start:

Contact the 10Duke Support team to obtain a key pair and certificate for enabling the setup of the connected app in Salesforce. The 10Duke Support team will generate the certificate and deliver it as a file in PEM format. The file will be called for example cert.crt or prod-sf-cert.pem.

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://login.salesforce.com/services/oauth2/success for the production environment, or

https://test.salesforce.com/services/oauth2/success for the sandbox environments.
Configure the connected app to use a self-signed certificate obtained from the 10Duke Support team by uploading the certificate into the connected app.
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)
Save the settings for the new connected app. It may take up to 10 minutes for Salesforce to process them.
Once the settings have been saved, make sure that the self-signed certificate has been uploaded.
Approve the client application by navigating to the following URL in your browser:

https://login.salesforce.com/services/oauth2/authorize?response_type=token&client_id=<CLIENTID>&redirect_uri=https://login.salesforce.com/services/oauth2/success for the production environment, or

https://test.salesforce.com/services/oauth2/authorize?response_type=token&client_id=<CLIENTID>&redirect_uri=https://test.salesforce.com/services/oauth2/success for the sandbox environments.

Note: We recommend completing the this step during a meeting with the 10Duke Support team as it helps ensure the connected app is created correctly. However, experienced users may complete the step independently.
Provide the following information to the 10Duke Support team for setting up the integration connection between Salesforce and 10Duke:
- Salesforce instance URL
- Issuer (CLIENT_ID_FROM_SALESFORCE)
- Subject (EMAIL_OF_SALESFORCE_USER_THAT_MADE_THE_APPROVAL_TO_CLIENT_APP)
  
  Note: The production and sandbox environments can use different emails. Ensure you use the correct email for each environment when you configure the contact for the OAuth application and the integration connection setup.
- Audience (https://login.salesforce.com for the production environment, or https://test.salesforce.com for the sandbox environments)

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

Setup in 10Duke Scale

Set up API keys for authorizing the Integration Service component to connect to the 10Duke Scale APIs: store the public API key in 10Duke Scale and provide the corresponding private key to 10Duke.

We recommend that you generate a new API key pair for the integration.

When storing the public API key in the UI console, note the following:

In Default key use, select Verify Scale JWT.
In Key ID, we recommend that you use a value that makes it easy to later identify where this API key is used. You could, for example, include a prefix such as “salesforce-integration” in front of the ID.

Provide the private key from the key pair to 10Duke. Make sure to use a secure method to communicate it, such as GNU Privacy Guard (GPG) encryption.

After all the setup steps have been completed, 10Duke can enable the integration in 10Duke Scale.

Account type configuration

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

Provide the 10Duke 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 Scale.

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