Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

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