CircleCI codecov Maven Central

AEM Commerce connector for Magento and GraphQL

This is an AEM Commerce connector for Magento and GraphQL, that provides some integration of Magento products and categories in the AEM Commerce console, and some authoring features like product and category pickers.

This connector only provides authoring features, this is not meant to be used to develop frontend components. To develop AEM frontend components, refer to the AEM CIF Core Components project.

Modules

The main parts of the project are:

Installation

For local development and on-prem customer deployments you can install all the modules of the connector and also its required dependencies with the all content package.

For AEM AMS customers please contact the SRE to deploy the CIF Connector.

Via "all" package

If you want to use the latest released version, just download it with the Maven Central link located at the top of this README and install it in your running AEM instance. You can also install the latest all content package with mvn clean install -PautoInstallAll.

If you want to build all the modules yourself and get all the latest (yet) unreleased changes, check the building and installing from source section below.

Inclusion as a Maven dependency

While the Connector can be installed via source as mentioned above, you may want to just include it as a dependency in your own Maven project. If doing so, and using the Filevault Package Maven Plugin, make sure to add a configuration to allow for indices as this project makes use of them:

allowIndexDefinitions=true

System Requirements

Starting with version 0.6.0, all connector artifacts will be released with the same version number (reactor release).

For previous versions, we only provide the version requirements of the all package. If you need to check the versions of other modules, simply checkout the corresponding cif-connector-all-x.y.z tag and check the versions of other modules in the corresponding POM files or in the POM of the all project.

CIF Connector AEM 6.4 AEM 6.5 Magento Java
1.0.0 6.4.4.0 6.5.0 2.3.4 & 2.3.5 1.8
0.8.1 6.4.4.0 6.5.0 2.3.2 & 2.3.3 1.8

For a list of requirements for previous versions, see Historical System Requirements.

CIF Magento GraphQL Configuration

The CIF Magento GraphQL AEM commerce connector has to be configured to access your Magento instance and bind the catalog data. Follow the steps below to configure the bundle:

1) Configure the generic GraphQL instance

2) Configuration of the connector

3) Create a cloud service configuration for Magento

4) Binding of product catalog to AEM resource tree

5) AEM content editor product drag & drop

Usage

The project also provides product and category pickers to be used in any component dialog to select products or categories.

Product Picker

To use the product picker a developer has to add /libs/commerce/gui/components/common/cifproductfield to a component dialog. For example use the following for the cq:dialog:

<product jcr:primaryType="nt:unstructured" fieldLabel="Product" name="./product" sling:resourceType="commerce/gui/components/common/cifproductfield"/>

The product field allows to navigation to the product a user want to select via the different views. A user also can use the integrated search to find a product. By default the product field will return the ID of the product, but this can be configured using the selectionId attribute.

The product picker field supports the following optional properties:

Product Drag'n'drop (DnD)

The connector includes a Sling post-processor that makes it possible to DnD a Product on a component, and configure the behavior of the DnD functionality. For example, you can refer to the cq:dropTarget configuration of the productcarousel and productteaser components in the AEM CIF Core Components. The following parameters can be configured:

Category Picker

The category picker (provided by /libs/commerce/gui/components/common/cifcategoryfield) can be used in a component dialog as well. The following snippet can be used in a cq:dialog configuration:

<category jcr:primaryType="nt:unstructured" fieldLabel="Category" name="./category" sling:resourceType="commerce/gui/components/common/cifcategoryfield"/>

The category picker field supports the following optional properties:

Using a scaffolding to display the product properties page

The project provides a sample scaffolding that only displays the basic information about a product. To link this scaffolding to your catalog root you have to do the following steps:

  1. Open CRXDe Lite and go to /apps/commerce/scaffolding/product
  2. Update the cq:targetPath property to point to the root of your catalog
  3. Save the changes

To see the properties page go to the products console (in Commerce --> Products) and select a cloud product. The Properties action should be available and it should open the properties page when clicked.

Building and installing from source

Pre-requisites

If you build and install each module manually, the magento-graphql and graphql-client bundles have to be installed in your AEM instance. You MUST also configure an instance of the GraphQL client, see the instructions on the corresponding repository to setup the client.

Building and installing

To build all the modules run in the project root directory the following command with Maven 3:

mvn clean install

If you have a running AEM instance, you can also build and deploy all sub-projects into AEM with

mvn clean install -PautoInstall

This installs everything by default to localhost:4502 without any context path. You can also configure the install location with the following maven properties:

Code Formatting

Java

You can find the code formatting rules in /parent. The code formatting is automatically checked for each build. To automatically format your code, please run:

mvn clean install -Pformat-code

JavaScript & CSS

For formatting JavaScript and CSS we use prettier. The formatting is automatically checked when running npm test in the content/cif-connector/tests folder. To automatically format your code, please run the following command in content/cif-connector/tests:

npm run prettier:fix

Testing

Integration Tests

Integration tests are located in it/http and rely on additional test content from the test content package in it/content. Instead of communicating directly with a commerce backend, the integration tests use the mock server in it/mock-server.

To run the integration tests, first install the connector and the test content package. Then execute the following command and point to your running AEM author instance:

mvn clean verify -Ptest-all -Dsling.it.instance.url.1=http://localhost:4502 -Dsling.it.instance.runmode.1=author -Dsling.it.instances=1

Karma Unit Tests

The client-side JavaScript code of the connector is covered using Mocha unit tests executed with Karma. Please make sure that for every contribution new client-side code is covered by tests and that all tests pass.

cd content/cif-connector/tests
npm install
npm test

Karma will test with Chrome and Firefox. Make sure you have both browsers installed.

Releases to Maven Central

Releases are triggered by manually running mvn release:prepare release:clean on the master branch in the top-level folder of this repository. Once you choose the release and the next snapshot versions, this commits the change along with a release git tag like for example cif-connector-reactor-x.y.z. Note that the commits are not automatically pushed to the git repository, so you have some time to check your changes and then manually push them. The push then triggers a dedicated CircleCI build that performs the deployment of all the artifacts to Maven Central.

Note that the skip-it property ensures that the integration tests sub-modules are not released.

Important: starting with version 0.6.0, we changed the release strategy to a "reactor" release when all the artifacts are released with the same version. This makes it easier to perform releases and simplifies versioning.

Contributing

Contributions are welcomed! Read the Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.