Document Properties
Kbid2499S2
Last Modified24-Mar-2020
Added to KB12-Aug-2013
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - Command-Line Client

1 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.

Note

For the moment, it does not fully duplicate the legacy CLC's functionality. E.g., currently the CLC does not support the import of CSV files.

CLC Overview

1.1 Preconditions

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

1.2 Glossary

Term

Description

CLC

Command-Line Client

REST

Representational State Transfer, a methodology for HTTP-based webservices.

1.3 References

See also:

2 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.

2.1 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.

2.1.1 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.

2.1.2 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.

The Command-line Client supports the import of the following object types:

  • product
  • category
  • customer
  • pricelist
  • variationtype

Note

Categories can only be imported into an existing catalog.

The Command-line Client supports all import modes available with the Commerce Management application:

  • OMIT
  • IGNORE
  • UPDATE
  • REPLACE
  • DELETE
  • INITIAL

Please see Intershop 7 Managing Online Shops | Chapter 2: Catalogs and Products | Catalog and Product Management: Concepts | Catalog Import and Export | Standard Import Modes for more detailed information about the import modes.

2.2 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

2.3 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>

3 Server-Side Functionality

3.1 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.

3.1.1 JobListResource

Method

URI

Parameters

Description

Return value

GET

/SMC/-/domains/<someDomain>/jobs


List all job configurations for a given domain

Collection<LinkRO>

GET

/SMC/-/domains/<someDomain>/jobs

?state=...

List all job configurations with a given state

Collection<LinkRO>

POST, PUT, and DELETE will not be supported as they would only be needed for management of job definitions (schedules), which is out of scope for this feature.

3.1.2 JobResource

Method

URI

Parameters

Description

Return value

GET

/SMC/-/domains/<someDomain>/jobs/<jobname>


Get a job info (including state)

JobRO

PUT

/SMC/-/domains/<someDomain>/jobs/<jobname>

Content: partial JobRO

Update job definition (e.g., to start a job)

JobRO

3.1.3 JobRO

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

3.2 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.

3.2.1 TypedBatchProcessListResource

Method

URI

Parameters

Description

Return value

GET

/batchprocesses


List known sub-resources (productimports, catalogimports, ...)

Collection<LinkRO>

GET

/batchprocesses

?type=import&subtype=...

List known sub-resources of type import that can handle a certain subtype (e.g., product, category, ...)

Collection<LinkRO>

3.2.2 GenericBatchProcessListResource

Method

URI

Parameters

Description

Return value

GET

/batchprocesses/<subResourceName>


List all batchprocesses for this type

Collection<LinkRO>

OPTIONS

/batchprocesses/<subResourceName>


Get information on possible ways to work with the resource.
Return allowed methods (standard OPTIONS handling), as well as an OptionsRO describing acceptable input

OptionsRO

POST

/batchprocesses/<subResourceName>

ParameterRO

Create (and run) a new batchprocess

Location Header pointing to newly created process + LinkRO

3.2.3 GenericBatchProcessResource

Method

URI

Parameters

Description

Return value

GET

/batchprocesses/<subResourceName>/<processid>


Get information about a process

JobRO

3.2.4 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]
    }

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets