Elastic Path Commerce Development

Using the EP-Core-Tool

Using the EP-Core-Tool

The EP Core Tool is an application for updating your system configuration settings through the command line. The application comes in two types: EP Core Tool Maven Plugin and an EP Core Tool Command Line Application.

The core-tool is in three separate modules:

  • ep-core-tool-logic - Contains the core tool logic and embedded EP core
  • ep-core-tool - Contains the maven plugin that depends on ep-core-tool-logic
  • ep-core-tool-cli - Contains the command line application that depends on ep-core-tool-logic

The ep-core-tool allows you to:

Installing EP Core Tools

The following must be set up on your production server:

  • The production database is installed
  • Your Nexus server is accessible
  • ep-core-tool-logic is deployed to your Nexus
  • Your server is currently running

Command Line Application

To install the EP Core Tool Command Line Application:

  1. Set the production server's database details in: core\ep-core-tool-cli\src\main\resources\epcoretool.config
  2. From the command line, run mvn install in core\ep-core-tool-cli to build the tool.
  3. The application builds to: core\ep-core-tool-cli\target\ep-core-tool-cli-<VERSION>-bin.zip
  4. Transfer and unzip the file to a folder on your production server.
  5. Install your database's JDBC driver:
    1. Linux - set IE_CLASSPATH to the fully-qualified path and jar filename of your JDBC driver. For example, export IE_CLASSPATH=/home/ep/.m2/repository/mysql/mysql-connector-java/5.1.44/mysql-connector-java-5.1.44.jar
    2. Windows - drop the JDBC driver into your deployment's lib folder: ep-core-tool-cli-7.0.0-SNAPSHOT\lib
  6. Open a command line and run operations from the folder as shown in the sections below.

Maven Plugin

To install the EP Core Tool Maven Plugin:

  1. Set the production server's database details in your .m2/settings.xml file.
  2. Build the Maven Plugin to your production server's Maven repository.
  3. Open a command line and run operations from a directory with a Elastic Path POM file as shown in the sections below.
Note:

You must run the EP Core Tool Maven Plugin commands inside a directory containing an Elastic Path POM file or else the commands will fail.

Changing Commerce Manager User Passwords

This Maven command updates Commerce Manager user passwords:

mvn ep-core-tool:set-cmuser-password -Dusername="USER" -Dpassword="PASSWORD"
epcoretool.bat set-cmuser-password user=password
Note:

The password must pass validation checks before it sets.

$ mvn ep-core-tool:set-cmuser-password -Dusername="admin" -Dpassword="ep31337"
[INFO] Searching repository for plugin with prefix: 'ep-core-tool'.
[INFO] ------------------------------------------------------------------------
[INFO] Building EP Core Maven Plugin
[INFO]    task-segment: [ep-core-tool:set-cmuser-password]
[INFO] ------------------------------------------------------------------------
[INFO] [ep-core-tool:set-cmuser-password {execution: default-cli}]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7 seconds

Pinging the Search Server

Ping the search server to discover the number of products that have been indexed.

mvn ep-core-tool:ping-search
epcoretool.bat ping-search
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'ep-core-tool'.
[INFO] ------------------------------------------------------------------------
[INFO] Building ep-core-tool Maven Mojo
[INFO]    task-segment: [ep-core-tool:ping-search]
[INFO] ------------------------------------------------------------------------
[INFO] Search service has 12481 products indexed in your default locale.
[INFO] BUILD SUCCESSFUL

Rebuild Search Indexes

Rebuild All Indexes

To request all search server indexes to rebuild:

mvn ep-core-tool:request-reindex
epcoretool.bat request-reindex
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'ep-core-tool'.
[INFO] ------------------------------------------------------------------------
[INFO] Building ep-core-tool Maven Mojo
[INFO]    task-segment: [ep-core-tool:request-reindex]
[INFO] ------------------------------------------------------------------------
[INFO] [ep-core-tool:request-reindex {execution: default-cli}]
[INFO] Created notification that product requires a rebuild.
[INFO] Created notification that cmuser requires a rebuild.
[INFO] Created notification that category requires a rebuild.
[INFO] Created notification that shippingservicelevel requires a rebuild.
[INFO] Created notification that promotion requires a rebuild.
[INFO] Created notification that customer requires a rebuild.
[INFO] Created notification that sku requires a rebuild.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 6 seconds

With the -Dwait=true argument, the plugin will return only after the rebuild is complete:

mvn ep-core-tool:request-reindex -Dwait=true
Note: EP Core Tool Command Line Application

The index wait functionality is unavailable for the EP Core Tool Command Line Application

$ mvn ep-core-tool:request-reindex -Dwait=true
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'ep-core-tool'.
[INFO] ------------------------------------------------------------------------
[INFO] Building ep-core-tool Maven Mojo
[INFO]    task-segment: [ep-core-tool:request-reindex]
[INFO] ------------------------------------------------------------------------
[INFO] [ep-core-tool:request-reindex {execution: default-cli}]
[INFO] Created notification that product requires a rebuild.
[INFO] Created notification that cmuser requires a rebuild.
[INFO] Created notification that category requires a rebuild.
[INFO] Created notification that shippingservicelevel requires a rebuild.
[INFO] Created notification that order requires a rebuild.
[INFO] Created notification that orderreturn requires a rebuild.
[INFO] Created notification that promotion requires a rebuild.
[INFO] Created notification that customer requires a rebuild.
[INFO] Created notification that sku requires a rebuild.
[INFO] Created notification that productassociation requires a rebuild.
[INFO] Indexes done: [category, customer, cmuser, shippingservicelevel] Waiting for: [product, promotion, sku]
[INFO] Indexes done: [category, customer, cmuser, shippingservicelevel, promotion] Waiting for: [product, sku]
[INFO] Indexes done: [category, customer, cmuser, shippingservicelevel, promotion, sku] Waiting for: [product]
[INFO] Indexes done: [category, customer, cmuser, shippingservicelevel, promotion, sku, product] Waiting for: []
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 minutes 25 seconds

Rebuilding a Specific Index

To request a specific index to rebuild, use: -Dindex=index_type

mvn ep-core-tool:request-reindex -Dindex=INDEX_TYPE
$ mvn ep-core-tool:request-reindex -Dindex=category
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'ep-core-tool'.
[INFO] ------------------------------------------------------------------------
[INFO] Building ep-core-tool Maven Mojo
[INFO]    task-segment: [ep-core-tool:request-reindex]
[INFO] ------------------------------------------------------------------------
[INFO] [ep-core-tool:request-reindex {execution: default-cli}]
[INFO] Created notification that category requires a rebuild.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 6 seconds

Checking Index Rebuild Status

mvn ep-core-tool:index-status
epcoretool.bat index-status
$ mvn ep-core-tool:index-status
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'ep-core-tool'.
[INFO] ------------------------------------------------------------------------
[INFO] Building ep-core-tool Maven Mojo
[INFO]    task-segment: [ep-core-tool:get-index-status]
[INFO] ------------------------------------------------------------------------
[INFO] [ep-core-tool:get-index-status {execution: default-cli}]
[INFO] category                       Tue Mar 22 17:12:58 PDT 2011 COMPLETE
[INFO] customer                       Tue Mar 22 17:12:58 PDT 2011 COMPLETE
[INFO] product                        Tue Mar 22 17:12:58 PDT 2011 COMPLETE
[INFO] promotion                      Tue Mar 22 17:12:59 PDT 2011 COMPLETE
[INFO] cmuser                         Tue Mar 22 17:12:59 PDT 2011 COMPLETE
[INFO] shippingservicelevel           Tue Mar 22 17:12:59 PDT 2011 COMPLETE
[INFO] sku                            Tue Mar 22 17:12:59 PDT 2011 COMPLETE
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL

Setting Elastic Path System Settings

You can use the ep-core-tool to set Elastic Path system configuration settings in place of the Commerce Manager.

Changing a single configuration setting

To set a single system configuration setting

mvn ep-core-tool:set-setting -DsettingName=setting -DsettingValue=VALUE
epcoretool.bat set-setting setting=value
epcoretool.bat set-setting setting@context=value
$ mvn ep-core-tool:set-setting -DsettingName=COMMERCE/SYSTEM/GEOIP/enable -DsettingValue=true
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'ep-core-tool'.
[INFO] ------------------------------------------------------------------------
[INFO] Building ep-core-tool Maven Mojo
[INFO]    task-segment: [ep-core-tool:set-setting]
[INFO] ------------------------------------------------------------------------
[INFO] [ep-core-tool:set-setting {execution: default-cli}]
[INFO] Old Value: COMMERCE/SYSTEM/GEOIP/enable@null=false
[INFO] New Value: COMMERCE/SYSTEM/GEOIP/enable@null=true
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7 seconds

To unset an individual value:

mvn ep-core-tool:unset-setting -DsettingName=setting
epcoretool.bat unset-setting setting

Change a group of system configuration settings

You can set a group of system configuration settings by modifying your settings.xml file and running mvn ep-core-tool:bulk-set-settings.

To change a group of system configuration settings:

  1. In your settings.xml file, insert the following block of code before the <profiles> tag:
    <build>
        <plugin>
            <groupId>com.elasticpath.tools</groupId>
            <artifactId>ep-core-tool</artifactId>
            <executions>
                <execution>
                    <goals>
                        <goal>bulk-set-settings</goal>
                    </goals>
                    <configuration>
                        <settings>
                        </settings>
                    </configuration>
                </execution>
            </executions>
    </plugin>
    <build>
  2. Under <settings>, place your new configuration settings values.
    <build>
        <plugin>
                <groupId>com.elasticpath.tools</groupId>
                <artifactId>ep-core-tool</artifactId>
                <executions>
                  <execution>
                    <goals>
                      <goal>bulk-set-settings</goal>
                    </goals>
                    <configuration>
                      <settings>
                        <setting>COMMERCE/SYSTEM/SEARCH/searchHost=${ep.search.url}</setting>
                        <setting>COMMERCE/SYSTEM/encryptionKey=${ep.encryptionKey}</setting>
                        <setting>COMMERCE/SYSTEM/EMAIL/emailCmUrl=${ep.emailCmUrl}</setting>
                        <setting>COMMERCE/SYSTEM/assetHttpHost=${ep.asset.http.host}</setting>
                        <setting>COMMERCE/SYSTEM/ASSETS/assetLocation=${project.build.directory}/copied-assets/assets</setting>
                      </settings>
                    </configuration>
                  </execution>
                </executions>
        </plugin>
    <build> 
  3. Run: mvn ep-core-tool:bulk-set-settings to change the values in your system.

ep-core-tool help

Gets the list of available ep-core-tool commands:

mvn ep-core-tool:help
$ mvn ep-core-tool:help
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'ep-core-tool'.
[INFO] ------------------------------------------------------------------------
[INFO] Building ep-core-tool Maven Mojo
[INFO]    task-segment: [ep-core-tool:help] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] [ep-core-tool:help {execution: default-cli}]
[INFO] com.elasticpath.tools:ep-core-tool:1.0-SNAPSHOT
ep-core-tool Maven Mojo
  (no description available)

This plugin has 6 goals:

ep-core-tool:bulk-set-settings
  Updates the setting value in the Elastic Path database. If a value already
  exists, it will be removed before being re-added.

ep-core-tool:get-index-status
  Display the current search server index rebuild status.

ep-core-tool:help
  Display help information on ep-core-tool.
  Call
    mvn ep-core-tool:help -Ddetail=true -Dgoal=<goal-name>
  to display parameter details.

ep-core-tool:request-reindex
  Adds a rebuild request to the index notification queue.

ep-core-tool:set-setting
  Updates the setting value in the Elastic Path database. If a value already
  exists, it will be removed.

ep-core-tool:unset-setting
  Updates the setting value in the Elastic Path database. If a value already
  exists, it will be removed.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3 seconds