Actions in your App

Your App's Actions will be available via a REST API, the Bitmio SDKs and the CLI.

You define the Action input types a handler webhook and optionally the response type.

Creating an Action

We create a simple action that is supposed to respond with a list of Trello cards based on a search input.

bitmio projects myapp actions create search_trello

This immediately gives you instructions on how to invoke the new Action.

It hasn't been configured yet so invoking it will only return an error.

Configure the Action handler

To handle an Action you have to supply a webhook URL to which your App delegates all requests.

bitmio projects myapp actions search_trello set-webhook YOUR_WEBHOOK_URL

If you invoke your Action now it will forward the webhook response.

Testing an Action

We test our Action by passing it a search property which our webhook hopefully handles correctly:

bitmio projects myapp actions search_trello run --search "My Card"

Note that this is not the way our App user will invoke the Action - more on that later but it will look a lot simpler:

bitmio myapp search_trello --search "My Card"

Defining the Action Input

We can pass arbitrary properties to our Action - typing the input is optional.

By defining our input types we can automatically generate API docs and validate input.

bitmio projects myapp actions search_trello set-input \
  --field search --type string --name "Search" \
  --field max_age --type int? --name "Maximum Age"

This defines two input properties:

A field with ID search of type string with a human readable name of "Search".
A field with ID max_age as an optional int? with a name of "Maximum Age"

Passing App Integrations as input

To relieve our action handler from having to store the Trello authentication, we can pass the previously created Trello auth:

bitmio projects myapp actions search_trello set-input \
  --field trello --type trello_auth --value integrations.trello

Or to pass in our second Trello integration previously connected:

bitmio projects myapp actions search_trello set-input \
  --field trello --type trello_auth --value integrations.my_other_trello

The correct identifiers for the integrations can be retrieved with:

bitmio projects myapp integrations

The action handler webhook will receive the access tokens of the passed app integrations along with the other fields.

We omitting the --value option we can ask the app user to provider their own Trello connection:

bitmio projects myapp actions search_trello set-input \
  --field trello --type trello_auth

Updating Input Field Types

If we wanted change the name of an existing field:

bitmio projects myapp actions search_trello set-input \
  --field max_age --name "Max. Age"

Deleting Input Fields

If we wanted to delete existing fields:

bitmio projects myapp actions search_trello set-input \
  --field max_age --delete

Defining the Action Output

Analog to the input we can type the Action output.

Let's add some type definitions for our search_trello action.

bitmio projects myapp actions search_trello set-output \
  --field items --type [] --name "Trello Search Results"

This tells our Action to expect a list of items in property items.

Creating Custom Types

We want to specify this further and describe the type of items returned.

For this we need to create a custom Type first:

bitmio projects myapp types create trello_card \
  --name "Trello Card"
  --field title --type string --name "Title"
  --field description --type long_text --name "Description"
  --field due_date --type date? --name "Due Date"

Which tells Bitmio about our custom Trello Card type with ID trello_card.

We can now update our Action output type:

bitmio projects myapp actions search_trello set-output \
  --field items --type [trello_card]

Bitmio will now warn us whenever the returned output does not match the type definition.

Creating Actions