FAQs, Troubleshooting & Best Practices

Best Practices

To provide you with the best possible experience, IFX will continue to provide guidelines for an optimal, performant integration.

Integration size considerations

IFX recommends grouping your integration code together based on integration type. For example, you could create a single integration to manage all handlers for Arc Subscription transactional emails and another integration to handle auto-tagging stories.

Rate Limits on Arc XP services

Calls to Arc XP services from IFX have rate limits which can impact performance and eventually lead to errors. As you approach the rate limits, you may notice requests to your integration are slowed down.

When you hit rate limits you will receive an http status 429, with the body below:

<html>
  <head><title>429 Too Many Requests</title></head>
  <body>
    <center><h1>429 Too Many Requests</h1></center>
    <hr><center>nginx</center>
  </body>
</html>

This will throw an exception in the ArcHttpClient as the response will not be JSON.

Integrations

How do I know which version is running on which environment?

Node

Use the List Bundles endpoint to see which bundle is set to live:

GET https://api.{myorg}.arcpublishing.com/ifx/api/v1/admin/bundles/{integrationName}/

Java

This depends on the settings of your deploy and promote files — it’s basically up to you. If your files are set to auto then it will use the latest tag from your repo for that environment (sandbox or prod):

If your files are set to disable then it would still be using the last version that was deployed or promoted.

If your files are set to a specific version then it would still be using that version which was deployed or promoted.

An event is not triggering in my integration logs

Is the event enabled for your application? For example, Subscriptions’ verify_email can be disabled in the UI https://{myorg}.arcpublishing.com/subscriptions/settings/identity/sign-in?site={mysite}

Java: Do I need to set the `app` value for apps that are not identity, retail or sales?

No, not if the app does not specify this, and arbitrary values will not do anything. The app value is specifically used for the Websocket connection for local testing, only those apps use the Websocket.

My integration is infinitely looping. How can I stop it?

Unsubscribe to the event that is causing the loop by setting enabled to false:

PUT /ifx/api/v1/admin/events/subscriptions

{
  "eventName": "story:update",
  "enabled": false,
  "integrationName": "myIntegration"
}

Messages with a priority of ingestion are not supported, which is commonly used for content migrations or bulk-updating content.

When updating content through the Draft API from IFX, it is crucial to include an HTTP header Arc-Priority: ingestion to avoid an infinite loop of story:update events.

const headers = {
  'Authorization': `Bearer ${arcPat}`,
  'Arc-Priority': 'ingestion'
};

Can I receive Content Events locally?

Yes! Check out this page

Why am I not seeing any updates within my integration or logs?

If using Node

Stop your integration using CTRL + C, then npm run localTestingServer

I’m having issues with my deployment.

Check out these articles for more information:

Bundle Deployment Workflow
Debugging and Testing Deployed Integrations

If you are still having an issue, submit an ACS ticket for more help.

Do I need a single event handler for every event I want to receive ?

No. A single handler can receive multiple events.

In Java, create the annotation with the event names separated by commas: @ArcAsyncEvent({"story:delete", "story:unpublish"})

In Node

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

eventsHandlers.js includes the handler files defined in eventsRouter.json

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

module.exports = {
  storyUpdateHandler,
  storyDeleteHandler,
}

“SyntaxError: Cannot use import statement outside a module”

When I run npm run build I am getting “SyntaxError: Cannot use import statement outside a module”

If this is calling out something inside of /node_modules/, run rm -rf node_modules && npm install

Environments

What environments are available to my integrations?

Sandbox and Production.

Performance

Why am I getting Cloudwatch Alarm Emails?

IFX requires an email address as part of the new integration Create API. The email address provided is used to assign to a set of default Cloudwatch Alarms. We create these alarms for you in an effort to notify in case of an issue.

Most of the emails are informational - if your integration starts taking longer than it usually does, or sees a spike in error results on it’s invocation, we will send the corresponding email address an alarm alert.

How you choose to deal with this info is up to you. If you decide it is not helpful you can unsubscribe from that alarm using the link included in the email.

Is my integration’s performance dependent on other traffic in the network?

No. All processes, even build & deploy jobs, are unaffected by other lambdas’ processes.

Logging

Follow integration runtime logs for adding logs to your integration.

Timeouts

My integration keeps timing out. What can I do?

There can be several factors that affect this. Usually it may be due to an external service’s longer response time.

More info on troubleshooting timeouts

It is recommended that you put synchronous and asynchronous event handlers into separate integrations. Why?

Asynchronous events are the “fire and forget” kind, and have little to no effect on the user experience. Since it is sitting there waiting on a response, sync events do effect user experience. Therefore you do not want async events clogging up your pipeline, delaying sync event response times.
You can deploy individual integrations separately, leaving other integrations unaffected.
1. Since async and sync events behave differently, having the debugging/logging/metrics separate makes it easier.

My integration needs to wait for something to happen

Make sure you are using async declarations and promises where necessary to ensure your function will wait for a process that might take long. Also, implement try/catch for subsequent API calls.

const timeoutTestHandler = async (event) => {
  console.log('starting timeout handler');
  const result = await myLongFunction();
  console.log(`result: ${result}`);
};

function myLongFunction() {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve('resolved');
    }, 30000); // wait 30s
  });
}

module.exports = timeoutTestHandler;

We can see in these logs that result:resolved is logged 30 seconds after starting timeout handler

Understanding Async Event Handling & Retries

Event Retries

If your asynchronous event handler experiences an error and does not successfully process an event, the system will automatically retry delivering the event up to two additional times. It’s crucial to design your handlers to gracefully manage potential failures. Note that if your code utilizes a top level try/catch statement to catch any errors, this automatic retry functionality will not occur.

More-Than-Once Delivery

In certain error scenarios, an asynchronous event might be delivered to your handler more than once. For detailed information about when this can occur, refer to the AWS documentation on Asynchronous Invocation: Asynchronous invocation - AWS Lambda. Designing your event handlers with idempotency is essential.

Idempotency Best Practices

Idempotent operations produce the same result whether executed once or multiple times. To ensure robust asynchronous event handling, adhere to idempotency principles. Examples can be found on Make a Lambda function idempotent.

Common Questions

Can we use IFX to write events to our own Kinesis streams?

At this time, Arc XP does not create roles for customers as a de facto rule.

Can we modify the ANS payload using the Draft API and store any environment variables needed for IFX?

You can adjust the ANS in your integration code using the Draft API. For storing environment variables create a file in the root of your project called .env inside of that file define variables as needed.

Debugging: Have you checked…

If an integration is not triggering, does the name of the handler annotation match the integration key?
If an integration is not triggering, is the integration enabled when you use the List Integrations endpoint to see the status of all your integrations?
If you are receiving a HTTP Status Code 401, is your Developer PAT still valid?
If you are receiving an error, can you reproduce reproduce it locally using a build of the same Git tag?
(Java only) If you are testing locally, does the developerKey Header you sent to the API match the developerKey defined in application-local.properties?
Have you checked your integration runtime logs?

If an error can’t be reproduced locally or if further research into a problem is needed, you may submit an ACS request.