Create a custom step for Workflow Builder: existing Bolt app

First update your package.json file to reflect version 1.20.0 of Bolt, then run the following command in your terminal:

npm install

First update your requirements.txt file to reflect version 1.20.0 of Bolt, then run the following commands in your terminal:

python3 -m venv .venv 
source .venv/bin/activate 
pip install -r requirements.txt

Open your app.js file and add the following function listener code for the request_time_off step.

app.function('request_time_off', async ({ client, inputs, fail }) => {
  try {
    const { manager_id, submitter_id } = inputs;

    await client.chat.postMessage({
      channel: manager_id,
      text: `<@${submitter_id}> requested time off! What say you?`,
      blocks: [
        {
          type: 'section',
          text: {
            type: 'mrkdwn',
            text: `<@${submitter_id}> requested time off! What say you?`,
          },
        },
        {
          type: 'actions',
          elements: [
            {
              type: 'button',
              text: {
                type: 'plain_text',
                text: 'Approve',
                emoji: true,
              },
              value: 'approve',
              action_id: 'approve_button',
            },
            {
              type: 'button',
              text: {
                type: 'plain_text',
                text: 'Deny',
                emoji: true,
              },
              value: 'deny',
              action_id: 'deny_button',
            },
          ],
        },
      ],
    });
  } catch (error) {
    console.error(error);
    fail({ error: `Failed to handle a function request: ${error}` });
  }
});

Anatomy of a .function() listener

The function listener registration method (.function()) takes two arguments:

• The first argument is the unique callback ID of the step. For our custom step, we’re using request_time_off. Every custom step you implement in an app needs to have a unique callback ID.
• The second argument is an asynchronous callback function, where we define the logic that will run when Slack tells the app that a user in the Slack client started a workflow that contains the request_time_off custom step.

The callback function offers various utilities that can be used to take action when a function execution event is received. The ones we’ll be using here are:

• client provides access to Slack API methods — like the chat.postMessage method, which we’ll use later to send a message to a channel
• inputs provides access to the workflow variables passed into the step when the workflow was started
• fail is a utility method for indicating that the step invoked for the current workflow step had an error

Open your app.py file and add the following function listener code for the request_time_off step.

@app.function("request_time_off")
def handle_request_time_off(inputs: dict, fail: Fail, logger: logging.Logger, say: Say):

    submitter_id = inputs["submitter_id"]
    manager_id = inputs["manager_id"]

    try:
        say(
            channel=manager_id,
            text=f"<@{submitter_id}> requested time off! What say you?",
            blocks=[
                {
                    "type": 'section',
                    "text": {
                        "type": 'mrkdwn',
                        "text": f"<@{submitter_id}> requested time off! What say you?",
                    },
                },
                {
                    'type': 'actions',
                    'elements': [
                        {
                            'type': 'button',
                            'text': {
                                'type': 'plain_text',
                                'text': 'Approve',
                                'emoji': True,
                            },
                            'value': 'approve',
                            'action_id': 'approve_button',
                        },
                        {
                            'type': 'button',
                            'text': {
                                'type': 'plain_text',
                                'text': 'Deny',
                                'emoji': True,
                            },
                            'value': 'deny',
                            'action_id': 'deny_button',
                        },
                    ],
                },
            ],
        )
    except Exception as e:
        logger.exception(e)
        fail(f"Failed to handle a function request (error: {e})")

Anatomy of a function() listener

The function decorator (function()) accepts an argument of type str and is the unique callback ID of the step. For our custom step, we’re using request_time_off. Every custom step you implement in an app needs to have a unique callback ID.

The callback function is where we define the logic that will run when Slack tells the app that a user in the Slack client started a workflow that contains the request_time_off custom step.

The callback function offers various utilities that can be used to take action when a function execution event is received. The ones we’ll be using here are:

• inputs provides access to the workflow variables passed into the step when the workflow was started
• fail indicates when the step invoked for the current workflow step has an error
• logger provides a Python standard logger instance
• say calls the chat.Postmessage API method

In that same app.js file, add the following action listener:

app.action(/^(approve_button|deny_button).*/, async ({ action, body, client, complete, fail }) => {
  const { channel, message, function_data: { inputs } } = body;
  const { manager_id, submitter_id } = inputs;
  const request_decision = action.value === 'approve';

  try {
    await complete({ outputs: { manager_id, submitter_id, request_decision } });
    await client.chat.update({
      channel: channel.id,
      ts: message.ts,
      text: `Request ${request_decision ? 'approved' : 'denied'}!`,
    });
  } catch (error) {
    console.error(error);
    fail({ error: `Failed to handle a function request: ${error}` });
  }
});

Anatomy of an .action() listener

Similar to a function listener, the action listener registration method (.action()) takes two arguments:

• The first argument is the unique callback ID of the action that your app will respond to. In our case, because we want to execute the same logic for both buttons, we’re using a little bit of RegEx magic to listen for two callback IDs at the same time — approve_button and deny_button.
• The second argument is an asynchronous callback function, where we define the logic that will run when Slack tells our app that the manager has clicked or tapped the Approve button or the Deny button.

Just like the function listener’s callback function, the action listener’s callback function offers various utilities that can be used to take action when an action event is received. The ones we’ll be using here are:

• client, which provides access to Slack API methods
• action, which provides the action’s event payload
• complete, which is a utility method indicating to Slack that the step behind the workflow step that was just invoked has completed successfully
• fail, which is a utility method for indicating that the step invoked for the current workflow step had an error

In that same app.py file, add the following action listener:

@app.action(re.compile("(approve_button|deny_button)"))
def manager_resp_handler(ack: Ack, action, body: dict, client: WebClient, complete: Complete, fail: Fail, logger: logging.Logger):

    ack()

    try:
        inputs = body['function_data']['inputs']
        manager_id = inputs['manager_id']
        submitter_id = inputs['submitter_id']
        request_decision = action['value']

        client.chat_update(
            channel=body['channel']['id'],
            message=body['message'],
            ts=body["message"]["ts"],
            text=f'Request {"approved" if request_decision == 'approve' else "denied"}!'
        )

        complete({
            'manager_id': manager_id,
            'submitter_id': submitter_id,
            'request_decision':  request_decision == 'approve'
        })

    except Exception as e:
        logger.exception(e)
        fail(f"Failed to handle a function request (error: {e})")

Anatomy of an .action() listener

Similar to a function listener, the action listener registration method (.action()) takes a single argument: the unique callback ID of the action that your app will respond to.

In our case, because we want to execute the same logic for both buttons, we’re using a little bit of RegEx magic to listen for two callback IDs at the same time — approve_button and deny_button.

The callback function argument is where we define the logic that will run when Slack tells our app that the manager has clicked or tapped the Approve button or the Deny button.

Just like the function listener’s callback function, the action listener’s callback function offers various utilities that can be used to take action when an action event is received. The ones we’ll be using here are:

• ack returns acknowledgement to the Slack servers
• action provides the action’s event payload
• body returns the parsed request body data
• client provides access to Slack API methods
• complete indicates to Slack that the step behind the invoked workflow step has completed successfully
• fail indicates when the step invoked for the current workflow step has an error
• logger provides a Python standard logger instance