Workflows and approval policies

Learn how to create and customize the approval workflow for the incoming invoices.

Overview

Before a payable can be paid, somebody has to approve the operation. Monite allows entities to automate the approval process using workflows. A workflow represents an approval policy with specific business logic. The logic looks like this:

If the payable:

  • was received from a specific counterpart (vendor or supplier),
  • was uploaded by a specific entity user,
  • was uploaded by any user with a specific role,
  • is in a specific currency (such as EUR or USD),
  • has a specific amount to be paid (for example, ≥ 5000 EUR or 100-500 USD),
  • has specific tags assigned to it,
  • or any combination of these conditions,

then it should be approved by:

  • a specific entity user (such as the Finance Manager),
  • any user with a specific role,
  • any N users from the given list,
  • several entity users in a specific order (for example, first by the Team Lead, then by the Finance Manager).

Entities can create multiple approval policy workflows with different trigger conditions to cover the business needs.

With workflows, the payable flow process works as follows:

  1. Whenever a payable is created or its attributes or status are changed, Monite checks if there is an applicable approval workflow.
  2. If such a workflow is found, Monite sends email notifications to the entity users designated as approvers.
  3. The approvers can either approve or reject the payable.
  4. Approved payables can then be paid.

Workflow structure

Workflows are defined using the Monite script and consist of two parts:

  • trigger: The conditions that define which documents this workflow applies to.
  • functions: Specify the users or roles whose approval is needed for those documents.

Below is a sample workflow that requires approval from a specific user for any payables over 500 EUR:

{
  "policy_name": "Sample workflow",
  "policy_description": "Manager's approval is required for any payables over 500 EUR",
  "workflow": {
    "trigger": {
      "version": 1,
      "object_type": "payable",
      "action": "create",
      "currency": "EUR",
      "amount": {
        "gt": 50000
      }
    },
    "functions": [
      {
        "call": {
          "method": "Payables.request_approval_by_entity_user",
          "params": {
            "entity_user_ids": [
              "5f3196d2-48ce-4c1e-b29e-c3e5d1fb7a13"
            ]
          }
        }
      }
    ]
  }
}

Create a workflow

To create a customized workflow, complete the following steps:

1. Create a role

To manage the workflow objects, the entity users must have a specific role assigned that allows them to create, read, update, and delete the workflows.

This role is created by calling POST /roles:

curl -X POST 'https://api.sandbox.monite.com/v1/roles' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "all-access-example",
  "permissions": {
    "objects": [
      {
        "object_type": "workflow",
        "actions": [
          {
            "action_name": "create",
            "permission": "allowed"
          },
          {
            "action_name": "read",
            "permission": "allowed"
          },
          {
            "action_name": "update",
            "permission": "allowed"
          },
          {
            "action_name": "delete",
            "permission": "allowed"
          }
        ]
      }
    ]
  }
}'

The successful response contains the ID assigned to this role:

{
  "id": "8cd8c515-9862-4cbb-8f1e-511d081e5b73",
  "name": "all-access-example",
  "permissions": {...},
  "status": "active",
  "created_at": "2022-04-22T13:15:20.415Z",
  "updated_at": "2022-04-22T13:15:20.415Z"
}

2. Assign the created role to the entity user

The previously created role ID must be assigned to the entity user that will create the workflow. The entity-level token is still necessary for this action:

curl -X PUT 'https://api.sandbox.monite.com/v1/entity_users/{entity_user_id}/{role_id}' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' 

3. Create a workflow

To create a workflow, call POST /workflows passing the workflow object:

curl -X POST 'https://api.sandbox.monite.com/v1/workflows' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "policy_name": "Sample workflow",
    "policy_description": "Manager approval is required for any payables over 500 EUR",
    "workflow": { ... }
   }'

4. Upload the payable

Submit the payable. If the collected payable matches the workflow trigger conditions, it will automatically be inserted into this workflow.

5. Get notified about the required actions

If the workflow started for a payable requires the approval of specific entity users, reminder notifications are sent by email indicating when the payable needs to be approved or paid.

The notification email contains information about the payable and the link to perform the required action.

The link for approval can be defined in the partner settings by calling PATCH /settings:

curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
  -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payable": {
      "approve_page_url": "https://monite.pay/cs_test_a1Olodw1w6YKbShWJHKcBPEATjtYF9I5aNbPOwTm"
    }
  }

Once all the required approvers have approved the payable, the entity user who uploaded the invoice is notified by an email with information about the invoice to be paid and a link to the payment provider.

List all workflows

To get a list of all existing workflows, call GET /workflows:

curl -X GET 'https://api.sandbox.monite.com/v1/workflows?order=asc&limit=100&sort=created_at&object_type=payable' \
  -H 'x-monite-entity-id: 9d2b4c8f-2087-4738-ba91-7359683c49a4'

The results can be:

  • Sorted by:

    • created_at

    • updated_at

    • policy_name

  • Filtered by:

    • object_type: exact match

    • policy_name: exact match, **contains, **icontains

    • action: exact match

    • created_by: exact match

    • created_at: exact match, **gt, **gte, **lt, **lte

    • updated_at: exact match, **gt, **gte, **lt, **lte

📘

Check also the standard pagination, sorting, and filtering parameters.

Retrieve a workflow by ID or name

To get information about a specific workflow by ID, call GET /workflows/{workflow_id}.

To find a workflow by name, call GET /workflows?policy_name=<Name>.

Check which workflow applies to which payable

Whenever a new workflow is created, or a payable is created or updated, Monite checks if there is a match between the workflows and payables. If a payable is found to match some workflow's trigger conditions, the workflow name is stored in the applied_policy property of the Payable object.

You can see this property in the responses from GET /payables and GET /payables/{payable_id}:

curl 'https://api.sandbox.monite.com/payables' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' 

In this example, two payables have workflows applied to them, whereas the third one does not (in which case the applied_policy is null):

{
  "data": [
    {
      "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
      ...
      "applied_policy": "Travel expenses"
    },
    {
      "id": "d76988a2-d710-4e81-832a-a008bfbcae5d",
      ...
      "applied_policy": "Website"
    },
    {
      "id": "49170bab-4fb9-4f4a-ba8f-45e1e6c13a24",
      ...
      "applied_policy": null
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}

Alternatively, you can call GET /payables/{payable_id}/workflow to get the contents and metadata of the workflow that applies to the given payable ID:

curl 'https://api.sandbox.monite.com/v1/payables/{payable_id}/workflow' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' 

The response contains the full workflow object:

{
  "id": "98737901-337a-49a6-8e08-78f0bf650440",
  "created_by_entity_user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "role": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Role name",
      "permissions": {
        "objects": [
          {
            "object_type": "payable",
            "actions": [
              {
                "action_name": "read",
                "permission": "allowed"
              }
            ]
          }
        ]
      },
      "status": "active",
      "created_at": "2022-08-26T12:22:22.334Z",
      "updated_at": "2022-08-26T12:22:22.334Z"
    },
    "userpic": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_at": "2022-08-26T12:22:22.334Z",
      "file_type": "payables",
      "name": "invoice.pdf",
      "region": "eu-central-1",
      "md5": "31d1a2dd1ad3dfc39be849d70a68dac0",
      "mimetype": "application/pdf",
      "url": "https://bucketname.s3.com/12345/67890.pdf",
      "size": 24381,
      "previews": [],
      "pages": []
    },
    "info": {
      "email": "[email protected]",
      "phone": "string"
    },
    "login": "Meme Lord",
    "first_name": "First name",
    "last_name": "Last name",
    "status": "active",
    "created_at": "2022-08-26T12:22:22.334Z",
    "updated_at": "2022-08-26T12:22:22.334Z"
  },
  "object_type": "payable",
  "policy_name": "Expense approval",
  "policy_description": "",
  "workflow": [
    {
      "call": {
        "method": "Payables.request_approval_by_entity_user",
        "params": {
          "entity_user_ids": [
            "5f3196d2-48ce-4c1e-b29e-c3e5d1fb7a13"
          ]
        }
      }
    }
  ],
  "trigger": {
    "version": 1,
    "object_type": "payable",
    "action": "create",
    "currency": "EUR"
  },
  "action": "create",
  "created_at": "2022-06-27T12:49:55.932Z",
  "updated_at": "2022-06-27T12:49:55.932Z"
}

Delete a workflow

To delete an existing workflow, call DELETE /workflows/{workflow_id}.

📘

It is not possible to delete or modify a workflow currently active (e.g. there are business logic objects currently being processed by the workflow).


Did this page help you?