Companion for Delivery Project

Bare project

The Companion for Delivery maven archetype is used to fetch the bare project:

groupId: fr.cantor.c4d
artifactId: c4d-maven-archetype
version: 5.0.0

Configure your maven settings and use the following command line to create it:

mvn archetype:generate -DarchetypeGroupId=fr.cantor.c4d -DarchetypeArtifactId=c4d-maven-archetype -DarchetypeVersion=<version>

TIP

Replace <version> by your Companion for Delivery version. The created project contains several examples, they are located in the examples folder of the project.

Structure

Minimum structure for a Companion for Delivery project:

.
├─── src/main/step
└─── pom.xml

Best Practice

Use Maven module to organize your project, here is an advance structure for your project:

.
├─── README.md
├─── docs/
├─── step-contexts/
│    ├─── src/
│    │    ├─── main/step/
│    │    └─── test/
│    └─── pom.xml
├─── step-datamodel/
│    ├─── src/
│    │    ├─── main/step/
│    │    └─── test/
│    └─── pom.xml
├─── step-integration/
│    ├─── src/
│    │    ├─── main/step/
│    │    └─── test/
│    └─── pom.xml
├─── step-tree/
│    ├─── src/
│    │    ├─── main/step/
│    │    └─── test/
│    └─── pom.xml
├─── step-portals/
│    ├─── src/
│    │    ├─── main/step/
│    │    └─── test/
│    └─── pom.xml
├─── step-privileges/
│    ├─── src/
│    │    ├─── main/step/
│    │    └─── test/
│    └─── pom.xml
├─── .gitlab-ci.yml
└─── pom.xml

These modules are created by default by the maven archetype generation. Here is a quick description of all modules :

step-contexts : Is used to define Dimension Points and Contexts. It is useful to separate it from other components because it can be used to prepare a new environment
step-datamodel : Contains your DataModel : Attributes, List Of Values, Object Types, ...
step-integration : Contains your Business Rules, Workflows, Event Processors and Integration End Points
step-tree : Corresponds to the "Tree" tab of the STEP Worbkbench. Use it to store your root nodes, Import/Export/Bulk Update configurations, Attribute Links, ...
step-portals : Contains your WebUI configurations
step-privileges : Defines custom Action Sets and Privilege Rules

Feel free to create as much modules as needed.

Module configuration (Single Update Mode, context, ...)

With Maven properties, each module can be configurated separately.

For instance,

by redefining the step-context property, a module can produce STEP XML that will import data in a given context, different than the other modules.
a module can produce STEP XML with SingleUpdate Mode activated, while other modules do not

For more information on Maven properties, visit https://maven.apache.org/pom.html#Propertiesopen in new window.

For more information on Companion for Delivery plugin configuration, see section Devops -> Maven configuration -> Companion for Delivery plugin configuration.

STEP instance information

You need to define STEP instance information to make it work like it's explain in section: Devops -> Maven configuration -> Profile Management.

<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <step.workspace>Main</step.workspace>
            <step.context>GL</step.context>
            <step.url>https://www.myserver.com/</step.url>
            <step.username>my_username</step.username>
            <step.password>my_password</step.password>
        </properties>
    </profile>
</profiles>

Maven goals

All companion goals have a -Dcompanion.report option that generates a json report

Compile

Works with files in src/main/step directory:

The .companion.csv, .companion.xlsx and .companion.xlsm files are transformed to STEPXML format using Sheet to Xml
The .companion.xml files are transformed to STEP format with Twirl
The .step.xml files are copied

mvn c4d:compile

All transformed and copied files are put in the directory target/classes/step.
They have the extension: .step.xml.

Package

Generates a single STEPXML file for all .step.xml files in the target/classes/step directory, and saves it in target using the following command line:

mvn c4d:package

The generated XML file is located by default in the following folder: target.

Decompile

Generates Companion for Delivery Excel, CSV or XML files from any STEPXML file or STEP:

mvn c4d:decompile -Dinput=<STEPXML file> -DoutputDirectory=<folder>

mvn c4d:decompile -DexportConfiguration=<Export Configuration ID> -DoutputDirectory=<folder> -P my-env-profile

See more options in section: Developer -> Decompiler.

Deploy

Generates a single STEPXML file for all .step.xml files in the target/classes/step directory, and imports it in the default STEP instance:

mvn c4d:deploy

The status of the environment for deployment can be checked with the following command:

mvn c4d:deploy -Dstatus

TIP

User can define maven profiles to manage multi STEP instances. More information in Devops -> Maven configuration -> Profile Management

Diff

Generates a Diff between STEPXML files or STEP environments:

mvn c4d:diff -DoriginalInputFile=<STEPXML file> -DrevisedInputFile=<STEPXML file>

See more options in section: Developer -> Diff.

STEPdoc

Companion for Delivery comes with STEPdoc, which generates the online documentation for your project, making it easily accessible to your team and stakeholders (multi-tenant platform).

See how to use it in the following section: Devops -> Documentation.

Portal splitter

Generate a .xml file for each screen contained in the portal xml configuration.
A root file .companion.template.xml including all screen is also generated.

mvn c4d:portal-splitter -DportalXmlFile=<Portal XML file> -DportalId=<Portal ID> -DoutputDirectory=<folder> -DpackageName=<package name>

License handling

Install license

Install the Companion for Delivery license. By default, installed license is enabled.

mvn c4d:license-install -Dfile=<path to the Companion for Delivery license file>

List installed licenses

List all the Companion for Delivery licenses installed.

mvn c4d:license-list

Display detail of a license

Display information about installed license.

mvn c4d:license-detail -Dlicense=<license UUID>

Enable/disable a license

Activate the license for use. Useful when several licenses are used in parallel.

mvn c4d:license-enable -Dlicense=<license UUID>

mvn c4d:license-disable -Dlicense=<license UUID>

Uninstall a license

Uninstall the license. To use it again you will have to reinstall it with the file provided.

mvn c4d:license-uninstall -Dlicense=<license UUID>

Clean and generate .companion.generated.csv file for each sheet of .companion.xlsx and .companion.xlsm files located in the same directory or within specified folder by -DoutputDirectory. This transformation is used for tracking changes inside companion.xlsx and companion.xlsm files.

mvn c4d:xlsx2csv -DinputDirectory=<input folder> -DoutputDirectory=<output folder> -DcleanOutputDirectory

The generated csv file follow the name convention XLSX_FILENAME.SHEET_ID.SHEET_NAME.companion.generated.csv

By default inputDirectory value is /src/main/step.

outputDirectory can be set to generate .companion.generated.csv in specified folder :

not present: CSV files are put in the same directory as the Excel file
present but not absolute path : csv for example, a directory is created at the root in all the modules which have XLSX files to transform
present and absolute path: A single directory is created with all the files placed in it (Be careful, if the clean is activated, all the modules will delete the files generated by the previous modules)

cleanOutputDirectory can be added to remove all .companion.generated.csv files before a new generation. Not set by default

TIP

You can also configure csv delimiter and quote. More information in Devops -> Maven configuration -> Companion for Delivery plugin configuration

Generate Test

Generate tests for each workflow from .scxml files.

mvn c4d:generate-test

By default inputDirectory value is /src/main/step and outputDirectory is /src/test.

After generation you need to implement test case in .spec.js. More information in Developer -> Companion for Delivery tests