Work with execution flow commands

This section describes about the execution flow commands such as Run, Log and Branch commands.

Run

The Run command allows an external call to execute a command. In conjunction with other Read commands and filters, this allows execution of a sub process based on input data.

For example, you may read information interfaces (custom extensions) of a given type from loaded ISM configurations then execute a sub configuration for each interface, optionally using functions on configuration details to determine which specific sub-configuration to run.

The following table lists the Run parameters in detail.

The following table lists the Run Trigger parameters in detail.

The following table lists the Run templates in detail.

Run registers gateway as a nested process

The following example calls the Registers gateway with a different config, passing in a parameter evaluated from the data being processed:

Example:

<run>

<arg>{{ $[working-dir]}}\capture-{{ @[register-type] }}.cfg</arg>

<arg>variables:interface={{ @[register-name] }}</arg>

</run>

Run AIM import controller

Run the AIM import controller, which does not return anything other than exit code 0, and use the output to detect if an error occurs.

Example:

<run

success-exit-code="0"

cmd="{{ $[!anet-import-exe] }}"

timeout="120"

standard-out-to-log="true"

max-retries="10"

retry-pause="{{ $attempt.multiply($attempt) }}">

<arg>process</arg>

<arg>package</arg>

<arg>/EngineHost:{{ $[!anet-import-server] }}</arg>

<arg>/EnginePort:{{ $[!anet-import-port] }}</arg>

<arg>/Id:{{ $[!anet-import-database] }}</arg>

<arg>/Package:{{ $[!anet-import-package] }}</arg>

<arg>/Force:false</arg>

<arg>/Wait:true</arg>

<arg>/object:{{ $[!anet-import-package] }}|{{ @[anet-folder] }}</arg>

<trigger action="warning" where="{{ $stdout contains 'ImportErrorWarning' }}"/>

<trigger action="error" where="{{ $stdout contains 'ImportErrorMessage' }}"/>

<trigger

action="retry"

where="{{ $stdout contains any ['Error checking out license', 'Import Server not available'] }}"

/>

</run>

Run robocopy

Run robocopy with common success exit codes.

Example:

<run success-exit-code="0-7,16" cmd="robocopy" timeout="15" standard-out-to-log="true">

<arg>*{{@PidProject}}.*</arg>

<arg>{{ $[output-folder] }}</arg>

<arg>{{ $[data-load] }}</arg>

<arg>/move</arg>

</run>

Run AutoCAD gateway with retry on licence checkout fail

Run the AutoCAD gateway and retry on a license checkout with increasing delay each attempt (because gateways currently do not retry or give a useful exit code to use).

Example:

<run cmd="C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway Configuration Tool\GatewayConfig.exe" timeout="1"

standard-out-to-log="true"

max-retries="5" retry-pause="{{ $attempt.multiply($attempt) }}">

<arg>{{ @fullname }}</arg>

<arg>{{ @parentfolder }}</arg>

<arg>{{ $[working-dir] }}\ac2d_{{$type}}.xml</arg>

<arg>-lg{{ $[working-dir] }}\logs\{{ @name }}.log</arg>

<arg>-gAC2D</arg>

<arg>-oSVG</arg>

<arg>-noProgress</arg>

<trigger action="retry" where="{{ $stdout contains 'Error checking out license' }}" />

</run>

Run AutoCAD gateway with parameterized configuration

Run a gateway and evaluate expressions in the config file to add flexibility.

Example:

<run cmd="{{ $[dwg-gateway-exe] }}" timeout="1" standard-out-to-log="true" max-retries="5" retry-pause="{{ $attempt.multiply($attempt) }}" evaluate-file-args="true">

<arg>{{ @fullname }}</arg>

<arg>{{ @parentfolder }}</arg>

<arg>{{ $[working-dir] }}\dwg_ac2d_{{ $[type] }}.xml</arg>

<arg>-lg{{ $[working-dir] }}\..\..\logs\{{ @name }}.log</arg>

<arg>-gAC2D</arg>

<arg>-oSVG</arg>

<arg>-noProgress</arg>

<trigger action="retry" where="{{ $stdout contains 'Error checking out license' }}" />

</run>

This run command then checks if anything is to be evaluated in the ACAD config file.

Run executable with protected configuration file details

Run a gateway and ensure sensitive information remains protected and encrypted at rest.

Example:

<run name="get_docregister" evaluate-file-args="true">

<cmd>{{ $[!aconex-gateway-exe] }}</cmd>

<arg>{{ $[working-dir] }}\trw.xml</arg>

</run>

with aconex gateway config:

<config>

<useSSL>true</useSSL>

<aconexHost>{{ $[!aconex-host].unprotect }}</aconexHost>

<projectId>{{ $[!aconex-project-id].unprotect }}</projectId>

<applicationKey>{{ $[!aconex-application-key].unprotect }}

</applicationKey>

<searchPattern>

<![CDATA[

]]>

</searchPattern>

and with regi.json file:

{

"Variables": {

"!aconex-gateway-exe": "..\\..\\..\\..\\aconex gateway\\sampleproject\\aconexservicegateway.exe",

"!aconex-host": "<REDACTED>zoW",

"!aconex-project-id": "<REDACTED>QSYc",

"!aconex-application-key": "<REDACTED>rg4=",

"!aconex-login": "<REDACTED>ivT7",

"!aconex-password": "<REDACTED>MFYY"

}

}

Log

The Log command enables configurable logging of messages.

Note: The logging is primarily intended for determining what happened at a system level and is not intended for user consumption.

However, as this is required sometime, two levels of logging output are emitted by default – one with only Errors, Warnings, and Information, which are much simpler to read.

The following table lists the Log parameters in detail.

The following table lists the LogRuleConfig parameters in detail.

Branch

The branch filter creates a branch in a pipeline that, as well as sending each object on to the next filter, also sends the object into the branch. It does not require any parameters.

The branch may contain any sequence of filters, including other branches if so desired, and may also include READ commands if that makes sense, though not currently as the first object.

Multiple branches containing WHERE filters may be used to implement decision making logic.

Branch flow to update two sql tables

The following would read a source and populate details and attribute level reporting tables.

Example:

<read output-limit="{{ $[output-limit] }}">

<waypoint folder="{{ $[waypoint-root] }}\master\operational"/>

</read>

<branch>

<select>

<fields>

<field name="ObjectID" value="{{ $[this.waypoint.index] }}"/>

<field name="ObjectName" value="{{ $[this.id].slice('|', -1) }}"/>

<field

name="ObjectFullName"

value="{{ '|'.join($project, $[this.id]) }}"

/>

<field name="ObjectDescription" value="{{ $[this.name] }}"/>

<field

name="ObjectClass"

value="{{ COALESCE($[this.class], 'UNKNOWN') }}"

/>

<field name="ObjectState" value="{{ @[TAG_STATUS] }}"/>

</fields>

</select>

<write>

<sqlserver

connection-string="{{ $[reporting database] }}"

target-table="EDW_Functional"

date-created-field="CreatedDate"

date-updated-field="LastModified"

>

<keys>

<key name="ObjectID"/>

</keys>

</sqlserver>

</write>

</branch>

<branch>

<pivot>

<field name="ObjectID" value="{{ $[this.waypoint.index] }}"/>

<field name="ObjectFullName" value="{{ '|'.join($project, $[this.id]) }}"/>

<field name="AttributeID" value="{{ $[attr.name] }}"/>

<field name="AttributeValue" value="{{ $[attr.value] }}"/>

<field name="AttributeUOM" value="{{ $[attr.units] }}"/>

<field

name="Include"

value="{{ if (FieldIsReference.isFalse or FieldPreservesAttribute) and ($[attr.name] not in ['class', 'unit']) then 'y' }}"

/>

</pivot>

<where condition="{{ @include equals 'y' }}"/>

<write>

<sqlserver

connection-string="{{ $[reporting database] }}"

timeout="600"

target-table="EDW_Functional_Attributes"

date-created-field="CreatedDate"

date-updated-field="LastModified">

<keys>

<key name="ObjectID"/>

<key name="AttributeID"/>

</keys>

</sqlserver>

</write>

</branch>