External actions

The "External Actions" feature empowers users to trigger and execute actions and processes in external systems, outside of fulfillmenttools. This includes functionalities such as sending consumer emails, adjusting payments, and other order-related processes.

The primary goal of this feature is to facilitate seamless communication with third-party systems. Users can define the capabilities and functionalities of external actions by utilising our API and seamlessly integrating our platform with other systems.

There are currently two types of external actions available: "LINK" and "FORM." With the "LINK" type, users can attach a link or deeplink to an order, enabling users to execute processes in the linked external system manually.

On the other hand, the "FORM" type allows you to define a modal where users can input data. Upon confirmation, an external event is triggered, enabling the execution of further processes (this must be done by a connector).

Executing an external action is logged and displayed in our order history, providing users with visibility into the actions taken throughout the order workflow.

Example for how to define a external action with Type FORM
{
    "processRef": "6aca1c80-c418-4064-b173-63fb120aef2d",
    "groups": ["Trainingsgruppe B"],
    "nameLocalized": {
        "de_DE": "Zahlungen anpassen",
        "en_US": "Adjust payments"
    },
    "action": {
        "type": "FORM",
        "elements": [
            {
                "elementType": "HEADLINE",
                "title": "string", // Returns value from "titleLocalized"
                "titleLocalized": {
                    "de_DE": "Zahlungen zu dieser Bestellung anpassen",
                    "en_US": "Adjust payments for this order"
                }
            },
            {
                "elementType": "SUBHEADLINE",
                "title": "string", // Returns value from "titleLocalized"
                "titleLocalized": {
                    "de_DE": "In diesem Modal können Sie Zahlungsanpassugen vornehmen. Dies kann entweder ein prozentualer oder ein frei gewählter Rabatt sein.",
                    "en_US": "In this modal you can make payment adjustments. This can either be a percentual or a freely selected discount."
                }
            },
            {
                "elementType": "TEXT",
                "style": "BODY",
                "title": "string", // Returns value from "titleLocalized"
                "titleLocalized": {
                    "de_DE": "-",
                    "en_US": "-"
                }
            },
            {
                "elementType": "TEXT",
                "style": "BODY",
                "title": "string", // Returns value from "titleLocalized"
                "titleLocalized": {
                    "de_DE": "Rabatt in %",
                    "en_US": "Discount in &"
                }
            },
            {
                "elementType": "TEXT_INPUT",
                "elementId": "4712",
                "label": "string", // Returns value from "labelLocalized"
                "titleLocalized": {
                    "de_DE": "%",
                    "en_US": "%"
                },
                "isMandatory": false,
                "validation": {
                    "validationType": "FLOAT",
                    "minValue": 1, // OPTIONAL
                    "maxValue": 100 // OPTIONAL
                }
            },
            {
                "elementType": "TEXT",
                "style": "BODY",
                "title": "string", // Returns value from "titleLocalized"
                "titleLocalized": {
                    "de_DE": "-",
                    "en_US": "-"
                }
            },
            {
                "elementType": "TEXT",
                "style": "BODY",
                "title": "string", // Returns value from "titleLocalized"
                "titleLocalized": {
                    "de_DE": "Rabatt in €",
                    "en_US": "Discount in €"
                }
            },
            {
                "elementType": "TEXT_INPUT",
                "elementId": "4713",
                "label": "string", // Returns value from "labelLocalized"
                "titleLocalized": {
                    "de_DE": "€",
                    "en_US": "€"
                },
                "isMandatory": false,
                "validation": {
                    "validationType": "INTEGER",
                    "minValue": 1, // OPTIONAL
                    "maxValue": 1000 // OPTIONAL
                }
            },

            {
                "elementType": "TEXT",
                "style": "INFO",
                "title": "string", // Returns value from "titleLocalized"
                "titleLocalized": {
                    "de_DE": "Die Anpassung der Abrechnung wird durch ein Fremdsystem durchgeführt.",
                    "en_US": "The billing adjustment is carried out by a third-party system."
                }
            }
        ],
        "success": {
            "label": "string", // Returns value from "labelLocalized"
            "labelLocalized": {
                "de_DE": "Bestätigen",
                "en_US": "CONFIRM"
            }
        },
        "cancel": { // OPTIONAL
            "label": "string", // Returns value from "labelLocalized"
            "labelLocalized": {
                "de_DE": "Abbrechen",
                "en_US": "CANCEL"
            }
        }
    }
}

Nice to know:

  • You can add multiple external actions to an order.

  • You can group external actions so they can be assigned to a theme

  • The user who triggered such an external action is displayed at the order history page on the right side. It looks like this

It is possible to create a subscription to receive events when executing an external action. You will be informed when the action has been executed, e.g. by clicking on a link.

Example of subscribing to an external action event

A POST call to subscribe to an external action event could look like this. In this example, a subscription is created to receive events when an external action is executed.\

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/subscriptions' \
--header 'Authorization: Bearer <TOKEN>' 
--header 'Content-Type: application/json' 
--data-raw '{
"callbackUrl": "https://webhook.site/1c90a559-dd18-4e45-95ec-04821d705466",
"event": "EXTERNAL_ACTION_EXECUTED",
"headers": [
{
"key": "X-My-Auth",
"value": "Basic ZnVsZmlsbG1lbnR0b29sczppc2Jlc3Q="
}
],
"name": "EXTERNAL_ACTION_EXECUTED"
}'

To get a deeper insight into how to create a subscription, follow the instructions from the Tutorial.

Last updated