Chapter 40. Launch Services

The architecture of a Launch Service is layered. It follows the basic design of multi-tiered applications utilizing a web browser.

Launch Services let you build a user-friendly form that the user fills in and sends to the CloverDX Server for processing.

Figure 40.1. Launch Services and CloverDX Server as web application back-end

To prepare a graph for publishing as a Launch Service, keep this in mind during the design process:

A graph or a jobflow published as a service usually means that the caller sends request data (parameters or data) and the transformation processes it and returns back the results.

In a Launch Service definition, you can bind service’s parameters to Dictionary entries. These need to be predefined in the transformation.

Dictionary is a key-value temporary data interface between the running transformation and the caller. Usually, although not restricted to, Dictionary is used to pass parameters in and out the executed transformation.

For more information about Dictionary, read the Dictionary section in the CloverDX Designer User’s Guide.

Each Launch Service configuration is identified by its name, user and group restriction. You can create several configurations with the same name, which is valid as long as they differ in their user or group restrictions.

User restrictions can then be used to launch different jobs for different users, even though they use the same launch configuration (i.e. name). For example, developers may want to use a debug version of the job, while the end customers will want to use a production job. The user restriction can also be used to prohibit certain users from executing the launch configuration completely.

Similarly, a group restriction can be used to differentiate jobs based on the user’s group membership.

If multiple configurations match the current user/group and configuration name, the most specific one is picked. (The user name has a higher priority than the group name.)

Adding New Launch Configuration

Use the New launch configuration button on the Launch Services tab to create a new Launch Service.

The name is the identifier for the service and will be used in the service URL. Then, select a sandbox and either a transformation graph or a jobflow that you want to publish.

Figure 40.2. Creating a new launch configuration

Once you create the new Launch Service, you can set additional attributes:

1. User and group access restrictions and additional configuration options (Edit Configuration)

2. Bind Launch Service parameters to Dictionary entries (Edit Parameters)

Figure 40.3. Overview tab

The Overview tab shows the basic details about the launch configuration. These can be modified in the Edit Configuration tab:

Edit Configuration

Figure 40.4. Edit Configuration tab

Editing configurations:

• Name - The name (identifier) under which the configuration will be accessible from the web.

• Description - The description of the configuration.

• Group - Restricts the configuration to a specific group of users.

• User - Restricts the configuration to a specified user.

• Sandbox - The CloverDX Sandbox where the configuration will be launched.

• Job file - Selects the job to run.

• Save run record - If checked, the details about the launch configuration will be stored in the Execution History. Uncheck this if you need to increase performance – storing a run record decreases response times for high frequency calls.

• Display error message detail - Check this if you want to get a verbose message in case the launch fails.

Edit Parameters

The Edit parameters tab can be used to configure parameter mappings for the launch configuration. The mappings are required for the Launch Service to be able to correctly assign parameters values based on the values sent in the launch request.

Figure 40.5. Creating new parameter

To add a new parameter binding, click on the Add parameter button. Every required graph/jobflow listener property defined by the job needs to be created here.

Figure 40.6. Edit Parameters tab

You can set the following fields for each property:

• Dictionary entry name - The name of the Dictionary entry defined in the graph/jobflow that you want to bind.

• HTTP request parameter name - The name of this property as it will be visible in the published service. This name can be different from Name.

• HTTP request parameter required - If checked, the parameter is mandatory and an error will be reported if it is omitted.

• Pass HTTP request body - If checked, the request body is set to dictionary entry as a readable channel.

• Pass value as graph parameter - If checked, the property value will be passed to the job also as a parameter (${ParameterName} where ParameterName is equal to Name). This lets you use the parameter anywhere in the job definition (not just places that support Dictionary). However, parameters are evaluated during job initialization. Thus, such a job cannot be pooled which decreases performance for high frequency repetitive calls to the service. In this case, consider redesigning the transformation to use Dictionary instead, allowing for pooling.

• Default parameter value - The default value applied in case the parameter is omitted in the launch request.

If you are using Launch Services, you have two ways how to be logged in: using form-based authentication of Server console or HTTP basic authentication of Launch Services.

The form-based authentication of Server console enables the user to create or modify Launch Services. If you are logged in this way, you act as an administrator of Launch Services.

To insert data into the Launch Service form, you should be logged in using the HTTP basic authentication. Follow the link to the Launch Service form and web browser will request your credentials. If you are logged in using HTTP basic authentication, you act as an user of Launch Services forms.

A launch request can be sent via HTTP GET or POST methods. A launch request is simply a URL which contains the values of all parameters that should be passed to the job. The request URL is composed of several parts:

(You can use a Launch Services test page, accessible from the login screen, to test drive Launch Services.)

[Clover Context]/launch/[Configuration name]?[Parameters]

Based on the above, the full URL of a launch request for our example with mountains may look like this: http://example.com:8080/clover/launch/NewMountains?heightMin=4000. In the request above, the value of heightMin property is set to 4000.

After the job terminates, the results are sent back to the HTTP client as content of an HTTP response.

Output parameters are defined in the job’s Dictionary. Every Dictionary entry marked as “Output” is sent back as a part of the response.

Depending on the number of output parameters, the following output is sent to the HTTP client:

Launch requests are recorded in the log files in the directory specified by the launch.log.dir property in the CloverDX Server configuration. For each launch configuration, one log file named [Configuration name]#[Launch ID].log is created. For each launch request, this file will contain only one line with following tab-delimited fields:

(If the property launch.log.dir is not specified, log files are created in the temp directory [java.io.tmpdir]/cloverlog/launch where java.io.tmpdir is a system property.)

If the configuration is not valid, the same launch details are saved into the _no_launch_config.log file in the same directory. All unauthenticated requests are saved to the same file as well.