Custom Actions Reference

Create a custom action

Creates a new custom action for an existing BRYTER application, with the given metadata.

HTTP/1.1
POST /api/application/<application-id>/actions
Accept: application/json
Content-Type: application/json
Authorization: Bearer <actions-api-key>

Configure you API client to use this settings

🧑‍💻

Example: you are going to create a custom action node that counts the words in a text input. So it takes the text entered in the previous node as input, then applies custom code to that input (counts the words number), and then returns a number representing the number of words the text contains.

{
  "key": "word-count",
  "name": "Word count",
  "description": "Counts words in the input text",
	"developerEmail": "mail@example.com",
  "parameters": [
    {
      "name": "Text to count",
      "type": "text",
      "description": "The text to count"
    }
  ],
  "result": {
    "type": "number",
    "description": "The number of words in the text"
  }
}

Request with JSON metadata body

HTTP/1.1 201 Created
Location: /api/action/<action-id>

Success response after creating a new action

Parameters

Parameters is an array of objects, where each object is a value that is passed to the custom code function. Below there is a full list of objects, currently available to use in the custom action. We can use any of them in any combinations.

{
  "name": "Text",
  "type": "text",
  "description": "The text value"
}

Text input parameter.

{
  "name": "Number",
  "type": "number",
  "description": "The number value"
}

Number input parameter.

{
  "name": "Datetime",
  "type": "datetime",
  "description": "The date value"
}

Date input parameter.

{
  "name": "Email",
  "type": "email",
  "description": "The email value"
}

Email input parameter.

{
  "name": "Single choice",
  "type": {
    "type": "single-choice",
    "choices": [
      {
        "id": "id_1",
        "label": "Label 1"
      },
      {
        "id": "id_2",
        "label": "Label 2"
      },
      {
        "id": "id_3",
        "label": "Label 3"
      }
    ]
  },
  "description": "The single choice value"
}

Single select input parameter with 3 options to choose from.

{
  "name": "Multiple select",
  "type": {
    "type": "multiple-select",
    "choices": [
      {
        "id": "id_1",
        "label": "Label 1"
      },
      {
        "id": "id_2",
        "label": "Label 2"
      },
      {
        "id": "id_3",
        "label": "Label 3"
      }
    ]
  },
  "description": "The multiple select value"
}

Multi-select input parameter with 3 options to choose from.

{
  "name": "Collection of numbers",
  "type": {
    "type": "collection",
    "items": "number"
  },
  "description": "The collection of numbers value"
}

Collection input parameter. Can consist of different objects of the same type. In this case it is a collection of numbers, but it also could be a collection of texts, dates, emails. We can’t combine objects of different type in one collection though.

Result

Result is the output of the custom action and it can be referenced in other nodes in the BRYTER module’s logical tree. In the metadata, the output is indicated in the result property which is a JSON object, and it can be a simple object that contains one result like in the example below

"result": {
  "type": "number",
  "description": "provides the sum of 2 number inputs"
}

Simple custom action result which is a number.

or it can be a complex object that other objects that are expected to be obtained as a result of performing a custom action.

"result": {
    "type": {
      "type": "object",
      "properties": {
        "text": {
          "type": "text"
        },
        "email": {
          "type": "email"
        },
        "number": {
          "type": "number"
        },
        "datetime": {
          "type": "datetime"
        }
      }
    },
  "description": "provides the object with different types of results"
}

Result as object with text, email, number, date values inside.

Update custom action metadata

Create a PUT method and add the action ID at the end (which you get as part of the response when creating an action) of the URL

PUT /api/actions/<ACTION ID>
{
  "key": "word-count",
  "name": "Word count",
  "description": "Counts words in the input text",
	"developerEmail": "hello@example.com",
  "parameters": [
    {
      "name": "text",
      "type": "text",
      "description": "The text to count words in"
    }
  ],
  "result": {
    "type": "number",
    "description": "The number of words in the text"
  }
}

Add or update a custom action’s code

Creates or replaces the custom code of an existing action, previously added to a BRYTER application, without changing its metadata.

💡

Make sure you know your action id if you are going to replace its custom code. It can be found in the list of all created custom actions.

HTTP/1.1
PUT /api/actions/<action-id>/implementation
Accept: application/json
Content-Type: application/typescript
Authorization: Bearer <actions-api-key>

Configure you API client to use this settings

function main(text: string): number {
  return text.split(/\s+/).length
}

Request, which body is the Javascript or TypeScript source

Delete a custom action

Deletes a custom action with the provided key.

⚠️

Deleting a custom action will break existing modules which reference them, so make sure you have updated any modules before deleting

HTTP/1.1
DELETE /api/actions/<action-id>
Content-Type: application/json
Authorization: Bearer <actions-api-key>

Get list of custom actions for an application

Returns a list of custom actions created for the specific application. Replace application-id with real application id to create correct request endpoint. For successful authorization use your actions-api-key as a token.

HTTP/1.1
GET /api/application/<application-id>/actions HTTP/1.1
Accept: application/json
Authorization: Bearer <actions-api-key>

Request

HTTP/1.1 200 OK
Content-type: application/vnd.restful+json

[
  {
    "key": "trim",
    "name": "Trim whitespace",
    "description": "Remotes whitespace from the start and end of a text value",
    "id": "dOhBvvZnVz92mExFqfTAx3",
    "eventsUrls": {
      "Test": {
        "/api/actions/dOhBvvZnVz92mExFqfTAx3/environments/iaHCdVI3RGae679bRJnSRg/events"
      },
      "Live": {
        "/api/actions/dOhBvvZnVz92mExFqfTAx3/environments/iaHCdVI3RGae679bRJnSRg/events"
      }
    }
  },
  {
    "key": "word-count",
    "name": "Word count",
    "description": "Counts words in the input text",
    "id": "P3jJuhcUJoWLFsYdjLZ3Ww",
    "eventsUrls": {
      "Test": {
        "/api/actions/P3jJuhcUJoWLFsYdjLZ3Ww/environments/x3GcRp5rQ5WlwTwWvJeCsg/events"
      },
      "Live": {
        "/api/actions/P3jJuhcUJoWLFsYdjLZ3Ww/environments/x3GcRp5rQ5WlwTwWvJeCsg/events"
      }
    }
  }
]

Success response, listing actions in alphabetical order by name

Get a list of events for a custom action

Whenever you run a module with a custom action there is an event log which shows the results. It can contain useful information in the case of a failure.

The only way to get these URLs is to copy them from the eventUrls when getting a list of custom actions, the format of the URLs is shown below.

HTTP/1.1
GET /api/actions/<action-id>/environments/<environment-id>/events
Accept: application/json
Authorization: Bearer <actions-api-key>

The response contains a list of events which can have the name “success” or “failure”. In the log you will see a list of all the log statements run in the custom action.

[
	{
		"id": "441bc03c-31c2-4923-aa7e-23fbcc122f8f",
		"name": "success",
		"data": {
			"timings": {
				"duration": 1,
				"startTime": 1678946839993
			},
			"logs": []
		}
	}
]