oms-Workflow/Docs/Dev/en/specification.md

Specification

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

interface WorkflowControllerInterface
{
    /**
     * 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;
}

WorkflowInstance.php

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.

Additional models may be useful depending on the workflow structure.

WorkflowInstanceMapper.php

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.

Additional mappers may be necessary if additional models are defined for the workflow.

Routes & Hooks (mandatory)

• 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
declare(strict_types=1);

return [
    'en' => [
        '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.