Execution Connector

Usage

You use the Execution Connector to call an external application within a workflow. You can call any application that can be started via the command line.

Prerequisites

Linux

Ensure that there is enough physical memory available when executing the Execution Connector in parallel. For each INUBIT process twice as much memory must be available as the maximum memory that is needed for the single INUBIT process.

Examples

Example: Reading a Directory Using the Execution Connector

When using the following configuration, the content of the directory /opt/data/archive is listed and wrapped into an XML structure by using ECHO statements:

module guide 1020 0

Example: Copying a File Using the Execution Connector

When using the following configuration, the file trace.log is copied into the directory /opt/data/tmp:

module guide 1021 0

Example: Creating a Directory Using the Execution Connector

The variable var.dir is used. If no directory with this name exists in var.dir, it will be created:

module guide 1022 0

Example: Passing Windows System Variables to Process

Usage

When using some commands, scripts etc.—e.g. the INUBIT command line interface startcli—it might be necessary to pass system variables to process.

The following example returns the time that has been elapsed since the INUBIT Process Engine was started.

Proceed as follows

  1. Create a new Workflow.

  2. Add an Execution Connector module.

  3. On the Execution Connector Properties tab, enter the following in the corresponding fields:

    • Command: startcli.bat

    • Parameters: -u <user> -p <password> --execCommand "uptime" https://<server>:<port>/ibis/servlet/IBISSoapServlet

    • Working directory: <inubit-installdir>/inubit/client/bin/

  4. Check the checkbox pass system variables to process.

  5. Check the checkbox Use output message in order to generate a result file.

    module guide 1023 0

  6. Click Finish to save the changes.

  7. Set start point to the Execution Connector module.

  8. Start test without file.

  9. Once the Workflow has been executed successfully, open the result file. It should look like this:

module guide 1023 1

Dialog Execution Connector Properties

In the dialog, you configure how the external application is called.

External command

  • Command

    Path and file name of the application to be called.

    Under Windows, enclose the path with quotation marks if it contains one or more blanks. Example: cmd.exe /C del "D:\PROD\ARCHIV\OBI\INVOICE OUT\OCR\AT\PDF\2021-10-24"

    The called application must be installed on the same computer as the Tomcat application server. The path can be entered relatively to the application server or absolutely.

    Non-closed commands can endanger the stability of the entire server!

    Example: cmd without /C to close the command once it has been executed.

  • Parameters

    Parameters for calling the external application. Separate multiple parameters by using a blank.

    Enclose path specifications with quotation marks, even for variables if they contain path specifications. Example:

    {ScriptFile} "/home/ibis/test file/test"

    If the variable filePath contains a path specification, enclose it with quotation marks:

    {ScriptFile} "{Property:filePath}"

    Use the button next to the parameter field to enter the following placeholders:

    • {File}

      For passing the input message as a temporary file to the called application. After its execution, the application writes the result into the same file.

      Use {InputFile} and {OutputFile} if two different files are to be used. {File} and {InputFile} are mutually exclusive! There’s no need to enclose {InputFile}, {OutputFile}, or file parameters in quotation marks.

    • {XPath:PathSpecification}

      Transfers a node value from the XML input message to the called application. Upon clicking this parameter, the XPath Assistant opens and helps you to create XPath expressions to read nodes. Refer to XPath Assistant.

    • {Property:PropertyName}

      Passes a module variable or a workflow variable.

    • {ScriptFile}

      Passes the content defined in the Script field.

    • {InputFile}

      Passes an input message to the called application, without reading it after execution, e.g.:

      • Command: cmd.exe

      • Argument: /C {ScriptFile.cmd} {InputFile}

      • Script: type "%1" > inputMessageDuplicated.dat

    • {OutputFile}

      Passes a temporary file to the called application, into which the application writes the result after execution. This placeholder is commonly used together with {ScriptFile}, e.g.:

      • Command: cmd.exe

      • Argument: /C {ScriptFile.cmd} {OutputFile}

      • Script: echo "This will be streamed into outputfile and provided to workflow" > "%1"

        For the parameters {File}, {ScriptFile}, {InputFile}, and {OutputFile} you can set one of the file extensions .cmd and .bat, respectively, e.g. {ScriptFile.bat}.

  • Working directory

    For the temporary files. The Execution Connector and some applications require a working directory. If you do not specify a directory, the respective default directory is used. The default working directory is <inubit-installdir>/inubit/bin.

    When the working directory differs from the script file path and the path contains one or more blanks, enclose the path with quotation marks.

    When the working directory differs from the script file path and the command line contains a parameter, add a quotation mark at the end of the command line, e.g.:

    Working directory: C:\temp
    Command line: cmd.exe, /C, "D:\te st\test.bat", "test", "test1""

Environment variables

Environment variables are passed as pairs consisting of a variable name and value separated by an = character. Multiple environment variables are separated by line breaks.

Under Windows, special characters as backslashes (\) and quotes (") must be escaped using a backslash (\), e.g.:

CATALINA_HOME=\"C:\\inubit 7\\server\\process_engine\"

Pass system variables to process

If selected, all system variables of the Process Engine’s system are passed to the Execution Connector process to enable the commands and scripts to access the system variables.

Script

Entry field

To enter a script, you must add the parameter {ScriptFile} into the Parameters field.
In order to access parameters defined in the Parameters field, use variables. Their syntax depends on the operating system being used:

  • Windows: %1

  • Linux: $1

A script can also be passed to the execution connector via variable mapping. To do this, the module property Script must be overwritten. The value must be transferred base64 encoded.

Check return value

Expected value

Numerical values:

  • If the entered and the actual return values are the same, the workflow execution is continued.

  • If a value is returned that is different to the expected value, the program’s error code is returned to the workflow (formatted in XML in the form <ExitValue>0</ExitValue>).

    The formatted error code is only returned, if the checkbox Pass back return value as XML was activated. Otherwise, the module throws an error.

  • If no return value is specified, the workflow is always continued.

    In order to ensure that faulty executions are always reported to the workflow, specify a return value of 0. This is because error codes are never equal to null.

Use of input and output message

  • Use input message

    (for Medium/Output Connector only)

    If this is selected, the input message of the Execution Connector is forwarded to the external application.

  • Use output message

    (for Input/Medium Connector only)

    If this is selected, the output message of the external application is transferred to the Execution Connector and is forwarded by it to the workflow.

  • Use error exit

    (for Input/Medium Connector only)

    If this is selected, the error output message of the external application is passed to the Execution Connector and then into the workflow.

Additional settings

  • Buffer size for input message

    Number of bytes for the allocation of memory. The default setting is 4096 bytes (applies if the input field is left blank).

    The greater the value, the larger the amount of memory required when the call takes place but the faster the transmission of the input message to the calling application.

    A small value means that less memory is required. However, it may take some time to pass the input message if the message is much larger than the buffer and therefore has to be passed in packages the same size as the buffer.

  • Pass back return value as XML

    Makes only sense if the return code will be evaluated!

    Prerequisite: Option Use output message must be checked!

    The return value is embedded in an XML structure and returned.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen