IFX Events

IFX is an event-based application. Integrations are hosted code, meant to receive events and apply custom logic to the data passed from the emitting application.

Integrations remain at rest until receiving an event from another application (i.e. Composer, WebSked) to which it is subscribed (more on this later). If no integrations are subscribe to that event, the event is skipped.

Event Types

IFX has two types of events: synchronous and asynchronous

Asynchronous Events

These events do not affect user experience because the process is “fire and forget”. The application that emitted the event is not expecing a response from your integation.

JAVA ONLY:
@ArcAsyncEvent	typeId: 1

Synchronous Events

These events can affect user experience because the emitting application is waiting on a response from your integration. For example, if a user is submitting a payment which is being processed through your integation, they will have to wait until the process is complete and a response is returned to the emitting application.

JAVA ONLY:
@ArcSyncEvent	typeId: 5

Event Namespace

Events will be in the format [app name]:[event name] i.e. websked:pitch_create

Event Payload

For all events, the contract is as follows:

{
  "key": "story:update", // event name
  "typeId": 5, // 1 or 5 (only relevant for JAVA)
  "version": 2,
  "time": 1620222229857, // timestamp
  "uuid": "",
  "body": {} // This JSON object is structured by the emitting application.
}

Event Menu

The Event Menu brings Arc XP’s Content, Commerce, and Experience applications together. Bookmark it so you can easily find it!

IFX stores a mapping of events to integrations. In order to receive events and invoke your integration, you must be subscribed to them. For each event you wish to subscribe to, you will specify the integration name to invoke when the event is received.

Review the menu and make note of the events you want to receive. Each of the events will provide a description and an example payload it will send.

At a high level:

1. View the menu of events
2. Select the events you want to receive
3. Use an API to subscribe to an event and specify which integration to invoke
4. Trigger and receive the event to your integration

Subscribing to an event

In order to receive events and invoke your integration, you must be subscribed to them. Send a POST request to the /admin/events/subscriptions endpoint to subscribe and specify the integration that should be invoked when the event is received.

curl --location 'https://api.[org].arcpublishing.com/ifx/api/v1/admin/events/subscriptions' \
--header 'Authorization: Bearer ${PAT Variable} ' \
--header 'Content-Type: application/json' \
--data '{
  "eventName": "story:update",
  "enabled": true,
  "integrationName": "myIntegrationName"
}'

Unsubscribing from an Event

Send a PUT request to the /admin/events/subscriptions endpoint to unsubscribe from an event by setting enabled to “false”. This will prevent that event from invoking your integration, and you can set it back to “true” if and when you need to.

curl -X PUT --location 'https://api.[org].arcpublishing.com/ifx/api/v1/admin/events/subscriptions' \
--header 'Authorization: Bearer ${PAT Variable} ' \
--header 'Content-Type: application/json' \
--data '{
  "eventName": "story:update",
  "enabled": false,
  "integrationName": "myIntegrationName"
}'

Viewing Your Event Subscriptions

Send a GET request to the /admin/events/subscriptions endpoint to view your organization’s existing subscriptions (or just view in your browser). Note that these results are cached for 5 minutes.

curl -X GET --location 'https://api.[org].arcpublishing.com/ifx/api/v1/admin/events/subscriptions' \
--header 'Authorization: Bearer ${PAT Variable} ' \
--header 'Content-Type: application/json' \

Custom Events

You can create your own custom events, private to your organization. Custom events can be used in two ways:

1. Create an Inbound Webhook that will invoke an integration
2. Create an event that will run on a scheduled basis

A custom event is used for either an Inbound Webhook or is scheduled — it cannot be used for both.

Creating a Custom Event

Create a custom event by sending a POST request to the /admin/events/custom endpoint.

{
  "eventName": "custom:pretend-company-notification",
  "description": "This is an event to receive notifications from Pretend Company, an external application."
}

Creating Scheduled Events

Scheduled events are triggered based on time, running without user action on a defined interval such as once a week. Scheduled integrations can be used for automatically triggering an integration to perform tasks such as generate reports, or reach out to any API (Arc or external) to gather the necessary data to perform such tasks.

When creating a scheduled event, include a parameter for schedule and set its value using a cron expression. If you’re unfamiliar with cron, or would like confirmation that your schedule is as desired, there are free online generators you can use such as this one: Cron Expression Generator & Explainer.

Caution

IFX does not accept cron strings with seconds. Therefore, if you use a cron generator website, you must delete the first zero for your input to be accepted.

What type of schedules can be set up?

You can set up any schedule that is greater than five minutes. You can specify frequencies such as:

• Minutes
• Hours
• Day of the month
• Month
• Day of the week
• Year

For example, the six-field cron expression 0 0 ? * SUN * is described as At 00:00:00am, on every Sunday, every month. You can learn more about cron schedules here: Cron Expression Generator & Explainer.

What about failures or guaranteed delivery of messages to IFX?

Your integration should handle errors. Using the Node.js language, you should use a try/catch statement, where on catch (error) you would need to decide what action you would like to take.

Creating a Scheduled Event

IFX scheduled events use the six-field AWS Cron Expression format (no seconds value). You can use a generator such as Cron Expression Generator & Explainer, but note this tool uses a seven-field format so you will have to remove the first field.

Create a scheduled, custom event by sending a POST request to the /admin/events/custom endpoint. In this case you will provide the schedule parameter:

{
  "eventName": "custom:myevent",
  "description": "This is my event that will run 12:00:00pm, on Wednesdays.",
  "schedule": {
    "cron": "0 12 ? * WED *"
  }
}

Modifying an Event’s Schedule

Modify an event’s schedule by sending a PUT request to the /admin/events/custom/:eventName endpoint.

{
  "description": "This is my event that will run every 7 days at noon.",
  "schedule": {
    "cron": "0 0 12 */7 * ? "
  }
}

Deleting a Schedule

You can delete an event’s schedule without deleting the event itself (this action cannot be undone). Send a DELETE request to the /admin/events/custom/:eventName/schedule endpoint.

---

Help us improve our documentation! Let us know if you do not find what you are looking for by posting suggestions to the Ideas Portal.