Workflow grammar

Owned by jrenbb
Last updated: Apr 19, 2016 by Alok Batra
3 min read
 Expand to see legends and methodology

Grammar definition methodology


General

There are five aspects that are important in TQL (and ADL) language specification. The first three has to do with Syntax:

1. Expansion: grammar rules that say one expression/component can be "expanded" into other expression(s)/component(s)

2. Containment (nesting): the nested XML/JSON tree structure for TQL components (e.g. Task "contains" Input, Invoke and Output)

3. Sequence: how the symbols are used in the correct sequence to generate meaningful expressions/components

The other two are about Semantics:

4. Semantics: what do the words/phrases mean and what value can they take as variables

5. Semantical hierarchy (System types): the inheritance relationship of system-defined types (such as Atom, String, Number, etc.)

#1 and #2 are systematically defined in the grammar definition, using containment graphs (like a tree). Containment graphs are read from top to down. The grammar itself does not confine the sequence between different child components of the same parent. However, there are places where different sequence will result in different execution of the code.

Since TQL (and ADL) is syntax free (currently supporting both XML and JSON), #3 (the sequence) mostly follows general XML grammar rules, and is self-explanatory. In places where there are TQL-specific rules, they are documented using the standard Railroad graph (with blue lines). Railroad graphs are read from left to right. Note that the language compiler does not make any distinction between XML elements and attributes. That is, any XML attribute can be given as an element and any element with text value can be given as an attribute.

#4 is documented in the grammar modifier tables.

#5 is documented in system defined types.


Legends & Notations

Terminal nodes are instances of the specified non-terminal used as an XML tag/container with the specified name.

Modifiers are terminal symbols (e.g."String", "Integer", "Duration" etc.) of a corresponding type.

Non-terminals and Non-terminal Modifiers are replaced by groups of terminal nodes or modifiers according to the production rules.

All terminals may contain any other content (e.g. TP parameters etc.). Such content is not governed by this grammar.


Function calls

Since this grammar is using the type system, some of the tag names are defined as function calls to current index API (e.g. fun.SubtypeOf(<type inheritance predicate>)). Such call is supposed to return a list of type names satisfying given predicate and one of them used as an actual tag name. Type predicates are logical expressions on type inheritance chains. For example (DataFacet and not.ThingFacet) means all types which inherit from DataFacet, but not from ThingFacet (this is because ThingFacet itself inherits from DataFacet and all descendants of DataFacet would also include all descendants of ThingFacet so we explicitly exclude them). It is assumed, that returned type lists will be relative to the current environment/scope. That is, only types defined in the scope of a current project need to be evaluated, as opposed to all types known to the system across all projects and all type repositories.

Cardinality

These are defined as 0..1, 1..1, 0..m, 1..m. Sometimes when multiples (>1) of the same child component structure are iterated under the same parent, the A-Stack recognizes their sequence of appearance and execute accordingly. For example, three Invokes within the same Task will be invoked sequentially to each other based on their order of appearance in the definition. In such cases, the cardinality is shown as [0..m] or [1..m].


Modifiers

TQL Modifiers can be written either as XML Elements or XML Attributes. The two are equivalent.



Go to page

Workflow

<Workflow  Limit="1" Live="1" Timeout="-1">...</Workflow>

<Workflow  Limit="5" Live="2" Timeout="PT3M">...</Workflow>

 

Referenced by:

Overall workflow structure definition

  • Limit: Maximum number of workflow instances existing at any given time.
  • Live: Maximum number of workflow instances running at the same time.
  • Timeout: Period of time after which a workflow instance is considered dead. Both XSD time period format and plain number of milliseconds allowed.

 

WfTask

<Task name="Main" while="true">

        ...

</Task>

 

Referenced by:

Task of workflow

  • While: Logical expression for repeatable tasks (only true/false is currently supported).

WfResult

Example


 <Workflow live="1" limit="1" Timeout="PT5S">  

       <Result name="ResponseCompleted" value="Response.$Completed" />

        <Task Name="Event" while="true">

              . ..

         </Task>

</Workflow>                 

Referenced by:

WfReturn

Example

<Workflow name="ExecuteRemoteQuery">

  <Return name="PostDataOutput" value="postTQLQuery.TQLResponse"/>

  <Task name="postTQLQuery">

    ...

  </Task>

</Workflow>

Referenced by:

WfInput

Example

<Workflow>
     ...
    <Task name="WdlTestTask">
      <Input name="Command" value="Input.Command"/>
       ...
    </Task>
  </Namespace>
</Workflow>

Referenced by: WfTask

WfOutput

Example

<Task name="Event" while="true">

         <Output name="RFID" skip-if="$NotOnSchedule([30..59/30sec])"/>

</Task>

Referenced by: WfTask

Output of workflow

  • SkipIf: Value guard. A logical expression to accept or reject the value.

LogInvoke

Example

  <Log level="info" name="Wait1" WaitFor="(Event1 or Event2) and (Event3 or Event4)" message="Trigger1 ([:WaitFor:])"/>

Referenced by:

InvokeGroup

Referenced by:

Workflow invokes with the Invoke tab name:

  • Name: Optional invoke name.
  • ExecuteInvoke - Command line invoke.

CommonInvokeArguments
Example

<Invoke name="ReadId" waitFor="Argument" get="[%:Event.Argument.URL.Value:%]"StopChar="0x0D" ReadTimeout="-1" WriteTimeout="-1" RepeatDelay="1"/>

Referenced by:

Common invoke arguments

  • WaitFor: A logical expression of possibly multiple outputs/events.
  • Unless: Delay termination output/event. Usually used with timeout/delay.
  • SkipIf: A logical expression to skip the invoke execution.
  • OnlyIf: A logical expression to execute invoke conditionally.
  • DelayUntil: Absolute invoke execution time.
  • DelayBefore: Invoke execution delay interval (delay before invoke starts executing).
  • Delay: Synonym for DelayBefore.
  • Timeout: Invoke type dependent hint. Different invoke types may interpret it differently.
  • DelayAfterInvoke result delay interval (delay after invoke has completed).

ScriptInvoke

Example
<Invoke name="JexlTest">
    <JexlScript>

          <!-- JexlScript Code -->

      </JexlScript>
</Invoke>

Referenced by: InvokeGroup

ExecuteInvoke

Example

<Invoke name="GetImage" url="[:Cart.URL:]" execute="sshpass ssh -o ConnectTimeout=10 -p 22 <usename>@<hostname> ls" />

Referenced by:

ExecuteInvoke - command line invoke

  • Execute: Command line to execute.
  • StdIn: Optional content of stdin stream.

HTTP Communications

Example

<Invoke name="neoRoot" get="http://localhost:7474/db/data/"/>

<Invoke name="Activate" post="[:Cart.URL:]/putxml" skip-if="[:isActive:]">

Referenced by:

HTTP Communications

  • HTTP GET - HttpGetInvokeArguments.
  • HTTP PUT - HttpPutInvokeArguments.
  • HTTP POST - HttpPostInvoke Arguments.
  • HTTP DELETE - HttpDeleteInvokeArguments.
  • get: http request URL for the method.
  • put: http request URL for the method.
  • post: http request URL for the method.
  • delete: http request URL for the method.

WfMessage

Example

<Message type="text/xml">

     <Value>

           <Command>

                       <Standby>

                              <Deactivate/>

                        </Standby>

             </Command>  

      </Value>

</Message>

Referenced by:

Serial Communications

Example

    <Invoke name="InvokeSerialRead" waitFor="Argument" get="perif://">...</Invoke>

Referenced by:

Serial Communications

  • get: device path regular expression (e.g. COM[3-9] or /dev/tty\\.usbserial.*).
  • put: device path regular expression (e.g. COM[3-9] or /dev/tty\\.usbserial.*).
  • post: device path regular expression (e.g. COM[3-9] or /dev/tty\\.usbserial.*).

CommonRxTxInvokeArguments

Example

<CreatePipeline arguments="RxTxServerExtensionArgs"

                            BaudRate="2400" StopChar="0x0D" />


Referenced by:

CommonRxTxInvokeArguments

  • MaxWait: Maximum message wait time in seconds.
  • OpenTimeout: Open timeout in msec.
  • ReadTimeout: Non-communication timeout in seconds.
  • WriteTimeout: Non-communication timeout in seconds.
  • RepeatDelay: Duplicate message delay in seconds.
  • OmitEmpty: Omit empty messages.
  • Encoding: Apply encoding/decoding to both the input and output. Only supported value is 'URL'.
  • DecodeOut: Apply decoding to the output message. Only supported value is 'URL'.
  • EncodeIn: Apply encoding to the input message. Only supported value is 'URL'.
  • Trim: Trim whitespace.
  • FlowControl: Possible values: in:rts/cts, out:rts/cts, in:xon/xoff, out:xon/xoff.
  • BaudRate: Interface baud rate.
  • DataBits: Possible values: 5,6,7,8.
  • StopBits: Possible values: 1,2,1.5.
  • Parity: Possible values: none,odd,even,mark,space.

Phidget Communications

Example

<Invoke name="ReadValue" waitFor="Argument"

                        post="phid://" SerialNumber="2"

                        DeviceType="PhidgetGPS"  delay="5" />


Referenced by:

CommonPhidInvokeArguments

Example

<Invoke name="ReadValue" waitFor="Argument"

                        post="phid://" SerialNumber="2"

                        DeviceType="PhidgetGPS"  delay="5" />

Referenced by: Phidget Communications (PhidInvokeArguments)

Perif Communications

Example

<Invoke name="InvokeZbee" waitFor="Argument" post="perif://">

  <Message>

    <Value>

      <InterfacePort>/dev/ttyUSB0</InterfacePort>

      <Baudrate>9600</Baudrate>

      <Interface>serial</Interface>

      <UniqueId>92034</UniqueId>

      <Operation>receive</Operation>

      <format>ascii</format>

      <Payload>$Null()</Payload>

      <Peripheral>serial</Peripheral>

    </Value>

  </Message>

</Invoke>


Referenced by:

CommonPerifInvokeArguments

Example

<Invoke name="InvokeZbee" waitFor="Argument" post="perif://">

  <Message>

    <Value>

      <InterfacePort>/dev/ttyUSB0</InterfacePort>

      <Baudrate>9600</Baudrate>

      <Interface>serial</Interface>

      <UniqueId>92034</UniqueId>

      <Operation>receive</Operation>

      <format>ascii</format>

      <Payload>$Null()</Payload>

      <Peripheral>serial</Peripheral>

    </Value>

  </Message>

</Invoke>

 

Referenced by: Perif Communications (PerifInvokeArguments)

USBCam Communications

Example

<Invoke name="GetImage" waitFor="ActionArgument" post="ucam://" >

  <Message>

    <Value>

      <USBCameraParameters>

        <ImageFormat></ImageFormat>

        <SaveToDisk></SaveToDisk>

        <ImageName></ImageName>

        <Size>

          <Height></Height>

          <Width></Width>

        </Size>

        <Configuration>

          <Standard></Standard>

          <Quality></Quality>

          <Channel></Channel>

          <Brightness></Brightness>

          <Contrast></Contrast>

          <Gamma></Gamma>

          <Gain></Gain>

          <Sharpness></Sharpness>

          <Saturation></Saturation>

          <Hue></Hue>

        </Configuration>

      </USBCameraParameters>

    </Value>

  </Message>

</Invoke>

Referenced by:

CommonUcamInvokeArguments

Example

<Invoke name="GetImage" waitFor="ActionArgument" post="ucam://" >

  <Message>

    <Value>

      <USBCameraParameters>

        <ImageFormat></ImageFormat>

        <SaveToDisk></SaveToDisk>

        <ImageName></ImageName>

        <Size>

          <Height></Height>

          <Width></Width>

        </Size>

        <Configuration>

          <Standard></Standard>

          <Quality></Quality>

          <Channel></Channel>

          <Brightness>]</Brightness>

          <Contrast></Contrast>

          <Gamma></Gamma>

          <Gain></Gain>

          <Sharpness></Sharpness>

          <Saturation></Saturation>

          <Hue></Hue>

        </Configuration>

      </USBCameraParameters>

    </Value>

  </Message>

</Invoke>

 

Referenced by: USBCam Communications (UcamInvokeArguments)

SMTP Communications

Example

<Invoke name="ReadValue" waitFor="Argument" post="smtp:<MailServer>" Hostname="<MailServer>">

  <Message>

    <Value>

      <Port>[:Port:]</Port>

      <Username>[:Username:]</Username>

      <Password>[Password:]</Password>

      <From>[:From:]</From>

      <To>[:To:]</To>

      <CC>[:CC:]</CC>

      <Subject>[:Subject:]</Subject>

      <Body>[:Body:]</Body>

      <StartTLS>[:StartTLS:]</StartTLS>

    </Value>

  </Message>

</Invoke>

Referenced by:

CommonSMTPInvokeArguments

Example

<Invoke name="ReadValue" waitFor="Argument" post="smtp:<MailServer>" Hostname="<MailServer>">

  <Message>

    <Value>

      <Port>[:Port:]</Port>

      <Username>[:Username:]</Username>

      <Password>[Password:]</Password>

      <From>[:From:]</From>

      <To>[:To:]</To>

      <CC>[:CC:]</CC>

      <Subject>[:Subject:]</Subject>

      <Body>[:Body:]</Body>

      <StartTLS>[:StartTLS:]</StartTLS>

    </Value>

  </Message>

</Invoke>

Referenced by: SMTP Communications (CommonSMTPInvokeArguments)