Procedures

Learn how to implement a procedure in a custom book.

To implement a procedure in a custom book, define a Python function in your book class and decorate it with @procedure.

Requirements

1. Naming

Ensure the name of your procedure adheres to the syntax guidelines specified in the name parameter of the @procedure decorator.

2. Method Docstrings

Your method docstring should include the following sections:

• A brief summary of the procedure

• Input Concepts

• Output Concepts

Examples are not required but are valuable for generating usage documentation.

3. Concept-Parameter Matching

Concepts and parameters must match to ensure they are properly mapped internally. Ensure your method definition adheres to the guidelines.

Using Procedures in Your Automation

Singularized Calls

A singularized call is a way to call a procedure by phrasing it as if it returns a single item, even though it returns a list by definition. A procedure supports singularized calls in addition to standard calls if it meets all of the following conditions:

• Returns a list.

• The output of the procedure is the object itself.

• The output noun phrase is plural.

• The procedure accepts filters.

You don't need to implement additional logic for singular calls. The system will automatically generate the singularized variation of any procedure that meets the above criteria.

Example

Consider a procedure that retrieves users from Outlook. It can be called in two ways:

• Standard Way: get some users from outlook whose whose mail is "example.com"

• Singularized Way: get a user from outlook whose whose mail is "example.com"

@procedure("to get some (users) from *office365*")
async def retrieve_users(self, filter_expression: Optional[FilterExpression] = None) -> List[OfficeUser]:
  """
  Retrieves Office 365 users accessible via the Microsoft Graph API.

  It requires the following permissions on the application:
  User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

  Returns:
  A list of Office 365 users.

  Example 1:
  Retrieve all users

  >>> get users from office365

  Example 2:
  Retrieve a user whose email matches the specified email address

  >>> get users from office365 whose mail is "[email protected]"
  """