In this article, we'll show you the available resources and go through the basic steps to get started with creating your own custom steps.
Creating custom action steps allows you to customize the workflows of your Betty Blocks applications further. With custom steps, you can define your logic to meet the unique needs of your project. In this guide, we’ll walk you through the basics of action steps, the requirements for creating them, and a step-by-step tutorial on how to get started.
What Are Action Steps?
Action steps are the building blocks of logic within Betty Blocks applications. They represent the events and operations that define the application’s behavior. The action steps are categorized as:
- Authentication
- CRUD (Create, Read, Update, Delete)
- Debugging
- External
- Flow
- Miscellaneous
When Betty Blocks’ default action steps aren’t enough, you can create custom ones to suit your application’s specific needs.
Getting Started with Custom Action Steps
To create custom action steps, you’ll need some basic knowledge of:
- JavaScript (ES6)
- Command-line tools (Terminal or Command Prompt)
You’ll also need the following:
- Betty Blocks CLI is installed and running, see our ‘how to set up’ article in case you haven’t installed it
- A Code Editor, we recommend Visual Studio Code (VS Code).
Once ready, follow these steps:
1. Initialize Your Application
Run the following command in your terminal to initiate a new application:
$ bb functions init <your-app-identifier> --app
For example, if your application’s domain is cli-wiki.betty.app, use cli-wiki as the identifier.
Navigate to the created folder:
$ cd <your-app-identifier>
If you’re using VS Code, open the project:
$ code .
2. Create a New Function
To add a new custom action step, initialize a function using:
$ bb functions new <function-name>
For example:
$ bb functions new hello-world
This creates a folder for the function, containing two files:
- function.json: Defines the structure of the action step.
- index.js: Contains the JavaScript implementation of the function.
Configuring Your Custom Action Step
3. Configure function.json
Open function.json and provide details about your action step:
- Label: Name of your action step.
- Description: Short description of its functionality.
- Category: The category under which it appears in the action builder. You can choose between:
- Authentication
- Crud
- Debugging
- External
- Flow
- Misc
- Icon: The icon shown that represents your step. Choose from the available icons here.
- Options: Inputs, outputs, and validations for your action step. For more information on how to set this part of the JSON Schema please see our Wiki.
- Yields: Determines the function’s ability to execute nested steps. Supported values:
- NONE: No nested steps.
- ALL: Executes all nested steps.
- PATHS: Executes specific paths.
Example function.json:
{
"label": "Say Hello",
"description": "Say Hello to the world",
"category": "Misc",
"icon": {
"name": "ChatIcon",
"color": "Teal"
},
"options": [
{
"meta": {
"type": "Text"
},
"name": "name",
"label": "Name",
"info": "The name that's going to be used to say hello to the world!",
"advanced": false,
"configuration": {
"placeholder": "Betty Blocks"
}
},
{
"meta": {
"type": "Output",
"output": {
"type": "Text"
}
},
"name": "greet",
"label": "As",
"info": "The resulting greet to the world."
}
],
"yields": "NONE"
}
4. Implement index.js
Define the logic of your custom step in index.js. Ensure input variables in index.js match those defined in function.json.
Example index.js:
import join from 'lodash/join';
const sayHello = async ({ name }) => {
if (name === 'oops') {
throw new Error('Ooops. Something went wrong.');
} else {
return {
greet: join(['Hello', name], ', ')
};
}
};
export default sayHello;
Publishing and Testing Your Function
5. Publish the Function
Once your function is complete, publish it to your application:
$ bb functions publish
On first-time publishing, you’ll need your application’s UUID. To learn how to retrieve your application's ID, you can check out this article: Betty Blocks app ID.
6. Test the Function locally
The Betty Blocks platform has the built-in function to test your actions on our platform,
If you want to test your new action as you normally would on our platform, you can skip this last part. But if you are interested in testing your custom action locally, you can definitely do that.
- Download isolatedVM. see the requirements and how to install them here.
If you don't have isolatedVM installed and try run the $ bb functions test command you will see this output:
Unable to run tests (isolated-vm is not installed). If you want to install isolated-vm, you will need to install the following requirements: (make, g++ and python) and run "npm update -g @betty-blocks/cli"
- Test away
Use the following command to test your function in an isolated environment:
$ bb functions test
Place test files in your project's/test folder and ensure they follow the *.test.js naming convention; the testing code won’t work otherwise.
Editing or Deleting Functions
You can change or remove a function by editing the .bb-cli.json file in your user directory.
!!Warning!! This file contains critical information about your project, so proceed cautiously when making changes.
Key Commands Reference
- Initialize Project:
$ bb functions init <app-id> --app
- Create New Function:
$ bb functions new <function-name>
- Validate Functions:
$ bb functions validate
- Publish Functions:
$ bb functions publish
- Test Functions:
$ bb functions test
- Bump Version:
$ bb functions bump
By following these steps, you’ll be able to create, configure, and deploy custom action steps that extend the functionality of your Betty Blocks application. Happy building!
Do you want to discuss the creation of your action step with other developers? Check out our community!