| Version | Date | Notes | By |
|---|---|---|---|
| 1.0 | 2020-12-07 | Initial release | ROB |
| 1.1 | 2020-12-09 | Conclusion of initial release | ROB |
| 1.2 | 2023-06-19 | Documenting new variable instance storage system | ROB |
| 1.3 | 2023-06-19 | Removed references to the dynamic attribute system (its completely separate now) | ROB |
In this section we will explain all the tables required for the process engine to work, and how they control token process state and disposition. The process engine data is separated into two areas definition and execution. Not all columns will be detailed, only columns that require explanation or are part of actual functioning of the process engine will be explained.
This area stores the structure of the process as well as the revisions for each process.
The revision structure contains the process structure, when a new revision is created, the process structure is copied (minus whatever alterations the user made for the new revision).
t20_bpmn_process_holders
| Column | Description |
|---|---|
| current_version | Stores the revision version that is in production |
| updated_at, updated_by | stores the datetime and user id when updated or when revisions are created / updated |
| status_id | stores 0 or 1 (fk with t00_boolean_statuses, enables or disables the entire process) |
t20_bpmn_process_holder_revisions
| Column | Description |
|---|---|
| version | Stores the version for that revision |
| status_id | Stores the status for that revision, valid values are "Elaborating", "Testing", "In production" and "Obsolete" |
| case_code_main_mask | Stores the code format with number mask |
| case_code_repeat_by | Stores the option that determines when the code incrementor is reset |
| case_code_repeat_by_mask | If repeat_by names an additional field, this stores the mask for it (similar to how documents work) |
| case_code_repeat_by_variable_definition | Stores variable definition id (in case repeat by is set to attribute value) |
| case_code_repeat_by_attribute_variable | Stores attribute definition id (in case repeat by is set to attribute value) |
repeat_by - This column controls when the incrementor for token processes resets, it has 4 options. Do not repeat never resets the incrementor. Repeat every year resets the incrementor based on the column created_at for the token process. Repeat every attribute value resets the incrementor per value of an attribute of a variable. Finally, Repeat for every process revision resets the incrementor per process revision.
These tables store the structure and options of the bpmn diagram, their objects and connections.
t20_bpmn_processes
| Column | Description |
|---|---|
| parent_id | In the BPMN 2.0 specification sub processes are tecnicaly full processes subordinate to another process, this column denotes that relationship (such that a process revision can have multiple processes as part of it's structure) |
t20_bpmn_process_objects
| Column | Description |
|---|---|
| swimlane_id | unused - This column will be used to indicate a given object is part of a given swimlane. |
| type_id | Indicates the type of object (the type obeys BPMN 2.0 specification) |
| boundary_of_id | Stores the id of the t20_bpmn_process_objects that this object is attached to by boundary |
| owner_user_id | deprecated - Stores the owner (responsible) of a given bpmn activity (this is now a many to many relation) via t20_bpmn_process_object_owning_users |
| parent_id | unused - Currently unused, provides parenting relation to bpmn objects. |
| gr_position_x | stores x position of object on the bpmn diagram |
| gr_position_y | stores y position of object on the bpmn diagram |
| gr_position_width | stores width of object on the bpmn diagram |
| gr_position_height | stores height of object on the bpmn diagram |
t20_bpmn_process_object_options
| Column | Description |
|---|---|
| option_name | Stores the name of the option, a bpmn object can have multiple options but only one option of the same name per object |
| option_type | Stores the type of option value, valid values are int, float, string and json |
| option_value | Stores the actual value |
Bpmn process object options store information related to integrating a bpmn 2.0 diagram with a process engine (In this case the SGU process engine) or with a scripting engine (Lua removed or WeFlow™).
For example the options exit_logic or script store the WeFlow script to be executed at that activity, with that token process context (variables and intrinsics).
t20_bpmn_process_object_connectors
This table stores the connections (flows) between objects and the type of connection it represents. As the SGU process engine is still in development, all types are interpreted without any diference.
| Column | Description |
|---|---|
| source_bpmn_process_object_id | Id of table t20_bpmn_process_objects where the connection starts |
| target_bpmn_process_object_id | Id of table t20_bpmn_process_objects where the connection ends |
| type_id | Type of connection, there are three types: "Flow", "Communication" and "Association" |
This section is used to define the variables, their structure and relation to one another so that during token process executions, they may be instanced and used to store attributes.
t20_variable_definition_objects
This table stores the variable definition object, in specific, it just stores the name (translatable) and is related by two other tables that store attributes and relations.
t20_variable_definition_attributes
This table stores the attributes for a given variable definition. The column data_type_id is a foreign key to the table t20_data_types. The variable definition system (and variable instancing in general) has been completely separated from the dynamic attribute system.
All tables related to t20_data_types are without management and serve to indicate the type / multiplicity of the attribute and what kinds of validations / frontend form components are valid to use with that type.
t20_variable_definition_relations
This table stores relations to other variable definitions as well as their multiplicity.
| Column | Description |
|---|---|
| related_definition_object_id | Variable definition object that this variable definition object is related to. |
| related_multiplicity | Multiplicity of relation (can be 'single' or 'multiple'). |
t20_token_process
| Column | Description |
|---|---|
| case_process_instance | Contains a unique string that uniquely identifies a case instance |
| status_id | Represents the current status of the token process. Possibilities are: "In execution", "Concluded", "Compensated" (not implemented yet), "Error" and "Timed out" |
| parent_token_id | If this is set then the token process is subordinate to another token process (sub processes for example are tecnically their own process, but the tokens they generate are allways subordinate to the parent token process, in the same way the subprocess is subordinate to the process it's contained by) |
| parent_token_processing_count | stores the processing count of the parent token object that inited this token process |
| code_main_incrementor | Stores the incrementation for the unique code generation |
| code_complete | Stores the complete generated code |
t20_token_process_object
| Column | Description |
|---|---|
| status_id | Indicates the state of the current token process object. Has the same states as the token process |
| token_processing_count | This is equal to the token_processing_value of the token process object preceding it, unless there are more token process tokens for the current bpmn process object. |
| object_id | Foreign key for the bpmn process object this token process object is "standing" on. Note that since bpmn process diagrams can loop in on themselves, it is possible to have multiple token process objects per bpmn process object |
| event_expecting_id | Foreign key of t00_boolean_options. This column is set to 1 if the associated bpmn process object is an catching or boundary event. Processing halts until event is caught. |
| event_resolved_id | Foreign key of t00_boolean_options. This column is set to 1 when the expected event is caught. |
| event_throwing_bpmn_object_id | Stores the id of the t20_bpmn_process_objects record that threw the event. |
| entry_at; entry_by | Stores the date and id of the user that moved the process into this position |
| exit_at; exit_by | Stores the date and id of the user that executed this token process object |
| case_exit_history | Stores a json dump of the variable instances and their attribute values as the token process executes |
| token_loop_uid | Stores a number that is unique per external itteration of a bpmn process object with loop characteristics |
| token_loop_itteration | Stores a number that increments per itteration of a bpmn process object's loop characteristics |
| error_treatment_exception_class | Stores the exception's fqcn |
| error_treatment_information | Stores additional information (this is specific to the exception's class) in development |
| error_information_is_handled | Foreign key for t00_boolean_options. If 1, then it means the error event was caught by a catcher further up the process tree, making it handled from the point of view of the process creator (i.e: the process creator forsaw there would be errors of this sort and added a boundary catcher with the appropriate options) |
| error_treatment_call_stack | Stores the call stack of the error, in case it is not a process user error but a bug with the process engine itself |
Note: The entry and exit columns will have the user set to User::WEMAKE_USER_ID if it is executed in the background (basicaly all bpmn objects except for user activities at this point).
t20_token_process_object_connectors
Similar to t20_bpmn_process_object_connectors this table stores the source and target token process objects. Since executed token process objects may vary based on gateway exit flows, there may be less token process connectors than related bpmn process object connectors. This table does not store the type of connection, and is mainly used by inclusive gateways so they can "walk back" to previous gateways to see which ones are active.
t20_token_process_owning_users
This table stores the users that own (are responsible for) the execution of this particular token process object. This table's information is determined when execution starts and is copied from t20_bpmn_process_object_owning_users as well as being added to from other sources such as attributes containing user ids, the creator id of token process (if that setting is active for this bpmn process object) as well as WeFlow scripts.
Table is nothing special, just user_id and token_process_object_id.
t20_token_process_future_token_object_commands
This table handles setting information for token objects that don't exist yet. It is used so that a previous token object can set information (for now only responsibles) on an upcomming token.
| Column | Description |
|---|---|
| code | The type of information to set (for now only set-responsibles exists) |
| originating_token_process_object_id | The id for the token process object that originated (set) the command |
| applicable_process_object_id | The id for the bpmn process object that, when creating a new token process object, the command will be executed unto |
| command_value | A json containing information required for the execution of the command (structure of json specific to command code) |
Variable instances are stored in independent related tables allowing the database engine of choice to perform the filtering for listing operations (old system used json records forcing all records to be opened for filtering with was impossible with very large datasets). Due to this, the tables required for variable instance storage are created when the process is moved from elaboration to testing / production.
There is a single table that serves as a container for the records t20_token_process_variable_definition_valueses establishing the connection between token process, the definition / relation pair, parenting relation and created by token process object:
| Column | Description |
|---|---|
| token_process_id | id of the token process that this variable instance is atached to |
| variable_definition_id | variable definition of the variable instance (allways present) |
| variable_relation_id | relation of the variable instance (present if variable related to ancestor variable definition) |
| parent_id | if variable instance decendant of variable instance (by way of variable definition relation) |
| created_by_token_process_id | set by the token object that created it |
The dynamic tables will connect to this one via t20_token_process_variable_definition_valueses.id. Depending on the multiplicity of a given attribute, there may be multiple dynamic records that connect to one t20_token_process_variable_definition_valueses record.
One dynamic table is created for each bpmn process revision holder / variable definition containing values for all attributes of multiplicity single with the name t20_values_table_<process_holder_revision_id>_<variable_definition_id> (for example t20_values_table_5_20). Also, a table for each attribute of multiplicity multiple is created with the name t20_values_table_<process_holder_revision_id>_<variable_definition_id>_<attribute_slug> (for example t20_values_table_5_20_ATTR00001)
The table for single attributes is organized like this:
| Column | Description |
|---|---|
| var_def_values_id | Id of the record in t20_token_process_variable_definition_valueses that originated this entry |
| token_process_id | Id of the token process |
| ATTR00001 .. N | Columns are dinamically created, one for each attribute with multiplicity single using the slug as the name |
The table for an attribute of multiplicity multiple is organized like this:
| Column | |
|---|---|
| var_def_values_id | Id of the record in t20_token_process_variable_definition_valueses that originated this entry |
| token_process_id | Id of the token process |
| valuestable |
id of the table for single attributes, this establishes the relation between the values from each single attribute for one variable instance and the multiple values for "this" attribute |
| value | One (of many) values for this attribute |
The initial query builder that retrieves this information from the database is created in the model TokenProcess::queryVariableInstanceQuerier(). The query builder can be made to return instanced models (slower) or raw data (faster) as well as returning aggregated data (number of X by column Y). The query has further conditions added to it by the VariableInstanceQuerier subsystem.