In this article
Stambia DI Designer is shipped with a command line utility which can be used to do various tasks such as building packages, building deliveries, extracting information from packages, ...
This article demonstrates how to use Stambia DI Designer's command line utility, and references all the available command with information from which version they can be used.
Overview
Executing Stambia DI Designer shell commands consists of preparing a script file containing all the shell commands to execute, and then execute this script file through the command line tool utility.
The script file is a simple text file containing a list of shell commands separated with a line return, the available list of shell commands being listed in "Shell Commands Reference" section.
When the script file is ready, you can execute it with the command line tool describe in "Command line tool reference" section.
Examples of commands are listed all along the article.
Command line tool reference
You can find in this section how to use the command line tool to execute a script file containing a list of shell commands.
The first step to use the command line tool is to open a command line prompt with your operating system and move to Stambia DI Designer's installation folder.
cd <Stambia DI Designer installation root folder>
You can then execute the command line tool as follow:
java -jar plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar -application com.indy.shell.application -console –noSplash -data "WORKSPACE_PATH" -script "SCRIPT_PATH" [-logFile "LOG_FILE_PATH"]
The following parameters are available on the command line tool:
| Parameter | Mandatory | Required Designer | Description |
| -console -noSplash | Yes | S18.3.2 or higher | These two options are required and used to launch the tool in command line mode |
| -data «WORKSPACE_PATH» | Yes | S18.3.2 or higher | Path to the Stambia Designer workspace where the Processes are stored |
| -script «SCRIPT_PATH» | Yes | S18.3.2 or higher | Path to the script file containing the list of shell commands to execute |
| -logFile «LOG_FILE_PATH» | No | S18.3.2 or higher | Path to a log file where information about the Packages generation will be logged |
| -cleanProjects | No | S18.3.3 or higher | Rebuild all the Processes before executing the script (It corresponds to the Project > Clean menu that can be used in the Designer) |
| -rebuildCache | No | S18.3.3 or higher | Rebuild the cache before executing the script (It corresponds to the Rebuild Cache menu of the Impact View in the Designer) |
| -importFrom | No | S18.3.3 or higher |
This option allows to import other projects that are not in the workspace which is defined with -data option. Specify here the path to a folder containing Projects that you want to import in the workspace before executing the script. This offers the possibility to build Packages from Projects that are not already present in the workspace. Important:
|
When using this command line tool, make sure that the workspace it is working on is not opened by any Designer or any other instance of the tool
Example of command:
java -jar plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar -application com.indy.shell.application -console -noSplash -data "D:/workspace/development" -script "D:/resources/scripts/commands.txt"
Example of content for the "commands.txt" 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"
For further information about the available commands which can be used in the script file, refer to the "Commands Reference" part of this article
Shell Commands Reference
You can find in this section the list of commands which can be used in the script file.
More detail for each command can be found further in the article.
| Command | Prerequisites | Description |
| buildPackage | Stambia DI Designer S19.0.19 and higher | Generate a package file from a list of Mappings and Processes. |
| buildDelivery | Stambia DI Designer S19.0.19 and higher | Generate a delivery from a given package |
| launch | Stambia DI Designer S19.0.0 and higher | Execute a launch configuration (defined in Stambia DI Designer from "Build > Package Configuration..." menu) |
| extractPackageInfo | Stambia DI Designer S19.0.19 and higher | Extract various information from a given package |
| validateConfFile | Stambia DI Designer S19.0.19 and higher | Check that a given Configuration file contains all the necessary externalized attributes for a given package |
| validatePackageSource | Stambia DI Designer S19.0.19 and higher | Check that the sources of package matches specific user defined rules |
| patch | Stambia DI Designer S19.0.19 and higher | Patch the sources of a given package |
| build package | packageWithDocumentation | Stambia DI Designer S18.3.2 and higher | deprecated command used to build packages |
Command - buildPackage
The buildPackage command allows to generate a package file from a list of Mappings and Processes.
The syntax is the following:
buildPackage -mainProcessWorkspacePath "<list of processes to include in package>" -package "<target package path>" [-conf <configuration name>] [-includeSources true | false] [-includeDocumentation true | false]
The following parameters are available:
| Parameter | Mandatory | Default value | Path supports workspace variable placeholder | Description |
Examples |
| mainProcessWorkspacePath | yes | X | X |
Processes and Mappings to include into the target package, separated with a pipe. Processes must be defined through workspace relative paths. Mappings must be defined through their associated built Processes workspace relative paths |
"myProject/myProcess.proc|myproject/indy.build/myMapping.proc" |
| package | yes | X | yes |
Absolute path of the target package to generate. |
Absolute path: "D:/Built/Generated Packages/myPackage.pck" Relative path using workspace variable placeholder: "WKS:/Generated Packages Project\myPackage.pck" |
| conf | no | default | X | Configuration name with which the package will be generated. | MyConfiguration |
| includeSources | no | false | X |
Defines if the source models (Metadata, Processes, Mappings) which are used to generated the package should be included inside the package. Having the sources inside the package can help to perform validations on package's sources and to patch an already generated package. |
true |
| includeDocumentation | no | false | X | Defines if the source models (Metadata, Processes, Mappings) documentation should be included inside the package. Included documentation can be visualized from Stambia Production Analytics for instance when importing the given packages. | true |
Workspace variable placeholder is a variable which can be used in some path parameters to represent the current workspace path.
The syntax to use it is WKS:/
Example: "WKS:/myProject/folder01/"
Examples:
Generating a package from one Process:
buildPackage -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc" -package "D:/Built Items/myPackage01.pck"
Generating 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"
Generating 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"
Generating a package in a location inside the current workspace using the workspace variable placeholder
buildPackage -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc" -package "WKS:/Target Packages Project/myPackage01.pck"
Generating package including sources and documentation
buildPackage -mainProcessWorkspacePath "MyProject/Source Models/process_A.proc" -package "D:/Built Items/myPackage01.pck" -includeSources true -includeDocumentation true
Command - buildDelivery
The buildDelivery command allows to generate delivery files from a package.
The syntax is the following:
buildDelivery -package "<target package path>" [-buildmode <build mode>] [-confFile <configuration file path>] [-outputFolder <output folder path>] [-processName <Name of the Process to build>] [-verbose true | false]
The following parameters are available:
| Parameter | Mandatory | Default value | Path supports workspace variable placeholder | Description |
Examples |
| package | yes | X | yes |
Absolute path of the package from which deliveries will be built |
Absolute path: "D:/Built/Generated Packages/myPackage.pck" Relative path using workspace variable placeholder: "WKS:/Generated Packages Project\myPackage.pck" |
| buildmode | no | substitution | X |
Defines the build mode to use for generating the target delivery. Two build modes are actually available to generate the deliveries, each one having its advantages, the substitution mode being used by default ifthis parameter is not specified. generation Mode which launches a generation mechanism to build the delivery. The principal advantage of this mode is that as a new generation step is performed, user does not have to set all the parameters in the extracted configuration file, neither to use a configuration file. The default value with which the package has been generated is used for parameters which has not been valuated in the configuration file. Another advantage is that it allows to customize Metadata parameters which were not defined as externalized when generating the package. This offers the possibility to add extra parameters on the extracted configuration file used to build the delivery, to replace parameters which were not anticipated when generating the package. The con is that because of the generation mechanism, it can be time consuming for large processes.
substitution Mode which consists of simply replacing the externalized attributes with the values provided inside the extracted configuration file. The builder simply retrieves the pre-built delivery which is inside the package and replace the parameters in. This is also the method that uses Stambia Production Analytics for generating deliveries, and this offers better performances as no generation is performed to build the delivery. This also offers the possibility to generate deliveries for all the processes contained in a multi-process package. In this mode it is mandatory to build the delivery using a configuration with all the externalized Metadata parameters valuated. |
substitution |
| confFile | no | default | X |
Path to the Configuration file which should be used to generate deliveries. The specified Confguration file should contain all the necessary externalized attributes requires to build the deliveries. |
"D:/Configuration Files/confA.conf" |
| outputFolder | no | stambiaRuntime/build/packages | yes | Absolute path to a target folder in which the delivery(ies) will be generated |
Absolute path: "D:/Built Items/Generated Deliveries/" Relative path using workspace variable placeholder: "WKS:/Generated Deliveries Project" |
| processName | no | X | X |
Name of the Process from which the delivery should be generated. This must be the name of a Process existing in the package. When not specified, the command will try to generate deliveries for all the Processes contained in the package. |
processA |
| verbose | no | false | X |
Defines if verbose mode should be enabled or not. When enabled, more information about the operations performed during the generation of deliveries is printed. |
false |
Workspace variable placeholder is a variable which can be used in some path parameters to represent the current workspace path.
The syntax to use it is WKS:/
Example: "WKS:/myProject/folder01/"
Examples:
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"
Generating deliveres 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"
Generating deliveres 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/"
Generating deliveres 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/"
Command - launch
The launch command allows to execute a launch configuration previously prepared in Stambia DI Designer.
For further information about launch configurations refer to the following article.
The syntax is the following:
launch <launch configuration name>
Examples:
Executing a launch configuration named "launch01"
launch launch01
Command - extractPackageInfo
The extractPackageInfo command allows to extract information from a package, such as the list of Processes contained inside, the date when it has been created, the list of sources models, the documentation, ...
The syntax is the following:
extractPackageInfo -package "<package path>" -extract <information to extract> -outputFile <output file path>
The following parameters are available:
| Parameter | Mandatory | Default value | Path supports workspace variable placeholder | Description |
Examples |
| package | yes | X | yes |
Absolute path of the package from which information must be extracted |
Absolute path: "D:/Built/Generated Packages/myPackage.pck" Relative path using workspace variable placeholder: "WKS:/Generated Packages Project\myPackage.pck" |
| extract | yes | X | X |
Information to extract from the list below.
sourceList When the package has been generated with the option to include sources inside, this option allows to extract the list of source models for a given package.
mainProcessList List of Processes contained in this package. This can be useful to know the Process Names if you want to generated corresponding deliveries with the BuildDelivery command.
manifest The manifest contains a bunch of information about a given package, such as the creation date, the user which created it, the designer version used to generate, the operating system and JVM used to generate it, the list of Processes and sources contained inside, ...
date Date when the package has been created
user User which created the package
packageId Package internal id
conf Extract package's configuration. This will extract all externalized attributes which values may need to be defined when generating deliveries from the package. This corresponding to ".conf" files used to generated deliveries. Refer to this article for further information about configuration files.
documentation Documentation included in the package, if it has been generated with the option to include documentation. This requires the 'outputFile' parameter to be defined with a folder path where the documentation will be extracted.
|
manifest |
| outputFile | no | X | yes |
Defines an output file where extracted information will be stored. When not specified the command will print extracted information into the console. Note that this is mandatory to define the outputFile parameter when extracting documentation. |
Absolute path: "D:/Extract/packageReport.txt" Relative path using workspace variable placeholder: "WKS:/Extract Information Project/packageReport.txt" |
Workspace variable placeholder is a variable which can be used in some path parameters to represent the current workspace path.
The syntax to use it is WKS:/
Example: "WKS:/myProject/folder01/"
Examples:
Extracting in the console the date when the package has been created
extractPackageInfo -package "D:/Built/Generated Packages/myPackage.pck" -extract date
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"
Extracting documentation
extractPackageInfo -package "D:/Built/Generated Packages/myPackage.pck" -extract documentation -outputFile "D:/Extract/documentationFolder/"
Extracting configuration file
extractPackageInfo -package "D:/Built/Generated Packages/myPackage.pck" -extract conf -outputFile "D:/Extract/extractedConfiguration.conf"
Command - validateConfFile
The validateConfFile command allows to check if a given configuration file is well configured for a given package.
It will check that all the required attributes are well valuated in the configuration file and optionally write all the missing ones in a user defined output file.
The syntax is the following:
validateConfFile -package "<package path>" -confFile <configuration name> [-missingConfFile <file path for writing detected missing attribute>] [-missingConfBehavior MERGE | OVERWRITE]
The following parameters are available:
| Parameter | Mandatory | Default value | Path supports workspace variable placeholder | Description |
Examples |
| package | yes | X | yes |
Absolute path of the package from which the configuration will be validated with. |
Absolute path: "D:/Built/Generated Packages/myPackage.pck" Relative path using workspace variable placeholder: "WKS:/Generated Packages Project\myPackage.pck" |
| confFile | yes | X | yes | Absolute file path of the Configuration file to validate. |
Absolute path: "D:/configuration/myConfiguration.conf" Relative path using workspace variable placeholder: "WKS:/Configuration Project/myConfiguration.conf" |
| missingConfFile | no | X | yes |
Absolute file path to a file which will be used to write all the detected missing attributes. |
Absolute path: "D:/validation/missingAttributes.conf" Relative path using workspace variable placeholder: "WKS:/Validation Project/missingAttributes.conf" |
| missingConfBehaviour | no | OVERWRITE | X |
Defines how the command should handle the case where the file defined with "missingConfFile" already exists. MERGE Missing attributes are appended to the existing file
OVERWRITE Existing file is deleted and missing attributes are added in a new one.
|
OVERWRITE |
Workspace variable placeholder is a variable which can be used in some path parameters to represent the current workspace path.
The syntax to use it is WKS:/
Example: "WKS:/myProject/folder01/"
Examples:
Validating a configuration
validateConfFile -package "D:/Built/Generated Packages/myPackage.pck" -confFile "D:/configuration/myConfiguration.conf"
Validating a configuration and writting the missing attributes in an output file
validateConfFile -package "D:/Built/Generated Packages/myPackage.pck" -confFile "D:/configuration/myConfiguration.conf" -missingConfFile "D:/validation/missingAttributes.conf"
Validating a configuration and appending the missing attributes in an output file
validateConfFile -package "D:/Built/Generated Packages/myPackage.pck" -confFile "D:/configuration/myConfiguration.conf" -missingConfFile "D:/validation/missingAttributes.conf" -missingConfBehaviour MERGE
Command - validatePackageSource
The validatePackageSource command allows to validate the sources of a package file based on checksum values.
The syntax is the following:
validatePackageSource -package "<package path>" -md5Rule <Model to Check>:<md5 Expected Checksum>[:mandatory][;...]
The following parameters are available:
| Parameter | Mandatory | Default value | Path supports workspace variable placeholder | Description |
Examples |
| package | yes | X | yes |
Absolute path of the target package to generate. |
Absolute path: "D:/Built/Generated Packages/myPackage.pck" Relative path using workspace variable placeholder: "WKS:/Generated Packages Project\myPackage.pck" |
| md5Rule | yes | X | X |
Semi-colon separated list of source models to compare with given checksums. The syntax is the following: <ModelId>:<md5ExpectedChecksum>[:mandatory] ModelId Internal Id of the model (Metadata / Mapping / Process) to check.
md5ExpectedChecksum The checksum the source model will be compared with.
mandatory Optionnal parameter to define if the command should throw an error if the given model does not exist in the package. Otherwise, the validation will simply be ignored and the next rule will be processed. The available values for this parameter are "true" and "false". The default value is "false" if the parameter is not defined. |
Example 1: "_NTUykF0mEemq07bBKXOAgw:71fc05b7087bc5614537509c3c2172d7"
Example 2: "_NTUykF0mEemq07bBKXOAgw:71fc05b7087bc5614537509c3c2172d7:true" |
Workspace variable placeholder is a variable which can be used in some path parameters to represent the current workspace path.
The syntax to use it is WKS:/
Example: "WKS:/myProject/folder01/"
Examples:
Validating one source model
validatePackageSource -package "D:/Built/Generated Packages/myPackage.pck" -md5Rule "_NTUykF0mEemq07bBKXOAgw:71fc05b7087bc5614537509c3c2172d7"
Validating one source model with mandatory mode
validatePackageSource -package "D:/Built/Generated Packages/myPackage.pck" -md5Rule "_NTUykF0mEemq07bBKXOAgw:71fc05b7087bc5614537509c3c2172d7:true"
Validating mutliple source models with mandatory mode
validatePackageSource -package "D:/Built/Generated Packages/myPackage.pck" -md5Rule "_NTUykF0mEemq07bBKXOAgw:71fc05b7087bc5614537509c3c2172d7:true;UUID_MD_SUPER_TYPE:8d8c0adfedb70305122100549e297958:true"
Command - patch
The patch command allows to patch an existing package with updated sources.
The idea of this command is to patch an existing package with an archive containing the sources which have changed (Metadata / Mapping / Process).
This is an advanced usage and we advise, when possible to prefer simply re-generating a package with the up to date sources.
The syntax is the following:
patch -package "<path to package to patch>" -patch <patch archive path> -outputPackage <output package path> [-verbose true | false]
The following parameters are available:
| Parameter | Mandatory | Default value | Path supports workspace variable placeholder | Description |
Examples |
| package | yes | X | yes |
Absolute path to the package to patch |
Absolute path: "D:/Built/Generated Packages/myPackage.pck" Relative path using workspace variable placeholder: "WKS:/Generated Packages Project\myPackage.pck" |
| patch | yes | X | X |
Absolute path to a zip archive containing the sources which have changed (Metadata / Mappings / Processes). |
"D:/Patches/patched_sources.zip" |
| outputPackage | yes | X | yes |
Absolute path for the output patched package that will be generated. |
Absolute path: "D:/Built/Generated Packages/myPatchedPackage.pck" Relative path using workspace variable placeholder: "WKS:/Generated Packages Project\myPatchedPackage.pck" |
| verbose | no | false | X |
Defines if verbose mode should be enabled or not. When enabled, more information about the operations performed during the patch is printed. |
true |
Workspace variable placeholder is a variable which can be used in some path parameters to represent the current workspace path.
The syntax to use it is WKS:/
Example: "WKS:/myProject/folder01/"
Examples:
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"
Command - build (deprecated)
The build command is used to generate a package file from a Process.
Note that this command is deprecated and has been replaced by "buildPackage" command.
It has been kept for backward compatibility, but we advise to migrate to the buildPackage command, which offers more options, when possible.
The syntax is the following:
build package | packageWithDocumentation "<Process path>" -target "<target folder>"
The following parameters are available:
| Parameter | Mandatory | Default value | Description |
Examples |
| package | packageWithDocumentation <Process path> | yes | X | Relative path within the workspace to the Process to build the package from.
If you want to generate the Package of a Mapping, specify the path of the Mapping’s built Process file (under indy.build folder) Note: The packageWithDocumentation mode requires a graphical UI on the machine where the generation is performed. |
Example 1: package "Tutorial - Fundamentals/Processes/Load All Datamart.proc"
Example 2: packageWithDocumentation "Tutorial - Fundamentals/Processes/Load All Datamart.proc" |
| target | yes | X |
Absolute path to the target directory in which the generated package will be created. |
"D:/Built/Generated Packages/myPackage.pck" |
Examples:
build package "Tutorial - Fundamentals/Processes/Load All Datamart.proc" -target "D:/Packages/" build package "My Project - 01/Process01.proc" -target "D:/Packages/" build package "My Project - 01/indy.build/mymapping.proc" -target "D:/Packages/" build packageWithDocumentation "My Project - 01/Process02.proc" -target "D:/Packages/"