Process flow definition file - Appistry EAF v3.7

Process Flows. Fabric process flows enable a fabric developer to organize their deployed task actions into a series of activities that fulfill a single client request. The developer declaratively describes a series of process flow activities for the fabric to execute. These activities may be execution of user-defined task code in Java, .NET or C/C++, or it may be a sub-process flow defined by the user. Additionally, the process flow defines any error handling steps in the event of problems. The fabric handles all of the rest. The developer does not write code to implement reliability, scalability or fault-tolerance. The simplest of business objects deployed as task actions in a fabric gain these benefits automatically. Process flows are defined in XML files as described below.

A single process flow represents a single type of request an application can handle. The process flow state represents a task or sub-process and the transition between that state and the next state in the process flow. The result of a task advances the process flow to the next state. The process flow definition file identifies the process, states, tasks, sub-processes, and state transition arcs.

Below is the basic syntax of a process flow definition file.

<?xml version='1.0'?>
<!DOCTYPE process SYSTEM 'ProcessDefinition.dtd'>
<process name='name' default_retries='number' default_timeout='number'>
  <group-access>
    <group name='group name'/>
    <group name='group name'/>
  </group-access>
  <state name='start' snapshot='true or false'>
    <task name='name' retries='number' timeout='number'/>
    <arc task-status='status' task-result='user defined' next-state='state'/>
  </state>
  <state name='name' snapshot='true or false'>
    <task-affinity task='isAvailableTask'>
      <resource-argument request-key='request attribute key'/>
      <rank-argument rank-type='max-weight or min-weight'/>
    </task-affinity>
    <task name='name'/>
    <arc task-status='status' task-result='user defined' next-state='state'/>
  </state>
  <state name='name' snapshot='true or false'>
    <sub-process name='name'/>
    <arc task-status='status' task-result='user defined' next-state='state'/>
  </state>
</process>

Process element	The process element has three attributes: name, default_retries, and default_timeout. The name attribute specifies the name of the process flow. This attribute is case sensitive. The name attribute can consist of alphanumeric characters (upper or lower case), hyphens , and underscores (_). The default_retries attribute is the number of times a task in this process flow is re-attempted before returning an error. A task element may also define a retries attribute which overrides the default_retries for that given task. The default_timeout attribute is the maximum amount of time, in seconds, a task in this process flow can take to complete before returning an error. A task element may also define a timeout attribute which overrides the default_timeout for that given task. A value of INFINITE means that the task will not be timed out. Please note however that the fabric Task APIs define methods allowing the task developer to override the process flow task timeout from within the executing task, allowing for tuning during execution. Below is an example of a process element. <process name='order_item' default_retries='2' default_timeout='2'>
Group-access element	The group-access element identifies the list of groups authorized to run the process flow. You can allow a group to run some process flows in an application and not other process flows. This element is optional. If you include group-access in the application definition file, it must follow the process element. Only groups authorized to run an application may run the process flow. If this element is not present, all groups with authorization to run the application can run the process flow.
Group element	The sub-element group has one attribute, name. The name attribute specifies the group name authorized to run the process flow. This element is only available if the group-access element is included in the process flow. Consult with your fabric administrator for group members and group names. Below is an example of the group-access and group elements. <group-access> <group name='group name'/> </group-access>
State element	Each state in the process flow represents a task or sub-process and the transition between that state and the next state in the process flow. The result of a task advances the process flow to the next state. A state element has two attributes: name and snapshot. The name is the name of the state and is case sensitive. The name attribute can consist of alphanumeric characters (upper or lower case), hyphens , and underscores (_). The snapshot attribute allows you to backup the process flow state when the task is completed. This allows a process flow whose current task fails, to continue from the last state snapshot. If snapshot='true', the state is backed up. If snapshot='false', the state is not backed up. If a task's retries are set to 0, then a snapshot automatically backs up the process flow state regardless of the snapshot setting. The state element must follow the group-access element if it is included in the process flow definition. If the group-access element is not included, the state element must follow the process element or a state element. Below is an example of a state element. <state name='hold-item' snapshot='true'>
Task element	A task is an action to be performed within the process flow. A task is categorized as repeatable or non-repeatable. A repeatable task is one that repeating in a failure condition does not affect the result. For example, if a task verifying a network connection ends in an undetermined state, the task can be repeated. The fabric considers any task defining 1 or more retries repeatable. A non-repeatable task is one that would be undesirable to repeat in a failure condition. For example, if a task posting a charge to an account ends in an undetermined state, the task should not be repeated since the charge may have been posted. The fabric considers any task defining 0 retries as non-repeatable. A task has three attributes: name, retries, and timeout. The name attribute is the name of the task and must be identical to the task name in the task definition file. This attribute is case sensitive and is required. The retries attribute specifies the number of times a task is re-attempted before returning an error. For example, if retries='0', the task is attempted one time, the original execution. If a task is considered non-repeatable, set the retries attribute to 0. Appistry recommends designing your process flow so you can set retries to 1 or more. This attribute overrides, for this task, the process flow default_retries attribute. The timeout attribute specifies the maximum amount of time, in seconds, a task can take to complete before returning an error. If a task defines a non-infinite timeout, and the task execution exceeds that timeout limit, the fabric attempts to retry this task when the task-status attribute (discussed below) is not-attempted or the connection to the worker running the task fails. If timeout='infinite', the task will not timeout. This attribute overrides, for this task, the process flow default_timeout attribute. A value of INFINITE means that the task will not be timed out. Please note however that the fabric Task APIs define methods allowing the task developer to override the process flow task timeout from within the executing task, allowing for tuning during execution. The task element must follow a state element. Below is an example of a task element. <task name='ItemHold' retries='1' timeout='1'/>
Task-affinity element	A task-affinity element identifies an affinity task to be performed in the process flow. An affinity task is a task that locates a needed resource in the fabric, such as a file stored on a worker. If an affinity task locates the resource, the process flow directs the state's main task execution to the worker having the resource. An affinity task may only be used in a process flow state that uses a task element action. The task-affinity element has only one attribute: task. The task attribute is the name of a task referenced by the task-affinity element in the task definition file. The name must be identical to the task-affinity name in the task definition file, is case sensitive, and is required. <task-affinity task='isAvailableTask'/>
Resource-argument element	The resource-argument element identifies resources required to execute the process flow's current state task. The user-defined resource may be hardware, for example available RAM on a worker, software, a file, etc. The request-key attribute specifies the name of a task request name/value pair, whose value is passed as an argument to the affinity task method as input. The resource-argument element is only available with the task-affinity element and is optional. Below is an example of a resource-argument element. <resource-argument request-key='request attribute key'/>
Rank-argument element	The rank-argument element indicates the worker selected to run the state's main task should be based on a rank. A worker's rank is based on the probability that worker has the required resource. The rank-type attribute indicates the amount of the specified resource a worker should have. The min-weight specifies the worker with the lowest rank should execute the state's task. The max-weight specifies the worker with the highest rank should execute the state's task. This element is only available with the task-affinity element and is optional. Below is an example of a rank-argument element. <rank-argument rank-type='max-weight or min-weight'/>
Sub-process element	A sub-process is a process flow initiated by another process flow. The sub-process name is the name of the process flow and is case sensitive. A sub-process does not have a retry or timeout attribute. The sub-process element must follow a state element. Below is an example of a sub-process element. The sub-process flow may define stricter group-access security, or none at all. <sub-process name='inventory-check'/>
Arc element	An arc defines the transition from one state to the next state based on the task's or sub-process' result. A task or sub-process results in a success or failure. A failure can occur because the worker cannot perform the task or sub-process, the worker takes longer than the time allowed to perform the task, or the fabric worker manager cannot gather information about the worker, the task, or sub-process. An arc is not required for every possible task-status. If an arc is not specified for a task-status, the next-state for that task-status is the finish state. An arc has three attributes: task-status, task-result, and next-state. The task-status attribute identifies the status of the task or sub-process. This attribute has three possible values: complete, not-attempted, and task-not-completed. complete The task or sub-process completed successfully. not-attempted The application fabric did not attempt to complete the task or sub-process. not-completed The task took too long to complete or the task or sub-process status could not be determined. The task-result is available only when the task-status is complete. You define the value for this attribute. The next-state attribute identifies the name of the proceeding state in the process flow. The arc element must follow a task, sub-process, or arc element. Below is an example of an arc element. <arc task-status='complete' task-result='HELD' next-state='purchase'/> <arc task-status='not-attempted' next-state='barState'/>

State rules

State names must be unique.
One state must be start.
finish cannot be a state name.
All arcs eventually progress to the finish state.
Retries are 0 or more.
Only arcs with a task-status of complete have a task-result attribute.
If a state has multiple arcs with a task-status of complete, each of those arcs must have a distinct task-result.
All arcs have a next-state attribute and it cannot be blank or null.
An arc is not required for every possible task-status. If an arc is not specified for a task-status, the next-state for that task-status is the finish state.

Example process flow definition file

<?xml version='1.0'?>
<!DOCTYPE process SYSTEM 'ProcessDefinition.dtd'>
<process name='order_item' default_retries='2' default_timeout='2'>
  <state name='start'>
    <task name='ItemLookup'/>
    <arc task-status='complete' task-result='AVAILABLE' nextstate=' hold-item'/>
    <arc task-status='complete' task-result='OUT_OF_STOCK' nextstate=' finish'/>
  </state>
  <state name='hold-item'>
    <task name='ItemHold'/>
    <arc task-status='complete' task-result='HELD' nextstate=' purchase'/>
    <arc task-status='complete' task-result='OUT_OF_STOCK' nextstate=' finish'/>
  </state>
  <state name='purchase'>
    <task name='ItemPurchase' retries='2' timeout='10'/>
    <arc task-status='complete' task-result='PURCHASED' nextstate=' finish'/>
    <arc task-status='complete' task-result='PURCHASE DENIED' nextstate=' hold-release'/>
  </state>
  <state name='hold-release'>
    <task name='ItemReleaseHold'/>
    <arc task-status='complete' next-state='finish'/>
  </state>
</process>