Configuration

The Configuration service allows apps and blocks to define static configuration parameters that users can set during app installation or block provisioning. These parameters can be of various types, such as strings, numbers, booleans, or even more complex structures using JSON Schema.

Declaring configuration

Both app definitions and block definitions can include a config field, which describes the map of configuration parameters available for that app or block.

Each field in the config map is represented by an object with the following fields:

• name (string, required): The name of the configuration parameter.
• description (string, optional): A human-readable description of the configuration parameter.
• type (Type, required): The type of the configuration parameter. This can be one of the basic types (string, number, boolean) or a complex type defined using JSON Schema.
• fixed (boolean, optional): If set to true, the configuration parameter cannot be changed after the app or block is installed/provisioned.
• required (boolean, required): Indicates whether the configuration parameter is required.
• default (any, optional): The default value for the configuration parameter if none is provided by the user.
• sensitive (boolean, optional): If set to true, the configuration parameter is treated as sensitive and will be masked in the UI.

Example: declaring app configuration

import { defineApp } from "@slflows/sdk/v1";

export const app = defineApp({
  // ... other app definition fields ...
  config: {
    apiKey: {
      name: "API Key",
      description: "The API key for accessing the external service.",
      type: "string",
      required: true,
      sensitive: true,
    },
    timeout: {
      name: "Timeout",
      description: "The timeout value in seconds.",
      type: "number",
      default: 30,
    },
    enableFeatureX: {
      name: "Enable Feature X",
      description: "Whether to enable Feature X.",
      type: "boolean",
      default: false,
    },
  },
});

Using configuration

When an app is installed or a block is provisioned, users can provide values for the defined configuration parameters. These values can then be accessed within any service handlers whose input includes the app or block context, under the config field.

Example: accessing app and block configuration

Below is a minimal example of accessing both app and block configuration parameters within a block event handler:

import { AppBlock } from "@slflows/sdk/v1";

export const myBlock: AppBlock = {
  // ... other block definition fields ...
  onEvent: async (input) => {
    console.log("App config:", input.app.config);
    console.log("Block config:", input.block.config);
  }
});

App access to block configuration

App installation configuration parameters are directly accessible to both the app itself, as well as all the blocks within that app installation. Block provisioning configuration parameters are only directly accessible within the specific block instance they are defined for.

However, the app installation service handlers can dynamically retrieve the list of all blocks using the same app installation using the list function from the blocks package in the Apps SDK. The return value of this method includes the configuration parameters for each block instance, allowing the app to access block-specific configuration as needed.

Example: app accessing block configuration

In the following example, an app receiving a webhook request on its HTTP endpoint finds all blocks that may be interested in this request based on their configuration:

import { blocks } from "@slflows/sdk/v1";

export const app = defineApp({
  // ... other app definition fields ...
  http: {
    async onRequest(input) {
      const { event, topic } = input.request.body;

    const interestedBlocks = (
      (await blocks.list({ typeIds: ["topicSubscription"] })).filter((block) => block.config.topic === topic);
    );

    // Perform actions with the interested blocks.
  }
});

Most likely, the app will then want to forward the event to each of these blocks using internal messaging via the Messaging service.