Designer Command-Line Interface (CLI)

Semarchy xDI Designer ships with a command-line interface (CLI) to process scripts that build packages or deliveries, extract information from packages, etc. to automate the build process.

Using Designer CLI

You can perform package generation and similar operations from the command line by running a script file from a Designer installation folder.

Create a Script File

The script file is a text file containing one designer command per line, as in the example below.

Example 1. Example of a Designer Script File

buildPackage -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc" -package "WKS:/Built Items/myPackage01.pck"
extractPackageInfo -package "WKS:/Built Items/myPackage01.pck" -extract manifest -outputFile "D:/Extract/packageReport.txt"
buildDelivery -package "WKS:/Built Items/myPackage01.pck" -buildmode substitution -confFile "D:/Configuration Files/confA.conf"

Run the Script File

Once you have created the script file, you can run it to perform your operations in batch.

From a command line, go to the Semarchy xDI Designer installation folder, and run the designer command:

Example 2. Windows

semarchy-xdi-designer-cli.bat
     -script "<SCRIPT_PATH>"
     -workspace "<WORKSPACE_PATH>"
     [-logFile "<LOG_FILE_PATH>"]
     [-cleanProjects]
     [-rebuildCache]
     [-importFrom "<FOLDER>"]

Example 3. Unix

semarchy-xdi-designer-cli.sh
     -script "<SCRIPT_PATH>"
     -workspace "<WORKSPACE_PATH>"
     [-logFile "<LOG_FILE_PATH>"]
     [-cleanProjects]
     [-rebuildCache]
     [-importFrom "<FOLDER>"]

This command uses the following parameters:

Parameter Description

Parameter	Description
`-script "<SCRIPT_PATH>"`	Path to the script file.
`-workspace "<WORKSPACE_PATH>"`	Path to the Designer workspace where the processes are stored.
`-logFile "<LOG_FILE_PATH>"`	Optional Path to a file storing the packages generation logs.
`-cleanProjects`	Optional Rebuild all the processes before executing the script. This corresponds to the Project > Clean menu action in Designer.
`-rebuildCache`	Optional Rebuild the cache before executing the script. This corresponds to the Rebuild Cache action of the Impact view in Designer.
`-importFrom "<FOLDER>"`	Optional Use this option to import projects not in the workspace defined in the `-workspace` option. `<FOLDER>` is the path to a folder containing Projects to import into the workspace before running the script.

-script "<SCRIPT_PATH>"

Path to the script file.

-workspace "<WORKSPACE_PATH>"

Path to the Designer workspace where the processes are stored.

-logFile "<LOG_FILE_PATH>"

Optional

Path to a file storing the packages generation logs.

-cleanProjects

Optional

Rebuild all the processes before executing the script. This corresponds to the Project > Clean menu action in Designer.

-rebuildCache

Optional

Rebuild the cache before executing the script. This corresponds to the Rebuild Cache action of the Impact view in Designer.

-importFrom "<FOLDER>"

Optional

Use this option to import projects not in the workspace defined in the -workspace option. <FOLDER> is the path to a folder containing Projects to import into the workspace before running the script.

Running a Designer script (Windows)

semarchy-xdi-designer-cli.sh
    -script "D:/resources/scripts/processPackages.txt"
    -workspace "D:/workspace/development"

Designer Commands

The Designer CLI provides the following capabilities:

Build Uber Runtime: Creates a standalone JAR containing a configured runtime and all its deliveries.
Build Package: Generates a package from a list of mappings and processes.
Build Delivery: Generate a delivery from a package.
Launch Configuration: Performs a launch configuration. Launch configurations are defined in Semarchy xDI Designer from the Build > Package Configuration menu.
Extract Package Info: Extracts information from a package
Validate Configuration File: Checks that a configuration file contains all the necessary externalized attributes for a given package
Validate Package Source: Checks that the sources of the package match specific user-defined rules.
Patch Package: Patches the sources in a given package.
Git Logical Merge: Performs a git merge using the EMF compare logical conflict resolution.
Git Logical Pull: Performs a git pull using the EMF compare logical conflict resolution.

Build Uber Runtime

This command creates a standalone JAR containing a configured runtime and all its deliveries. It fuses the runtime into a single jar file with the deliveries, modules, and properties.

buildUberRuntime
    -outputFilePath "<output_jar_file>"
    -runtimeConfiguration "<runtime_configuration_file>"
    [-runtimeFolder "<runtime_folder>"]
    -deliveryList "<delivPath1;...;delivPathN>"
    [-moduleFolder "<modules_folder_path>"]
    [-log4jConfiguration "<>"]
    [-additionalFolder "<additionnal_folder_path>"]

This command supports the following parameters:

Parameter Description

outputFilePath

Full path of the generated jar file. Note that the command fails if this file already exists.

runtimeConfiguration

Path to the runtime configuration file (engineParameters.xml) that is included with the runtime. This option is mandatory.

A sample file for the jar generation usage is available in the runtime/properties/samples/engineParameters/example-configuration-uberjar/ folder.

runtimeFolder

Runtime installation folder, used as a source to generate the jar file. It defaults to the built-in runtime.

deliveryList

Semi-colon-separated list deliveries files to include in the Jar. The full path must be specified for each delivery file. For example,

D:\build\deliveries\MyDeliv01.deliv;D:\build\deliveries\MyDeliv02.deliv

moduleFolder

Folder containing the modules to embed in the jar. The built-in runtime module folder is used by default.

log4jConfiguration

Path to a log4j.xml configuration file. By default, the built-in runtime log4j.xml configuration is used.

additionalFolder

A folder from which content is added to the Jar and deployed to the <deploymentFolder>/runtime/user-conf. Use this option if the deliveries need additional files to work or to include configurations files such as key stores.

Example 4. Generating a JAR from the integrated runtime with his modules, with two deliveries

buildUberRuntime
    -outputFilePath "D:\MyFolder\MyJar.jar"
    -deliveryList "D:\build\deliveries\MyDeliv01.deliv;D:\build\deliveries\MyDeliv02.deliv"
    -runtimeConfiguration "D:\samples\engineParameters.xml"

Example 5. Generating a JAR from another runtime, with other modules, with one delivery

buildUberRuntime
    -outputFilePath "D:\My_Folder\MyJar.jar"
    -deliveryList "D:\build\deliveries\MyDeliv01.deliv"
    -runtimeConfiguration "D:\samples\engineParameters.xml"
    -runtimeFolder "D:\runtime"
    -moduleFolder "D:\runtime\modules"

Use the Generated Jar

The generated JAR can be used to run deliveries, using the following command:

java
    <java_options>
    -jar <jar_file>
    StartDelivery -name <delivery_name>
    [-debug]

This command uses the following options:

<java_options>: Java startup options.
<jar_file>: Path to the generated jar file.
<delivery_name>: Name of the delivery to start.
-debug: This option generates extensive logging on the system output and preserves the temporary deployment folder for troubleshooting purposes.

This command reproduces the start delivery script. You can use other options of this command like variables, session name, etc.

Example 6. Start a delivery from a generated jar

java -jar MyJar.jar StartDelivery -name MyDeliv01

Build Package

This command generates a package file from a list of mappings and processes.

buildPackage
    -mainProcessWorkspacePath "<process_list>"
    -package "<target_package>"
    [-conf <configuration_name>]
    [-includeSources (true|false)]
    [-includeDocumentation (true|false)]

This command supports the following parameters:

Parameter Description

mainProcessWorkspacePath

Pipe-separated list of processes and mappings to include in the package. Processes are found in the workspace by their relative path.

To generate a package for a mapping, specify the path of the mapping built process file (.proc file) that exists in the workspace folder. Do not specify the path of a mapping (.map) file.

package

Absolute path of the target package to generate. This path supports Workspace Variable Placeholder.

Absolute path example: D:/Built/Generated Packages/myPackage.pck

Relative path with a workspace variable placeholder: WKS:/Generated Packages Project\myPackage.pck

conf

Configuration name with which the package is generated. The configuration named default is used if none is specified.

includeSources

Defines if the source metadata, processes, and mappings used to generate the package should be included in the package. Having the sources in the package allow validations on these sources and to patch an already generated package. This option defaults to false.

includeDocumentation

Defines if the documentation of the source metadata, processes, and mappings should be included inside the package. The documentation can be visualized for example in Semarchy xDI Production Analytics. This option defaults to true.

Workspace Variable Placeholder

File locations can use a specific syntax to look from files within the workspace. Using the WKS:<relative_path> syntax, a file can be located within the workspace folder. For example,

WKS:/Project001/myPackage.pck

refer to the myPackage.pck file in the /Project001/ folder in the Semarchy xDI Designer workspace folder.

Example 7. Generate a package from one Process

buildPackage
    -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc"
    -package "D:/Built Items/myPackage01.pck"

Example 8. Generate a package from two Processes

buildPackage
    -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc|MyProject/Source Models/process_B.proc"
    -package "D:/Built Items/myPackage01.pck"

Example 9. Generate a package from one Process and one Mapping

buildPackage
    -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc|MyProject/Source Models/indy.build/mapping_A.proc"
    -package "D:/Built Items/myPackage01.pck"

Example 10. Generate a package in the current workspace using the workspace variable placeholder

buildPackage
    -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc"
    -package "WKS:/Target Packages Project/myPackage01.pck"

Example 11. Generate a package with sources and documentation

buildPackage
    -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc"
    -package "D:/Built Items/myPackage01.pck"
    -includeSources true
    -includeDocumentation true

Build Delivery

This command generates deliveries from a package.

buildDelivery
    -package "<package_path>"
    [-buildmode (generation|substitution)]
    [-confFile <configuration_file_path>]
    [-outputFolder <output_folder_path>]
    [-processName <process_name>]
    [-verbose (true|false)]
    [-verifyModules <modules_folder>]

This command supports the following parameters:

Parameter Description

Parameter	Description
`package`	Path of the package from which the deliveries are built. This path supports Workspace Variable Placeholder.
`buildmode`	The mode specifies how delivery should be generated. See Understand the Build Mode for more details. This option defaults to `substitution`.
`confFile`	Path to the configuration file which should be used to generate deliveries. This configuration file should contain all the necessary externalized attributes required to build the deliveries. The `default` configuration is used if none is set.
`outputFolder`	Target folder in which the deliveries are generated. This path supports Workspace Variable Placeholder. The path defaults to the built-in runtime generation sub-folder: `runtime/build/packages`.
`processName`	Name of the Process in the package from which the delivery should be generated. When not specified, the command generates deliveries for all processes in the package.
`verbose`	When this option is enabled, additional information about the operations performed during deliveries generation is printed on the standard output. This option defaults to `false`.
`verifyModules`	If this folder is defined, the operation checks that all required modules are present in the specified folder and that they match those expected in the package manifest. If a required module missing, then the delivery is not generated and an error message indicates the missing module. The default value for this option is the default `runtime/modules/` modules folder.

package

Path of the package from which the deliveries are built. This path supports Workspace Variable Placeholder.

buildmode

The mode specifies how delivery should be generated. See Understand the Build Mode for more details. This option defaults to substitution.

confFile

Path to the configuration file which should be used to generate deliveries. This configuration file should contain all the necessary externalized attributes required to build the deliveries. The default configuration is used if none is set.

outputFolder

Target folder in which the deliveries are generated. This path supports Workspace Variable Placeholder. The path defaults to the built-in runtime generation sub-folder: runtime/build/packages.

processName

Name of the Process in the package from which the delivery should be generated. When not specified, the command generates deliveries for all processes in the package.

verbose

When this option is enabled, additional information about the operations performed during deliveries generation is printed on the standard output. This option defaults to false.

verifyModules

If this folder is defined, the operation checks that all required modules are present in the specified folder and that they match those expected in the package manifest. If a required module missing, then the delivery is not generated and an error message indicates the missing module.

The default value for this option is the default runtime/modules/ modules folder.

Example 12. Generating deliveries for all the Processes contained in a package

buildDelivery -package "D:/Built Items/myPackage01.pck" -buildmode substitution -confFile "D:/Configuration Files/confA.conf"

Example 13. Generating deliveries for a given Process contained in a package

buildDelivery -package "D:/Built Items/myPackage01.pck" -buildmode substitution -confFile "D:/Configuration Files/confA.conf" -processName "process_A"

Example 14. Generating deliveries with a custom output folder

buildDelivery -package "D:/Built Items/myPackage01.pck" -buildmode substitution -confFile "D:/Configuration Files/confA.conf" -processName "process_A" -outputFolder "D:/Built Items/Generated Deliveries/"

Example 15. Generating deliveries using workspace variable placeholder in path locations

buildDelivery -package "WKS:/Generated Packages Project\myPackage.pck" -buildmode substitution -confFile "D:/Configuration Files/confA.conf" -processName "process_A" -outputFolder "WKS:/Generated Deliveries Project/"

Launch Configuration

This command executes a launch configuration previously prepared in Semarchy xDI Designer.

launch <launch_configuration_name>

Example 16. Execute a launch configuration named "launch01"

launch launch01

Extract Package Info

This command extracts information from a package, such as the list of processes, the creation date, the documentation, etc.

extractPackageInfo
    -package "<package_path>"
    -extract <information_to_extract>
    -outputFile <output_file_path>

This command supports the following parameters:

Parameter Description

Parameter	Description
`package`	Path of the package from which the information is extracted. This path supports Workspace Variable Placeholder.
`extract`	Information to extract, from the following list: sourceList: When the package has been generated with sources, this option extracts the list of source models. mainProcessList: List of Processes contained in this package. Use this command to know the Process Names before using the BuildDelivery command. manifest (default): The manifest contains information about the package, such as the creation date, the creator, the Designer version used, the operating system and JVM, etc. date: Package creation date. user: Package creator. packageId: Package internal ID. conf: Package configuration. This extracts all externalized attributes that values may need to be defined to generate deliveries from the package. This corresponds to the ".conf" file used to generate deliveries. documentation: Documentation included in the package if it has been generated with it. This option requires the `outputFile` parameter to be defined with a folder where the documentation is extracted.
`outputFile`	Output file where the extracted information is stored. When not specified the command prints the information to the standard output. This option is mandatory when extracting the documentation. This path supports Workspace Variable Placeholder.

package

Path of the package from which the information is extracted. This path supports Workspace Variable Placeholder.

extract

Information to extract, from the following list:

sourceList: When the package has been generated with sources, this option extracts the list of source models.
mainProcessList: List of Processes contained in this package. Use this command to know the Process Names before using the BuildDelivery command.
manifest (default): The manifest contains information about the package, such as the creation date, the creator, the Designer version used, the operating system and JVM, etc.
date: Package creation date.
user: Package creator.
packageId: Package internal ID.
conf: Package configuration. This extracts all externalized attributes that values may need to be defined to generate deliveries from the package. This corresponds to the ".conf" file used to generate deliveries.
documentation: Documentation included in the package if it has been generated with it. This option requires the outputFile parameter to be defined with a folder where the documentation is extracted.

outputFile

Output file where the extracted information is stored. When not specified the command prints the information to the standard output. This option is mandatory when extracting the documentation. This path supports Workspace Variable Placeholder.

Example 17. Extracting in the console the date when the package has been created

extractPackageInfo -package "D:/Built/Generated Packages/myPackage.pck" -extract date

Example 18. Extracting in a file the date when the package has been created

extractPackageInfo -package "D:/Built/Generated Packages/myPackage.pck" -extract date -outputFile "D:/Extract/packageReport.txt"

Example 19. Extracting documentation

extractPackageInfo -package "D:/Built/Generated Packages/myPackage.pck" -extract documentation -outputFile "D:/Extract/documentationFolder/"

Example 20. Extracting configuration file

extractPackageInfo -package "D:/Built/Generated Packages/myPackage.pck" -extract conf -outputFile "D:/Extract/extractedConfiguration.conf"

Validate Configuration File

This command checks that a configuration file contains all the necessary externalized attributes for a given package.

validateConfFile
    -package "<package_path>"
    -confFile <configuration_file_path>
    [-missingConfFile <missing_attributes_file>]
    [-missingConfBehavior (MERGE|OVERWRITE)]

This command supports the following parameters:

Parameter Description

Parameter	Description
`package`	Path of the package to check the configuration with. This path supports Workspace Variable Placeholder.
`confFile`	Path to the configuration file to check. This path supports Workspace Variable Placeholder.
`missingConfFile`	Path to a file where the missing attributes are written. This path supports Workspace Variable Placeholder.
`missingConfBehaviour`	This option defines how the command handles the case where the "missingConfFile" file already exists. MERGE: Missing attributes are appended to the existing file. OVERWRITE (default): The existing file is deleted and missing attributes are added in a new one.

package

Path of the package to check the configuration with. This path supports Workspace Variable Placeholder.

confFile

Path to the configuration file to check. This path supports Workspace Variable Placeholder.

missingConfFile

Path to a file where the missing attributes are written. This path supports Workspace Variable Placeholder.

missingConfBehaviour

This option defines how the command handles the case where the "missingConfFile" file already exists.

MERGE: Missing attributes are appended to the existing file.
OVERWRITE (default): The existing file is deleted and missing attributes are added in a new one.

Example 21. Validate a configuration

validateConfFile
    -package "D:/Built/Generated Packages/myPackage.pck"
    -confFile "D:/configuration/myConfiguration.conf"

Example 22. Validate a configuration and write missing attributes to a file

validateConfFile
    -package "D:/Built/Generated Packages/myPackage.pck"
    -confFile "D:/configuration/myConfiguration.conf"
    -missingConfFile "D:/validation/missingAttributes.conf"

Example 23. Validate a configuration and append missing attributes to a file

validateConfFile
    -package "D:/Built/Generated Packages/myPackage.pck"
    -confFile "D:/configuration/myConfiguration.conf"
    -missingConfFile "D:/validation/missingAttributes.conf"
    -missingConfBehaviour MERGE

Validate Package Source

This command checks that the sources of the package match specific user-defined rules. The validatePackageSource command checks the sources in a package file based on checksum values.

The syntax is the following:

validatePackageSource
    -package "<package_path>"
    -md5Rule "<model_id>:<md5_expected_checksum>[:(true|false))];..."

This command supports the following parameters:

Parameter Description

Parameter	Description
`package`	Path of the package to check. This path supports Workspace Variable Placeholder.
`md5Rule`	The rule is a semicolon-separated list of source models to compare with given checksums. The syntax for each source model to check is: `<model_id>:<md5_expected_checksum>[:(true\|false))]` where: `<model_id>` is the internal ID of the metadata, mapping, or process to check. `<md5_expected_checksum>` is the MD5 checksum the source model is compared with. `(true\|false)`: This boolean defines this check as mandatory. This means that the command should throw an error if the given model does not exist in the package. Otherwise, the validation is ignored and the next rule processed, which is the default value.

package

Path of the package to check. This path supports Workspace Variable Placeholder.

md5Rule

The rule is a semicolon-separated list of source models to compare with given checksums.

The syntax for each source model to check is: <model_id>:<md5_expected_checksum>[:(true|false))] where:

<model_id> is the internal ID of the metadata, mapping, or process to check.
<md5_expected_checksum> is the MD5 checksum the source model is compared with.
(true|false): This boolean defines this check as mandatory. This means that the command should throw an error if the given model does not exist in the package. Otherwise, the validation is ignored and the next rule processed, which is the default value.

Example 24. Validate a source model

validatePackageSource
    -package "D:/Built/Generated Packages/myPackage.pck"
    -md5Rule "_NTUykF0mEemq07bBKXOAgw:71fc05b7087bc5614537509c3c2172d7"

Example 25. Validate a source model with a mandatory rule

validatePackageSource
    -package "D:/Built/Generated Packages/myPackage.pck"
    -md5Rule "_NTUykF0mEemq07bBKXOAgw:71fc05b7087bc5614537509c3c2172d7:true"

Example 26. Validate multiple source models with mandatory rules

validatePackageSource
    -package "D:/Built/Generated Packages/myPackage.pck"
    -md5Rule "_NTUykF0mEemq07bBKXOAgw:71fc05b7087bc5614537509c3c2172d7:true;UUID_MD_SUPER_TYPE:8d8c0adfedb70305122100549e297958:true"

Patch Package

This command patches the sources in a given package.

The command patches an existing package from an archive containing sources (metadata, mappings, and processes) that have been modified.

This command is advanced. It is recommended to regenerate the package entirely instead

The syntax is the following:

patch -package "<package_path>"
    -patch <patch_archive_path>
    -outputPackage <output_package_path>
    [-verbose (true|false)]

This command supports the following parameters:

Parameter Description

Parameter	Description
`package`	Path of the package to patch. This path supports Workspace Variable Placeholder.
`patch`	Absolute path to a zip archive containing the sources which have changed. This path supports Workspace Variable Placeholder.
`outputPackage`	Path of the generated patched package. This path supports Workspace Variable Placeholder.
`verbose`	When this option is enabled, additional information about the operations performed during the patch operation is printed on the standard output. This option defaults to `false`.

package

Path of the package to patch. This path supports Workspace Variable Placeholder.

patch

Absolute path to a zip archive containing the sources which have changed. This path supports Workspace Variable Placeholder.

outputPackage

Path of the generated patched package. This path supports Workspace Variable Placeholder.

verbose

When this option is enabled, additional information about the operations performed during the patch operation is printed on the standard output. This option defaults to false.

Example 27. Patching an existing package

patch
    -package "D:/Built/Generated Packages/myPackage.pck"
    -patch "D:/Patches/patched_sources.zip"
    -outputPackage "D:/Built/Generated Packages/myPatchedPackage.pck"

Git Logical Merge

This command performs a git merge through the EMF compare logical merge. The logical merge allows to automatically resolve the conflicts when applicable.

The syntax is the following:

gitLogicalMerge
    -repositoryName <repository>
    -reference <branchName|tagName>
    [-verbose]

The git repositories must be declared and configured inside the designer workspace used, as a prerequisite. The command applies to already configured git repositories only.

This command supports the following parameters:

Parameter Description

Parameter	Description
`repositoryName`	Name of the repository on which the merge will be performed. This corresponds to the repository name as defined in the designer workspace. It is mandatory.
`reference`	Name of the branch/tag to merge inside the current branch. It is mandatory.
`verbose`	When this optional parameter is defined, the command will trace inside the output (the console or the script logFile) the exact list of conflicting files, when there is a conflict. The list is logged as a line return delimited list of files, with the complete git file path for each file.

repositoryName

Name of the repository on which the merge will be performed. This corresponds to the repository name as defined in the designer workspace. It is mandatory.

reference

Name of the branch/tag to merge inside the current branch. It is mandatory.

verbose

When this optional parameter is defined, the command will trace inside the output (the console or the script logFile) the exact list of conflicting files, when there is a conflict. The list is logged as a line return delimited list of files, with the complete git file path for each file.

Git Logical Pull

This command performs a git pull through the EMF compare logical merge. The logical merge allows to automatically resolve the conflicts when applicable.

The syntax is the following:

gitLogicalPull
    -repositoryName <repository>
    -reference <branchName|tagName>
    [-verbose]

The git repositories must be declared and configured inside the designer workspace used, as a prerequisite. The command applies to already configured git repositories only.

This command supports the following parameters:

Parameter Description

Parameter	Description
`repositoryName`	Name of the repository on which the pull will be performed. This corresponds to the repository name as defined in the designer workspace. It is mandatory.
`verbose`	When this optional parameter is defined, the command will trace inside the output (the console or the script logFile) the exact list of conflicting files, when there is a conflict. The list is logged as a line return delimited list of files, with the complete git file path for each file.

repositoryName

Name of the repository on which the pull will be performed. This corresponds to the repository name as defined in the designer workspace. It is mandatory.

verbose