Generate deliveries

A delivery is a self-contained file that includes the tasks a runtime needs to run an integration flow, as well as these tasks' configuration. For example, it may contain connection information, passwords, table names, and more.

You generate, deploy, and execute or schedule delivery execution on a runtime.

Delivery generation consists of creating the delivery file on the local filesystem. You can generate deliveries in three ways:

Generate deliveries from the Designer

When generating a delivery from xDI Designer, you do not need to generate packages ahead of time. Designer configures and generates packages automatically from your projects.

The configuration you select in Designer at the time of generation is used by the generated delivery.

To generate a delivery from the Designer:

  1. In the Project Explorer, select the mapping or process you want to create a delivery from.

  2. Right-click and select Build/Run > Build > Delivery.

  3. Wait for xDI Designer to finish.

You can select multiple processes and mappings in the Project Explorer to generate multiple deliveries at once. You can also select entire projects or folders to generate deliveries for all the processes and mappings they contain.

You can also script delivery generation using Designer scripts.

Output directory

Designer saves generated deliveries to an output build directory.

By default, the build directory is set to temp/deliveries. This is a subdirectory of the Designer installation directory, or the Contents/Eclipse/ directory of its macOS Application package.

If you want to change the output build directory, follow these steps:

  1. Navigate to the configuration subdirectory inside either the installation directory, or the Contents/Eclipse/ directory of the macOS Application package.

  2. Open the config.ini file in a text editor.

  3. Find the line starting with xdi.designer.generation.build.delivery.output.folder.

  4. Change the value after the = equals sign to a different relative or absolute path.

  5. Save the file.

Restart xDI Designer to apply the changes.

Deliveries you create with Build > Delivery are not visible to an xDI runtime.

To use these deliveries, manually deploy them, or use the Build/Run > Publish > Delivery option to deploy them to the connected runtime. For more information, see Deploy deliveries.

Generate deliveries from Semarchy xDI Analytics

For production environements, xDI Analytics provides features to import, configure, generate and deploy deliveries in multiple environments from the generated packages, using delivery projects.

Generate deliveries from the command line

You generate deliveries from a command line using the builddelivery script that is shipped with the Semarchy xDI Runtime.

These scripts use packages generated by the Development Team to build the deliveries.

You can also script delivery generation in a design environment using Designer scripts.
Example 1. Build Delivery Script (Windows)
builddelivery.bat <package_file>
    [-buildmode <mode>]
    [-listprocessnames]
    [-extract]
    [-conf <name> | -conffile <file path>]
    [-processname <name>]
    [-deliveryfolder <folder path>]
Example 2. Build Delivery Script (Linux/Unix/macOS)
builddelivery.sh <package_file>
    [-buildmode <mode>]
    [-listprocessnames]
    [-extract]
    [-conf <name> | -conffile <file path>]
    [-processname <name>]
    [-deliveryfolder <folder path>]

Command line options

The builddelivery command supports the following parameters:

  • <package_file>: Package (.pck) file containing the packages to build as deliveries

  • -buildmode <mode>: The mode specifies how delivery should be generated. See Understand the build mode for more details.

    • substitution: This mode replaces the externalized attributes with the values provided in the extracted configuration file, without performing an entire re-generation.

    • generation (default): This mode performs a re-generation phase.

  • -listprocessnames: This option lists the processes contained in the package.

  • -extract: This option extracts to a configuration file all the externalized metadata values used in the processes.

  • -conf <name> | -conffile <file path>: Configuration file name or path.

    • With the -extract option, this option defines the configuration file into which the externalized metadata values are extracted.

    • When building deliveries, this option defines the configuration used to build the deliveries. This configuration is mandatory when building deliveries in substitution mode. In generation mode, the default values are used if no configuration is specified.

  • -processname <name>: Single process in the package for which a delivery must be generated. If this option is not specified, all processed in the package are generated (substitution mode only).

  • -deliveryfolder <folder path>: Folder into which deliveries are generated.

    The deliveries are generated in the folder build/deliveries if the -deliveryfolder option is not specified.

Understand the build mode

The delivery Build Mode specifies how deliveries should be generated.

Generation

This mode performs a generation prior to building the delivery. It is the mode used by default.
With this mode:

  • You do not need to set all the parameters in the configuration file, or to provide a configuration file. Unspecified metadata attributes unspecified are set to those defined in the generated package.

  • You can customize attributes that were not externalized when generating the package, and possibly configure additional parameters in the configuration file, for example, to replace attributes that were not anticipated when generating the package.

This mode has the following limits:

  • Due to the generation phase, this mode may be time-consuming for large processes.

  • You cannot generate deliveries for all the processes contained in a package. If a package contains multiple processes, you must specify the process to generate using the -processname option.

Substitution

This mode does not perform a generation phase. It replaces the externalized metadata attributes values of the pre-built deliveries contained in the package with those provided in the configuration file.
With this mode:

  • You must specify a configuration using the -conf or -conffile options.

  • The configuration must include all the values for the externalized metadata attributes.

  • The externalized attributes are replaced in the pre-built deliveries contained in the package.

  • You can generate deliveries for all the processes contained in a package.

This mode is used by xDI Analytics to generate deliveries. It offers better performances since the generation phase is not performed.
Choosing the Build Mode

In most cases, the substitution mode works as it offers better performances and allows building all the processes contained in a package.

The generation mode is still the default for backward compatibility. However, it should be used mainly to override values for metadata attributes that were not originally externalized in the generated package.

Work with configuration files

The configuration file contains all the externalized metadata attributes from the package.

In a package:

  • Certain attributes are externalized by default. For example, the JDBC URL, User, or password for database connections.

  • Other attributes can be defined as externalized in the metadata at design time.

With the -extract option you extract a configuration file from the package that contains externalized attributes. The configuration file is named according to the -conf (or -conffile) option.

In the configuration file, externalized attributes are commented, and show their default value. You can uncomment the lines for the values that you want to set and provide the value.

The following sample shows the configuration for a database connection.

The externalized attributes appear with an ID. This ID is not modified if the metadata is renamed in the project. The preceding comment helps you understand the attribute location.
Example 3. Original Configuration File
#################################################################
### Name: super/Rdbms MetaData/Hypersonic SQL/HSQL - localhost_62210
### Type: com.stambia.rdbms.server
#_–1vK4CVLEeWjxY2_6aCFbA/url=jdbc:hsqldb:hsql://localhost:62210
#_–1vK4CVLEeWjxY2_6aCFbA/user=sa
#################################################################
### Name: super/Rdbms MetaData/Hypersonic SQL/HSQL - localhost_62210/HOTEL_MANAGEMENT
### Type: com.stambia.rdbms.schema
#_aUU9YE26Eeay9ZeykqAlHA/TABLE_SCHEM=HOTEL_MANAGEMENT +
#################################################################

To configure the URL, user, and schema for the database connection, uncomment the attribute that you want to set and provide the value, as shown in the example below.

Example 4. Modified Configuration File
#################################################################
### Name: super/Rdbms MetaData/Hypersonic SQL/HSQL - localhost_62210
### Type: com.stambia.rdbms.server
_–1vK4CVLEeWjxY2_6aCFbA/url=jdbc:hsqldb:hsql://productionhost:62210
_–1vK4CVLEeWjxY2_6aCFbA/user=productionuser
#################################################################
### Name: super/Rdbms MetaData/Hypersonic SQL/HSQL - localhost_62210/HOTEL_MANAGEMENT
### Type: com.stambia.rdbms.schema
_aUU9YE26Eeay9ZeykqAlHA/TABLE_SCHEM=HOTEL_PRODUCTION_SCHEMA
#################################################################
Passwords must be encrypted in configuration files with the encrypt <password> command on the runtime console.

Delivery generation example

The following script illustrates

Below are examples of script usage

# List the processes in a package
builddelivery.sh mypackage.pck -listprocessnames

# Extract the configuration
builddelivery.sh mypackage.pck -conf myconf -extract

# Build a delivery using the configuration
builddelivery.sh mypackage.pck -conf myconf

#  Build a delivery using the configuration, process name, and delivery folder
builddelivery.sh mymultipackage.pck -conf myconf \
    -processname "Load All Datamart" \
    -deliveryfolder ~/deliveries/

# Build all the deliveries of a multi-process package into a target folder
# The substitution mode is mandatory.
builddelivery.sh mymultipackage.pck -conf myconf \
    -deliveryfolder ~/deliveries/ \
    -buildmode substitution