External actions

More external actions API information can be found here: REST API documentation – External actions

The external actions feature empowers users to trigger and execute actions and processes in external systems, outside of fulfillmenttools.

• Multiple external actions can be added to a process.

• External actions can be grouped and assigned to a theme.

External action with type: 'BLANK_LINK'

The following example creates an external action that renders as a link to an external system, such as a payment provider's portal. The action is configured by setting the action.type to BLANK_LINK and providing a destination URL in action.linkUrl.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/externalactions

{
  "processRef": "6aca1c80-c418-4064-b173-63fb120aef2d",
  "nameLocalized": {
    "de_DE": "Zahlungen anpassen",
    "en_US": "Adjust Payment"
  },
  "groups": [
    "string"
  ],
  "action": {
    "type": "BLANK_LINK",
    "linkUrl": "https://service.payment-provider.example/orders"
  }
}

External action with type: 'FORM'

This example creates a form that can be used to send data to an external system, such as a payment provider. When a user submits the form, fulfillmenttools sends a webhook containing the form data.

This example adds a form that will look like this and is able to inform a payment provider system:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/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",
        "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.",
        "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": "This modal allows for payment adjustments. This can be either a percentage or a freely selected discount."
        }
      }, {
        "elementType": "TEXT",
        "style": "BODY",
        "title": "string",
        "titleLocalized": {
          "de_DE": "-",
          "en_US": "-"
        }
      }, {
        "elementType": "TEXT",
        "style": "BODY",
        "title": "string",
        "titleLocalized": {
          "de_DE": "Rabatt in %",
          "en_US": "Discount in &"
        }
      }, {
        "elementType": "TEXT_INPUT",
        "elementId": "4712",
        "label": "string",
        "titleLocalized": {
          "de_DE": "%",
          "en_US": "%"
        },
        "isMandatory": false,
        "validation": {
          "validationType": "FLOAT",
          "minValue": 1,
          "maxValue": 100
        }
      }, {
        "elementType": "TEXT",
        "style": "BODY",
        "title": "string",
        "titleLocalized": {
          "de_DE": "-",
          "en_US": "-"
        }
      }, {
        "elementType": "TEXT",
        "style": "BODY",
        "title": "string",
        "titleLocalized": {
          "de_DE": "Rabatt in €",
          "en_US": "Discount in €"
        }
      }, {
        "elementType": "TEXT_INPUT",
        "elementId": "4713",
        "label": "string",
        "titleLocalized": {
          "de_DE": "€",
          "en_US": "€"
        },
        "isMandatory": false,
        "validation": {
          "validationType": "INTEGER",
          "minValue": 1,
          "maxValue": 1000
        }
      }, {
        "elementType": "TEXT",
        "style": "INFO",
        "title": "string",
        "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",
      "labelLocalized": {
        "de_DE": "Bestätigen",
        "en_US": "CONFIRM"
      }
    },
    "cancel": {
      "label": "string",
      "labelLocalized": {
        "de_DE": "Abbrechen",
        "en_US": "CANCEL"
      }
    }
  }
}

External action with type: 'COMMENT'

An external action with type: 'COMMENT' allows users to add notes to a process. These notes are then created by making a subsequent request to the logs endpoint.

First, create the COMMENT action and associate it with a process:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/externalactions

{
  "processRef": "6aca1c80-c418-4064-b173-63fb120aef2d",
  "nameLocalized": {
    "de_DE": "Zusatzinformation Kunde",
    "en_US": "Additional customer information"
  },
  "groups": [
    "additional-information"
  ],
  "action": {
    "type": "COMMENT"
  }
}

Once the action is created, use its externalActionRef to post a comment to the logs endpoint.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/externalactions/{externalActionRef}/logs

{
  "requiresAnonymization": false,
  "actionPayload": {
    "comment": "Consumer segment A - high priority",
    "externalActionRef": "9e4a3c11-a582-4c60-9118-1a5a2a2eda87"
  }
}