Using Rulex Platform Command Line Interface#

This page describes in detail all the possible flags and options you can use from the command line prompt (cmd or PowerShell in Windows) to launch Rulex Platform Desktop Version in all its possible modes.

We are going to refer in the rest of the page to the Rulex Platform Command Line Interface with its abbreviation (CLI).

Launching modes#

Rulex Platform Standalone Version can be launched in the following modes:

  • GUI: this is the default mode of the executable, if no extra argument is provided.

  • batch: this page will focus on this second launching mode. The batch mode runs the application without a graphical user interface, executing the command expressed by the subsequent arguments, and closing the application. Batch mode allows the execution of a list of operations as a command line string, and represents the counterpart of the REST API environment for standalone version.

    The following paragraphs describe the two ways of expressing subsequent arguments allowing Rulex Platform to execute a particular exposed operation:

To run Rulex Platform Desktop in GUI mode, simply type the application executable ./Rulex Platform.exe

To run Rulex Platform Desktop in batch mode, add the flag –batch to the usual command: ./Rulex Platform.exe –batch

General Approach#

In the general approach, the different components of an API call (route, headers, params, body etc…) are expressed as keyword arguments in the command line. This allows to perform any general API call of Rulex Platform from a PowerShell/cmd script directly on the desktop version, without any other plugins.

Rulex Platform Desktop CLI exposes shortcuts for the most commonly used commands, i.e. a dedicated set of arguments and keywords to simplify the command line creation, and speed up script construction.

Any call used with any approach can produce these general exit codes:

Code

Name

Description

6

BAD ARGUMENTS

The command sent cannot be parsed, since keywords or arguments are provided in an incorrect form.

5

LICENSE ERROR

The license used is invalid or has expired.

-2

MEMORY ERROR

The command has generated a memory overflow or memory crash.

-4

PYTHON UNHANDLED EXCEPTION

The command has produced an unhandled exception in the Python Middleware code.

-8

INTERNAL UNHANDLED EXCEPTION

The command has produced an unhandled exception in the GOLD/C kernel.

General API Client Batch Approach

For a complete description of all exposed API calls, refer to API Documentation

A general form for a batch command is the follows:

&".\Rulex Platform.exe" --batch resource -a create -c flow -rs {envPath} -rtp environment -q label=MyCreatedFlow -b `{"view":"allow", "modify":"allow", "share":"deny"}`

Which is made up of the following sections:

Route Mapping

To express the route of the API call in the command line, the following options can be used:

Option

Description

recipient

The recipient microservice of the API request, which can be: api, resource, control, session, compute.

–action, -a

The action (it is automatically converted to lowercase). It is the Get/Set/List/Create/Delete part of the API route call.

–command, -c

The command (it is automatically converted to lowercase). It is the part immediately after the action in the API route call.

–resource, -rs

The resource affected by the command, which corresponds to the resource identifier inserted in the API route call.
It can be expressed as an id or a path. If it is expressed as a path, the resource type needs to be expressed too.

–resourceType, -rtp

The resource type. It is used together with –resource when the resource is expressed through a path, rather than an id.

Query String Params

To express the query string params of the API call in the command line, the following options can be used:

Option

Description

–queryParams, -q

The query parameters of the API call.
They must be expressed as a sequence of strings of the form <key>=<value>, separated by commas.

Body

To express the body of the API call in the command line, the following options can be used:

Option

Description

–body, -b

The body of the API call, expressed as JSON.

Authorization

Using this general approach you can also use command line keywords to express the authorization information needed to establish the permissions in the command. If no keywords are specified, authorization of the current user sending the command is used. To express information to authorize the command in the command line, the following options can be used:

Option

Description

–token, -t:

The token of the request (created with the command, or API call at the auth token endpoint).

–refreshToken, -rt

The refresh token of the request (created with the command, or API call at the auth token endpoint).

–clientId, -ci

The client id of the REST API service principal used to send the request.

-clientSecret, -cs

The client secret of the REST API service principal used to send the request.

Headers

Using this general approach, you can also use command line keywords to express general information about the request, which is usually imposed using headers in standard API calls.
 To express information about the headers in the command line, the following options can be used:

Option

Description

–requestId, -id

The request id associated to this call. This may be useful for tracking down information on the log.

–async, -as

Controls whether the request needs to be executed in asynchronous mode. The default value is sync.

Exit Codes

In the general approach, the exit code is always the status code of the corresponding API call:

  • 500 if the request call was not successful.

  • 200 if the request call was successful.

Batch Mode Shortcuts#

The most commonly used commands, for which a shortcut is present in the CLI, are the following:

Keywords and arguments, together with exit codes, are specific for each shortcut; hence we will describe them one by one.

Compute Flow

Here’s an example of the compute flow shortcut call:

&".\Rulex Platform.exe" --batch computeflow -fp "/RulexDesktop/Env_TestUser/Test" -iss

The list of all the possible flags is the following one:

Option

Description

–flowPath, -fp

The flow path to be computed.

–computationMode, -m

The computation mode of the flow. Possible values are:

  • flow (default) - no tasks need to be specified.
  • upto:{tasks}
  • downon:{tasks},
  • selected:{tasks}.

–inMemory, -im

Computes the whole flow in in-memory mode.

–inMemorySourceSaving, -iss

Computes the whole flow in in-memory with saved sources mode.

–procVars, -pv

A space-separated list of process variables for the computation, provided with syntax =.

–onetime,-ot

Performs a one-time computation.

Specific exit codes for the command are:

  • 2 (FLOW SELECTION FAILED): the flow indicated by flowPath is not a flow, or it does not exist, or it is locked at the moment of the command.

  • 4 (TASK COMPUTATION FAILED): some tasks have ended in a managed error during the computation.

  • 12 (FLOW INITIALIZATION ERROR): a managed error occurred during task initialization, which failed. Possible root causes are improper topology, loops in import tasks, GOLD error in evaluation of environment or flow variables.

Import Flow

Here’s an example of the import flow shortcut call:

&".\Rulex Platform.exe" --batch importflow -fp {path of the flow} -u {path of the rfl file}

The list of all the possible flags is the following one:

Option

Description

–flowPath, -fp

The flow path into which the flow will be imported. If it is not present, a flow will be created in the path location.

–flowUrl, -u

The local path of the .rfl file imported, or the relative path with respect to the given filesystem root.

–filesystem, -fs

The path of a filesystem resource, from which we want to import a flow.

Specific exit codes for the command are:

  • 9 (IMPORT UNSUCCESSFUL): the import operation failed with a managed error.

Export Flow

Here’s an example of the export flow shortcut call:

&".\Rulex Platform.exe" --batch exportflow -fp {path of the flow} -u {path of the rfl file}

The list of all the possible flags is the following:

Option

Description

–flowPath, -fp

The flow path to be exported.

–flowUrl, -u

The local path of the file .rfl created by the export, or the relative path with respect to the given filesystem root.

–filesystem, -fs

The path of a filesystem resource, to which we want to export the flow.

Specific exit codes for the command are:

  • 10 (EXPORT UNSUCCESSFUL): the export operation failed with a managed error.

Create Flow

Here’s an example of the create flow shortcut call:

&".\Rulex Platform.exe" --batch createflow -fp {path of the flow}

The list of all the possible flags is the following:

Option

Description

–flowPath, -fp

The path where the flow will be created.

Specific exit codes for the command are:

  • 2 (FLOW SELECTION FAILED): the creation failed because the flowPath cannot be created due to a managed error. Possible root causes are that the flow already exists, or the environments in the path are not present, or sufficient permissions are not granted.

Delete Flow

Here’s an example of the delete flow shortcut call:

&".\Rulex Platform.exe" --batch deleteflow -fp {path of the flow}

The list of all the possible flags is the following:

Option

Description

–flowPath, -fp

The path of the flow to be deleted.

Specific exit codes for the command are:

  • 11 (DELETE UNSUCCESSFUL): the delete operation failed with a managed error.

Execute Macro

Here’s an example of the execute macro shortcut call:

&".\Rulex Platform.exe" --batch executemacro -fp {path of the flow} -e {event name}

The list of all the possible flags is the following one:

Option

Description

–flowPath, -fp

The path of the flow containing the event to be executed.

–eventName, -e

The name of the event of the flow indicated by the --flowPath argument to be executed by the executemacro command.

–macroPath, -mp

The path of the macro to be executed (alternative to the pair flow/event).

Specific exit codes for the command are:

  • 13 (MACRO COMPUTATION FAILED): macro or event execution failed with a managed error.