Catalog Syndication Utilities
Overview 🚀
The Elastic Path Commerce Cloud Catalog Syndication Utilities are a flexible set of scripts built on Elastic Path’s RESTful e-commerce API that assist with pushing products, collections, categories and brands to external services from Elastic Path Commerce Cloud. The utilities use the e-commerce capabilities provided by Elastic Path Commerce Cloud and transacts data in a RESTful manner.
The Catalog Syndication Utilities currently support pushing to:
- Algolia
- Coveo
Documentation 📖
Prerequisites
Before you begin, ensure that you have the following accounts set up:
- Elastic Path Commerce Cloud account
- Algolia account - Algolia is supported for syndicating products, collections, categories and brands to.
- Coveo account - Coveo is supported for syndicating products only.
Configure Catalog
- Create at least 1 Product (Catalogue -> Products). Ensure you have an image uploaded for the product, and the status of the product is set to Live.
- Create at least 1 Brand (Catalogue -> Brands)
- Create at least 1 Category (Catalogue -> Categories)
- Create at least 1 Collection (Catalogue -> Collections)
- Link your Product(s) to the appropriate category, brand and collection(s). All categories, brands and collections created MUST be linked to at least 1 product.
Development tools
An Elastic Path Commerce Cloud Catalog Syndication Utilities development environment requires the following software:
- Git
- Node.js
- Yarn
- ngrok
- Visual Studio Code with the following extensions:
- Windows Only: Windows Subsystem for Linux (WSL)
Knowledge Requirements
To customize and extend the utilities, you need knowledge in the following technologies:
Start Running the Utilities
Note: If you are running a Windows environment, launch the Windows Subsystem for Linux application and perform the following steps from the console window.
# Clone the Git repository
git clone https://github.com/elasticpath/catalog-syndication.git
# Go into the cloned directory, and the utility subdirectory
cd catalog-syndication/push-catalog-to-<service>
# Install all the dependencies for all sub-project and create necessary symlinks in-between them
yarn
# In the root directory, create an .env file and add the required variables with your account information.
# For more information, see Configuration Parameter Descriptions.
For Algolia
# Executes the script to perform the syndication:
yarn build
# Cleans the project if any errors encountered, prior to re-building:
yarn clean
For Coveo
# Start the server for the function, the server will typically start on PORT `3000`, if not, make a note for the next step.
yarn dev
# Start ngrok, This will expose PORT `3000` to the outside world. Make a note of the `http` URL ngrok provides.
ngrok http 3000
Create the Elastic Path Commerce Cloud Webhook
You must now tell Elastic Path Commerce Cloud the ngrok URL above. Head to the Elastic Path Commerce Cloud Dashboard.
- login and go to
Settings > Integrations
and clickCreate
. - Enter a name and description for your Integration.
- Enter the ngrok http URL in the
URL
field. - Enter the
ELASTICPATH_WEBHOOK_SECRET
from the.env
file(this can be any random string) in theSecret Key
field. - Check
created
/updated
/deleted
observables for Product. - Click
Save
.
Create the Coveo Resources
Login to the Coveo Administration Console.
Create fields
- Navigate to
Content > Fields
. - Click
Add field
. - Fill in the details referencing the following JSON
- Repeat for all of the following fields:
[
{
"name": "productid",
"description": "",
"type": "STRING",
"facet": true
},
{
"name": "objecttype",
"description": "",
"type": "STRING",
"facet": true
},
{
"name": "name",
"description": "",
"type": "STRING",
"facet": true
},
{
"name": "sku",
"description": "",
"type": "STRING"
},
{
"name": "description",
"description": "",
"type": "STRING",
"facet": true
},
{
"name": "body",
"description": "",
"type": "STRING"
},
{
"name": "objectid",
"description": "The EPCC ID of the object",
"type": "STRING"
},
{
"name": "price",
"description": "Display price of the product",
"type": "STRING"
},
{
"name": "amount",
"description": "Display price of the product",
"type": "LONG",
"facet": true
},
{
"name": "slug",
"description": "Display price of the product",
"type": "STRING"
},
{
"name": "brands",
"description": "Display price of the product",
"type": "STRING",
"multiValueFacet": true,
"multiValueFacetTokenizers": ";"
},
{
"name": "categories",
"description": "Display price of the product",
"type": "STRING",
"multiValueFacet": true,
"multiValueFacetTokenizers": ";"
},
{
"name": "collections",
"description": "Display price of the product",
"type": "STRING",
"multiValueFacet": true,
"multiValueFacetTokenizers": ";"
},
{
"name": "imgurl",
"description": "Display price of the product",
"type": "STRING",
"facet": true
}
]
Create a Source
- Navigate to
Content > Sources
. - Click
Add source
. - Choose
Push
. - Enter a name for the source.
- Click
Add source
.
Create Source Mappings
- Click on the source you just created, then click
More > Manage Mappings
on the top utility bar. - Click the JSON tab and paste in the following:
{
"common": {
"rules": [
{ "field": "title", "content": [ "%[name]" ] },
{ "field": "productid", "content": [ "%[id]" ] },
{ "field": "body", "content": [ "<html><body>%[description]</body></html>" ] }
]
},
"types": []
}
- Click
Save and rebuild source
.
Create a Catalog
- Navigate to
Commerce > Catalogs
. - Click
Add catalog
. - Enter a name.
- Select the source you created for
Associated Sources
. - Select
Multiple channels
forDefine your channel
. - Click
Add catalog
.
Create an API Key
- Navigate to
Organization > API Keys
. - Click
Add key
. - Enter a name for the key.
- Under the
Privileges
tab, selectFull access
for thePreset
dropdown. - Click
Add key
. - Copy and save the key, you won't be able to retrieve it from the console later.
Configuration Parameter Descriptions ⚙️
Parameters that require configuration must be added to the /catalog-syndication/.env
file:
Service | Parameter | Importance | Type | Description |
---|---|---|---|---|
Algolia/Coveo | ELASTICPATH_CLIENT_ID |
Required | String | The Client ID of your store. |
Algolia | ALGOLIA_INDEX_NAME |
Required | String | Name of Algolia index used for search functions. |
ALGOLIA_APP_ID |
Required | String | Algolia application identifier. | |
ALGOLIA_ADMIN_KEY |
Required | String | Algolia administrative API key used to modify records. | |
Coveo | ELASTICPATH_CLIENT_SECRET |
Required | String | The Client secret of your store. |
ELASTICPATH_STORE_ID |
Required | String | The store ID. | |
ELASTICPATH_WEBHOOK_SECRET |
Required | String | A random string for authenticating between Elastic Path and the function. | |
COVEO_ORG_ID |
Required | String | Coveo organization ID. | |
COVEO_SOURCE_ID |
Required | String | ID of the source you created in Coveo. | |
COVEO_API_KEY |
Required | String | The API key you created, used to connect to Coveo. |
Contributors ✨
Thanks goes to these wonderful people (emoji key):
Yilin-W 💻 |
Michelle Wan 💻 |
Shaun Maharaj 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!
Terms And Conditions
- Any changes to this project must be reviewed and approved by the repository owner. For more information about contributing, see the Contribution Guide.
- For more information about the license, see GPLv3 License.