Flowable
********

- :doc:`dev-flowable`

Install
=======

.. warning:: Flowable servers must stay on Ubuntu 22.04 LTS
             (see `Ubuntu 24.04 LTS`_ for more information)

.. warning:: The SMTP settings for the mail server are not configured, but
             do **not** rush to put them right.  Flowable tasks send emails in
             the background and we do **NOT** want customers receiving
             duplicate or out of date emails!

Ubuntu 22.04 LTS
----------------

.. warning:: Flowable servers must stay on Ubuntu 22.04 LTS
             (see `Ubuntu 24.04 LTS`_ for more information)

Ubuntu 24.04 LTS
----------------

.. warning:: Flowable does **not** work on Tomcat 10 (Ubuntu 24.04 LTS),
             so we need something for our development machines.

I updated the Salt states to manually install Tomcat 9 into ``/var/lib/tomcat``
for Ubuntu 24.04 LTS.  This is **only** for development machines which need to
reproduce the live server environment::

  sudo tail -f /var/lib/tomcat/logs/catalina.out

Docker
------

.. warning:: **Live** Flowable servers must stay on Ubuntu 22.04 LTS (for now)

For development on Ubuntu 24.04 LTS, we can use the Docker container.

Download :download:`./misc/docker/docker-compose.yaml/`::

  docker compose up -d

  # find the 'CONTAINER ID'
  docker container ls -a
  # view the logs e.g.
  docker logs dd80c2bc20b8

  docker compose down

Browse to
http://localhost:8080/flowable-rest/docs/?url=specfile%2Fprocess%2Fflowable-swagger-process.json#!/Tasks/listTasks

Login with ``kermit``, ``kermit``.

Podman
------

.. warning:: **Live** Flowable servers must stay on Ubuntu 22.04 LTS (for now)

For development on Ubuntu 24.04 LTS, we can use the Podman container.

Download `flowable-rest.yaml`_::

  podman kube play flowable-rest.yaml

  podman pod start flowable-rest
  podman pod stop flowable-rest
  podman pod restart flowable-rest

  podman pod logs -f flowable-rest
  podman pod rm flowable-rest

Browse to
http://localhost:8080/flowable-rest/docs/?url=specfile%2Fprocess%2Fflowable-swagger-process.json#!/Tasks/listTasks

Login with ``kermit``, ``kermit``.

Useful links
------------

- `flowable-rest WAR application not working with version 10 of Apache Tomcat`_
- `feat: Ubuntu 24.04 - only manual install tomcat for development`_
- `Update Salt states so they support Ubuntu 24.04 - #7733`_
- `A future solution may be Flowable in Docker / Podman - #7757`_

Issues
======

.. _sys-flowable-value-too-long:

value too long
--------------

I spent several hours diagnosing a ``value too long`` error e.g::

  workflow.activiti.ActivitiError:
  'ActivitiError, 500 error: for url:
  http://localhost:8080/flowable-rest/service/runtime/tasks/10a5a39-8ea7-11ee:
  {"message": "Internal server error",
    "exception":
      ### "Error updating database. Cause: org.postgresql.util.PSQLException:
      ERROR: value too long for type character varying(255)
      ### The error may exist in org/flowable/task/service/db/mapping/entity/HistoricTaskInstance.xml
      ### The error may involve org.flowable.task.service.impl.persistence.entity.HistoricTaskInstanceEntityImpl.insertHistoricTaskInstance-Inline
      ### The error occurred while setting parameters
      ### SQL: insert into ACT_HI_TASKINST (
        ID_, REV_, TASK_DEF_ID_, PROC_DEF_ID_, PROC_INST_ID_, EXECUTION_ID_,
        SCOPE_ID_, SUB_SCOPE_ID_, SCOPE_TYPE_, SCOPE_DEFINITION_ID_,
        PROPAGATED_STAGE_INST_ID_, NAME_, PARENT_TASK_ID_, DESCRIPTION_,
        OWNER_, ASSIGNEE_, START_TIME_, CLAIM_TIME_, END_TIME_, DURATION_,
        DELETE_REASON_, TASK_DEF_KEY_, FORM_KEY_, PRIORITY_, DUE_DATE_,
        CATEGORY_, TENANT_ID_, LAST_UPDATED_TIME_
      ) values ( ?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ? )
      ### Cause: org.postgresql.util.PSQLException:
      ERROR: value too long for type character varying(255)"}'

- I checked the Postgres logs (:ref:`sys-postgres-logging-sql`)
  but this didn't help because the parameters are not written if the query
  fails.
- I also checked the data in the python code and none of it was over 255
  characters.

The ``documentTitle`` field was 179 characters long:

- The next task in the workflow had a fairly long ``name`` which also used the
  ``documentTitle`` e.g. ``Please review ${documentTitle} etc etc...``
- When combined, the ``name`` is too long (over 255 characters)

For more information, see https://www.kbsoftware.co.uk/crm/ticket/6958/


.. _`A future solution may be Flowable in Docker / Podman - #7757`: https://www.kbsoftware.co.uk/crm/ticket/7757/
.. _`feat: Ubuntu 24.04 - only manual install tomcat for development`: https://gitlab.com/kb/salt/-/commit/e4f411d73551ff2eac5e5a80ba14d6b27f876d12
.. _`flowable-rest WAR application not working with version 10 of Apache Tomcat`: https://github.com/flowable/flowable-engine/issues/2939
.. _`flowable-rest.yaml`: https://gitlab.com/kb/podman-projects/-/blob/main/flowable-rest/flowable-rest.yaml
.. _`Update Salt states so they support Ubuntu 24.04 - #7733`: https://www.kbsoftware.co.uk/crm/ticket/7733/