From 0a925e4bd5818b96740258248a0b3787ae9b97f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Hern=C3=A1ndez?= <122884379+andreshernandez-e2x@users.noreply.github.com> Date: Fri, 13 Oct 2023 12:12:16 -0400 Subject: [PATCH] add short instructions for running bulk import locally (#181) * add short instructions for running bulk import locally * change phrasing for a couple of points * clarify price selection for products --- plugin/docs/how-to-deploy-ct-connect.md | 6 ++++++ plugin/docs/how_to_run_bulk_import.md | 25 ++++++++++++++++++++++++- 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/plugin/docs/how-to-deploy-ct-connect.md b/plugin/docs/how-to-deploy-ct-connect.md index e9c4de4..78c1155 100644 --- a/plugin/docs/how-to-deploy-ct-connect.md +++ b/plugin/docs/how-to-deploy-ct-connect.md @@ -36,6 +36,12 @@ The creation of the API keys also needs to be done manually. See [https://help.klaviyo.com/hc/en-us/articles/360002165611-Understand-multi-account-user-privileges](https://help.klaviyo.com/hc/en-us/articles/360002165611-Understand-multi-account-user-privileges) for more info. +## Importing data in bulk into Klaviyo + +While this plugin has both a real-time sync and a bulk import component, the bulk import side of it is not supported under Connect at this time due to some technical limitations. Bulk imports have to be handled by deploying the plugin somewhere else or just running it locally. + +Running bulk import in a local environment is covered under the [how to run bulk import](./how_to_run_bulk_import.md) documentation. + ## How does the plugin work with commercetools Connect? Under the hood, Connect uses some well-known technologies to host integrations for projects, like GCP CloudRun and diff --git a/plugin/docs/how_to_run_bulk_import.md b/plugin/docs/how_to_run_bulk_import.md index d1f845b..bbc98ff 100644 --- a/plugin/docs/how_to_run_bulk_import.md +++ b/plugin/docs/how_to_run_bulk_import.md @@ -78,4 +78,27 @@ The bulk data import module requires all the following environment variables to For `/sync/categories` and `/sync/products` there's an option to send the `"deleteAll": true` and `"confirmDeletetion": "products"` (or `"categories"`), to trigger a complete deletion of these resources from the Klaviyo Catalog. Keep in mind this **DOES NOT** differentiate between data that came from the plugin and data that might have been imported/created from another source. This is why both properties are required in body to start the process. -Additionally, all endpoints shown above support adding `/stop` to the URL to cancel the process. This only stops the process, any modifications will not be reverted and any import tasks still running on Klaviyo servers will still complete. \ No newline at end of file +Additionally, all endpoints shown above support adding `/stop` to the URL to cancel the process. This only stops the process, any modifications will not be reverted and any import tasks still running on Klaviyo servers will still complete. + +## Running in a local machine + +Setting up bulk import to run in a local machine is very straightforward. Just follow these steps: + +1. Head to the `plugin` directory and run `yarn install` to install all dependencies. +2. Copy the `.env.test` file to `.env` and set the required environment variables. Remove/change any other variables as needed. + - `.env.test` may have variables which are not needed for your use case or may be missing some variables. Double check the environment variables above to avoid issues. +3. Run `yarn run start-ts` to start the plugin. The port used for any of the components will be shown in your console. +4. Open Postman or similar, prepare a POST request with the right URL. For example: `http://localhost:6779/sync/customers`. +5. Send the request. If all went well, you should get a `2XX` status code right away. +6. Monitor progress in your console, you'll get a summary of imported/errored items at the end. + - Errors will be logged along the way, a decently sized console buffer is recommended. + - Errors similar to `Product with ID does not exist in Klaviyo` are expected, checks are performed before creating/updating items in Klaviyo. + +Also, do keep in mind there are sequences/rules that should be followed when importing data: + +- Customers and Orders don't have a strict dependency on each other, but importing Customers first is strongly recommended. +- Categories must be imported before Products, since there's a dependency between them. +- Products must have at least one (1) image and one (1) valid price. + - For example, if you set `PREFERRED_CURRENCY` you need at least a price to match said currency, otherwise any will do. + - Prices with past expiration dates will also be ignored. For future dates, the closest one will be used and the rest will be ignored. +- For products, in cases where more than one locale/currency/inventory channel is defined, only one will be chosen and imported based on configuration and priorities. \ No newline at end of file