Referring to workflow components

(This is a draft of a document addressing issue #2)

RestFlow defines a standard format for referring to actors and nodes in documentation and other text meant primarily for human consumption. These standards are by used RestFlow when producing logging and exception messages as well as in text renderings of traces.

The names of nodes are enclosed in square brackets, [NodeName], and actors in angle-brackets, <ActorName>, even in documentation, so that it is always clear whether what type of component a name refers to (this also reduces the need to include the words 'Node' or 'Actor' in component names). The square brackets for nodes alludes to the fact that nodes are often represented as blocks in workflow diagrams. The angle brackets are inspired by the template/generics type notation of C++, Java, and C#. A node can be thought of as a placeholder (or template) for computations, with actors providing the concrete implementations of those computations.

Because workflows are actors, the names of workflows (and sub-workflows) are also enclosed in angle brackets. Containment of a node by a workflow is indicated either by placing the node (and associated actor if relevant) on a new, indented line following the name of the workflow (see Examples below); or by separating the workflow and the contained node by a forward slash on the same line, e.g. <WorkflowName>/<NodeName>. (Spaces may be placed on either side of the slash to make it easier to see the node-actor pair at each level of nesting.) The multiline format is preferable wherever space permits. Deeper nesting is indicated by increasingly indented lines of text, with a node and actor on each line; or by additional / symbols.

Examples

Outside the context of a workflow

Node

[NodeName]

[my.nodes.NodeName]

Actor

<ActorName>

<my.actors.ActorName>

In the context of a workflow

Node configured to use a particular actor

[NodeName]<ActorName>

[my.nodes.NodeName]<my.actors.ActorName>

Node in a top-level workflow

<WorkflowName> / [NodeName]

<WorkflowName>
   [NodeName]

<my.workflows.WorkflowName> / [my.nodes.NodeName]

<my.workflows.WorkflowName>
   [my.nodes.NodeName]

Actor in a top-level workflow

<WorkflowName> / [NodeName]<ActorName>

<WorkflowName>
   [NodeName]<ActorName>

<my.workflows.WorkflowName> / [my.nodes.NodeName]<my.actors.ActorName>

<my.workflows.WorkflowName>
   [my.nodes.NodeName]<my.actors.ActorName>

Node in a singly nested workflow

<WorkflowName> / [NodeName]<SubworkflowName> / [AnotherNodeName]

<WorkflowName>
   [NodeName]<SubworkflowName>
      [AnotherNodeName]

<my.workflows.WorkflowName> / [my.nodes.NodeName]<your.workflows.SubworkflowName> / [your.nodes.AnotherNodeName]

<my.workflows.WorkflowName>
   [my.nodes.NodeName]<your.workflows.SubworkflowName>
      [your.nodes.AnotherNodeName]

Actor in a singly nested workflow

<WorkflowName> / [NodeName]<SubworkflowName> / [AnotherNodeName]<ActorName>

<WorkflowName>
   [NodeName]<SubworkflowName>
      [AnotherNodeName]<ActorName>