slice: integer, specifies a realm-slice in whose context the workflow engine must operate
entityid: mandatory, string, a unique ID for this specific entity instance which is about to start its workflow traversal. Note that Crux will not ensure the uniqueness of this value in its own tables -- this value is for the application code, and is supposed to help it map the entity with the workflow traversal stages it is going through.
entity: a JSON object with a set of fields and values. These fields must have names defined in the workflow schema and the values are the ones which the workflow engine will use to traverse the workflow. All the fields shown above are purely examples -- they are not specs of Crux. They illustrate how a sample entity's attributes may be specified. The names of the fields, like voucherdate, branch, etc must match the attributes in the for this class. One field is mandatory and reserved: the class. The value of class here must match the value of class of the workflow specified. Here are more details of how an entity is represented.
app: the application ID to which this workflow belongs
workflow: the name of the workflow where the workflow engine will start the traversal
trace: optional, integer, 0 means no trace, 1 means high level trace, and 2 means detailed trace of the workflow engine's processing. If the parameter is omitted, it means the caller wants no trace (trace = 0).
parent: optional, integer, an ID of some other workflow instance, returned from an earlier call toWFinstanceNew(). If the request includes this, it is indicating to Crux that this new instance is a child of an earlier instance, i.e. this instance is being initiated because another instance indicated that one of its steps was in fact a sub-workflow (see the stepworkflow table).
Processing
Any authenticated user may make this call, from one of the permitted IP addresses.
The call will verify
the entity must conform to the structure given in this section
all attributes of entity match the names in the schema
no attributes are missing from entity
all values of the fields in entity match types of the attributes as specified in the schema
the value of app specified in the request matches the app ID with which this workflow is associated
the workflow named has is_active == true and internal == false
the class of the workflow must match that of entity
there is no record in the wfinstance table with the same values for the tuple (slice,app,workflow,entityid). One entity cannot traverse one workflow multiple times in parallel -- it's a logical inconsistency.
If any of these conditions fail, the call will return with a suitable error immediately. Else it will add two attributes to the entity object:
"step": "START",
"stepfailed": false
Then it will check whether all the rulesets and schema belonging to the slice specified in the request are loaded into the in-memory cache. If they are not present, the call will load them.
Then it will call doMatch() with:
entity: the entity submitted in the request
ruleset: a pointer to the in-cache data structure holding the workflow
actionset: an empty action set data structure
seenruleset: an empty array
trace: integer, as supplied in the request
When doMatch() returns, the call will check whether doMatch() has returned with a critical error. If yes, then it sends an error response to the client with the appropriate details. If there is no critical error, then it will inspect the tasks and properties of the actionset returned. The properties object of actionset must always contain either an attribute called done or an attribute called nextstep. If neither is present, or if a third attribute is present, then the call must log a critical error and return this error in its response. If all this is ok, then it will insert records in the wfinstance table as per the following scheme:
if there is an attribute done in properties of actionset, this means that the workflow has been traversed to its end, and nothing needs to be done. In that case, no record will be inserted in wfinstance.
If there is only one name in tasks, then there is at this point only one step to be performed. Therefore, one record will be entered into the table, as detailed below.
if the actionset.tasks contains multiple step names, then this means that these steps may be executed concurrently. In that case, multiple records will be inserted, one for each task.
New records in the wfinstance table will have the following values
instanceid: the entityid from the request
slice: from the request
app: from the request
class: from the class field of the ruleset being executed
workflow: from the request
step: the value of one of the tasks returned in the tasks array of actionset. If only one task is returned in this array, then one record will be created. If multiple tasks were returned in the tasks array, then the corresponding number of records will be created, one for each task.
nextstep: the value of the nextstep attribute in the properties object in actionset. If only one task was returned in tasks, then the value of nextstep will be equal to that task name. If multiple tasks were returned, then nextstep will have some other name which may have no connection with the task names listed.
doneat: set to null
parent: will be set to null, thereby indicating that this workflow instance is not a sub-workflow of any other workflow.
It will then look up the stepworkflow table to see if any of the task values obtained from actionset.properties.tasks are specified in stepworkflow. (There could be multiple values in the tasks set.) The stepworkflow table specifies if one of the steps, say S1, returned by workflow X is itself to be executed by traversing another multi-step workflow, e.g. workflow Y. In that case, the name Y is specified in stepworkflow against step S1. If this is the case, then this information needs to be returned to the caller.
Response
If all goes well, and it is a simple case where there is just one next step to be executed, the response will be:
where everything is mandatory other than subflows, done and tracedata. The tasks array will have a set of objects, one per next step. In this example, there is only one next step, therefore, there is just one object. The name of the attribute of that object is passportchk, which is the name of the step to execute, and the value is 8734, which is the ID of the row in wfinstances corresponding to this entry.
Trace data will only be present, in the form of a large JSON block, if it has been requested.
It is possible that the call returns with the indication that the workflow traversal has been completed. In this case, the response will only contain:
{
"done": true
}
This parameter informs the caller that this entity has reached the last step in its workflow and there is nothing more to be done. It is rare in a real system for WFinstanceNew() to get a response of "done": true, since this call is just the start of a workflow traversal. In cases when done = true is being returned, tracedata may optionally be returned too, to indicate the matching engine's process to arrive at this conclusion.
If the workflow has thrown up a set of concurrent steps which need to be performed, the response will be of the form:
where everything will be mandatory and present, other than subflows, done and tracedata. The nextstep member will not be present when the tasks array has just one next step, and will always be present if tasks returns multiple steps. The tasks array has an ID against each next step.
The subflows object here is shown specifying the workflow name to call to execute the step called passportchk. The subflows block will only be present if there is a record for passportchk in the stepworkflow table. This attribute has no connection with whether tasks specifies one or multiple next steps.
It is expected that the application code will take note of this sub-workflow indication and will trigger a separate workflow for this entity for dopassportworkflow by making a separate call to WFinstanceNew() and using the same instance ID which it had used before.
the value of app specified in the request matches the app ID with which this workflow is associated
the workflow named has is_active == true and internal == false
the class of the workflow must match that of entity
there is no record in the wfinstance table with the same values for the tuple (slice,app,workflow,entityid). One entity cannot traverse one workflow multiple times in parallel -- it's a logical inconsistency.
If actionset returned by doMatch() contains only single task then only one record will get inserted into wfinstance table
If actionset returned by doMatch() contains only multiple tasks then multiple records will get inserted into wfinstance table One for each task
if actionset tasks present in stepworkflow table then accordingly which step and workflow returned to the caller
-if actionset.properties has done attribute which is true then nothing will get inserted in wfinstance table
This creates a new instance of a workflow. This is called when one entity (i.e. one object instance) begins its journey through a workflow.
Request
where:
slice
: integer, specifies a realm-slice in whose context the workflow engine must operateentityid
: mandatory, string, a unique ID for this specific entity instance which is about to start its workflow traversal. Note that Crux will not ensure the uniqueness of this value in its own tables -- this value is for the application code, and is supposed to help it map the entity with the workflow traversal stages it is going through.entity
: a JSON object with a set of fields and values. These fields must have names defined in the workflow schema and the values are the ones which the workflow engine will use to traverse the workflow. All the fields shown above are purely examples -- they are not specs of Crux. They illustrate how a sample entity's attributes may be specified. The names of the fields, likevoucherdate
,branch
, etc must match the attributes in the for this class. One field is mandatory and reserved: theclass
. The value ofclass
here must match the value ofclass
of the workflow specified. Here are more details of how an entity is represented.app
: the application ID to which this workflow belongsworkflow
: the name of the workflow where the workflow engine will start the traversaltrace
: optional, integer,0
means no trace,1
means high level trace, and2
means detailed trace of the workflow engine's processing. If the parameter is omitted, it means the caller wants no trace (trace = 0
).parent
: optional, integer, an ID of some other workflow instance, returned from an earlier call toWFinstanceNew()
. If the request includes this, it is indicating to Crux that this new instance is a child of an earlier instance, i.e. this instance is being initiated because another instance indicated that one of its steps was in fact a sub-workflow (see the stepworkflow table).Processing
Any authenticated user may make this call, from one of the permitted IP addresses.
The call will verify
entity
match the names in the schemaentity
entity
match types of the attributes as specified in the schemaapp
specified in the request matches the app ID with which thisworkflow
is associatedis_active == true
andinternal == false
class
of the workflow must match that ofentity
wfinstance
table with the same values for the tuple(slice,app,workflow,entityid)
. One entity cannot traverse one workflow multiple times in parallel -- it's a logical inconsistency.If any of these conditions fail, the call will return with a suitable error immediately. Else it will add two attributes to the
entity
object:Then it will check whether all the rulesets and schema belonging to the
slice
specified in the request are loaded into the in-memory cache. If they are not present, the call will load them.Then it will call
doMatch()
with:entity
: the entity submitted in the requestruleset
: a pointer to the in-cache data structure holding the workflowactionset
: an empty action set data structureseenruleset
: an empty arraytrace
: integer, as supplied in the requestWhen
doMatch()
returns, the call will check whetherdoMatch()
has returned with a critical error. If yes, then it sends an error response to the client with the appropriate details. If there is no critical error, then it will inspect thetasks
andproperties
of theactionset
returned. Theproperties
object ofactionset
must always contain either an attribute calleddone
or an attribute callednextstep
. If neither is present, or if a third attribute is present, then the call must log a critical error and return this error in its response. If all this is ok, then it will insert records in thewfinstance
table as per the following scheme:done
inproperties
ofactionset
, this means that the workflow has been traversed to its end, and nothing needs to be done. In that case, no record will be inserted inwfinstance
.tasks
, then there is at this point only one step to be performed. Therefore, one record will be entered into the table, as detailed below.actionset.tasks
contains multiple step names, then this means that these steps may be executed concurrently. In that case, multiple records will be inserted, one for each task.New records in the
wfinstance
table will have the following valuesinstanceid
: theentityid
from the requestslice
: from the requestapp
: from the requestclass
: from theclass
field of the ruleset being executedworkflow
: from the requeststep
: the value of one of the tasks returned in thetasks
array ofactionset
. If only one task is returned in this array, then one record will be created. If multiple tasks were returned in thetasks
array, then the corresponding number of records will be created, one for each task.nextstep
: the value of thenextstep
attribute in theproperties
object inactionset
. If only one task was returned intasks
, then the value ofnextstep
will be equal to that task name. If multiple tasks were returned, thennextstep
will have some other name which may have no connection with the task names listed.doneat
: set tonull
parent
: will be set tonull
, thereby indicating that this workflow instance is not a sub-workflow of any other workflow.It will then look up the
stepworkflow
table to see if any of thetask
values obtained fromactionset.properties.tasks
are specified instepworkflow
. (There could be multiple values in thetasks
set.) Thestepworkflow
table specifies if one of the steps, sayS1
, returned by workflowX
is itself to be executed by traversing another multi-step workflow, e.g. workflowY
. In that case, the nameY
is specified instepworkflow
against stepS1
. If this is the case, then this information needs to be returned to the caller.Response
If all goes well, and it is a simple case where there is just one next step to be executed, the response will be:
where everything is mandatory other than
subflows
,done
andtracedata
. Thetasks
array will have a set of objects, one per next step. In this example, there is only one next step, therefore, there is just one object. The name of the attribute of that object ispassportchk
, which is the name of the step to execute, and the value is8734
, which is the ID of the row inwfinstances
corresponding to this entry. Trace data will only be present, in the form of a large JSON block, if it has been requested.It is possible that the call returns with the indication that the workflow traversal has been completed. In this case, the response will only contain:
This parameter informs the caller that this entity has reached the last step in its workflow and there is nothing more to be done. It is rare in a real system for
WFinstanceNew()
to get a response of"done": true
, since this call is just the start of a workflow traversal. In cases whendone = true
is being returned,tracedata
may optionally be returned too, to indicate the matching engine's process to arrive at this conclusion.If the workflow has thrown up a set of concurrent steps which need to be performed, the response will be of the form:
where everything will be mandatory and present, other than
subflows
,done
andtracedata
. Thenextstep
member will not be present when thetasks
array has just one next step, and will always be present iftasks
returns multiple steps. Thetasks
array has an ID against each next step.The
subflows
object here is shown specifying the workflow name to call to execute the step calledpassportchk
. Thesubflows
block will only be present if there is a record forpassportchk
in thestepworkflow
table. This attribute has no connection with whethertasks
specifies one or multiple next steps.It is expected that the application code will take note of this sub-workflow indication and will trigger a separate workflow for this entity for
dopassportworkflow
by making a separate call toWFinstanceNew()
and using the same instance ID which it had used before.