Implementing Operations

To implement an operation in a BDK project, define a Python function in your Book class and decorate it with the @procedure decorator.

Requirements

1. Naming

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

• Naming Conventions
• Output Concepts
• Proper Nouns

2. Method Docstrings

Your method docstring should include the following sections:

• A brief summary of the operation
• 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.

👍

Examples of Operations

Refer to this section for examples of operation implementations.

Using Operations in Your Automation

Singularized Calls

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

• Returns a list.
• The output of the operation is the object itself.
• The output noun phrase is plural.
• The operation accepts filters.

👍

You don't need to implement additional logic for singular calls. BDK will automatically generate the singularized variation of any operation 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]"
  """