External actions

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

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" (actually there is also a third one "COMMENT" - but this will be taken up at the end of this article).

External action type LINK

With the "LINK" type, users can attach a link or deeplink to an process, enabling users to execute processes in the linked external system manually.

External action type FORM

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 LINK

A POST-call might look like this if you want to add an external action from type LINK. This example just adds a link to a payment provider.

POST {{host}}/api/externalactions

{
      "processRef": "PROCESS-REF-TO_WHICH_THE_ACTION_SHOULD_REFER",
      "nameLocalized": {
        "en": "Zahlungen anpassen",
        "de": "Adjust Payment"
      },
      "groups": [
        "string"
      ],
      "action": {
        "type": "BLANK_LINK",
        "linkUrl": "yourpaymentprovider.com/xyz..."
      }
    }

Example for how to define a external action with Type FORM

A POST-call might look like this if you want to add an external action from type FORM. This example adds a form which will look like this and is able to inform a payment provider system:

POST {{host}}/api/externalactions

{
    "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": "Adjust payments for this order", // Returns value from "titleLocalized"
                "titleLocalized": {
                    "de_DE": "Zahlungen zu dieser Bestellung anpassen",
                    "en_US": "Adjust payments for this order"
                }
            },
            {
                "elementType": "SUBHEADLINE",
                "title": "In this modal you can make payment adjustments. This can either be a percentual or a freely selected discount.", // 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 process.

• 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

  

  *the username who triggered the external action is pixelated

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"
}'

External action type COMMENT

Next to the two above mentioned external actions LINK and FORM there is also a third one called COMMENT. When adding such a external action to a process it does not create another entry in the three dot menu. The purpose of this action is not to trigger an action to an external system but to receive info from such a system.

There are 2 ways to add info - you can add information to a process - you can add information to a process but relate it to another external action like FORM

Adding information to the process without relation to another external action allows you to add some general information to the process which might be important for fulfillment. An example would be: A CRM system added information about the consumer-segment which informs a user that this order might be handled in a specific way.

If you want to add information which relates to another external action you have the possibility to store "the answer" / "reaction" of the triggered system and connect it to the technicality of the external action. An example would be: You created an external action from type "FORM" which triggers a payment system in order to reduce the paid amount by 10%. The payment system itself now might inform you that the 10% was successfully reduced. In this case it would make sense that this information is not only connected to the process but connected directly to the external action FORM of this process which was originally responsible for the trigger "payment adjustment".

Those additional information are then displayed in the order history on the right hand side.

Example on how to add info to a process (and optionally relate it to another external action)

First an external action with type "COMMENT" is added to an existing order. This enables you to add generally information to an order

Such a POST call might look like this:

POST {{host}}/api/externalactions

{
    "processRef": "PUT-IN-A-PROCESS-ID",
    "nameLocalized": {
        "de_DE": "Zusatzinformation Kunde",
        "en_US": "Additional customer information",
    },
    "groups": [
        "Additional information"
    ],
    "action": {
        "type": "COMMENT"
    }
}

After that you add the actual information with

POST {{host}}/api/externalactions/externalActionRef/logs

{
  "requiresAnonymization": false,
    "actionPayload": {
    "comment": "Consumer seqment A - high priority",
    "externalActionRef":"optional-ref"
  }
}

Note: The externalActionRef is optional and determines whether the comment has a reference to a specific external action or not

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