LogoLogo
About
  • Home
  • Guides
  • BDK
  • REST API
  • BDK Overview
  • Planning Guide
  • Setup Guide
  • Development Guide
  • Deployment
  • Learning a BDK Book
  • Connection Commands
  • BDK API Reference
    • Concepts
    • Connections
    • Decorators
      • @book
      • @concept
      • @config
      • @connect
      • @oauth
      • @oauthtoken
      • @procedure
    • Docstrings
    • Enums
      • FilterBinaryOperator
      • FilterUnaryOperator
    • Filter Expressions
    • Noun Phrases
    • Procedures
Powered by GitBook
On this page
  • Implementing Procedures
  • Requirements
  • 1. Naming
  • 2. Method Docstrings
  • 3. Concept-Parameter Matching
  • Using Procedures in Your Automation
  • Singularized Calls

Was this helpful?

Export as PDF
  1. BDK API Reference

Procedures

Learn how to implement a procedure with the BDK.

Last updated 1 month ago

Was this helpful?

Implementing Procedures

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

Requirements

1. Naming

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

2. Method Docstrings

Your method 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 .


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. BDK 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 "john@acme.org"
  """

Refer to for examples of procedure implementations.

@procedure
@procedure
docstring
guidelines
this section