RCE provides an interface that allows external applications to access and run single tools or complete workflows within RCE instances. This allows existing applications to make use of RCE's features (like network distribution, data management, logging, ...) when integrating the application itself is not possible or desirable. For example, applications that are based on frequent user interaction are not a good fit for being run as part of an automated workflow, but may still want to use some of RCE's features.
This section describes how to publish tools or workflows such that they can be used via Remote Access. It will guide you through the creation of a simple example, which you can expand to build your own solutions.
The basic idea of the Remote Access interface is that the external application opens an SSH connection to RCE, and initiates the tool or workflow execution via text commands. Input and output data, as well as log files, are transfered using SCP. For using the integrated tools and workflows remotely, a standalone remote access tool is currently under development and will be released soon. The integrated tools can also be used in a remote RCE instance via SSH connections.
In RCE 5.0.0, the "remote access" feature was able to invoke a single integrated tool. Starting with RCE 5.1.0, arbitrary user-defined workflows can be executed. The following sections describe each approach separately.
These steps will guide you through the configuration of an integrated tool. Using this example, you will be able to easily integrate your own text-based tools into RCE and invoke them using the Remote Access interface.
Setting RCE up as a "Remote Access Server".
Download and unpack/install an RCE distribution.
Start RCE and select the "Help > Configuration Information" menu option. From the list of configuration examples, double-click "Remote Access Server" to open it. Mark all text (Ctrl-A) and copy it to the clipboard (Ctrl-C).
Select the "Help > Open Configuration File" menu option, select all text (Ctrl-A) and paste the copied text from the example configuration.
Save the file, and select "File > Restart" to apply the new configuration. The Remote Access SSH interface is now running, with a pre-configured SSH account of "ra_demo", password "ra_demo".
IMPORTANT: "ra_demo" is just an example account for testing within a secure network. Create a new account with a better password (for example using the configuration UI described in the "Configuration" section) before using the Remote Access interface in production. Publishing tools using this default account is a potential security risk.
Define an example tool using the following steps.
Select the "File > Integrate Tool" menu option.
Follow the tool integration wizard to integrate your tool (more information can be found using the help function in RCE and in the chapter "Integration of External Tools" of this user guide.
Publish your tool in the "public" group (cf. Section 3.5, “Tool publishing and authorization” ) to make the tool available via Remote Access.
You now have an example tool that can be accessed with the "Remote Access" feature. How to setup a client to access this tool see the "Configuring an RCE instance as an SSH client" section
To get an impression of how this feature interacts with existing RCE features, you can examine several areas within the RCE instance.
Open the "Workflow List" view in RCE and watch it while the "run-tool" script is executing. After a short preparation time where the input data is uploaded, you will see the automatically generated workflow containing the tool being executed. It will disappear automatically if it finishes successfully; if it fails, it will remain in the list for review.
Open the "Workflow Console" view; if the tool produced any output, it should be visible there.
Open the "Workflow Data Browser" and refresh it; there should be a "Remote_Tool_Access-..." workflowe entry matching the remote tool run. When you expand this entry, you should see the uploaded content of the input folder, the generated output folder, any generated text output (in the "Execution Log" folder), and the exit code of the tool process (also in the "Execution Log" folder). It will disappear automatically if the tool finishes successfully
These steps will guide you through the creation of a remote-executable workflow, and will show you how to invoke it using the provided example scripts.
Download and unpack/install an RCE distribution.
Run RCE and select the "Help > Open Configuration Information" menu option. From the list of configuration examples, double-click "Remote Access Server" to open it. Mark all text (Ctrl-A) and copy it to the clipboard (Ctrl-C).
Select the "Help > Open Configuration File" menu option, select all text (Ctrl-A) and paste the copied text from the example configuration.
Save the file, and select "File > Restart" to apply the new configuration. The Remote Access SSH interface is now running, with a pre-configured SSH account of "ra_demo", password "ra_demo".
IMPORTANT: "ra_demo" is just an example account for testing within a secure network. Create a new account with a better password (for example using the configuration UI described in the "Configuration" section) before using the Remote Access interface in production. Publishing tools using this default account is a potential security risk.
As a first example we are going to execute the umodified "Remote_Workflow_Access_Template" workflow file in the Workflow Examples Project. If you haven't created this project already, right-click in the Project Explorer on the left side, and choose "New > Workflow Examples Project", and choose a name for it. The template file is contained within the project folder. To get an impression of the basic setup, open the template workflow file. You will see an SCP Input Loader on the left side with two outputs. On the right side, there is an SCP Output Collector with one input (these two are helper components that are only used for remote access workflows). These are the points where the Remote Workflow Access feature sends the provided inputs into your workflow, and collects the final outputs.
As a security measure, you need to explicitly publish your workflow to allow remote access to it. This is done via a console command at this time; future RCE versions will most likely add a option to do this from the GUI. To issue this command, open the "Command Console" view (if it is not already visible) by selecting "Windows > Show View > Other" from the menu, and then double-clicking "Command Console" in the "RCE" section.
Right-click your workflow file in the "Project Explorer" and select the "Copy full path" entry in the popup menu to copy the full path to the workflow file to the clipboard.
This step demonstrates how the get the path of a workflow file in the current workspace, but you can use workflow files that are located anywhere on your system.
To make the workflow available for remote execution, enter the command ra-admin
publish-wf " in the command window.
Press Ctrl-V in place of <workflow file>"
<id><workflow file> to
insert the path to your workflow file there. For
<id>, choose a string (without whitespace)
that callers can use to execute the workflow. Press "enter" to execute the
command. The workflow file will be inspected, and you will either see a
message describing what is missing, or a message that the workflow was
successfully published. Fix any errors until the workflow is
published.
Starting with RCE 6.2.0, published workflows are persistent by default, so they will
still be available after the local RCE instance is restarted. Use the
ra-admin unpublish-wf <id> command to remove a
published workflow from remote access.
To publish a workflow for the current RCE instance's life-time only,
use the -t option: ra-admin publish-wf -t
".<workflow file>"
<id>
If some of the workflow's components use placeholders for configuration values, you can
use the -p option to specify a placeholder values file. The
structure of placeholder value files is explained in Section 3.3.3.1, “Configuration Placeholder Value Files”. Placeholder files can used with both
persistent and non-persistent workflows (see above).
Example: ra-admin publish-wf -p myPlaceholderValues.json myWorkflowFile.wf
myPublishId
You now have a workflow file that can be executed using the "Remote Access" feature.
To get an impression of how this feature interacts with existing RCE features, you can examine several areas within the RCE instance.
Open the "Workflow List" view in RCE and watch it while the "run-wf" script is executing. After a short preparation time where the input data is uploaded, you will see the workflow being executed. It will disappear automatically if it finishes successfully; if it fails, it will remain in the list for review. You can also double-click on a running or workflow to monitor its execution.
Open the "Workflow Console" view; if the tool produced any output, it should be visible there.
Open the "Workflow Data Browser" and refresh it; there should be an entry for the Remote Access workflow. When you expand this entry, you should see the uploaded content of the input folder, the generated output folder, any generated text output (in the "Execution Log" folder), and the exit code of the tool process (also in the "Execution Log" folder).
After running the example/template workflow as described in the previous section, you can proceed to building your own actual workflow.
As described above, open the "Remote_Workflow_Access_Template" workflow file. You will see an SCP Input Loader on the left side with two outputs. On the right side, there is an SCP Output Collector with one input (these two are helper components that are only used for remote access workflows). These are the points where the Remote Workflow Access feature sends the provided inputs into your workflow, and collects the final outputs. You can change the data types or add/delete inputs/outputs in the properties view of the input loader/output collector. The Script component in the middle is just a placeholder - unless you need a Script component anyway, you can just delete it.
There are two basic approaches to building your workflow:
Either you start with the template, and build your workflow between the two standard components. This is straight-forward, but means that you cannot test run the workflow from the RCE GUI (as the Input Loader will fail), but have to use the Remote Access feature to test it.
The other approach is to build your workflow normally, where you add an SCP Input Loader and SCP Output Collector with the outputs and inputs you need. You can then test (and if needed, modify) your workflow from the GUI until it behaves as it should. Then, mark all components except the Input Provider and Output writer in your workflow, and select "Copy" from the right-click menu. Switch to the template file, click an empty area, and select "Paste" from the right-click menu. Then, connect the two template components (Input Provider and Output Writer) as in your original workflow.
(Advanced Usage) You can also build your workflow in the template file, add your own Input Provider and Output Writer, and use the new "Enable/Disable Component" feature to toggle between them for testing and Remote Access usage. As this requires some helper components to work, this is not recommended for your first example, but may be a useful trick to keep in mind.
After you have finished building your workflow, the process of publishing and executing it is the same as described above for the unmodified template file. Please note that publishing your workflow for remote execution automatically creates an (invisible) copy of it. Modifications you make to your workflow file are not published right away. Once you have made the changes you want to publish, run the same "ra-admin publish-wf" command again to update the published version.
Tip: To repeat a previous command, presse the "up arrow" key in the Command Console window.