TIF ENOVIA Connector - Launch External Process

18 October 2016

1. Launch External Process

This kind of integration job is used for launching external processes, with input that can be files that are checked-out from ENOVIA or data that is extracted from ENOVIA.

The output from the external processing can either be checked back into ENOVIA, 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 into different formats. For readability, only one conversion is included. It is however possible to run several executions to create multiple differet 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>
            <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>
            </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 or extract some payload data 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.

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.

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>

<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 occurence of such child element will result in an argument to be passed.

The <Arg> element may contain macros, which is resolved to file-ids from the preparation tasks. Such macro may be define in a couple of different ways, see the table below:
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.

And the supported child elements are

Element Attributes Description

<Match>

  • dir (if omitted, root dir assumed)

  • name (file name pattern)

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.

Example:

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