From 06c77090422eda268d6953e126fc51540ac54ffc Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Mon, 28 Mar 2022 21:27:25 +0200 Subject: [PATCH] drafting specification docs --- Docs/Dev/en/SUMMARY.md | 1 + Docs/Dev/en/specification.md | 192 ++++++--- Docs/Dev/en/structure.md | 6 +- .../img/workflow_execution_path.drawio.svg | 397 ++++++++++++++++++ Docs/Help/en/SUMMARY.md | 2 + Docs/Help/en/introduction.md | 33 ++ 6 files changed, 583 insertions(+), 48 deletions(-) create mode 100644 Docs/Dev/img/workflow_execution_path.drawio.svg create mode 100644 Docs/Help/en/SUMMARY.md create mode 100644 Docs/Help/en/introduction.md diff --git a/Docs/Dev/en/SUMMARY.md b/Docs/Dev/en/SUMMARY.md index 8a97952..9d3530a 100755 --- a/Docs/Dev/en/SUMMARY.md +++ b/Docs/Dev/en/SUMMARY.md @@ -1,3 +1,4 @@ # Developer Content +* [Specification]({%}&page=Dev/specification) * [Structure]({%}&page=Dev/structure) diff --git a/Docs/Dev/en/specification.md b/Docs/Dev/en/specification.md index bcc4ac1..e2a21de 100755 --- a/Docs/Dev/en/specification.md +++ b/Docs/Dev/en/specification.md @@ -1,60 +1,158 @@ # Specification -```json +## Files + +A workflow relies on some mandatory files which must be provided when creating a workflow. Additionally, workflows may provide optional files to enhance the user experience and provide additional functionality. The following names are reserved file names and must not be used for other purposes. Apart from these file names you may create and upload any template, helper or model files to create a workflow suitable to your needs. + +### Controllers & Models (mandatory) + +* WorkflowController.php +* WorkflowInstance.php +* WorkflowInstanceMapper.php + +#### WorkflowController.php + +The **WorkflowController.php** file must implement the **WorkflowControllerInterface** class. This file is mostly responsible to perform all actions associated with the workflow. Some of the functionality which would normally be implemented in this controller file are: + +* Creating and updating workflow instances +* Performing workflow specific actions +* Displaying workflow information through templates (see below) +* Exporting and importing data from and to workflows + +##### WorkflowControllerInterface + +```php +interface WorkflowControllerInterface { - "steps": [ - { - "name": "step-name", - "event-name": "unique-event-name-generated-on-upload", - "type": 1, - "template": "visual-template", - "users": [], - "groups": [], - "event-listeners": [ - "event-to-listen-for-1" - "event-to-listen-for-2" - ], - "pre": { - "event-trigger": [ - "event-to-trigger-1" - "event-to-trigger-2" - ], - "script": [ - "script-to-run-1" - "script-to-run-2" - ] - }, - "post": { - "event-trigger": [ - "event-to-trigger-1" - "event-to-trigger-2" - ], - "script": [ - "script-to-run-1" - "script-to-run-2" - ] - } - }, - { - .... - } - ] + /** + * Create instance from request + * + * @param RequestAbstract $request Request + * + * @return WorkflowInstanceAbstract + * + * @since 1.0.0 + */ + public function createInstanceFromRequest(RequestAbstract $request) : WorkflowInstanceAbstract; + + /** + * Create list of all instances for this workflow from a request + * + * @param RequestAbstract $request Request + * + * @return array + * + * @since 1.0.0 + */ + public function getInstanceListFromRequest(RequestAbstract $request) : array; + + /** + * Change workflow instance state + * + * @param RequestAbstract $request Request + * + * @return WorkflowInstanceAbstract + * + * @since 1.0.0 + */ + public function apiChangeState(RequestAbstract $request, ResponseAbstract $response, $data = null) : void; + + /** + * Store instance model in the database + * + * @param WorkflowInstanceAbstract $instance Instance + * + * @return void + * + * @since 1.0.0 + */ + public function createInstanceDbModel(WorkflowInstanceAbstract $instance) : void; } ``` -Good synergy with job module required... job runs every x and might invoke a workflow/workflow-step +#### WorkflowInstance.php -## Type +The **WorkflowInstance.php** file hast to extend the **WorkflowInstanceAbstract.php** file. The workflow instance should contain most if not all of the information associated with a specific workflow instance. Since workflow data is highly dependent on the type of workflow every workflow must implement its own workflow instance model. -* 1 = Autorun after previous event -* 2 = Only if event listener is called +> Additional models may be useful depending on the workflow structure. -Every step receives the status code of all steps + the custom data created from the previous steps +#### WorkflowInstanceMapper.php -After every step the handler writes custom data to the workflow run information. +The **WorkflowInstanceMapper.php** file has to extend the **DataMapperFactory.php** file. This file is responsible for reading, creating, updating and deleting a workflow instance in the database. If data needs to be stored in a database the workflow also must provide a **db.json** file (see below) which creates the database tables for the workflow. -This means every workflow has a configuration and whenever a new workflow get's triggered a new "workflow entry" is created. +> Additional mappers may be necessary if additional models are defined for the workflow. -## Template +### Routes & Hooks (mandatory) -e.g. user interface for this step \ No newline at end of file +* Hooks.php +* Routes.php + +Both the hooks file and the routes file follow the same implementation guidelines as for modules. However the hooks and routes files for workflows will only be loaded when handling workflow actions. + +### Database (optional but often necessary) + +* db.json + +The **db.json** file foollows the same implementation guidelines as for modules. This file is used to setup the database tables associated with the workflow (e.g. instance table). + +Tables must follow the format `workflow_{workflow_id}_yourtablename` where `{workflow_id}` will be automatically replaced with the workflow id during the workflow setup process. + +### Language file (optional but recommended) + +* lang.php + +Instead of using a fixed localization it is recommended to create a **lang.php** file which contains all the localizations. Even if only one localization is initially used this is the recommended way because it makes it very easy to extend to additional languages later on if necessary. + +Format (example): + +```php + [ + 'Identifier' => 'Translation in English', + ], + 'de' => [ + 'Identifier' => 'Translation in German', + ], + 'it' => [ + 'Identifier' => 'Translation in Italian', + ], +]; + +``` + +### Template files (optional but often recommended) + +* instance-create.tpl.php +* instance-list.tpl.php +* instance-profile.tpl.php +* template-profile.tpl.php + +#### instance-create.tpl.php + +The **instance-create.tpl.php** is used to display a form which can be used to create a new workflow instance. + +#### instance-list.tpl.php + +The **instance-list.tpl.php** is used to show all instances of a workflow in a list. + +#### instance-profile.tpl.php + +The **instance-profile.tpl.php** is used to show the workflow instance with all its information (e.g. state, status, user data, ...). Additionally, this template may also contain user input options. + +#### template-profile.tpl.php + +The **template-profile.tpl.php** file may contain the workflow information for the admin, settings options for the workflow, file editor and more to manage the workflow. + +### Export files (optional) + +* Excel: *.xls.php / *.xlsx.php +* Word: *.doc.php / *.docx.php +* Powerpoint: *.ppt.php / *.pptx.php +* Pdf: *.pdf.php +* Json: *.json.php +* Csv: *.csv.php + +The export files can be used to export workflow instance information in different layouts. \ No newline at end of file diff --git a/Docs/Dev/en/structure.md b/Docs/Dev/en/structure.md index 84b60a1..2cb12b2 100755 --- a/Docs/Dev/en/structure.md +++ b/Docs/Dev/en/structure.md @@ -2,4 +2,8 @@ ## ER -![ER](Modules/Workflow/Docs/Dev/img/er.png) \ No newline at end of file +![ER](Modules/Workflow/Docs/Dev/img/er.png) + +## Call graph + +![Call graph](Modules/Workflow/Docs/Dev/img/workflow_execution_path.drawio.svg) \ No newline at end of file diff --git a/Docs/Dev/img/workflow_execution_path.drawio.svg b/Docs/Dev/img/workflow_execution_path.drawio.svg new file mode 100644 index 0000000..0ad5d87 --- /dev/null +++ b/Docs/Dev/img/workflow_execution_path.drawio.svg @@ -0,0 +1,397 @@ + + + + + + + + + +
+
+
+ API call +
+
+
+ + + API call + + + + + + + + + +
+
+
+ Cli event endpoint +
+ (Admin Module / ApiController) +
+
+
+ + + Cli event endpoint... + + + + + + + + + +
+
+
+ Cli Application +
+
+
+ + + Cli Application + + + + + + + + + +
+
+
+ Event handling (Admin Module / CliController) +
+
+
+ + + Event handling (Admi... + + + + + + + + + +
+
+
+ Triggers events +
+
+
+ + + Triggers even... + + + + + + + + + +
+
+
+ Re-triggers original event +
+
+
+ + + Re-triggers o... + + + + + + + + + +
+
+
+ Workflow event hook (Workflow Module / CliController) +
+
+
+ + + Workflow event hook... + + + + + + + + + +
+
+
+ + Find workflows which are bound to the event + +
+
+
+ + + Find workflow... + + + + + + + + + +
+
+
+ Any Module (Api) +
+
+
+ + + Any Module (Api) + + + + + + + + + +
+
+
+ Admin Module (Api) +
+
+
+ + + Admin Module (Api) + + + + + + + + + +
+
+
+ Admin Module (Cli) +
+
+
+ + + Admin Module (Cli) + + + + + + + + + +
+
+
+ Workflow Module (Cli) +
+
+
+ + + Workflow Module (Cli) + + + + + + + +
+
+
+ Workflow Endpoint (Cli) +
+
+
+ + + Workflow Endpoint (C... + + + + + + + + + +
+
+
+ + Every event is cought by the Admin Module with a wildcard hook + +
+
+
+ + + Every event is cough... + + + + + + + + +
+
+
+ Use +
+ Cli App +
+
+
+ + + Use... + + + + + + + + +
+
+
+ Fallback: use +
+ Wep App +
+
+
+ + + Fallback: use... + + + + + + + +
+
+
+ Forwards event +
+
+
+ + + Forwards event + + + + + + + + + +
+
+
+ + Every event is cought by the Workflow Module with a wildcard hook + +
+
+
+ + + Every event is cough... + + + + + + + + + +
+
+
+ Workflow Template & Instance +
+
+
+ + + Workflow Template &... + + + + + + + +
+
+
+ Modify Workflow instance state +
+
+
+ + + Modify Workfl... + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file diff --git a/Docs/Help/en/SUMMARY.md b/Docs/Help/en/SUMMARY.md new file mode 100644 index 0000000..f7aa0df --- /dev/null +++ b/Docs/Help/en/SUMMARY.md @@ -0,0 +1,2 @@ +# User Content + diff --git a/Docs/Help/en/introduction.md b/Docs/Help/en/introduction.md new file mode 100644 index 0000000..5085657 --- /dev/null +++ b/Docs/Help/en/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +The **Workflow** module allows organizations to automize and structure internal processes and guidelines. With workflows it's essentially possible to extend and modify how the application behaves based on the companies needs. Examples for workflows can be approval processes, step-by-step instructions which must be followed and many more. + +## Target Group + +The target group for this module is every organization which would like to create organization specific workflows/processes. The implementation of such workflows requires programming knowledge in PHP and potentially JavaScript. Other modules may provide their own example workflows which provide a good starting point and may be useful with minor configuration adjustments. + +# Requirements + +Workflows need to check many user actions and see if any workflows are linked to these user actions. This process is slow because of the large amount of potnetial user actions. In order to avoid the application slowing down it is recommended to run these checks asynchrounisly. However for this to be possible the application must have permissions to execute and run the cli application which is not possible on all server environments (e.g. simple web servers). + +By default the application will test during the installation process if the Cli application can be executed from within the web application. + +> Make sure you add the php.exe path to the environment variables on Windows! + +# Setup + +This module doesn't have any additional setup requirements since it is installed during the application install process. + +# Features + +## Permission Management + +It's possible to only give selected users and groups access to certain workflows. + +## Input handling + +The workflows can be created in a way which allows UI interaction by the user, automatic modification through actions within the application and it's also possible to allow workflows to handle uploaded user data. + +## Localization + +The module allows users to create workflows which also support localization.