How to Learn a BDK Book

1. Retrieve the HTTPS endpoint from your deployment.

2. Place this at the beginning of your automation, substituting your own endpoint in the syntax:

learn "https://<your-endpoint>"

After successfully building your Book and creating a Docker image, the next step is deployment. You have the flexibility to deploy your Book to any environment that supports external access and routing, ensuring it can be reached from Kognitos. The choice of deployment method will depend on your organization's specific preferences and requirements. Common deployment options include:

• On-premises infrastructure

Prerequisites

Ensure the following prerequisites are met and dependencies are installed before proceeding.

Setting Up Your Project

Set up your project using the BDK Template, a tool designed to simplify the creation of Books.

1. Clone and Initialize

Enter the following project details or press Enter to keep the defaults:

2. Enter Project Directory

Navigate into the new project directory. Replace project_slug with your own Project Slug from the previous step:

3. Create a Virtual Environment (recommended)

We recommend creating a virtual environment to isolate and manage your project dependencies.

2. Create a virtual environment:

3. Activate the virtual environment

Note: To later exit the virtual environment later, run deactivate.

4. Install dependencies

What is the BDK?

Although Kognitos builds and maintains a variety of Books to address common automation use cases, there may be situations where a custom Book is needed. The BDK is designed to help with:

1. Custom Integrations

With the BDK, you can create procedures that interact with third-party APIs, databases, and external services. If your organization uses tools or services not natively integrated with Kognitos, you can build a custom Book to integrate them directly into your automation workflows.

2. Extending Core Functionalities

Extend Kognitos’ features to support more complex scenarios beyond standard functionality. Whether you need to support advanced data manipulation or custom data validation, the BDK provides the tools to create custom Books that meet your unique requirements.

BDK Components

The BDK is comprised of the following software components:

Book Development Lifecycle

The Book Development Lifecycle outlines the stages of software development for a new Book and how the BDK components interact throughout the process.

1. Planning

The planning phase is where the Book's functionality is defined. In this stage, you identify the external systems the Book will integrate with and outline the workflows or automation goals. This stage clarifies objectives and requirements, setting the foundation for development.

2. Development

The development phase is where the Book’s functionality is implemented using the BDK API and other tools:

• The BDK Book Template provides starter code to streamline setup.

• The BDK Linter enforces coding standards and identifies potential issues.

• The BDK Poetry Plugin manages dependencies, versioning, and documentation.

3. Testing

The testing phase ensures that Books perform as intended. The BDK Book Template includes a testing framework for validating Book functionality.

4. Packaging & Deployment

In this stage, the Book is packaged and prepared for deployment. The code is packaged with the BDK Runtime using Docker and deployed externally.

5. Execution

Once deployed, the Book is ready to run in Kognitos, enabling you to extend your automations with custom workflows.

Resources

• Planning Your BDK Project

• BDK Setup Guide

• BDK Development Guide

• BDK API Reference

Example Books

Project Structure

The project is organized with the following structure:

📂 sample_book
├── 📁 src
│   └── 📁 sample_book
│       ├── 📃 __init__.py
│       ├── 📃 __version__.py
│       └── 📃 book.py
│       └── 📁 data
│           └── 🖼️ icon.svg
├── 📁 tests
│   └── 📃 test_book.py
├── 📃 Dockerfile
├── 📃 pyproject.toml
├── 📃 poetry_scripts.py
├── 📃 poetry.lock
├── 📃 README.md
└── 📃 USAGE.md

Root Directory

The project root directory is named using the Project Slug (default: sample_book).

Source Code Directory

• 📃 book.py: Contains the core class where your Book is defined and implemented.

• 📁 data: Holds images like 🖼️ icon.svg, the default SVG used as a Book's icon.

Test Directory

• 📃 test_book.py: Contains unit tests to validate the Book's functionality.

Configuration and Dependency Files

• 📃 Dockerfile: Builds the Docker image.

• 📃 pyproject.toml: Manages dependencies and settings.

• 📃 poetry_scripts.py: Custom automation script.

• 📃 poetry.lock: Locks dependency versions.

Documentation

• 📃 README.md: Project overview documentation, including setup and usage instructions.

• 📃 USAGE.md: Reference documentation for your Book. This file is not included by default. For details on how to generate it, see Generating Documentation.

Implementation

Implement your Book in book.py. This class is auto-generated by the BDK Template and serves as the starting point for your Book’s implementation. Use decorators to configure settings, define procedures, and establish API connections. Refer to the BDK API Reference and example Books for details.

Development Commands

This section outlines essential commands for Book development and testing.

Formatting

Code formatting automatically adjusts your code's structure, ensuring adherence to coding standards, readability, and maintainability. To apply the formatting, run:

poetry run format

Linting

Pylint is used as the source linter for BDK projects. The linter analyzes and enforce coding standards, checks for errors in Python code, and improves code quality. To run the linter:

poetry run lint

Generating Documentation

This command will generate a comprehensive USAGE.md file by extracting and formatting the docstrings from your code. To generate the documentation, run:

poetry run doc

Testing

Pytest is used to test and validate your book. To run the test suite:

poetry run tests

Packaging with Docker

Build a Docker image to package your Book:

docker build -t <project_slug>:<version> .

docker build --platform linux/amd64 -t <project_slug>:<version> .

Running Your Book Locally

To test your Book in Kognitos before deployment, you can run your Docker image locally with ngrok. Ngrok is a tool that creates a secure tunnel to your local machine and provides a public URL to make your local Docker image accessible from the platform.

1. Install ngrok

Follow the installation steps for ngrok based on your system. You will need to sign up for a free account.

2. Obtain your ngrok authtoken

Navigate to Your Authtoken in the ngrok portal and copy your token.

3. Add your authtoken

ngrok config add-authtoken <token>

4. Configure the ngrok api key as an environment variable:

export NGROK_AUTHTOKEN=<token>

5. Build & run in ngrok mode

This command will invoke a custom script that builds the Docker image and runs it in ngrok mode:

poetry run host

If you are running into issues with `poetry run host`, you can package and run your book manually with the following command:

docker run -e BDK_SERVER_MODE=ngrok -e NGROK_AUTHTOKEN=<auth_token> <project_slug>:<version>

Make sure to replace auth_token, project_slug, and version with your own values.

6. Copy the URL

You'll see the ngrok address in the following format in the logs. Copy the URL:

listening on https://<SOME_UUID>.ngrok-free.app

7. Add the URL to your automation

Copy the URL and paste it into your Kognitos Playground using this syntax:

learn "https://f1d7-100-34-252-18.ngrok-free.app"

What are Concepts?

Concepts define how data flows in and out of a procedure:

• Input concepts represent the inputs that a procedure requires.

• Output concepts represent the results that a procedure generates.

Concept Types

Input and output concepts can be defined as either standard or custom types.

Standard Types

The following Python data types can be used to define concepts:

Custom Types

Concepts vs. Parameters

Concepts and parameters are two different entities that are closely related.

Concepts

Parameters

Parameters are operated on by Python functions. They are defined in a function's signature and are specific to the function's implementation.

How Are They Related?

Concept-Parameter Matching

Concepts and parameter names must match to ensure they are properly mapped internally.

Guidelines

Match concepts to parameters by following these guidelines:

1. Replace spaces with underscores.

2. Drop possessive constructions ('s).

4. Don't map articles ('an', 'a', 'the') to parameters; only the nouns they connect should be considered.

5. Define optional parameters in cases where the input concept is not explicitly defined in the procedure name.

Example 1

In this example, the concept red car maps to the parameter red_car. The space is replaced with an underscore.

Example 2

In the example below:

• servicenow's ticket maps to ticket

• field maps to field

• outlook's standard user maps to standard_user

Example 3

In this example, the concept ticket maps to the parameter ticket. The possessive construct ('s) is dropped and the word "field" is ignored.

Example 4

In the example below, the concept of priority is not explicitly stated in the procedure name. It maps to the optional function parameter, priority.

Example 5

In this example:

• the city maps to the parameter city

• the unit maps to the optional parameter the unit

The output concept, current temperature, is wrapped in parenthesis in the procedure name.

Overview

Syntax

Keyword Arguments

is_a=["red dragon", "big house", "wooden door"] = red dragons's big house's wooden door

Example

The following example demonstrates the usage of the @concept decorator to define the custom concept sms message:

Overview

Syntax

Use the following syntax to write a connection command in a Kognitos automation:

Components

• {preposition} – Any preposition that aligns with the plurality of the noun phrase. For example:

  • Plural noun phrase: via some API keys

  • Singular noun phrase: via a client credentials method

Passing Arguments

To pass arguments to your connection, add the with keyword at the end of the syntax. List each argument on a separately indented line, using the following format:

Examples

1. Without Connection Arguments

2. Using Connection Arguments

In this example, api keys is the noun phrase, and several connection arguments are provided.

Overview

The @book decorator is used to identify a class as a Book.

Syntax

Keyword Arguments

Default Icon

If an icon is not specified, this will be used as the default.

Example

Implementing Connections

Multiple Connections

Method Docstrings

In your connection method docstring, include the following sections in addition to a brief summary:

1. Arguments

Specify the Python function's parameters.

2. Labels

When a label is provided in the docstring, the lowercase form is used in a connection command. When not provided, the label will be inferred from the Python variable name.

Example

In this example, API Key is the label for the api_key connection argument. The lowercase version of the label is used in a connection command (api key):

Additional Examples

1. api_key: ApI kEy

In this example, the connection command uses the lowercase form of ApI kEy:

1. api_key: aPi_KeY

In this example, the connection command uses the lowercase version of aPi_KeY:

1. No Label

If a label is not provided in the docstring, it is inferred from the Python variable name, api_key:

Software Requirements

• GitHub Account

• Docker

• Cookiecutter

• Python 3.11+

Book Design

Designing a Book involves defining these procedures to ensure they align with the automation’s objectives. To guide this process, take into account the following considerations:

1. Functionality

Questions

• What actions does the user need to automate in Kognitos?

• Can the actions be broken down into individual steps?

Examples

Consider these procedures for a Weather Book:

• Get the current temperature in a specific city.

• Check the current air quality index (AQI).

• Determine delays or disruptions caused by severe weather for shipping and transportation.

• Notify attendees of weather-related changes for events.

2. Data

Questions

• What input or parameters are needed for each procedure?

• What output or data should each procedure return upon completion?

• How will data be transformed, manipulated, or processed in each procedure?

Examples

Consider an procedure that gets the temperature in a specific city:

3. Error Handling

Questions

• What are the potential error scenarios that could occur?

• How will these errors be handled and/or logged?

Examples

Consider the following error scenarios for a Weather Book:

1. Invalid Input

• A user enters a non-existent city name (e.g., "Atlantis").

• The system receives a blank input for the city name.

2. API Unavailability

• The weather API is temporarily down or unreachable.

• A network timeout occurs during an API call.

Integrations

If you plan to integrate with an external API in your Book, it’s important to assess the target service's requirements, limitations, and authentication mechanisms. The following considerations will ensure your chosen API aligns with your automation needs and integrates seamlessly into your BDK project.

1. Authentication & Authorization

Questions

• Does the API require authentication? If so, what kind?

• Are there specific permissions or roles required to access certain API endpoints?

• Can you obtain the necessary access and permissions for all required credentials?

2. Functionality & Data Flow

Questions

• Which API endpoints will your Book use?

• What data will be sent or received?

3. Rate Limits and Usage

Questions

• Are there API rate limits or usage quotes?

• Does the API’s rate limit support the expected request volume for your workflows?

• Are there additional costs or restrictions for exceeding usage limits?

4. Documentation and Support

Questions

• Is the API documentation comprehensive and easy to follow?

• Does the API provider offer support?

5. Scalability

Questions

• Can the API handle increasing request volumes as workflows grow?

• Does the API support additional functionality that might be required in future Books?

Deployment

Considerations

1. Ensure the required infrastructure is in place to deploy a Docker container in the cloud, on-premises, or in a hybrid environment.

2. Plan strategies for:

   1. Managing the container lifecycle, including scaling, networking, and security.

   2. Implementing logging to track container activity

   3. Monitoring container health and performance

   4. Updating Docker images for new releases with clear versioning and testing practices.

Overview

The @oauthtoken decorator marks a function as handling OAuth tokens, enabling the function to be automatically recognized as part of an OAuth workflow.

Syntax

Note: This decorator always applies to the same method signature, but the method itself can have any name.

Example

Overview

The config decorator is used to decorate a property in a Book class that defines default configuration values.

Syntax

Keyword Arguments

Example

Overview

The @oauth decorator is used to apply OAuth-based authentication to classes. It adds OAuth-specific metadata, such as endpoints, arguments, and provider details, to the class, enabling integration with OAuth services.

Syntax

Parameters

Example

Enum Definition

from enum import Enum

class OAuthFlow(Enum):
    """Represents the different OAuth 2.0 flow types."""
    AUTHORIZATION_CODE = 0
    CLIENT_CREDENTIALS = 1

Enum Members

Example Usage

@oauth(
    id="oauth",
    provider=OAuthProvider.MICROSOFT,
    flows=[OAuthFlow.AUTHORIZATION_CODE],
    authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
    token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
    scopes=[
        "https://graph.microsoft.com/Files.ReadWrite",
        "https://graph.microsoft.com/Sites.ReadWrite.All",
    ],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook

Enum Definition

from enum import Enum

class FilterUnaryOperator(Enum):
    """Represents the unary operators used in filtering procedures."""
    NOT = 0

Enum Members

Enum Definition

from enum import Enum

class FilterBinaryOperator(Enum):
    """Represents the different binary operators used in filtering procedures."""
    AND = 0
    OR = 1
    EQUALS = 2
    NOT_EQUALS = 3
    IN = 4
    HAS = 5
    LESS_THAN = 6
    GREATER_THAN = 7
    LESS_THAN_OR_EQUAL = 8
    GREATER_THAN_OR_EQUAL = 9

Enum Members

Enum Definition

from enum import Enum

class OAuthProvider(Enum):
  	"""Represents the supported OAuth 2.0 providers."""
    MICROSOFT = 0
    GOOGLE = 1

Enum Members

Example Usage

@oauth(
    id="oauth",
    provider=OAuthProvider.MICROSOFT,
    flows=[OAuthFlow.AUTHORIZATION_CODE],
    authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
    token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
    scopes=[
        "https://graph.microsoft.com/Files.ReadWrite",
        "https://graph.microsoft.com/Sites.ReadWrite.All",
    ],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook

Overview

Filter expressions enable you to define filter criteria for your procedures using the whose keyword. These expressions allow you to filter data based on conditions such as equality, comparisons, and more. For example:

get users from office365 whose email is "john@mail.org"

Implementation

1. Include the filter_expression parameter

To implement a filter expression, you need to provide the special filter_expression parameter in your procedure method definition. For example:

@procedure("to read some (*SMS* messages)")
def read_sms_messages(
    self,
    offset: Optional[int],
    limit: Optional[int],
    filter_expression: Optional[FilterExpression],
) -> List[SMSMessage]:
    """
    Read some SMS messages using the Twilio API.
    """

2. Implement Visitors

The FilterExpressionVisitor class is an abstract base class that defines methods for visiting different types of filter expressions. Each type of filter expression (binary, unary, value, noun phrase) is defined as a subclass of FilterExpression. You will need to define a class that implements these methods to handle filter expressions. For example:

class MyFilterVisitor(FilterExpressionVisitor):
    def visit_binary_expression(self, expression: FilterBinaryExpression) -> T:
        # Implement logic for handling binary expressions
        pass

    def visit_unary_expression(self, expression: FilterUnaryExpression) -> T:
        # Implement logic for handling unary expressions
        pass

    def visit_value(self, expression: ValueExpression) -> T:
        # Implement logic for handling value expressions
        pass

    def visit_noun_phrases(self, expression: NounPhrasesExpression) -> T:
        # Implement logic for handling noun phrases expressions
        pass

Below is an example implementation of the FilterExpressionVisitor class in the Twilio Book:

SENDER_NUMBER = NounPhrase.from_word_list(["sender", "number"])
RECIPIENT_NUMBER = NounPhrase.from_word_list(["recipient", "number"])
DATE_SENT = NounPhrase.from_word_list(["date", "sent"])


class SMSMessageFilter(FilterExpressionVisitor):
    """
    Extract filtering information from the expression
    """

    current_noun_phrase: Optional[NounPhrase] = None
    current_value: Optional[Any] = None

    recipient_number: Union[str, object] = values.unset
    sender_number: Union[str, object] = values.unset
    date_sent: Union[datetime, object] = values.unset
    date_sent_before: Union[datetime, object] = values.unset
    date_sent_after: Union[datetime, object] = values.unset

    def visit_binary_expression(self, expression: FilterBinaryExpression):
        expression.left.accept(self)
        expression.right.accept(self)

        if expression.operator == FilterBinaryOperator.EQUALS:
            if self.current_noun_phrase == SENDER_NUMBER:
                self.sender_number = str(self.current_value)
            elif self.current_noun_phrase == RECIPIENT_NUMBER:
                self.recipient_number = str(self.current_value)
            elif self.current_noun_phrase == DATE_SENT:
                if not isinstance(self.current_value, datetime):
                    raise TypeMismatchError("date_sent", ConceptScalarType.DATETIME)

                self.date_sent = self.current_value
        elif expression.operator == FilterBinaryOperator.GREATER_THAN:
            if self.current_noun_phrase == DATE_SENT:
                if not isinstance(self.current_value, datetime):
                    raise TypeMismatchError("date_sent", ConceptScalarType.DATETIME)

                self.date_sent_after = self.current_value
        elif expression.operator == FilterBinaryOperator.LESS_THAN:
            if self.current_noun_phrase == DATE_SENT:
                if not isinstance(self.current_value, datetime):
                    raise TypeMismatchError("date_sent", ConceptScalarType.DATETIME)

                self.date_sent_before = self.current_value
        elif expression.operator == FilterBinaryOperator.AND:
            pass
        else:
            raise ValueError(f"unsupported filtering operator: {expression.operator}")

    def visit_unary_expression(self, expression: FilterUnaryExpression):
        pass

    def visit_value(self, expression: ValueExpression):
        self.current_value = expression.value

    def visit_noun_phrases(self, expression: NounPhrasesExpression):
        if len(expression.noun_phrases) != 1:
            raise ValueError(
                f"unsupported filtering noun phrase: {expression.noun_phrases}"
            )

        if expression.noun_phrases[0] not in [
            SENDER_NUMBER,
            RECIPIENT_NUMBER,
            DATE_SENT,
        ]:
            raise ValueError(
                f"unsupported filtering noun phrase: {expression.noun_phrases}"
            )

        self.current_noun_phrase = expression.noun_phrases[0]

3. Processing Filter Expressions

Once you’ve defined your visitor class, you need to pass an instance of it to the filter expression. This is done by calling accept onfilter_expression. For example:

visitor = MyFilterVisitor()
filter_expression.accept(visitor)

Example

In this example, a filter expression is used in the read some SMS messages procedure:

@procedure("to read some (*SMS* messages)")
def read_sms_messages(
    self,
    offset: Optional[int],
    limit: Optional[int],
    filter_expression: Optional[FilterExpression],
) -> List[SMSMessage]:
    """
    Read some SMS messages using the Twilio API.

    Returns:
        A list of SMS messages that matches the specified filtering criteria

    Example 1:
        Retrieve SMS messages filtered by sender and recipient numbers

        >>> read some sms messages whose sender number is "+18004445555" and whose recipient number is "+18004446666"

    Example 2:
        Retrieve SMS messages filtered by the date in which they were sent

        >>> convert "2022-03-01T15:00:00Z" to a datetime
        >>> use the above as the message date
        >>> read some sms messages whose date sent is the message date

    Example 3:
        Retrieve SMS messages that were sent in the specified time period

        >>> convert "2022-03-01T15:00:00Z" to a datetime
        >>> use the above as the start date
        >>> convert "2022-03-03T15:00:00Z" to a datetime
        >>> use the above as the end date
        >>> read some sms messages whose date sent is after the start date and whose date sent is before the end date
    """
    client = Client(self._account_sid, self._auth_token)

    filter_visitor = SMSMessageFilter()

    if filter_expression is not None:
        filter_expression.accept(filter_visitor)

    messages = client.messages.list(
        to=filter_visitor.recipient_number,
        from_=filter_visitor.sender_number,
        date_sent=filter_visitor.date_sent,
        date_sent_before=filter_visitor.date_sent_before,
        date_sent_after=filter_visitor.date_sent_after,
    )

    if offset is not None:
        messages = messages[offset:]

    if limit is not None:
        messages = messages[:limit]

    return [SMSMessage.from_message_instance(message) for message in messages]

Overview

A noun phrase is a group of words centered around a noun. It consists of:

• Head: The main noun representing the fact.

• Modifiers: Optional words providing additional context to the head noun.

The NounPhase class can be used to represent a noun phrase.

Modifiers

A modifier is an optional part of a noun phrase that provides additional detail about the head noun. It appears before the head and refines the fact being referenced.

Example: Creating a Noun Phrase with Modifiers

# Create a noun phrase with a head and modifiers
np = NounPhrase("dog", ["big", "white"])
print(np)  # Outputs: big white dog

In this example:

• Head: "dog"

• Modifiers: "big", "white"

The resulting noun phrase is "big white dog".

Parameters as Noun Phrases

Parameters can be defined as NounPhrase types to tell the system to use a fact's name instead of its value.

Example: Defining a Parameter as a Noun Phrase

Consider the following procedure method definition, where the city parameter is defined as a NounPhrase:

@procedure("to get the (current temperature) at a city")
def current_temperature(
  self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")
) -> float:

This procedure can be called in an automation where London is a fact with a specific value:

London is "windy"
get the current temperature at London

In this example, when London is specified as the city parameter, the system uses the name of the fact (London) instead of its value ("windy").

Overview

The @connect decorator is used to wrap functions that handle connections or authentication tasks. It defines the syntax for writing a connection command, which instantiates the connection in Kognitos to the third-party API or service that's implemented in your Python function.

Syntax

@connect(*args, **kwargs)

Keyword Arguments

Implementation Example

This is an example implementation of connecting to the OpenWeather API using an API key:

@connect(noun_phrase="api keys")
def connect(self, api_key: str):
  """
  Authenticate to Open Weather API using the specified API key. 
  You can obtain your own API key by visiting Open Weather's 
  website at https://openweathermap.org/appid.

  Arguments:
      api_key: The API key to be used for connecting

  Labels:
      api_key: API Key
  """
  api_key = os.getenv("API_KEY", api_key)
  test_url = f"{self._base_url}?appid={api_key}&q=London"
  response = requests.get(test_url, timeout=self._timeout)
  if response.status_code == 401:
      response_data = response.json()
      if "Invalid API key" in response_data.get("message", ""):
          raise ValueError("Invalid API key")

  self._api_key = api_key

Refer to connections for additional context and usage examples.

Overview

The @procedure decorator is used to denote a method within a Book class as a procedure. This links a method to a specific procedure in the Kognitos platform.

Syntax

@procedure(name: str, **kwargs)

Guidelines

1. Naming Conventions

Names must begin with to. This defines the action or intent of the procedure. For example:

• @procedure("to capitalize a (string)"

• @procedure("to get the (current temperature)")

• @procedure("to send an *SMS* message")

2. Output Concepts

Output concepts are wrapped in parentheses (). For example:

@procedure("to capitalize a (string)")

3. Proper Nouns

Proper nouns are wrapped between asterisks **. For example:

@procedure("to get some (users) from *office365*")

In this example, office365 is considered a proper noun. The procedure is referred to as 'get some users from office365' rather than the office365.

Parameters

Keyword Arguments

Examples

1. Capitalizing a String

This method implements a procedure that capitalizes a string with one input concept and one output concept.

@procedure("to capitalize a (string)", connection_required=False)
def capitalize_string(self, string: str) -> str:
  """
  Capitalizes the input string.

  Input Concepts:
    the string: The string value you want to capitalize.

  Output Concepts:
    the string: The capitalized string.

  Example 1:
    Capitalize the string "hello"

    >>> capitalize "hello"

  """
  return string.capitalize()

2. Creating an Order in Truckmate

This method implements a procedure that creates an order in Truckmate. It has one input concept and two output concepts.

@procedure("to create an order in truckmate and get the order number and the bill number")
def create_order(self, order: OrderRequestConcept) -> Tuple[int, str]:
    """
    Create a new order in Truckmate.

    Input Concepts:
        the order: The Truckmate order request (acc to openAPI spec)

    Output Concepts:
        the order number: Order ID of the created order
        the bill number: Bill Number of the created order

    Raises:
        ValueError: If the order is not created successfully.

    Example 1:
        Create the order in Truckmate
        >>> create a json
        >>> use the above as the order
        >>> set the order's id to 1234
        >>> set the order's title to "Awesome title"
        >>> set order's body to "This is the body"
        >>> create the order in truckmate and get the order number and bill number
    """
    logger.info("Creating Order in Truckmate")
    post_body = OrdersPostRequest(orders=[order])
    response = post_orders.sync_detailed(
        client=self._client,
        body=post_body,
    )
    if response.status_code == 201:
        orders_response = response.parsed.to_dict()  # type: ignore
        if orders_response.get("orders"):
            order = orders_response.get("orders")[0]  # type: ignore
            return order.get("orderId"), order.get("billNumber")

    error_response = response.parsed.to_dict()  # type: ignore
    logger.error(
        "Error while creating order in truckmate:  %s",
        error_response.get("errorText"),
    )
    raise ValueError(error_response)

3. Reading SMS messages using the Twilio API

The following method implements a procedure that reads SMS messages using the Twilio API. In this example, SMS is a proper noun.

@procedure("to read some (*SMS* messages)")
def read_sms_messages(
    self,
    offset: Optional[int],
    limit: Optional[int],
    filter_expression: Optional[FilterExpression],
) -> List[SMSMessage]:
    """
    Read some SMS messages using the Twilio API.

    Returns:
        A list of SMS messages that matches the specified filtering criteria

    Example 1:
        Retrieve SMS messages filtered by sender and recipient numbers

        >>> read some sms messages whose sender number is "+18004445555" and whose recipient number is "+18004446666"

    Example 2:
        Retrieve SMS messages filtered by the date in which they were sent

        >>> convert "2022-03-01T15:00:00Z" to a datetime
        >>> use the above as the message date
        >>> read some sms messages whose date sent is the message date

    Example 3:
        Retrieve SMS messages that were sent in the specified time period

        >>> convert "2022-03-01T15:00:00Z" to a datetime
        >>> use the above as the start date
        >>> convert "2022-03-03T15:00:00Z" to a datetime
        >>> use the above as the end date
        >>> read some sms messages whose date sent is after the start date and whose date sent is before the end date
    """
    client = Client(self._account_sid, self._auth_token)

    filter_visitor = SMSMessageFilter()

    if filter_expression is not None:
        filter_expression.accept(filter_visitor)

    messages = client.messages.list(
        to=filter_visitor.recipient_number,
        from_=filter_visitor.sender_number,
        date_sent=filter_visitor.date_sent,
        date_sent_before=filter_visitor.date_sent_before,
        date_sent_after=filter_visitor.date_sent_after,
    )

    if offset is not None:
        messages = messages[offset:]

    if limit is not None:
        messages = messages[:limit]

    return [SMSMessage.from_message_instance(message) for message in messages]

Format

• Docstrings are placed immediately after function, class, or method definitions.

• A brief summary that describes the functionality begins the docstring.

• The summary is followed by organized sections, separated by blank lines and labeled with headers.

In BDK projects, docstrings are applied to decorated methods and classes.

Supported Sections

The following sections are supported in BDK docstrings, with alternative headers available for labeling flexibility.

1. Arguments and Parameters

Documents the arguments or parameters that a function or class accepts.

Supported Headers: Args, Arguments, Parameters, Params

Example

2. Return Values

Documents the return value of a function or method.

Supported Headers: Returns

Example

3. Error Handling

Lists any exceptions or errors that a function might raise.

Supported Headers: Raises, Exceptions, Except

Example

4. Instance Attributes

List instance attributes in a class.

Supported Headers: Attributes

Example

5. Code Authors

Attributes the author(s) of the code.

Supported Headers: Author

Example

6. Labels

Supported Headers: Labels

Example

7. OAuth Labels

Supported Headers: OAuth Labels

Example

8. OAuth Arguments

Supported Headers: OAuth Arguments

Example

9. Input Concepts

Supported Headers: Input Concepts

Example

10. Output Concepts

Supported Headers: Output Concepts

Example

11. Examples

Outlines usage examples for a procedure.

Supported Headers: Example, Examples, Example [1-5]

Example

Implementing Procedures

To implement a procedure 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 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.

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"
  """