<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<sect1 id="tool_access">
	<title>Remote Workflow Access</title>
	<para>RCE provides the possibility to publish complete workflows which can then be accessed and run 
	via Remote Access Connections from other RCE instances.</para>
	<para>This section describes how to publish 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. </para>
	<sect2>
		<title>Setting up the Workflow Execution Example/Template</title>
		<para>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.</para>
		<para>
			<itemizedlist>
				<listitem>
					<para>Configure your RCE instance as an SSH Remote Access Server as described in 
					<xref linkend="ra-connections"/>.</para>
				</listitem>
				<listitem>
					<para>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. </para>
				</listitem>
				<listitem>
					<para>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.</para>
				</listitem>
				<listitem>
					<para>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.<note>
							<para>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.</para>
						</note></para>
				</listitem>
				<listitem>
					<para>To make the workflow available for remote execution, enter the command <code>ra-admin
							publish-wf "<replaceable>&lt;workflow file></replaceable>"
								<replaceable>&lt;id></replaceable></code> in the command window.
						Press Ctrl-V in place of <replaceable>&lt;workflow file></replaceable> to
						insert the path to your workflow file there. For
							<replaceable>&lt;id></replaceable>, 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.</para>
					<note>
						<para>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
								<code>ra-admin unpublish-wf &lt;id></code> command to remove a
							published workflow from remote access.</para>
						<para>To publish a workflow for the current RCE instance's life-time only,
							use the <code>-t</code> option: <code>ra-admin publish-wf -t
									"<replaceable>&lt;workflow file></replaceable>"
									<replaceable>&lt;id></replaceable></code>.</para>
					</note>
				</listitem>
				<listitem>
					<para>If some of the workflow's components use placeholders for configuration values, you can
						use the <code>-p</code> option to specify a placeholder values file. The
						structure of placeholder value files is explained in <xref
							linkend="placeholder_files"/>. Placeholder files can used with both
						persistent and non-persistent workflows (see above).</para>
					<para>Example: <code>ra-admin publish-wf -p myPlaceholderValues.json myWorkflowFile.wf
							myPublishId</code></para>
				</listitem>
				<listitem>
					<para>You now have a workflow file that can be executed using the "Remote Access"
						feature.</para>
				</listitem>
				<listitem>
					<para>Configure another RCE instance an SSH Remote Access Client as described in 
					<xref linkend="ra-connections"/> and connect it to the instance publishing the workflow
					The workflow will now be shown as a component in the palette of the client instance and 
					can be used in workflows like any another component.</para>
				</listitem>
				<listitem>
					<para>To get an impression of how this feature interacts with existing RCE
						features, you can examine several areas within the RCE instance.<itemizedlist>
							<listitem>
								<para>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.</para>
							</listitem>
							<listitem>
								<para>Open the "Workflow Console" view; if the tool produced any
									output, it should be visible there.</para>
							</listitem>
							<listitem>
								<para>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).</para>
							</listitem>
						</itemizedlist></para>
				</listitem>
			</itemizedlist>
		</para>
	</sect2>
	<sect2>
		<title>Building Your Own Remote Access Workflow</title>
		<para>After running the example/template workflow as described in the previous section, you
			can proceed to building your own actual workflow.</para>
		<para>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.</para>
		<para>There are two basic approaches to building your workflow:<itemizedlist>
				<listitem>
					<para>Either you start with an SCP Input Loader and an SCP Output Collector 
					    (either drag them into the workflow from the Palette, or modify 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.</para>
				</listitem>
				<listitem>
					<para>The other approach is to build your workflow normally, where you add an Input Provider
						and Output Writer 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 <emphasis>except</emphasis> 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 (SCP Input Loader and SCP Output Collector) as in your original
						workflow.</para>
					<note>
						<para>(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.</para>
					</note>
				</listitem>
			</itemizedlist></para>
		<para>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.<note>
				<para>Tip: To repeat a previous command, presse the "up arrow" key in the Command
					Console window.</para>
			</note></para>
	</sect2>
</sect1>
