Partner Portal

MoniteScript

Learn and explore all the possibilities of the Monite script.

Overview

MoniteScript is our unique declarative programming language based on JSON syntax that allows the creation of complex business logic scenarios related to business logic objects.

Through the MoniteScript, it is possible to implement customized scenarios, such as:

  • Set a specific approval policy for all payables with more than 300 EUR worth to be approved by a specific entity user.
  • Set a specific approval policy for all payables between 1000 and 5000 GBP worth to be approved by any user with a specific role.

πŸ“˜

Currently, the MoniteScript only supports the payable object. More objects will be added to the MoniteScript in the near future.

The sample script below defines an approval policy in which all the payables over 500 worth submitted for approval must be approved by at least two users from a given list:

{
  "name": "Sample approval policy",
  "description": "Approval of two users required for any payables over 500 worth",
  "trigger": {"all": ["{event_name == 'submitted_for_approval'}", "{invoice.amount >= 50000}"]},
  "script": [
    {
      "call": "ApprovalRequests.request_approval_by_users",
      "params": {
          "user_ids": [
            "91bff192-1a13-4a13-a4da-a2945ed0537d", 
            "ae6e88a8-c088-428c-ace2-d657bf407805",
            "c2daca46-c0cb-45a3-a3a2-bfb1e768104c"
          ],
          "required_approval_count": 2
        }
      }
    ]
}

The MoniteScript consists of two parts:

  • trigger: The conditions for the script execution.

  • script: The main logical statement executed.

Trigger

The trigger defines the conditions that cause the script to be executed. According to the sample trigger below, all payables submitted for approval above 500 worth will be affected by the script:

  "trigger": {"all": ["{event_name == 'submitted_for_approval'}", "{invoice.amount >= 50000}"]},

The conditions of the trigger are defined by combining expressions with the parameters event_name and invoice. You can use the attributes of the invoice object such as invoice.amount and invoice.tags.name.

This is the list of available values for the parameterevent_name that can trigger actions:


Payables
  • created
  • updated
  • deleted
  • partially_paid
  • paid
  • approved
  • submitted_for_approval
  • created_from_mail
  • created_from_file_upload
  • rejected
  • canceled
  • ocr_finished

Script

The script is the main logical statement to be executed.

Below is an example of a script function. This example requires approval from two users from a given list:

"script": [
  {
    "call": "ApprovalRequests.request_approval_by_users",
    "params": {
        "user_ids": [
          "91bff192-1a13-4a13-a4da-a2945ed0537d", 
          "ae6e88a8-c088-428c-ace2-d657bf407805",
          "c2daca46-c0cb-45a3-a3a2-bfb1e768104c"
        ],
        "required_approval_count": 2
      }
    }
]

The MoniteScript language

The elements that compose the MoniteScript language are described below:

Connectors

A connector represents a business logic object as a class in the MoniteScript language. The connector has a group of methods to deal with a certain piece of functionality in MoniteScript.

The call clause is followed by the connector method that is going to be called. Optionally accepts params whose values are instances of a raw expression. Every parameter from that expression is going to be passed as an argument to the chosen connector method:

{
  "call": <Connector name expression>,
  "params": <Raw expression>
}

The connectors can also feature the any and all expressions:

{  
  "any": [  
    {  
      "call": <Connector name expression>,  
      "params": <Raw expression>  
    },  
    {  
      "call": <Connector name expression>,  
      "params": <Raw expression>  
    }  
  ]  
}
{
  "all": [
    {
      "call": <Connector name expression>,
      "params": <Raw expression>
    },
    {
      "call": <Connector name expression>,
      "params": <Raw expression>
    }
  ]
}

These are the supported connectors:


Payables

Payables

The payables connector has methods that allow you to modify the status of the payable. The params must be declared in raw expression.

Here are the available methods and their parameters for the Payables connector:

  • mark_as_paid(payable_id: uuid, comment: str)
  • approve(payable_id: uuid)
  • reject(payable_id: uuid)

Examples:

"script": [
  {
    "call": "Payables.mark_as_paid",
    "params": {
       "payable_id": "{invoice.id}",
       "comment": "Marked from approval.",
    },
  },
]
"script": [
  {
    "call": "Payables.approve",
    "params": {
       "payable_id": "{invoice.id}"
    },
  },
]
"script": [
  {
    "call": "Payables.reject",
    "params": {
       "payable_id": "{invoice.id}"
    },
  },
]

Approval requests

Approval requests

The approval requests connector is used to require approvals from users or roles. Here are the available methods for the approval requests connector:

  • request_approval_by_users(object_id: uuid, user_ids: list[uuid], required_approval_count: int)
  • request_approval_by_roles(object_id: uuid, role_ids: list[uuid], required_approval_count: int)

Examples:

"script": [
  {
    "call": "ApprovalRequests.request_approval_by_users",
    "params": {
       "user_ids": ["ae6e88a8-c088-428c-ace2-d657bf407805"],
       "required_approval_count": 1,
    },
  }
]
"script": [
  {
    "call": "ApprovalRequests.request_approval_by_roles",
    "params": {
       "object_id": "{invoice.id}",
       "role_ids": ["ae6e88a8-c088-428c-ace2-d657bf407805"],
       "required_approval_count": 1,
    },
  }
]

If statement

The if statement consists of three clauses: if, then, and else. An if clause can contain any expression that evaluates to a boolean value, while then and else clauses contain a JSON array of other statements. The else clause is optional.

{  
    "if": <Boolean Expression>,  
    "then": [<Statement or Expression>, ...],  
    "else": [<Statement or Expression>, ...]  
}

Expressions

The expressions used in MoniteScript are:


Primitives

Primitives

Primitives expressions include all JSON primitive types:

  • null
  • boolean
  • number
  • string

Array

Array

Evaluates to a JSON array of values, each one of which is also an expression. It is used inside any and all expressions.

[<Expression>, <Expression>, ...]

Any

Any

Returns true if at least one of the values in its array expression is true. So{"any": [true, false, false]} evaluates to true.

{
  "any": <Array expression>
}

All

All

Returns true only if all of the values in its array expression are true.
So {"all": [true, false, false]} evaluates to false.

{
  "all": <Array expression>
}


Not

Not

Evaluates to a boolean that is the complement of its inner expression.

{
  "not": <Expression>
}

Binary operation

Binary operation

Compares two operands and evaluates the result of the operation. The following operators are supported:

  • ==
  • !=
  • =
  • < or >
  • <= or >=
{
  "left_operand": <Expression>,
  "operator": "==",
  "right_operand": <Expression>
}


Name

Name

Retrieves the values of the variable Event, which has all the information about the event that triggered the MoniteScript execution.

Name expression supports the basic operations of access on the object: square bracket indexing (object_list[0]) and dot access (object.attribute).

{
  "name": "Event.invoice.counterparts[0].id"
}

Connector name

Connector name

Evaluates to specific methods from the connector classes. It uses the same syntax as the name expression with the only difference being that it evaluates to a non-JSON object.

As a result, connector name expression can only be used within call expressions.

"Payables.get"

Raw

Raw

Evaluates to a JSON object. It is only necessary because many other expressions are also JSON objects. The raw expression exists to distinguish expressions from regular JSON objects.

{
    <Any String>: <Expression>,
    <Any String>: <Expression>,
    ...
}


Evaluated string

Evaluated string

The evaluated string expression can evaluate to other expressions in the MoniteScript language. It allows writing simple scripts without delving into the complexities of binary operations and calls.

They are regular JSON strings wrapped in {}, to distinguish them from non-evaluated strings.

The different types of evaluated string are:

Primitive string

Evaluates to a simple string.

Evaluated string:

"{'hello world'}"

Evaluates to:

"hello world"

Name expression string

Evaluates to a name expression.

Evaluated string:

"{Event.invoice.amount}"

Evaluates to:

{
    "name": "Event.invoice.amount"
}

Binary expression string

A one-line syntax that evaluates to a binary operation expression.

Binary expression string:

"{83 > 11}"

Evaluates to false, which is the result of:

{
    "left_operand": 83,
    "operator": ">",
    "right_operand": 11
}

However, evaluated strings are recursive, so the following is supported:

Evaluated string:

"{Event.invoice.amount <= 100000}"

Evaluates to:

{
    "left_operand": {
        "name": "Event.invoice.amount"
    },
    "operator": "{=",
    "right_operand": 100000
}

Call string

A one-line syntax that evaluates to a call expression.

Evaluated string:

"{Payables.pay('payable_uuid')}"

Evaluates to:

{
  "call": "Payables.pay",
  "params": {
      "payable_id": "payable_uuid"
  },
}

Also, this evaluated string:

"{Payables.pay(Event.invoice.id)}"

Evaluates to:

{
  "call": "Payables.pay",
  "params": {
    "payable_id": {
      "name": "Event.invoice.id"
    }
  },
}


Chain Logic

Chain logic allows you to perform a series of sequential actions on a script, where each action is dependent on the previous one, without needing to write separate lines of code for each action. There are three types of chain logic:


Straight chain

Straight chain

On a straight chain, the first action must be executed before the script continues to the next. In the example below, the first approval must be performed before the second one, so the payable approval can be concluded:

[
  {
      "call": "ApprovalRequests.request_approval_by_users",
      "params": {
          "user_ids": [random_user_and_role_uuid],
          "required_approval_count": 1,
      },
  },        
  {
      "call": "ApprovalRequests.request_approval_by_users",
      "params": {
          "user_ids": [random_user_and_role_uuid],
          "required_approval_count": 1,
      },
  },
  "{Payables.approve(invoice.id)}"
]

"And" logic

β€œAnd” logic

A chain with an "And" condition refers to a situation where multiple conditions or actions are combined together using the all operator, and all of those conditions must be true or actions must be successfully executed for the overall chain to be considered successful.

In the example below, all approval requests are sent and their approval is required to conclude the payable approval:

[
  {
      "all": [
          {
              "call": "ApprovalRequests.request_approval_by_users",
              "params": {
                  "user_ids": [random_user_and_role_uuid],
                  "required_approval_count": 1,
              },
          },
          {
              "call": "ApprovalRequests.request_approval_by_roles",
              "params": {
                  "role_ids": [random_user_and_role_uuid],
                  "required_approval_count": 2,
              },
          },
      ]
  },
  "{Payables.approve(invoice.id)}"
]

β€œOr” logic

β€œOr” logic

A chain with an "Or" condition refers to a situation where multiple conditions or actions are combined together using the any operator, and at least one of those conditions must be true or actions must be successfully executed for the overall chain to be considered successful. Once one of the conditions returns true, the next ones will be canceled.

In the example below, only one type of approval is required to conclude the payable approval:

[
  {
      "any": [
          {
              "call": "ApprovalRequests.request_approval_by_users",
              "params": {
                  "user_ids": [random_user_and_role_uuid],
                  "required_approval_count": 1,
              },
          },
          {
              "call": "ApprovalRequests.request_approval_by_roles",
              "params": {
                  "role_ids": [random_user_and_role_uuid],
                  "required_approval_count": 2,
              },
          },
      ]
  },
  "{Payables.approve(invoice.id)}"
]