diff --git a/docs/platform/integration/commercetools/cache-invalidation.md b/docs/platform/integration/commercetools/cache-invalidation.md new file mode 100644 index 00000000..d0c6f135 --- /dev/null +++ b/docs/platform/integration/commercetools/cache-invalidation.md @@ -0,0 +1,80 @@ +--- +id: cache-invalidation +title: Cache invalidation +sidebar_label: Cache invalidation +--- + +import CodePackage from '@site/src/components/CodePackage'; + + + +## Overview + +CommerceTools provides notifications about changes on their platform with use of [Subscriptions](https://docs.commercetools.com/api/projects/subscriptions#top). +Falcon Platform provides out of the box integration with CommerceTools messaging system on the base of Google PubSub. + +### Setup Google PubSub + +Before setting up any subscriptions on CommerceTools side PubSub configuration should be done. +First create a topic and a subscription. The topic has to give the `pubsub.topics.publish` permission to the service account `subscriptions@commercetools-platform.iam.gserviceaccount.com.` +We will need your Google project ID (`google-cloud-project-id`) and topic id (`topic-id`) to setup CommerceTools subscription. + +### Create new CommerceTools subscription + +To create a new susbcription on CommerceTools side we recommend using [Postman](https://www.postman.com/). +Please follow [Postman configution manual](postman) before proceeding further. + +### 1. Create subscription for product and category updates + +The final step is to run the request `Project -> Subscriptions -> Create Subscription` (`{{host}}/{{project-key}}/subscriptions`). + +Set the request body to `JSON` and add the following object: + +```json +{ + "destination" : { + "type" : "GoogleCloudPubSub", + "projectId" : "google-cloud-project-id", + "topic": "topic-id" + }, + "changes": [{ + "resourceTypeId": "category" + }], + "messages" : [ { + "resourceTypeId" : "product", + "types" : ["ProductPublished"] + }], + "key" : "product-publish" +} +``` + +This will create a new subscription that will trigger cache invalidation for given Category or Product. +#### Note. +Product update will be triggered only when product is published. Publishing the product would also invalidate category cache, so product should show up on the listing page. + +### 2. Create service access key. +Please checkout the [official Google Cloud dic](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) +On how to create service account keys. +Using `Editor role` for your access level is recommended. However you can fine tune permissions if you like. If application will not be able to access resource you will see +``` +Error: User not authorized to perform this action +``` +in the console on server startup. + +### 3. Connecting to pubsub from you local. +To connect you local environment to pubsub just put your service access file into `server/config` folder. And rename it to `pubsub_service_account.json`. +Server will read the credentials from `server/config/pubsub_service_account.json` on startup. + +### 4. Connecting to pubsub from Deity Cloud. +We strongly discourage commiting your service access files to GIT and using it for connection from cloud environment. +Instead you can use the following command to base64 encode content of the file and set it using our cloud cli tool to environment variable +``` +dcloud env:var:set -s test COMMERCETOOLS_SA_DATA "$(base64 -i ./pubsub_service_account.json)"; +``` + +To make sure new variable name is applied to container - run +``` +dcloud env:var:apply test +``` + +In the above command we used `test` as environment code. Those could be also `stage`, `production.` \ No newline at end of file diff --git a/docs/platform/integration/commercetools/overview.md b/docs/platform/integration/commercetools/overview.md index 1e765b11..37fb7ea1 100644 --- a/docs/platform/integration/commercetools/overview.md +++ b/docs/platform/integration/commercetools/overview.md @@ -52,7 +52,12 @@ Replace values below with values applicable for your store. "url": "https://api.australia-southeast1.gcp.commercetools.com", "authUrl": "https://auth.australia-southeast1.gcp.commercetools.com", "clientId": "XXXXXXXXXXXXXXXXXXXXXXXX", - "secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" + "secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", + "pubsub": { + "projectId": "google-cloud-project-id", + "subscriptionName": "topic-id", + "pullIntervalInSeconds": 10 + } } } } @@ -67,4 +72,5 @@ The following environment variables are mapped directly to the configuration opt - `COMMERCETOOLS_URL` - `COMMERCETOOLS_AUTH_URL` - `COMMERCETOOLS_CLIENT_ID` -- `COMMERCETOOLS_SECRET` \ No newline at end of file +- `COMMERCETOOLS_SECRET` +- `COMMERCETOOLS_SA_DATA` - Google cloud Service Access file content \ No newline at end of file diff --git a/docs/platform/integration/commercetools/payments.md b/docs/platform/integration/commercetools/payments.md index ba6047e8..7cee9020 100644 --- a/docs/platform/integration/commercetools/payments.md +++ b/docs/platform/integration/commercetools/payments.md @@ -18,41 +18,9 @@ Please follow the steps below. ## Installation -Installation custom types in CommerceTools requires us to run an API request. - -We recommend using [Postman](https://www.postman.com/) to do this. - -### 1. Create an API key - -In your CommerceTools dashboard you'll need to create a new API key that has permissions to `manage_types`. Save these credentials for a later step. - -:::note Create a new key -We recommend creating a new key for this action so you can't reduce the permissions needed for your main API key used by the Deity application. -::: - -### 2. Download sample Postman collections - -CommerceTools have a handy repository containing `JSON` collection files you can import directly into Postman. - -[https://github.com/commercetools/commercetools-postman-collection/tree/master/api](https://github.com/commercetools/commercetools-postman-collection/tree/master/api) - -Please download and import these. - -### 3. Add your credentials - -The collections from step 1 required you to add some credentials as Postman variables. These variables are from **step 1**: - -- `auth_url` -- `client_id` -- `client_secret` -- `project_key` -- `host` - -### 4. Authorize your requests - -If you completed **step 2** you should be able to run the request `Authorization -> Obtain access token`. This will create an access token and save it as a Postman variable for later requests. - -### 5. Install the payment types +To create a new susbcription on CommerceTools side we recommend using [Postman](https://www.postman.com/). +Please follow [Postman configution manual](postman) before proceeding further. +### Install the payment types The final step is to run the request `Project -> Types -> Create Type` (`{{host}}/{{project-key}}/types`). diff --git a/docs/platform/integration/commercetools/postman.md b/docs/platform/integration/commercetools/postman.md new file mode 100644 index 00000000..5046722c --- /dev/null +++ b/docs/platform/integration/commercetools/postman.md @@ -0,0 +1,42 @@ +--- +id: postman +title: CommerceTools Integration +sidebar_label: Postman +--- + +import CodePackage from '@site/src/components/CodePackage'; + + + +## Overview +Postman is a handy application that provides tooling for setting up projects on the initial stage. + +### 1. Create an API key + +In your CommerceTools dashboard you'll need to create a new API key that has permissions to `manage_types`. Save these credentials for a later step. + +:::note Create a new key +We recommend creating a new key for this action so you can't reduce the permissions needed for your main API key used by the Deity application. +::: + +### 2. Download sample Postman collections + +CommerceTools have a handy repository containing `JSON` collection files you can import directly into Postman. + +[https://github.com/commercetools/commercetools-postman-collection/tree/master/api](https://github.com/commercetools/commercetools-postman-collection/tree/master/api) + +Please download and import these. + +### 3. Add your credentials + +The collections from step 1 required you to add some credentials as Postman variables. These variables are from **step 1**: + +- `auth_url` +- `client_id` +- `client_secret` +- `project_key` +- `host` + +### 4. Authorize your requests + +If you completed **step 2** you should be able to run the request `Authorization -> Obtain access token`. This will create an access token and save it as a Postman variable for later requests. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 123cf5f3..22231a43 100644 --- a/sidebars.js +++ b/sidebars.js @@ -106,7 +106,9 @@ module.exports = { label: 'CommerceTools', items: [ 'platform/integration/commercetools/overview', - 'platform/integration/commercetools/payments' + 'platform/integration/commercetools/postman', + 'platform/integration/commercetools/cache-invalidation', + 'platform/integration/commercetools/payments', ], }, {