The tools are executed by using a command line call on the operating system via the "Execution Script". When the tool finished executing (with or without error), its exit code is handed back to the execution script and can be analyzed in this script. If in the script nothing else is done, the exit code is handed back to RCE. When there is an exit code that is not "0", RCE assumes that the tool crashed and thus lets the component crash without executing the "Post Script". Using the option "Exit codes other than 0 is not an error" can prevent the component to crash immediately. With this option enabled, the post script wil be executed in any way and the exit code from the tool execution can be read by using the placeholder from "Additional Properties". In this case, the post script can run any post processing and either not fail the component, so the workflow runs as normal, or let the compoennt crash after some debugging information was written using the Script API "RCE.fail("reason")".

Extending the common Tool Integration concept, the CPACS Tool Integration has some additional features.

All the features listed above can be configured in the tool integration wizard on the dedicated CPACS Tool Properties page.

The mappings can be specified by XML or XSLT as shown in the following examples. RCE differentiates between these methods in accordance to the corresponding file extension (.xml or .xsl).

For XML mapping, the following mapping modes are supported (see the mapping mode definitions in the mapping examples below):

If a target element described by the target path is not available in the XML file, it is created including all of its parent elements.

Example for an input or tool specific XML mapping :

<?xml version="1.0" encoding="UTF-8"?>
<map:mappings xmlns:map="http://www.rcenvironment.de/2015/mapping" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

    <map:mapping mode="append">
        <map:source>/path/to/your/element</map:source>
        <map:target>/toolInput/data/var1</map:target>
    </map:mapping>
    
    <map:mapping mode="delete">
        <map:source>/path/to/your/element</map:source>
        <map:target>/toolInput/data/var2</map:target>
    </map:mapping>

    <map:mapping mode="delete-only">
        <map:target>/toolInput/data/var3</map:target>
    </map:mapping>

    <map:mapping>
        <map:source>/path/to/your/element</map:source>
        <map:target>/toolInput/data/var4</map:target>
    </map:mapping>
    
    <xsl:for-each select="$sourceFile/result/cases/case">
        <map:mapping mode="delete">
            <map:source>/path/to/your/case[<xsl:value-of select="position()" />]/element</map:source>
            <map:target>/toolInput/data/condition[<xsl:value-of select="position()" />]/var</map:target>
        </map:mapping>
    </xsl:for-each>

</map:mappings>

Input or tool specific XSLT mapping:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="cpacs_schema.xsd">
 <xsl:output method="xml" media-type="text/xml" />
 <xsl:template match="/">
  <toolInput>
   <data>
    <var1>
     <xsl:value-of select="/path/to/your/element" />
    </var1>
   </data>
  </toolInput>
 </xsl:template>
</xsl:stylesheet>

Example of an output XML mapping:

<?xml version="1.0" encoding="UTF-8"?>
<map:mappings xmlns:map="http://www.rcenvironment.de/2015/mapping" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

    <map:mapping>
        <map:source>/toolOutput/data/result1</map:source>
        <map:target>/path/to/your/result/element</map:target>
    </map:mapping>

</map:mappings>

And output XSLT mapping:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" exclude-result-prefixes="xsi">
  <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>
  <!--Define Variable for toolOutput.xml-->
  <xsl:variable name="toolOutputFile" select="'./ToolOutput/toolOutput.xml'"/>
  <!--Copy complete source file to result file -->
  <xsl:template match="@* | node()">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()"/>
    </xsl:copy>
  </xsl:template>
  <!--Modify a value of an existing node-->
    <xsl:template match="/path/to/your/result">
    <element>  
    <xsl:value-of select="document($toolOutputFile)/toolOutput/data/result1"/>
    </element>
    </xsl:template>
</xsl:stylesheet>

Please ensure to use the proper namespace for map (xmlns:map="http://www.rcenvironment.de/2015/mapping") in XML mapping files and the proper namespace for xsl (xmlns:xsl="http://www.w3.org/1999/XSL/Transform") in both types of mapping files.

The figure below illustrates how the additional features are used in the run process of an user-integrated CPACS tool.

The way to integrate a CPACS tool on a server running RCE in headless mode is as follows: Perform the steps to integrate a CPACS tool on a client instance and make sure that the path of the CPACS tool configured on the Launch Settings page (step 8) matches the absolute tool path on your server system. Afterwards, you will find the configuration files inside your rce profile folder at the following location:

/integration/tools/cpacs/[YourToolName]

Copy the folder [YourToolName] to the same location inside the profile folder running with your headless server instance. Use the "auth" commands (cf. Section 3.5, “Tool publishing and authorization” ) to publish your tool. If the server instance is already running, your tool will be available immediately after publishing.

Before integrating the workflow shown above, we assume that you have already constructed a workflow that implements the behavior that you want to provide to other users as a component. Moreover, we assume that this workflow contains some input providers that feed initial data into the workflow and some output writers that persist the results of the computation implemented by the workflow. In the figure above, these input providers and output writers are situated to the left of the component DiscComp and to the right of the optimizer, respectively. Finally, the workflow to be integrated must not contain any placeholders (cf. Section 3.3.3.1, “Configuration Placeholder Value Files” ). Otherwise user input would be required at execution time in order to assign values, which would prevent automated execution of the integrated workflow.

Integrating a workflow consists of nothing more than determining endpoints of components in the inner workflow that will be exposed to the outer workflow by the resulting component. In this case, we opt to expose the input c of DiscComp as well as the output x_output of Optimizer. In general, inputs will be exposed as inputs on the component in the outer workflow, while outputs will be exposed as outputs. It is not possible to expose an input of a component in the inner workflow as an output to the outer workflow, or vice versa.

In order to integrate the above workflow as a component, we first remove the input providers and output collectors that handle the inputs and outputs that are to be passed into the inner workflow by the outer workflow. In the example above, we simply deactivate the two components (e.g. via the keyboard shortcut Ctrl + D) and obtain the workflow shown in the following figure.

While previously, all endpoints of all components were connected, now there exist two unconnected endpoints: The input c of DiscComp as well as the output x_optimal of Optimizer. The workflow is now ready for integration as a component.

Integration of workflows is performed via the command console and, in particular, via the command wf integrate. This command has the following general form:

wf integrate [-v] <component name> <absolute path to .wf file> [<exposed endpoint definition>...]

The optional argument -v enables verbose mode. If this parameter is set, the command outputs detailed information about the endpoints that are exposed to the calling workflows. This does not change the behavior of the command.

The parameter component name determines the name of the component that is integrated, i.e., the name that will appear in the pallet and in the workflow editor. Since in our example the purpose of the new component in our example is to determine some optimal parameter x, we opt to call the component FindOptimalX.

The parameter absolute path to .wf file is self-explanatory and denotes the path on your local file system where the workflow file describing the workflow to be integrated is located. In our example we assume that the workflow file is located at /home/user/workflow.wf.

Each succeeding parameter is interpreted as the definition of an exposed endpoint. Each such definition is of the following form:

--expose <component name>:<internal endpoint name>:<exposed endpoint name>

Here, component name refers to the name of the component in the inner workflow whose endpoint is to be exposed. The parameter internal endpoint name denotes the name of the endpoint of the component that is to be exposed, while the parameter exposed endpoint name determines the name of the endpoint on the resulting component. Make sure that each exposed endpoint name is unique within the context of the resulting component, as the behavior of a component with multiple inputs or outputs of the same name is undefined.

Recall that you do not need to specify whether the endpoint is exposed as an input or as an output, but that the underlying endpoint determines the configuration of the endpoint on the resulting component: Inputs are only ever exposed as inputs, whereas outputs are only ever exposed as outputs. This principle extends to the configuration of inputs: If the endpoint on the component in the inner workflow is, e.g., configured be required for component execution and to only expect a constant value, then the endpoint on the resulting component is configured analogously.

Furthermore recall that we want to expose the input c of DiscComp as well as the output x_output of Optimizer. We want the former input to retain its original name, while we want to expose the latter input as optimalX. In order to integrate the example workflow prepared above as a component, we thus issue the following command:

wf integrate FindOptimalX "/home/user/workflow.wf"--expose DiscComp:c:c --expose Optimizer:x_optimal:optimalX

When enabling verbose mode via the switch -v, RCE writes the following output

Input Adapter : c --[Float,Constant,Required]-> c @ 03b5b758-3b44-4a53-b832-be9991321285
Output Adapter: x_optimal @ 402cac5e-2206-48cc-a62f-803bd320a15a --[Float]-> x_opt

where 03b5b758-3b44-4a53-b832-be9991321285 and 402cac5e-2206-48cc-a62f-803bd320a15a denote the IDs of the component DiscComp and of Optimizer, respectively.

Once the execution of the command has finished, a new component named FindOptimalX with a single input named c and a single output named optimalX will be available for use in all other workflows.

Recall that each workflow that RCE executes is controlled by some particular instance, i.e., by the workflow controller. Since executing an integrated workflow executes the underlying workflow, RCE requires a workflow controller for doing so. That workflow controller may or may not be the same as the one executing the outer workflow. Currently, the instance executing the component serves as the workflow controller for the execution of the inner workflow. That instance will execute a copy of the workflow that has been created when the workflow was integrated, i.e., changes made to the workflow after integration will have no effect on the behavior of the integrated component.

Futhermore, since the publishing instance serves as workflow controller for the execution of the integrated workflow, the execution of the integrated workflow will show up in the datamanagement of the publishing instance under the name <component name> running as component '<node name>' of workflow '<outer workflow>', where <component name> denotes the name as which the publishing instance published the component, <node name> denotes the name under which the component is used in the outer workflow, and <outer workflow> denotes the name under which the calling workflow is stored in the data management of its workflow controller.

Technically, before starting the integrated workflow, the workflow controller injects two additional components into the workflow, one so-called input adapter and one so-called output adapter.These components are not accessible by the user when constructing workflows and are only used in transport data from the inputs to the component on the side of the calling workflow to the exposed inputs as well as data from the exposed outputs of the workflow to the outputs of the component in the calling workflow, respectively.

Upon execution of the integrated component in the calling workflow, the instance publishing the component first injects the input and the output adapter as described above. It subsequently executes the workflow and collects the results via the output adapter. The execution takes place as if the workflow were executed using the command wf run.

Since the integration of workflows as components is currently under development and only released as a beta feature, there are some caveats and known issues that you should be aware of. We have alluded to these limitations and caveats throughout this section, but briefly list them here again for the sake of readability.

Furthermore, there are some common questions that may occur in the context of integrating a workflow as a component. We collect and answer these questions here again for the sake of readability.