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
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.
- 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.
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)
To customize and extend the utilities, you need knowledge in the following technologies:
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.
# Executes the script to perform the syndication:
yarn build
# Cleans the project if any errors encountered, prior to re-building:
yarn clean
# 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
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
.
Login to the Coveo Administration Console.
- 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
}
]
- Navigate to
Content > Sources
. - Click
Add source
. - Choose
Push
. - Enter a name for the source.
- Click
Add source
.
- 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
.
- 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
.
- 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.
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. |
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!
- 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.