Introduction

Previous Intershop/Enfinity versions had an integrated command-line client. That client had some shortcomings, especially that it could only be used from a working installation (i.e., it was not working standalone), and that is was not easily extensible/customizable.

The new command-line client is created as a standalone tool. It supports the main functions of the old command-line client:

• triggering jobs and
• running imports.

The new CLC is self-contained and can be run from a system without any further Intershop installations. The new client is just one way to access this functionality: It interacts with a server-side REST API that can also be used via any other REST client (ultimately, even a browser or cURL would be enough).

Main characteristics:

• The server-side REST-API is independent of the client (directly callable, via provided clients, or any other REST-client)
• The client-side code interacting with the REST-API is independent from Enfinity code (no dependencies on cartridges, no assumptions of an installed server or build environment).

It is able to trigger new processes based on a job definition and a set of configuration values.

Preconditions

• Installed JDK 1.8
• Valid server certificate in the Java keystore

Glossary

References

See also:

• Concept - REST Framework
• Reference - Job Handling REST API (valid to 7.9)

Client-Side Functionality

The client-side code comprises of a set of classes handling the communication with the server. The parameter handling depends on the calling mechanism.

All client code resides in a self-contained, independent component tool_clc, and is installed to <IS.INSTANCE.LOCAL>/tools/clc/. The contents of <IS.INSTANCE.LOCAL>/tools/clc/ can be copied to any other system and can run there without an installed Intershop server.

Tasks

All tasks have to implement CLCTask, which extends the standard Ant Task.

The runjob and import tasks have to communicate with the REST API on the server. For that purpose, the Jersey REST client is used.

As both import and runjob require access to the Jersey client, AbstractRestTask provides common functionality (handling of parameters like hostname, login etc., basic error handling). Also, as both tasks require handling of JobRO-representations from the server, AbstractJobClient provides common functionality specific to jobs.

RunJobsTask

The purpose and implementation of the RunJobsTask are simple:

• find the job with the given name and domain by querying the JobListResource
• try to start it by performing a PUT with the new state "RUNNING" on the job
• report the result by performing a GET on the returned JobResource

If not started with -w false, the task will wait for the job to finish and report the execution duration.

ImportTask

The import task is just a bit more substantial.

When started, it

• queries the TypedBatchProcessListResource for subresources supporting the import of the type from argument -t
• if a resource exists, it
  • sends an OPTIONS request
  • checks the result for parameters for the POST method
  • looks for the relevant parameters and sets the values from the command-line arguments
  • creates a new Impex-Job by performing a POST on the resource
  • reports the result by performing a GET on the returned JobResource

If the job finished with an error, the output and the log file will contain the relevant lines from the server impex-log.

Executable

Tasks can be registered to the command-line client using isclc.properties (stored in the same directory as the batch file):

intershop.clc.tasks.runjob = com.intershop.clc.internal.tasks.RunJobsTask
intershop.clc.tasks.import = com.intershop.clc.internal.tasks.ImportTask

intershop.clc.logging.loglevel = WARN

The command-line client itself basically acts as a wrapper providing parameter handling and interaction handling for the tasks.

This also means that additional tasks can be added at any time.

Running the client without parameters returns a list of registered tasks:

ES1|e:\target\tool_clc\release>isclc
Expected command as first parameter. Known commands are:
  runjob
  import

Running a task without further parameters returns a parameter overview for the task:

ES1|e:\target\tool_clc\release>isclc runjob
The following options are required: -password, -p -domain, -d -host, -h -job, -j

Usage: isclc runjob [options]
  Options:
  * -domain, -d
       The domain to which the job belongs.
    -?, -help
       Display usage
       Default: false
  * -host, -h
       The target system. Format: IP_or_Name[:Port]
    -interval, -i
       If waiting until finished, poll every <n> seconds
       Default: 1
  * -job, -j
       The job that should be started.
    -login, -l

       Default: admin
  * -password, -p

    -servergroup, -g
       The server group at the target system.
       Default: BOS
    -wait, -w
       Wait until finished
       Default: true

You may enter the parameters directly via the command line. If a parameter contains spaces or special characters quoting is required. On Windows systems use double quotes, on Unix systems use single quotes. Alternatively, you can also provide the parameters via a prepared plain text file:

isclc runjob @AnalyzeDB.parameters

with AnalyzeDB.parameters listing the required parameters:

-host
127.0.0.1
...
-j
AnalyzeDatabaseSchema

Ant-Tasks

A sample build.xml defining the tasks is contained in the cartridge tool_clc.

This makes it possible to use the tasks like this:

	<target name="AnalyzeDBSchema" depends="clc.init">
		<runjob host="127.0.0.1" group="BOS" waituntilfinished="true" login="admin" password="\!InterShop00\!" domain="root" jobname="AnalyzeDatabaseSchema" />
	</target>

Server-Side Functionality

REST-API /jobs

The /jobs resource is registered as a sub-resource of the SMC REST API. It can be accessed via <server>/SMC/-/domains/<someDomain>/jobs.
The implementations as well as the resource description ( *.component files) reside in the new cartridge app_bo_rest_job.

JobListResource

JobResource

JobRO

The JobRO exposes information about the job, including its current status.

REST-API /batchprocesses

The batch process resources are registered as sub-resources of the EnterpriseBackoffice REST API. They can be accessed via <server>/<Organization-Site>/<ChannelBackoffice-AppUrlID>/batchprocesses.
The implementations as well as the resource description ( *.component files) reside in the new cartridge app_bo_rest_job.

The new command-line client allows to retrieve supported batch processes (and thereby include import targets) from the server, including information on the required parameters.

To make it easy to add support for new batch process types to the API, the resources ...ListResource, ...Resource and their wiring are added automatically. The type-specific handling can be wired using a BatchProcessHandler for a certain type, e.g., ProductImportHandler extends BatchProcessHandler, CatalogImportHandler extends BatchProcessHandler and so on.

Using this generic approach, a cartridge can add a new type by adding the following snippet to its instances.properties:

    <fulfill requirement="type" of="intershop.EnterpriseBackoffice.RESTAPI.BatchProcessListResource">
        <instance with="BatchProcessType" name="intershop.EnterpriseBackoffice.RESTAPI.mycustomimports">
            <fulfill requirement="name" value="mycustomimports" />
            <fulfill requirement="handler">
                <instance with="MyCustomImportHandler" />
            </fulfill>
        </instance>
    </fulfill>

The GenericBatchProcessListResource and GenericBatchProcessResource are wired to support the given name"mycustomimports" in the URI. They automatically generate and use the wired handler"MyCustomImportHandler" to provide OptionROs to the client and create new batch processes of the supported type.

The first version of the import resources uses a PipelineBasedImportHandler extends BatchProcessHandler which basically uses the existing pipelines (similar to the old Web service). The pipeline mappings can be configured (and/or extended, replaced) using the Component Framework. In addition, import handlers can be added one at a time for each supported import type, gradually evolving the server-side code away from import pipelines.

TypedBatchProcessListResource

GenericBatchProcessListResource

GenericBatchProcessResource

OptionsRO

The OptionsRO should expose information about possible parameters.

The HTTP method OPTIONS is explicitly for requesting information about possible actions on a resource. The standard only requires the header Allow to be sent in response (with a comma-separated list of allowed HTTP methods for this resource).
However, it does allow to return a response body as well.

An OptionsRO consists of one ParameterRO per supported HTTP method.

    


{
    "methods":
    {
        "POST":
        {
            "attributes":
            [
                {
                    "name": "loglevel",
                    "type": "String",
                    "value": "["DEBUG", "ERROR", "WARN", "INFO"]"
                },
                {
                    "name": "unitname",
                    "type": "String",
                    "value": "The name of the unit where the import should be done"
                },
                {
                    "name": "description",
                    "value": "Create and start a new batch process of type import"
                },
                {
                    "name": "locale",
                    "type": "String",
                    "value": "The ISO locale code that should be used for the import"
                },
                {
                    "name": "filename",
                    "type": "String",
                    "value": "The name of the file to import"
                },
                {
                    "name": "mode",
                    "type": "String",
                    "value": "["INITIAL", "UPDATE", "DELETE", "IGNORE", "REPLACE"]"
                },
                {
                    "name": "skipValidation",
                    "type": "Boolean",
                    "value": "Set to true to try a direct import without validating the file first"
                }
            ],
            "type": "Parameters"
        }
    },
    "type": "Options"
}

The client reduces the ParameterRO for the corresponding HTTP method and send this as parameters:

    {
        "type":"Parameters",
        "loglevel":"DEBUG",
        "unitname":"PrimeTech-PrimeTechSpecials",
        ...
        "testNumber":0,
        "testArray":[100,200,300]
    }