Create and manage integrations

This document walks you through the workflow for creating and managing integrations. IFX integrations can be managed using the API or the Arc XP CLI.

Best Practices

Use descriptive names for your integrations to easily identify their purpose.
Regularly update and maintain your integrations to ensure compatibility with the latest Arc XP features.
Monitor integration performance and logs to quickly identify and resolve issues.

Do not include the environment in your integration name. Using different names by environment (for example, printIntegration_sandbox and printIntegration_prod) is unnecessary. Sandbox and production are already isolated, so integrations will not affect each other even when they share the same integration name.

Use the same integration name in both sandbox and production.

If you need to distinguish between environments, include the environment in the bundle name instead. This allows you to deploy a sandbox-specific bundle to sandbox and a production-specific bundle to production while keeping the integration name consistent.

Example:

Sandbox integration name: printIntegration
Sandbox bundle name: printIntegration_v2_sandbox
Production integration name: printIntegration
Production bundle name: printIntegration_v2_production

Create an Integration with Arc XP CLI

The Arc XP CLI offers commands to manage integrations all in one place. For instructions on getting the CLI running on your local machine, visit this page.

Create an Integration with IFX’s APIs

You will need to create your integration for each environment.

POST /admin/integration/

The payload:

{
  "integrationName": "{integrationName}",
  "description": "{description}",
  "email": "{email}"
}

Download starter package

Once you create an integration, a starter package is created for you, deployed, and available to download.

To get the name of your new bundle, start by listing the bundles for your integration:

/ifx/api/v1/admin/integration

Using the -o option in a cURL allows you to specify where to download the resource and what to name it and the -L to follow redirects.

curl -L -o myIntegration.zip \
'https://api.{:org}.arcpublishing.com/ifx/api/v1/admin/bundles/:integrationName/download/:bundleName' \
--header 'Authorization: Bearer [token]'

You can also use Postman’s “Send and Download” option when sending the request.

Postman's “Send and Download” button

Add starter code to repo

Unzip the zip file and then initialize a git repository inside of it to track your changes.

Update an integration

PUT /admin/integration/{integrationName}

With this endpoint, you can update the alarm email, the description, and enable or disable an integration.

List integrations

GET /admin/integration

This endpoint will list all of your integrations and their details:

KEY	DESCRIPTION
status	”provisioning complete” or “provisioning in progress”
liveBundle	Shows the name of the bundle that is currently live/promoted
created	The date the integration was created formatted as `"2023-06-30T19:44:02.02Z"`
updated	The date the integration was updated formatted as `"2023-06-30T19:44:02.02Z"`

Get an integration’s details

GET /admin/integration/{integrationName}

This endpoint gets you the data about a single integration. Example return payload:

{
  "runtime": "node",
  "description": "{description}",
  "integrationName": "{intName}",
  "enabled": true,
  "created": "2023-06-30T19:44:02.02Z",
  "email": "{email}",
  "liveBundle": "{bundleName}",
  "status": "create complete" or "provisioning in progress"
}

Have a feature request or suggestion? Let us know on Our Ideas Portal.