Bundle Management

Bundles are the zipped code that will run your integrations, and they function very much like PageBuilder and Themes bundles. They are built locally then uploaded to the server. When first uploaded they will be “unused”. Deploying a bundle makes it as ready for use and it can be promoted to “live”. There can only be one promoted bundle at a time, and this is the code that will run when your integration is invoked.

Be sure to fully test your bundle’s code before deciding to promote it. If something happens to go wrong, you can quickly “roll back” by promoting the last-known working bundle. In the absence of a usable bundle, you have the option to disable your integration in case of an emergency.

Bundle Status Terminology

The following table represents the status of a bundle associated with an integration:

STATUS	DESCRIPTION
Unused	The zipped bundle has been uploaded but is not deployed and cannot be promoted. Note that uploaded bundle names must be unique!
Deploying	The bundle is actively being deployed. This process usually takes about 30-40s.
Deployed	The uploaded bundle is deployed to an environment so that it can be promoted, and the version of the bundle can be seen on the property deployVersion.
Promoting	The bundle is actively being promoted to “live”. This process usually takes about 10s.
Live	A deployed bundle is promoted as live and is being used by the integration, receiving live traffic.

test, test, test!

Once you promote a bundle, test it throughly (especially in a production environment) to ensure all processes are working as expected.

If you encounter issues with a live bundle, you can quickly switch back to a previous version by clicking “Promote” on a deployed bundle in the UI, or by using the promote API endpoint and providing the bundle’s name.

Build a Bundle Locally

Node.js

The runtime expects a fairly rigid code structure for uploaded code, but as long as a few norms are followed bundling your integration will be painless.

Pre-bundle Checklist

1. Run npm install to make sure you have everything your integration needs in the /node_modules directory
2. Ensure sure your integration code runs and has been linted. For your privacy and application security, IFX will not do any validation on your integration code.
3. Exclude any devDependencies and test code you do not want deployed

Tip

If you encounter issues with node modules, clear out any hiccups with rm -rf node_modules and then rerun npm install. If you still have an issue you may have to do more investigating.

Bundle it Up!

“Bundle” is the term PageBuilder uses to denote a zip file, and in IFX we’ve coopted that term.

When you create a new integration, we provide a deployed starter package for you. This package includes the scripts needed to zip everything into the top of the directory /dist. These are not designed to be modified, but you can add your own if you’d like.

"scripts": {
    "localTestingServer": "node node_modules/@arcxp/arcxp-ifx-node-sdk/localTestingServer",
    "prelocalTestingServer": "node node_modules/@arcxp/arcxp-ifx-node-sdk/eventsHandlersModuleGenerator",
    "postinstall": "npm run prelocalTestingServer",
    "clean": "rimraf dist/",
    "build": "npm run clean && cpy src/* .env.sandbox .env.production ./node_modules/ ./dist",
    "zip": "(cd dist/ && zip -r ../dist.zip ./* -x \"dist.zip\")"
 }

When you have tested your code and are ready to bundle your integration code:

1. Run npm run build. This will also help to catch most errors.
   
   After this has executed, the unzipped code is put into /dist:
   
   

2. Zip it up with npm run zip

If you are feeling like a rockstar, you can comine the two commands:
npm run build && npm run zip

Naming a Bundle

After running npm run zip there will be a zip file in the project root called dist.zip.

My personal preference is to rename this to represent my versions. For example, the last bundle I uploaded was called gigi-v3.zip so I run mv dist.zip gigi-v4.zip

naming a bundle

When uploading, all bundle names must be unique.

Self-bundling

There may be cases where your integration is built in Typescript or other supersets. This can be done but requires you to bundle your code a bit differently.

For more information on supersets, see Using TypeScript and Other JS Supersets in Integrations

The end goal is to include:

1. The source code
2. Node modules directory
3. Any environment var files you want to include into the zip file

This can often be achieved by running

zip -r ../myzip.zip src/ node_modules/ env.sandbox .env.production

Error when running npm run build

If you get this error when building the bundle “SyntaxError: Cannot use import statement outside a module” and it is calling out something inside of /node_modules, run rm -rf node_modules && npm install

Java

We highly recommend you use our Boilerplate code as a starting point for your integration. It has all the build steps needed already configured into Maven. Java can be a tricky beast to compile!

To zip your integration, simply run:

./mvnw clean package spring-boot:repackage install

This will package everything into the /target directory with the name <org>-<integration>-<version>.zip

Once you have zipped up your integration you can move on to the Upload a Bundle step.

Managing Integration Bundles

 

You can manage bundles using either the API (explained more below) or the IFX UI.

UI Bundle Management

To manage bundles through the UI, simply navigate to your Arc Home page and click on the IFX tile. This will display a list of all your integrations, allowing you to click on each one to view its details. Here you can also upload, deploy and promote the associated bundles.

API Bundle Management

List an Integration’s Bundles

See a list of bundles and thier statuses associated with an integration.

GET /ifx/api/v1/admin/bundles/:integrationName

Upload a Bundle

In order for a bundle to be available for use you will need to upload it.

reminder

Bundle names must be unique!

Once you have zipped up your code, use the Upload API to make it available for deployment. Upon success, it will return the metadata of the newly uploaded bundle. The maximum size is 100MB.

curl -X POST \
 --location 'https://api.{:org}.arcpublishing.com/ifx/api/v1/admin/bundles/:integrationName' \
 --header 'Authorization: Bearer ' \
 -F 'name=myIntegration-1-1-0' \
 -F 'bundle=@/path/to/zip/myIntegration.zip;type=application/zip'

Download a Bundle

Download an integration’s bundle.

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

Deploy a Bundle

An unused bundle means that it is uploaded to a server andready to be used, but is has not yet been deployed. Use the Deploy API to deploy an unused bundle and make it eligible for promotion to live.

POST /ifx/api/v1/admin/bundles/:integrationName/deploy/:bundleName

Promote a Bundle to Live

In order for a deployed bundle to go live and receive traffic on an environment, it must be promoted. Promoting a bundle is the same thing as a “release”.

POST /ifx/api/v1/admin/bundles/:integrationName/promote/:version

test, test, test! (again)

Once you promote a bundle, test it throughly (especially in a production environment) to ensure all processes are working as expected.

If you encounter issues with a live bundle, you can quickly switch back to a previous version by clicking “Promote” on a deployed bundle in the UI, or by using the promote API endpoint and providing the bundle’s name.

---

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.