Communicators

In this guide, you'll learn how to communicate with external APIs and services from a DBOS application.

We recommend that all communication with external services be done in communicator functions. For example, you can use communicators to serve a file from AWS S3, call an external API like Stripe or access a non-Postgres data store like Elasticsearch. Encapsulating these calls in communicators is especially important if you're using workflows so the workflow knows to execute them only once.

Communicators must be annotated with the @Communicator decorator and must have a CommunicatorContext as their first argument. As with other DBOS functions, communicator inputs and outputs must be serializable to JSON. Here's a simple example using Axios to call the Postman Echo API:

  @Communicator()
  static async greetPostman(ctxt: CommunicatorContext, greeting: string) {
    await axios.get("https://postman-echo.com/get", {
      params: {
        greeting: greeting
      }
    });
    ctxt.logger.info(`Greeting sent to postman!`);
  }

Retries

By default, DBOS automatically retries any communicator function that throws an exception. It retries communicator functions a set number of times with exponential backoff, throwing an exception if the maximum number of retries is exceed. Retries are fully configurable through arguments to the @Communicator decorator.

Retries​

Retries