# Custom action plugins

A custom action plugin is a [plugin](/advanced-usages/plugins.md) that can be associated to a custom action node in an automation, allowing you to trigger a custom action in an automation.

This feature is useful for triggering actions not available in the current list of actions in automations.

{% hint style="success" %}
If you don't know what a plugin is, you can find [complete documentation in the specific section.](/advanced-usages/plugins.md)
{% endhint %}

## Endpoints to implement

Custom action plugins have only one predefined endpoint to implement.

## Trigger a custom action

<mark style="color:green;">`POST`</mark> `myworker/v1/scenario_custom_actions`

This entry point is called any time a UserPoint goes through a custom action node in an automation.

#### Request Body

| Name               | Type   | Description                                                                                |
| ------------------ | ------ | ------------------------------------------------------------------------------------------ |
| user\_point\_id    | string | The ID of the UserPoint.                                                                   |
| custom\_action\_id | string | The ID of the custom action plugin instance. **Used to retrieve the instance properties.** |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "status": "ok"
}
```

{% endtab %}

{% tab title="500 Here is what the plugin should respond if it encounters an unexpected error." %}

```javascript
{
  "status": "error",
  "message": "..."
}
```

{% endtab %}
{% endtabs %}

See [Plugin Instances ](/advanced-usages/plugins.md#instances)to learn why you should use the `custom_action_id` parameter to retrieve the instance properties.

## Available outbound services

The code of the custom action plugin can call the following API endpoints to retrieve[ its instance context](/advanced-usages/plugins.md#instances).

## Retrieve the instance

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/scenario_custom_actions/:id`

Use the custom\_action\_id from the incoming request to retrieve the custom action plugin instance that has been called.

#### Path Parameters

| Name | Type   | Description                                                                                          |
| ---- | ------ | ---------------------------------------------------------------------------------------------------- |
| id   | string | ID of the custom action plugin instance, typically the `custom_action_id` from the incoming request. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "status": "ok",
  "data": {
    "id": "1000",
    "name": "Custom action plugin example",
    "organisation_id": "1000",
    "group_id": "com.example-organisation.scenario-custom-action",
    "artifact_id": "example-organisation-example-custom-action"
    "creation_ts": 1617100419508,
    "created_by": "28453014",
    "version_id": "1001",
    "version_value": "1.0.0"
  }
}
```

{% endtab %}
{% endtabs %}

## Retrieve the instance properties

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/scenario_custom_actions/:id/properties`

Get the properties associated with the custom action plugin instance.

#### Path Parameters

| Name | Type   | Description                                                                                        |
| ---- | ------ | -------------------------------------------------------------------------------------------------- |
| id   | string | ID of the custom action plugin instance, typically the`custom_action_id` from the incoming request |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "status": "ok",
  "data": [
    {
      "technical_name": "provider",
      "value": { "value": "mediarithmics" },
      "property_type": "STRING",
      "origin": "PLUGIN_STATIC",
      "writable": true,
      "deletable": false
    },
    {
      "technical_name": "name",
      "value": { "value": "Custom action example" },
      "property_type": "STRING",
      "origin": "PLUGIN_STATIC",
      "writable": false,
      "deletable": false
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Creating a custom action plugin

See the [plugins](/advanced-usages/plugins.md) documentation to see [how plugins are created and deployed](/advanced-usages/plugins.md).

{% hint style="success" %}
A custom action plugin has the `SCENARIO_CUSTOM_ACTION` plugin type. Its group id should be `{domain.organisation.scenario-custom-action}` (for example `com.mediarithmics.scenario-custom-action`).

Its artifact id should be the name of the custom action plugin, i.e. `example-custom-action`.
{% endhint %}

Use our [Plugin SDK](/resources/tools-and-libraries/plugin-sdk.md) to create your custom action plugin in `Node.js`: the required routes are already defined and you only have to override specific functions.

{% hint style="info" %}
You can find a sample custom action plugin [in the examples folder of the plugin SDK](https://github.com/MEDIARITHMICS/plugins-nodejs-sdk/tree/master/examples/activity-analyzer).
{% endhint %}

We can provide you with a *Hello World* project using our SDK. Please contact your support to gain access to it.

The project structure and files work as [with every other plugin](/advanced-usages/plugins/creation.md).

### Interfaces to implement

You should extend `CustomActionBasePlugin` class and implement the `onCustomActionCall` function from the plugin SDK.

The `onCustomActionCall` function is called every time a UserPoint runs through a custom action node in an automation. It is responsible for implementing the custom action.

{% hint style="warning" %}
Don't forget to catch your errors. You should log / respond with the appropriate message to facilitate debugging.
{% endhint %}

```javascript
import { core } from '@mediarithmics/plugins-nodejs-sdk';

export class MyCustomActionPlugin extends core.CustomActionBasePlugin {
  protected onCustomActionCall(
    request: core.CustomActionRequest,
    instanceContext: core.CustomActionBaseInstanceContext
  ): Promise<core.CustomActionPluginResponse> {

    // do stuff here

    const response: core.CustomActionPluginResponse = {
      status: 'ok',
    };

    return Promise.resolve(response);
  }
}
```

## Create a custom action plugin instance

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/scenario_custom_actions`

Use this method to create a custom action plugin instance attached to an organisation. This will display the custom action as a choice in the custom action automation node.

#### Request Body

| Name             | Type   | Description                                                                                      |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------ |
| organisation\_id | string | The ID of the organisation you want to attach this instance to.                                  |
| name             | string | The name for this instance. If not given, the instance ID will be used in the interface instead. |
| artifact\_id     | string | The artifact ID of the plugin.                                                                   |
| group\_id        | string | The group ID of the plugin.                                                                      |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": "ok",
    "data": {
        "id": "string",
        "name": "string",
        "organisation_id": "string",
        "group_id": "string",
        "artifact_id": "string",
        "creation_ts": 1618842498220,
        "created_by": "string",
        "version_id": "string",
        "version_value": "string"
    }
}
```

{% endtab %}
{% endtabs %}

## Update a custom action plugin instance property

<mark style="color:orange;">`PUT`</mark> `https://api.mediarithmics.com/v1/scenario_custom_actions/:id/properties/technical_name=:name`

Use this method to update a property for the custom action plugin instance.

#### Path Parameters

| Name | Type   | Description                                   |
| ---- | ------ | --------------------------------------------- |
| name | string | The technical name of the property to update. |
| id   | string | The ID for the custom action plugin instance. |

#### Request Body

| Name            | Type    | Description                                                                                                                                                                       |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| deletable       | boolean |                                                                                                                                                                                   |
| writable        | boolean |                                                                                                                                                                                   |
| origin          | string  | One of `PLUGIN_STATIC`, `PLUGIN`, `INSTANCE`.                                                                                                                                     |
| property\_type  | string  | One of `DOUBLE`, `INT`, `BOOLEAN`, `ASSET`, `DATA_FILE`,  `URL`, `STRING`, `AD_LAYOUT`, `STYLE_SHEET`, `PIXEL_TAG`, `RECOMMENDER`, `NATIVE_IMAGE`, `NATIVE_TITLE`, `NATIVE_DATA`. |
| technical\_name | string  | The technical name of the property to update.                                                                                                                                     |
| value           | object  | Value format depends on property type. If property type is `STRING`,  value will be an object `{"value": "string"}`.                                                              |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": "ok",
    "data": {
        "technical_name": "string",
        "value": {
            "value": "string"
        },
        "property_type": "STRING",
        "origin": "PLUGIN",
        "writable": true,
        "deletable": false
    }
}
```

{% endtab %}
{% endtabs %}

## Debugging

### Plugin logs and metrics

You can monitor custom action plugins[ as you do with all plugins](/advanced-usages/plugins/monitoring.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.mediarithmics.io/advanced-usages/automations/custom-action-plugins.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.