Creating Handlers to Receive Events with IFX

This guide is designed for developers to understand how to create event handlers within an integration to receive both asynchronous (async) and synchronous (sync) events.

Prerequisites

Before you begin writing handlers, you should:

Have an integration up and running on your local machine
Have a PAT
Understand the event types, what they do, and how they are triggered
Determine which event(s) you would like to listen to
Subscribe to those events

Creating an Event Handler

Navigate to /src directory. There are a few files you’ll need to know about.

eventsRouter.json: handles routing events to their handlers. You can name your handlers whatever you like, but something a bit descriptive for what the handler is… handling.

This defines which handler should process which events. The keys should be the names of the events handler files (without extension) and their value should correspond to the events that they are going to process. In case more than one handler specifies the same event, the first one that is defined will be the one that will process the event.

{
  "storyUpdateHandler": ["story:create", "story:update"],
  "storyDeleteHandler": ["story:delete"]
}

When you run npm run localTestingServer or npm install, eventsHandlers.js is auto-generated to include the handler files defined in eventsRouter.json. There is no need to modify this file, it’s just to show how it works.

const defaultHandler = require('./eventsHandlers/defaultHandler');
const storyUpdateHandler = require('./eventsHandlers/storyUpdateHandler');
const storyDeleteHandler = require('./eventsHandlers/storyDeleteHandler');

module.exports = {
  defaultHandler,
  storyUpdateHandler,
  storyDeleteHandler,
}

Now inside of the /eventsHandler directory we need to add these files.

const storyUpdateHandler = (event) => {
  console.log(`my logic in storyUpdateHandler`);
  console.log(JSON.stringify(event, null, 2));
}

module.exports = storyUpdateHandler;

const storyDeleteHandler = (event) => {
  console.log(`my logic in storyDeleteHandler`);
  console.log(JSON.stringify(event, null, 2));
}

module.exports = storyDeleteHandler;

Now if I run npm run localTestingServer I see the following with no errors:

> @myorgname/myorgname-bg4@1.0.0 prelocalTestingServer
> node node_modules/@arcxp/arcxp-ifx-node-sdk/eventsHandlersModuleGenerator

The 'eventsHandlers' file content:
const defaultHandler = require('./eventsHandlers/defaultHandler');
const storyDeleteHandler = require('./eventsHandlers/storyDeleteHandler');
const storyUpdateHandler = require('./eventsHandlers/storyUpdateHandler');

module.exports = {
  defaultHandler,
  storyDeleteHandler,
  storyUpdateHandler,
}

> @myorgname/myorgname-bg4@1.0.0 localTestingServer
> node node_modules/@arcxp/arcxp-ifx-node-sdk/localTestingServer

Local Server Started at http://127.0.0.1:8080/ifx/local/invoke

We can send an event to the handler by POSTing to http://localhost:8080/ifx/local/invoke with a payload:

{
    "organizationId": "myorgname",
    "currentUserId": "",
    "key": "story:update",
    "typeId": 1,
    "body": {
        "date": "2022-10-05T20:28:10.958Z",
        "subheadlines": {
            "basic": ""
        },
        "description": {
            "basic": ""
        },
        "language": "",
        "source": {
            "system": "composer",
            "name": "myorgname",
            "source_type": "staff"
        },
        "type": "story",
        "id": "3CPAWBS43ZEB7GDZC73MT6ORY4",
        "last_updated_date": "2022-10-05T20:28:05.008Z",
        "workflow": {
            "status_code": 1
        },
        "version": "0.10.7",
        "canonical_website": "sample",
        "headlines": {
            "tablet": "",
            "print": "",
            "meta_title": "",
            "native": "",
            "web": "",
            "mobile": "",
            "basic": "fadfasdf",
            "table": ""
        },
        "created_date": "2022-10-05T20:28:05.008Z",
        "_id": "3CPAWBS43ZEB7GDZC73MT6ORY4"
    },
    "version": 2,
    "uuid": ""
}

In my Terminal logs:

my logic in storyUpdateHandler
{
  "version": 2,
  "key": "story:update",
  "body": {
    "date": "2022-10-05T20:28:10.958Z",
    "subheadlines": {
      "basic": ""
    },
    "description": {
      "basic": ""
    },
    "language": "",
    "source": {
      "system": "composer",
      "name": "myorgname",
      "source_type": "staff"
    },
    "type": "story",
    "id": "3CPAWBS43ZEB7GDZC73MT6ORY4",
    "last_updated_date": "2022-10-05T20:28:05.008Z",
    "workflow": {
      "status_code": 1
    },
    "version": "0.10.7",
    "canonical_website": "sample",
    "headlines": {
      "tablet": "",
      "print": "",
      "meta_title": "",
      "native": "",
      "web": "",
      "mobile": "",
      "basic": "fadfasdf",
      "table": ""
    },
    "created_date": "2022-10-05T20:28:05.008Z",
    "_id": "3CPAWBS43ZEB7GDZC73MT6ORY4"
  },
  "typeId": 1,
  "time": null,
  "uuid": ""
}

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