# Connecting to Salesforce Commerce Cloud The B2C Commerce API is a collection of RESTful APIs for interacting with B2C Commerce instances. It goes by a few different names: Salesforce Commerce API, the acronym SCAPI, or just Commerce API. The API enables developers to build a wide range of applications: from full storefronts to custom merchant tools to augment Business Manager. For all B2C Commerce customers, the API is available at no extra cost. The API is broken into two main groups of APIs: Shopper APIs and Admin APIs. And within each group, they're divided into API families and into smaller groups focused on related functionality. **Topics** + [AWS Glue support for Salesforce Commerce Cloud](salesforce-commerce-cloud-support.md) + [Policies containing the API operations for creating and using connections](salesforce-commerce-cloud-configuring-iam-permissions.md) + [Configuring Salesforce Commerce Cloud](salesforce-commerce-cloud-configuring.md) + [Configuring Salesforce Commerce Cloud connections](salesforce-commerce-cloud-configuring-connections.md) + [Reading from Salesforce Commerce Cloud entities](salesforce-commerce-cloud-reading-from-entities.md) + [Salesforce Commerce Cloud connection option reference](salesforce-commerce-cloud-connection-options.md) + [Limitations](salesforce-commerce-cloud-connector-limitations.md) # AWS Glue support for Salesforce Commerce Cloud AWS Glue supports Salesforce Commerce Cloud as follows: **Supported as a source?** Yes. You can use AWS Glue ETL jobs to query data from Salesforce Commerce Cloud. **Supported as a target?** No. **Supported Salesforce Commerce Cloud API versions** v1. # Policies containing the API operations for creating and using connections The following sample policy describes the required AWS permissions for creating and using connections. If you are creating a new role, create a policy that contains the following: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ You can also use the following managed IAM policies to allow access: + [ AWSGlueServiceRole ](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Grants access to resources that various AWS Glue processes require to run on your behalf. These resources include AWS Glue, Amazon S3, IAM, CloudWatch Logs, and Amazon EC2. If you follow the naming convention for resources specified in this policy, AWS Glue processes have the required permissions. This policy is typically attached to roles specified when defining crawlers, jobs, and development endpoints. + [ AWSGlueConsoleFullAccess ](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – Grants full access to AWS Glue resources when an identity that the policy is attached to uses the AWS Management Console. If you follow the naming convention for resources specified in this policy, users have full console capabilities. This policy is typically attached to users of the AWS Glue console. # Configuring Salesforce Commerce Cloud Before you can use AWS Glue to transfer data from Salesforce Commerce Cloud, you must meet these requirements: ## Minimum requirements + You have a Salesforce Commerce Cloud client application with clientId and clientSecret. + Your Salesforce Commerce Cloud account is enabled for API access. If you meet these requirements, you’re ready to connect AWS Glue to your Salesforce Commerce Cloud account. For typical connections, you don't need do anything else in Salesforce Commerce Cloud. # Configuring Salesforce Commerce Cloud connections Salesforce Commerce Cloud supports CLIENT CREDENTIALS grant type for OAuth2. + This grant type is considered 2-legged OAuth 2.0 as it is used by clients to obtain an access token outside of the context of a user. AWS Glue is able to use the client Id and client secret to authenticate Salesforce Commerce Cloud APIs which are provided by custom services that you define. + Each custom service is owned by an API-Only user which has a set of roles and permissions which authorize the service to perform specific actions. An access token is associated with a single custom service. + This grant type results in an access token which is short lived, and may be renewed by calling identity endpoint. + For more information on Salesforce Commerce Cloud documentation on generating the Client credentials, see [ Salesforce documentation ](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html). To configure an Salesforce Commerce Cloud connection: 1. In AWS Secrets Manager, create a secret with the following details. It is required to create a secret for each connection in AWS Glue. 1. For customer managed connected app - Secret should contain the connected app Consumer Secret with USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET as key. 1. In AWS Glue Studio, create a connection under **Data Connections** by following the steps below: 1. Under Data Connections, choose **Create connection**. 1. When selecting a **Data Source**, select Salesforce Commerce Cloud. 1. Provide your Salesforce Commerce Cloud **Short Code**, **Organization ID**, and **Site ID**. 1. Select the Salesforce Commerce Cloud Domain URL of your Salesforce Commerce Cloud account. 1. Select the IAM role which AWS Glue can assume and has permissions for following actions: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. Provide the OAuth scopes - optional, User Managed Client Application ClientId of the Salesforce Commerce Cloud you want to connect to. 1. Select the `secretName` which you want to use for this connection in AWS Glue to put the tokens. 1. Select the network options if you want to use your network. 1. Grant the IAM role associated with your AWS Glue job permission to read `secretName`. 1. In your AWS Glue job configuration, provide `connectionName` as an **Additional network connection**. # Reading from Salesforce Commerce Cloud entities **Prerequisites** + A Salesforce Commerce Cloud Object you would like to read from. Refer the supported entities table below to check the available entities. **Supported entities** | Entity | Can be Filtered | Supports Limit | Supports Order By | Supports Select \$1 | Supports Partitioning | | --- | --- | --- | --- | --- | --- | | Assignments | Yes | Yes | Yes | Yes | Yes | | Campaigns | Yes | Yes | Yes | Yes | Yes | | Catalogs | Yes | Yes | Yes | Yes | Yes | | Categories | Yes | Yes | Yes | Yes | Yes | | Coupons | Yes | Yes | Yes | Yes | Yes | | Gift Certificates | Yes | Yes | Yes | Yes | Yes | | Products | Yes | Yes | Yes | Yes | Yes | | Promotions | Yes | Yes | Yes | Yes | Yes | | Source Code Groups | Yes | Yes | Yes | Yes | Yes | **Example** ``` salesforce_commerce_cloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "campaign", "API_VERSION": "v1" } ) ``` **Salesforce Commerce Cloud entity and field details** Entities list: + Assignments: [ https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments ]( https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments) + Campaigns: [ https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns ](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns) + Catalogs: [ https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs ](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs) + Categories: [ https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories ](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories) + Gift Certificates: [ https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates ](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates) + Products: [ https://developer.salesforce.com/docs/commerce/commerce-api/references/products ](https://developer.salesforce.com/docs/commerce/commerce-api/references/products) + Promotions: [ https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions ](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions) + Source Code Groups: [ https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups ](https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups) **Partitioning queries** Additional spark options `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND`, `NUM_PARTITIONS` can be provided if you want to utilize concurrency in Spark. With these parameters, the original query would be split into `NUM_PARTITIONS` number of sub-queries that can be executed by spark tasks concurrently. + `PARTITION_FIELD`: the name of the field to be used to partition query. + `LOWER_BOUND`: an inclusive lower bound value of the chosen partition field. For date, we accept the Spark date format used in Spark SQL queries. Example of valid values: `"2024-02-06"`. + `UPPER_BOUND`: an exclusive upper bound value of the chosen partition field. + `NUM_PARTITIONS`: number of partitions. Entity-wise partitioning field support details are captured in below table: | Entity | Partitioning Field | DataType | | --- | --- | --- | | Campaigns | lastModified | DateTime | | Campaigns | startDate | DateTime | | Campaigns | endDate | DateTime | | Catalogs | creationDate | DateTime | | Categories | creatiionDate | DateTime | | Gift Certificates | merchantId | String | | Gift Certificates | creatiionDate | DateTime | | Products | creatiionDate | DateTime | | Products | lastModified | DateTime | | Source Code Groups | creationDate | DateTime | | Source Code Groups | startTime | DateTime | | Source Code Groups | endTime | DateTime | **Example** ``` salesforceCommerceCloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupons", "API_VERSION": "v1", "PARTITION_FIELD": "creationDate", "LOWER_BOUND": "2020-05-01T20:55:02.000Z", "UPPER_BOUND": "2024-07-11T20:55:02.000Z", "NUM_PARTITIONS": "10" } ) ``` # Salesforce Commerce Cloud connection option reference The following are connection options for Salesforce Commerce Cloud: + `ENTITY_NAME`(String) - (Required) Used for Read. The name of your Object in Salesforce Commerce Cloud. + `API_VERSION`(String) - (Required) Used for Read/Write. Salesforce Commerce Cloud Rest API version you want to use. Example: v1. + `SELECTED_FIELDS`(List) - Default: empty(SELECT \$1). Used for Read. Columns you want to select for the object. + `FILTER_PREDICATE`(String) - Default: empty. Used for Read. It should be in the Spark SQL format. + `QUERY`(String) - Default: empty. Used for Read. Full Spark SQL query. + `PARTITION_FIELD`(String) - Used for Read. Field to be used to partition query. + `LOWER_BOUND`(String)- Used for Read. An inclusive lower bound value of the chosen partition field. + `UPPER_BOUND`(String) - Used for Read. An exclusive upper bound value of the chosen partition field. + `NUM_PARTITIONS`(Integer) - Default: 1. Used for Read. Number of partitions for read. # Limitations The following are limitations for the Salesforce Commerce Cloud connector: + The Contains filter is not working as expected when partitioning. + CDN Zones' entity doesn't support sandbox instances, and it supports only Development and production instance types. For more information, see [ https://help.salesforce.com/s/articleView?id=cc.b2c\$1embedded\$1cdn\$1overview.htm ](https://help.salesforce.com/s/articleView?id=cc.b2c_embedded_cdn_overview.htm). + In Salesforce Commerce Cloud, there is no API endpoint to fetch Dynamic Metadata. As a result, there is no provision to support the custom fields in the Product and Category entity. + Site id is a mandatory query parameter. You must pass the Site Id value through the Custom Connector Setting. For more information, see [Base URL and Request Formation ](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html). + You can apply filters on maximum two fields (excluding Levels if present) in single API request with the combination of different operators as mentioned in the below table: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html) + In some of the entities, the data type for the fields while retrieving is different from when it is used as searchable fields. As a result, there is no provision of filter feature for these fields. The following table provides the details about such fields. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html)