Salesforce Commerce Cloud

This guide is intended for Salesforce Commerce Cloud merchants who are connecting their store to Violet. During the connection process, the merchant will configure their store to connect it to Violet. Total time for completion is around 20 minutes.

​

Create API Client for OCAPI

From the account manager you will create and configured a new API Client for use by Violet. You can learn more about API Clients in the Salesforce Commerce Cloud documentation. The API Client should be created while you are logged into the account who’s email address you will be sharing with Violet.

1. Navigate to the Account Manager and sign in. The email address used to sign in is the Account Manager Email Address value in Violet Connect.

2. From the left sidebar menu click API Client.

3. Click the Add API Client button.

4. Enter a display name that will help you identify this API client with Violet.

5. Enter a secure password. This is the OCAPI Client Password value in Violet Connect.

6. Ensure that Access Control is Enabled.

7. Add your organization to the client.

8. If you are testing with a Sandbox store follow these steps:

   a. Search for the Sandbox API User role and select the role.

   b. To assign the role to the API client, click Add.

   c. Select the filter icon to specify the role scope.

   d. In the Add Instance Filters tab, select your organization.

   e. Enter the names of the instances to which you want the API client to have access.

   f. Select the instances.

   g. Click Add.

9. In the Default Scopes field, enter the following values:

mail

roles

tenantFilter

profile

openId

10. Enter the following in the redirect URL field: https://admin.us01.dx.commercecloud.salesforce.com/oauth2-redirect.html.

11. In the Token Endpoint Auth Method selector select client_secret_post.

12. In the Access Token Format selector select JWT.

13. Click the Save button.

14. As the new API client is created, an ID will be generated. Keep track of this value as it will be used in the next step. This is the OCAPI Client ID value in Violet Connect.

​

Configure OCAPI

Next you will configure the OCAPI. This will require you to enter the following code snippets into the OCAPI configuration area of your system for both the Data and Shop API’s.

1. Navigate to Administration → Site Development → Open Commerce API Settings.
2. In the Type selector, select Data.
3. In the Context selector, select Global.
4. Add the Violet client by entering the following code snippet into the textarea. If the area is currently empty you can copy/paste the entire snippet. If there is already something entered in the textarea you should should only copy the individual client piece and add to the list of clients already present.
5. Replace the CLIENT_ID_FROM_PREVIOUS_STEP_HERE with the ID of the API Client you created in the previous step.

{
  "_v": "23.1",
  "clients": [
    {
      "client_id": "CLIENT_ID_FROM_PREVIOUS_STEP_HERE",
      "resources": [
        {
          "resource_id": "/ocapi_configs/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "methods": ["get", "post", "put", "patch", "delete"],
          "read_attributes": "(**)",
          "write_attributes": "(**)",
          "resource_id": "/**"
        }
      ]
    }
  ]
}

6. Click the Save button to save the Data/Global settings.
7. In the Context selector, select the value that matches the site you are connecting to Violet. This is the Site ID value in Violet Connect.
8. In the Type Selector select Shop.
9. Add the Violet client by entering the following code snippet into the textarea. If the area is currently empty you can copy/paste the entire snippet. If there is already something entered in the textarea you should should only copy the individual client piece and add to the list of clients already present.
10. Replace the CLIENT_ID_FROM_PREVIOUS_STEP_HERE with the ID of the API Client you created in the previous step.

{
  "_v": "23.1",
  "clients": [
    {
      "client_id": "CLIENT_ID_FROM_PREVIOUS_STEP_HERE",
      "resources": [
        {
          "methods": ["get", "post", "put", "patch", "delete"],
          "read_attributes": "(**)",
          "write_attributes": "(**)",
          "resource_id": "/**"
        }
      ]
    }
  ]
}

​

Generating an Access Key

Next you will generate an Access Key which acts as a password with access limited only to the OCAPI. Violet will use the key when accessing your system through the OCAPI.

1. In the top right corner of the business manager, click the User Profile icon.
2. Click the Generate Access Key button, a modal will open.
3. Select the Agent User Login and OCAPI scope and click the Generate button. Note: If the Agent User Login and OCAPI is not listed it means there is already a key generated with this scope. If you have that key available, you are done with this section. If not you must responsibly delete the existing key and generate a new one.
4. The access key will be exposed in plain text just one time, be sure to store this value for later use. This is the Access Key value in Violet Connect.

​

Configuring the Violet Payment Method

Next you will configure a new payment method that will be utilized by Violet when submitting orders back into your system. This will involve creating a new Customer Group, Payment Processor, and Payment Method, each of which will only be utilized by Violet.

1. Navigate to Merchant Tools → Customers → Customer Groups.
2. Click the New button to create a new customer group for Violet customers.
3. Select Static as the type.
4. Enter VIOLET_API as the customer group ID. Optionally enter a description indicating that this customer group is for customers created through the Violet API.
5. Click the Save button.
6. Navigate to Merchant Tools → Ordering → Payment Processors.
7. Click the New button to create a new payment processor for Violet orders.
8. Enter VIOLET_API as the ID then click the Apply button to save it.
9. Navigate to Merchant Tools → Ordering → Payment Methods.
10. Click the New button to create a new payment method for orders created by Violet.
11. Enter VIOLET_API as the payment method ID and Violet as the payment method name.
12. Ensure that the Enabled column is set to Yes.
13. In the details section, click the Edit button next to the Customer Groups label.
14. Select the VIOLET_API customer group and click the Assign button to apply it to the payment method. This will limit the payment method to only orders created by Violet.
15. In the Payment Processor selector, select VIOLET_API .
16. Click the Apply button to save the payment method.

​

Enabling the SCAPI (Optional)

Through the OCAPI connection that was configured in the previous steps Violet will be able to provide end-to-end commerce functionalities for the channels connected to your store. There are a few functionalities though that are not available in the OCAPI and can only be enabled through the SCAPI. These include the following:

• Marking an Order as ready for export.
• Marking an Order as paid.
• Marking an Order as confirmed.

If the automation of these actions is important to your operations than you will need to perform the following additional steps.

1. Navigate to Administration → Site Development → Salesforce Commerce API Settings.
2. If no Short Code is present, click the Request Short Code button. This is the Short Code value in Violet Connect.
3. Following the Short Code is the Organization ID. This is the Organization ID value in Violet Connect.
4. If you do not know your Realm ID or Instance ID, they can generally be located in the Organization ID. The typical Organization ID is as follows, f_ecom_[Realm ID]_[Instance ID]. As an example, if your Organization ID is f_ecom_aaaa_001 your Realm ID is aaaa and your instance ID is 001. These are the Realm ID and Instance ID values in Violet Connect.

From the account manager you will create and configured a new API Client for use by Violet. You can learn more about API Clients in the Salesforce Commerce Cloud documentation. The API Client should be created while you are logged into the account who’s email address you will be sharing with Violet.

Next you will create a new API Client. Unfortunately SFCC does not allow us to use the same API Client that was created for OCAPI when interacting SCAPI. You will be performing the same actions you did when configuring the OCAPI Client, but with slightly different Roles and Scopes.

1. Navigate to the Account Manager and sign in.

2. From the left sidebar menu click API Client.

3. Click the Add API Client button.

4. Enter a display name that will help you identify this API client with Violet.

5. Enter a secure password. This is the SCAPI Client Password value in Violet Connect.

6. Ensure that Access Control is Enabled.

7. Add your organization to the client.

8. Under Roles perform the following steps:

   a. Search for the Salesforce Commerce API role and select the role.

   b. To assign the role to the API client, click Add.

   c. Select the filter icon to specify the role scope (the scope is required by the Salesforce Commerce API).

   d. In the Add Instance Filters tab, select your organization.

   e. Enter the names of the instances to which you want the API client to have access.

   f. Select the instances.

   g. Click Add.

9. In the Default Scopes field, enter the following values:

mail

roles

tenantFilter

profile

openId

10. In the Allow Scopes field enter the following vaues:

sfcc.shopper-baskets-orders.rw

sfcc.orders.rw

sfcc.catalogs.rw

sfcc.products.rw

11. Enter the following in the redirect URL field: https://admin.us01.dx.commercecloud.salesforce.com/oauth2-redirect.html.
12. In the Token Endpoint Auth Method selector select client_secret_post.
13. In the Access Token Format selector select JWT.
14. Click the Save button.
15. As the new API client is created, an ID will be generated. Keep track of this value as it will be used in the next step. This is the SCAPI Client ID value in Violet Connect.

​

Special Refund Considerations

Beyond the usual process for refunding an order this platform has special limitations and considerations that need to be kept in mind when interacting with orders from Violet:

As there is no concept of refunds in both the OCAPI and SCAPI, Violet is unable to be notified of refunds or access any refund data. As a temporary workaround, you will need to perform one of the following steps.

Option 1: Mark Order as Cancelled This option requires the least amount of effort. Simply mark any Violet orders as cancelled when the order is refunded and Violet will treat it as a refund.

Option 2: Notify Violet of Refunds This option will likely require the involvement of your engineering team. When a refund occurs, you will need to send information about the refund to Violet so that it can process the refund accordingly. If you choose this option, the integration documentation will be shared with you by Violet or the channel that onboarded you.

Whats Next Violet will begin integrating with the order management systems that you connect to your Salesforce Commerce Cloud stores. Once we have an integration with the OMS you use you will be able to remove/skip the above fallback options as Violet will be able to discover refunds automatically.