Actions

Actions allow admins to create predefined Web requests which take user-provided inputs.

Overview

• Actions can be created by admins, and can be run by:
• Admins, or
• Users with "Can edit" permissions
• An Action an admin-defined Web request, which can target:
• Your own Web server, or
• A 3rd party Web server
• An Action can take, and be run with, admin-defined inputs
• These inputs can be set to come pre-filled, for the user who goes to run the Action
• Upon running the action, our back-end constructs a Web request based on the Action's definition and the submitted values of the inputs
• Inputs can be wired up to pass their submitted values to the URL, headers, and/or body of the Web request to be executed
• An action can be associated with a table from one of your SQL database connections
• In this case, the Action becomes available to be run with values from a selected record when working in a view based on that table
• Additionally, the action's pre-fill values can incorporate values from the selected record

Step 1: Add an API connection to Basedash

• From your Workspace via “Add connection”
• From within an App, when adding an Action, you'll be prompted to select an existing API connection, or if you have none, to proceed to creating one. (See below screenshot)

• Once created, API connections appear in the sidebar from your Workspace. (See below screenshot)

An API connection provides the foundation for one or more Actions

• An API connection defines:
• A base URL, e.g. https://www.example.com/api
• Zero or more request headers, e.g. Authorization Bearer 12345678-9876-pretend-example-token

• https://www.example.com/api
• /widgets/go
• /collections/archive
• /users/{{ userID }}/settings
• /widgets?id={{ widgetID }}
• ...

The building blocks of an HTTP request

• The API connection provides:
• The Base URL
• Common request headers
• The Action provides:
• The HTTP method
• A URL path
• Endpoint-specific request headers
• A request body

Step 2: Create an Action

Screenshot legend:
1) Action name
2) HTTP method
3) Base URL (from the chosen API connection)
4) URL path
5) Interpolation helper
    (a popover available in multiple places in the Action builder)
6) User inputs
7) Request headers
    (including those that come from the chosen API connection)
8) Request body
    (can be empty)
9) Preview area
    (As you define the Action you'll see it reflected here)
10) cURL area
    (Values from the preview inputs will be reflected here)
History pane (not pictured)

1. Select the HTTP request method from the dropdown (e.g. POST)
2. Select the Base URL (defined in your chosen API connection, see ”Adding an API connection” above)
3. Optionally provide a URL path to be joined with the Base URL

4. Provide a short, descriptive Name for your action
5. Optionally, choose an Associated table from one of your SQL database connections

6. Optionally provide Button text to be seen on the button your users use to ultimately run the action
7. Provide a detailed Description to be presented to users of the Action
1. The Description text ends up presented above the User inputs when going to run the Action
2. You can include links in the description (e.g. to your own documentation, or to documentation about the endpoint) and they will be rendered as links for users of the Action
8. Define one or more User inputs
1. Click the “+” button to the right of the User inputs section heading
2. Provide a Label for the input
3. The Identifier will be automatically generated based on the Label
🏷️
The Identifier is used as a handle for interpolating input values into the following parts of the Action: - URL Path - Header values - Body (More details in the below section, “Variable interpolation”)
4. Choose a Type for the input (text or textarea)
5. Optionally provide some Prefill text, which will be used to prefill the input for the user going to run the Action
🪄
If the Action is associated with a table from one of your SQL connections, in the Prefill text you can interpolate column values using the double curly bracket syntax, e.g. {{ User.fullName }} (More details in the below section, “Variable interpolation”)
6. Optionally provide some Helper text which will be displayed adjacent to the given input for the user going to run the Action
9. Define one or more Headers
📒
The Headers defined in an Action are specific to the Action being created. They get included with the Web request along with any “common” headers which come from the chosen API connection (See above section on “API connections”)
1. Provide a Name for the header
2. Provide a Value for the header
🪄
In a header’s Value you can interpolate values from the Action’s User inputs using the double curly bracket syntax, e.g. {{ userId }} (More details in the below section, “Variable interpolation”)
10. Optionally define a Body for the Action
1. The Body is the plain-text payload for the Web request to be executed
2. It might be a JSON string, or delimited key value pairs, or something else, depending on the type of payload expected by your endpoint
🪄
In the Action’s Body you can interpolate values from the Action’s User inputs using the double curly bracket syntax, e.g. {{ userId }} (More details in the below section, “Variable interpolation”)

Working with the Preview area

• You’ll see a preview for User input fields appearing on the right in the Preview area.
• You can try running the Action from there in the Preview area (but if you have unsaved changes you’ll need to save first).
• You’ll also see a snippet of shell script with a curl command.
• You can use this to get an idea of the ultimate Web request that will be executed.
• You can copy and paste it into a terminal and try running it with test data to see how the endpoint responds. This can be a useful tool for development, debugging, and testing.
• The curl command can help to diagnose issues, to see whether the issue is with the Web request itself, or possibly with Basedash’s execution of the Web request (in either case, please don’t hesitate to reach out to us for support anytime).
• You can type values into the User inputs of the preview area and see them reflected in the curl command via interpolation

Saving and testing your action

• As you build up your Action, note that changes are not saved until you hit the “Save” or “Done editing” button in the header.
• If you click “Save”, your Action will be saved, but you’ll remain in Action builder. You can try inputting values and running your Action there from the Preview area. You’ll also see warnings for common issues with defining an Action.
• If you click “Done editing”, you’ll be taken to the Action page for the action you’ve created
• Try running your Action there and seeing the response
• Click the “Edit” button to return to the Action builder and modify, and then save again, and repeat.

Explainer: Variable Interpolation

• Say you have a variable userName, and you want to put the value of that variable into a message.
• You can write the message like so: "Hello, {{ userName }}. How's it going?".
• And then, when you execute the interpolation (say with a value for userName of “Louis”), then what you get is the message: “Hello, Louis. How’s it going?”

Case 1: Interpolating User inputs into the Web request

1. The URL path
• e.g. /users/{{ userID }}/settings
2. The Value of a request Header
• e.g. Say you add a custom Header whose Name is User-ID, then you could set its Value to be {{ userID }}
3. The request Body, e.g.

{
  "renew": true,
  "userID": {{ userID }}
}

• The request URL would end up like: https://www.example.com/users/42/settings
• The request header would end up like: User-ID 42
• The request Body would end up like:

{
  "renew": true,
  "userID": 42
}

Case 2: Interpolating column values to be “prefilled” into a User input

• A User input called “Message”:
• You could define the Prefill text to be Hello, {{ Subscriber.fullName }}, thank you for signing up.
• A User input called “Email”:
• You could define the Prefill text to be {{ Subscriber.email }}
• A User input called “Plan renewal date”
• You could define the Prefill text to be {{ Subscriber.renewsOn }}

• “Message” would be prefilled with e.g. “Hello, Amelia, thank you for signing up.”
• “Email” would be prefilled with e.g. “amelia@example.com”
• “Plan renewal date” would be prefilled with e.g. “Jul 26, 2022”

Use with caution!

• You have an endpoint which deals with a resource called “collection”
• The route for this endpoint is https://api.yourcompany.com/collections/:collectionId
• You create an Action which would take the “Collection ID” via User input (with variable identifier collectionID) and pass it through to the URL
• You’ve setup your chosen API connection to have the following Base URL: https://api.yourcompany.com
• You define the URL path for your Action to be /collections/{{ collectionID }}
• Then, someone goes to run the action, and they are asked to provide a value for the “Collection ID”
• Normally, they would pass an ID like 42
• But, what if they passed the following: /72/widgets/128?!?

Step 3: Run the Action

1. Select an Action to go to its corresponding Action page (see screenshot)


Not pictured: You can view the history of runs of the action in the sidebar on this page.

2. Provide values to the User inputs
1. Depending on how the Action has been authored, they may be prefilled
2. You can modify any of the values of any of the inputs as you like. If you want to discard what you’ve put in the inputs and return to the initial prefilled values you can refresh the page
3. Review the values of your inputs, and then click the Run action button below the inputs (button text may be customized by the Action’s author)
4. Wait for response from the Web request to appear in a toast message in the bottom-right corner of the window

1. From your chosen view, select a record
2. You should see the Record details appear in the sidebar. If the sidebar isn’t expanded, click the left-arrow button to expand it
3. You should see the Available actions for the view. (See below screenshot)

4. Choose one of the Actions, and you will then open up the Action runner, and any Prefill values for the User inputs which were written to take data from the selected record, should have that data incorporated. (See below screenshot)

Coming soon

• Ability to see history of Actions run in your workspace via our Activity feed
• Ability to customize which Actions appear on a given view
• Currently, for an Action which is associated with a particular SQL database table, that Action would appear in the "Record details" sidebar on all views based on that table.
• More robust handling of whitespace and quotes
• Currently, there is little flexibility for formatting of the body of the Web request and how inputs are passed
• Ability to specify different body types, such as:
• raw
• form-data
• GraphQL
• JSON
• More detailed error messages when an action fails to run
• Richer UI for handling the response from the Web request
• e.g. prettified JSON
• Better interpolation flow (e.g. autocompletion)
• Warnings for issues in the Action builder interface
• Ability to define User inputs which are, locked, and/or hidden
• Ability select a record from the Associated table from the Action page
• Currently the only way to run an Action with values from a selected record is via a view)
• Ability for admins to manage "secrets" in a more discreet way
• Currently, if you define an API or an Action that requires credentials, e.g in a request Header, you have to put your credential there in the Basedash UI, and it is from then on visible to admins.
• Pull in data for a view from an API call (e.g. via an endpoint which returns a payload of JSON items)
• Better support for HTTP Basic authentication for an API connection

• Actions
• Overview
• Step 1: Add an API connection to Basedash
• An API connection provides the foundation for one or more Actions
• The building blocks of an HTTP request
• Step 2: Create an Action
• Working with the Preview area
• Saving and testing your action
• Explainer: Variable Interpolation
• Case 1: Interpolating User inputs into the Web request
• Case 2: Interpolating column values to be “prefilled” into a User input
• Use with caution!
• Step 3: Run the Action
• Coming soon