TIF ENOVIA/3DExperience Connector - Launch External Process

18 October 2016

1. Launch External Process

This kind of integration job is used for launching one or more external processes(es), with input that could consist of files that are checked-out from the ENOVIA/3DExperience database and/or just meta data created via a payload configuration.

The output from the external processing can either be checked back into the ENOVIA/3DExperience, for example if you perform conversion of files, or you can collect the output and send it to a destination, such as FTP or Webservice etc.

Before digging into the details of the configuration format for such a job, we will start by showing an example of how such a configuration can look alike.

The example below illustrates how to utilize the external process to convert files inside ENOVIA/3DExperience into different formats. For readability, only one conversion is included. It is however possible to run several executions to create multiple different output variants.

<Job>
    <ExternalProcess>
        <Prepare>
            <MkDir dir="input" id="in" />
            <MkDir dir="output" id="out" />
            <Checkout format="generic" file="*.png,*.jpg,*.gif" into="${path:in}/${filename}" id="src-file" />
        </Prepare>

        <Exec forEachFileRef="src-file">
            <Executable>/usr/bin/magick</Executable>
            <Arguments>
                <Arg>${path:src-file}</Arg>
                <Arg>-resize</Arg>
                <Arg>120x120</Arg>
                <Arg>${path:out}${separator}${filename:src-file}</Arg>
            </Arguments>
            <PostActions>
                <Checkin
                    src="${path:out}${separator}${filename:src-file}"
                    format="Thumbnail"
                    fileName="${filename:src-file}"
                    overwrite="true" />
            </PostActions>
        </Exec>
    </ExternalProcess>
    <Events>
        <Error>
            <SendMail>
                <TO>...</TO>
                <CC>...</CC>
                <Subject>...</Subject>
                <Message>
                    message...
                    ${STACK_TRACE}
                </Message>
            </SendMail>
        </Error>
    </Events>
</Job>

Another example illustrating how to generate some output that later is transferred to another system is shown below:

<Job>
    <ExternalProcess>
        <Prepare>
            <SetParam name="currentState" select="current" />
            <SetParam name="someAttribute" select="attribute[Some Attribute]" />
            <ExtractPayload id="payload" config="MyPayloadConfig.xml" into="data.xml" />
            <Checkout id="src-file" format="generic" fileName="*.abc" into="${filename}" />
        </Prepare>
        <Exec>
            <Executable>/usr/bin/app</Executable>
            <Arguments>
                <Arg>${path:payload}</Arg>
                <Arg>${currentState}</Arg>
                <Arg>${someAttribute}</Arg>
            </Arguments>
        </Exec>
        <Output stdout="true" stderr="true">
            <Match dir="/" name="*.*" />
        </Output>
        <Destinations>
            <File id="..." />
        </Destinations>
    </ExternalProcess>
</Job>

Many configuration aspects are the same as for transfer data.

The main difference is the <ExternalProcess> element, which is described in the next chapter.

1.1. Configuration Details

The <ExternalProcess> element allows the following content

<Prepare>

Defines any preparations required. For example checkout files from ENOVIA/3DExperience, extract some payload data, set some parameters or create directories.

<Exec>

Describes what external process to execute, and what argument to pass. You can define multiple <Exec> elements if you need to invoke different processes or invoke with different arguments.

<Output>

Optional element used to describe what output to collect from the external process. This is often used together with <Destinations>.

<Destinations>

Defines destinations. Please read more here.

Each of these elements are defined in more detail in the next chapters.

1.2. Prepare

Preparing the external process execution is normally required. You may for example do any of the below:

Create directory or directories

Whenever you launch an external process, a dedicated working directory is created and the process is launched with that directory as working dir. You can create additional subdirectories here-in. That is accomplished by the <MkDir> element.

Checkout of files

You may checkout one or more files from the object, which you launch the job for. That is done via the <Checkout> element.

Creation of Payload data

You can also create meta data content using a payload definition. This is accomplished via the <ExtractPayload> element.

Set parameters

You can also set additional job-parameters that are available during the job execution. This is accomplished via the <SetParam> element.

For each of the prepare actions, you need to specify an id, which later is used when referencing the file or directory.

The id is used in many macros, to resolve its path, absolute path, name or extension.

Example:

<Prepare>
    <Checkout id="src-file" /> (1)
</Prepare>
<Exec>
    <Executable>...</Executable>
    <Arguments>
        <Arg>-input</Arg>
        <Arg>${path:src-file}</Arg> (2)
    </Arguments>
</Exec>
1 Associated the checked out files with the ID "src-file"
2 Reference the src-file
Element Attributes Description

<MkDir>

  • id (required)

  • dir (required)

Creates a directory within the working dir. The dir attribute specifies the name of the directory.

<Checkout>

  • id (required)

  • format (optional)

  • fileName (optional)

  • into (optional)

Checks out one or more files from ENOVIA.

If you do not configure "format" and "fileName" at all, those values are tried to retrieve from RPE variables (for example if you execute this job on for example check-in event) instead. If they are not present, the job will fail. However, you can also configure attributes with empty values to force all formats and/or filenames.

The format attribute can either be an empty string to force all formats, or, a comma separated list of ENOVIA format names.

The fileName attribute can either be an empty string to force all files, or, a comma separated list of wildcard match strings like .png,.gif. The file names are matched in case-insensitive mode.

<ExtractPayload>

  • id (required)

  • config (required)

  • into

Extracts the payload for the current object using the specified configuration and store the result in the specified file.

<SetParam>

  • name (required)

  • select (optional)

  • macro (optional)

  • allowEmpty (optional)

  • default (optional)

Can be used to set job parameters resolved from the current object, which the job is executed around.

In some cases when you only need one or a few attributes from the source object available, then it is easier to resolve these via the SetParam instead of using the ExtractPayload. The latter should be used when you have more data to be extracted.

1.3. Exec

The <Exec> element defines what to execute and what arguments to supply to the external process.

This element supports the following attributes:

Attribute Description

forEachFileRef

Defines an optional ID that refers to a file or files, which is provided by a prepare action. If the file reference ID refers to a collection of files, the executable will be executed for each of them.

processTimeout

Defines a timeout in milliseconds, which if exceeded will cause the external process to be stopped. Note that by default, no limit is specified.

And the supported child elements are

Element Attributes Description

<Executable>

-

Defines the executable to be invoked. Example: <Executable>/usr/bin/magick</Executable>

<Env>

  • name (required)

  • value (required)

Defines additional environment variables to be set while during the process execution.

<Arguments>

-

Defines the arguments to pass to the external process (see below).

<PostActions>

-

Defines optional post actions to be performed. Currently, only Checkin is a supported post operation.

The <Arguments> element allows nested <Arg> elements. Each occurrence of such child element will result in an argument to be passed at the same position.

The <Arg> element may contain macros, which can be used to resolve against the file-ids from the preparation tasks OR against job parameters. See: this document for more info around job macros.

To reference file/directory information created by the preparation actions, see the table below for information:

Example Description

${path:FILE_REF_ID}

Resolves the path relative from the working dir to the file with the specified ID.

${abspath:FILE_REF_ID}

Resolves the absolute path to the file with the specified ID

${filename:FILE_REF_ID}

Returns the file name of the file with the specified ID

${name:FILE_REF_ID}

Returns the file name excluding its suffix of the file with the specified ID

${ext:FILE_REF_ID}

Returns the suffix of the file with the specified ID

Other supported macros:

Example Description

${pathseparator}

The path separator for the current platform

${separator}

The separator for the current platform

${objectid}

The ID of the current business object

${basedir}

The workdir for the current execution (the absolute path)

The currently supported post actions defined below <PostActions> are shown below:

Element Attributes Description

<Checkin>

  • src (required)

  • format

  • fileName

  • overwrite

Checks in the source file into ENOVIA.

1.4. Output

The <Output> element is used when you want to collect the output from your external process. The output will typically be a ZIP file unless you only want to collect the standard output OR standard error from the external process.

To get standard output or standard error as output without being zipped, set either attribute "stdout" OR "stderr" true, not both. Do not include any Match child elements.

This element supports the following attributes:

Attribute Description

stdout

Defines if to include standard output. Default is false.

stderr

Defines if to include standard error. Default is false.

returnFirstMatch

An option that allows by-passing the creation of a ZIP file and just return the first found file according to the match instructions. Note that setting this to TRUE also requires at least one nested <Match> element to be present.

And the supported child elements are

Element Attributes Description

<Match>

  • dir (optional, string)

    • If omitted, root dir assumed

  • name (optional, string)

    • File name pattern, example: *.png. If omitted all files are matched. NOTE: The matching is performed case-insensitively.

  • recurse (optional, boolean, default: FALSE)

    • If set to true the dir is recursively walked to find files to be included

  • saveIn (optional, string)

    • Defines a static path for the files found regardless what directory they were created in

  • saveRelativeToRoot (optional, boolean, default: TRUE)

    • If set to FALSE then the target directory in the ZIP file is calculated relative from the dir attribute. This attribute is typically used together with the recurse attribute.

  • flatten (optional, boolean, default: FALSE)

    • If set to true, then the directory structure is ignored and any found file is added to the root of the ZIP file.

Defines what content to include in the generated ZIP file.

The <Match> element will define what files to be included in the generated ZIP file. Use wildcards on the name attribute to match more than one file.

Configuration example:

<Output stdout="true">
    <Match dir="${path:out-dir}" name="*.png" />
    <Match dir="${path:out-dir}" name="*.gif" />
</Output>