Custom Workflows
----------------

Custom Workflows can be added to:

* Domain Models
* Relations
  
A Custom Workflow can be called from a model *instance*.

The usage in the URLs and parameters below are:

[model]

* Domain Model [domain/DomainModelName]
* Relation [relation/RelationName] 

[pkid]

Model instance pkid

[CustomWF]

Custom Workflow name. The name is of the format *add-*, *del-* to indicate the operation type. 

* For Domain Models, the Custom Workflow name suffix corresponds with a Group name of Domain Model attributes.
* For Relations, the Custom Workflow name suffix corresponds with the alias of the joined model type. 

To get the payload schema for a Custom Workflow, carry out a *list* API call for the instance, with parameters: 

.. tabularcolumns:: |p{2.5cm}|p{0.8cm}|p{7cm}|p{3cm}|

+----------------+-------+-------------------------------+-------------------------+
| Task           | Call  | URL                           | Parameters              |
+================+=======+===============================+=========================+
| Get payload    | GET   | /api/[model]/[pkid]/          | hierarchy=[hierarchy]   |
| schema         |       |                               |                         |
|                |       |                               | format=json             |
|                |       |                               |                         |
|                |       |                               | schema=true             |
|                |       |                               |                         |
|                |       |                               | schema_rules=true       |
+----------------+-------+-------------------------------+-------------------------+

The response contains:

* The **action** to carry out the Custom Workflow. For example, for an **add** 
  action on a domain model DOMAIN100 instance with a group name or alias called ADDRESS:

  ::

     AddADDRESS: {
     href: "/api/domain/DOMAIN100/523c2213a61654174273ab07/+AddADDRESS/"
     title: "Addaddress"
     schema: "ADDRESS"
     method: "POST"
     submit: "payload"
     class: "add"
     }

* The **schema** of the model in the response contains the specification of the **submit** payload for the Custom Workflow.

.. tabularcolumns:: |p{1.5cm}|p{0.8cm}|p{7cm}|p{2cm}|p{1cm}|

+----------------+-------+-------------------------------------------------+------------------------+-----------+
| Task           | Call  | URL                                             | Parameters             | Payload   |
+================+=======+=================================================+========================+===========+
| Call Custom    | POST  | /api/domain/[model]/[pkid]/+[CustomWF]/         | hierarchy=[hierarchy]  | See below |
| add workflow   |       |                                                 |                        |           |
+----------------+-------+-------------------------------------------------+------------------------+-----------+

Payload for grouped attributes is defined in the schema that is returned from the GET call above.
For PUT methods the resource data is replaced with the data specified in the request.
All fields of the resource is replaced with the fields in the request.

This means that:

* fields not present in the request that are present in the resource will be dropped from the resource
* fields present in the request that are not present in the resource will be appended to the resource
* the data of fields present in the request is used to update fields that already exist in the resource

PATCH methods operate in two modes depending on the content type:

* ``Content type: application/json``
* The values of data fields present in the request is used to update the corresponding resource fields.
  This means that:

  * Fields present in the request but not in the resource is appended to the resource.
    The value of each field that is already present in the resource is updated from the request data.

Note: Field values that are set to null in the request is dropped from the resource.
Fields that are present in the resource but not in the request are left untouched.

``Content type: application/json-patch+json``

Existing resource data is patched according to RFC6902.


Modifying data fields:

* To drop the field from a data model, specify null as the parameter value (i.e. ``{"field": null}``)
* To blank out a string value set the parameter value to an empty string (i.e. ``{"field":""}``)
* When the key (field name) appears in the field for a parameter, then the field is updated with
  the supplied value.
* Any field that is not specified in the request will be left untouched
* When a key (field name) is specified but no value is supplied, or an empty string is supplied,
  the value is blanked out or set to NULL

.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM