Coding

For integrations to work, they must be coded using some predefined standards. We currently only support the NodeJS language, and all the following examples will be using this language.

TunnelHub CLI (Command Line Interface)

To help during the development process, we created a CLI package to interact with our platform in a simple and productive way. To install, you must have NodeJS v12+ and NPM installed

  • npm install -g @tunnelhub/cli

If you are using Yarn, run:

  • yarn global add @tunnelhub/cli

If the installation runs correctly, you can check the available commands with the command:

  • tunnelhub help

If you prefer, we also provide a shortened version of the commands with the prefix th such as:

  • th help

Main commands

There are several commands, but we will list below the most used when creating automations.

th login

To run deploys, list existing automations or create new resources, you must be authenticated with our platform. This can be done with the th login command. This will start the OAuth authentication flow:

  1. A browser window will open automatically.

  2. You'll be redirected to the TunnelHub login page.

  3. Enter your credentials and complete the login process.

  4. After successful authentication, you can return to your terminal.

If you prefer to use password-based authentication instead of OAuth, use:

bashCopytunnelhub login --password

When running with the password option, you will be prompted for three pieces of information:

  • Tenant ID

  • Username

  • Password

The Company ID can be in the information button on the upper right bar of the system, in the Company ID field. The username and password fields are the same as those used to enter the portal.

th create-automation

This command creates automation in TunnelHub and also generates an initial skeleton for your application based on four models:

  • No delta (individual)

  • No delta (in batch)

  • With delta (individual)

  • With delta (in batch)

According to the chosen model, a different template will be created with all the code necessary to start your automation.

It is necessary to inform in which environment you are creating the automation through the --env parameter at the end of the command

th deploy-automation

This command uploads your application to TunnelHub and publishes it instantly. The pre-configured templates already come with the pre-configured Webpack and are ready to run in the AWS Lambda environment.

It is necessary to inform in which environment you are creating the automation through the --env parameter at the end of the command and also a message in the --message parameter to stay in the deployment history.

TunnelHub SDK

For your automation to interact with the platform, it is necessary to use our SDK in your application. To install, you must have NodeJS v12+ and NPM installed

  • npm install @tunnelhub/sdk

If you are using Yarn, run:

  • yarn add @tunnelhub/sdk

Within the SDK, there are several functions that can be used, which are documented on the SDK page in NPM. The most important thing is that your automation follows the patterns of the basic templates, being an implementation of a class that inherits from one of the main flows.

Accessing data from systems

In your automation constructor, the event variable has the systems data assigned in our panel in the systems properties. You can import the fields available in the SDK’s type definition with the command below:

  • import { TunnelHubSystem } from '@tunnelhub/sdk/src/types/data'

Check out the example below:

import { TunnelHubSystem } from '@tunnelhub/sdk'
import { NoDeltaIntegrationFlow } from '@tunnelhub/sdk';

export default class Integration extends NoDeltaIntegrationFlow {
  private readonly systems: TunnelHubSystem[];

  constructor(event: any, context: any) {
    super(event, context);
    this.systems = event.systems ?? [];
    

    const system = this.systems.find(value => value.internalName === 'MY_SYSTEM');
    if (!system) {
      throw new Error(`The MY_SYSTEM system needs to be assigned to automation`);
    }
  }
  /**
    ...
  **/
}

Accessing parameters

In your automation constructor, the event variable has the parameters defined in our panel in the parameters properties. You can import the fields available in the SDK’s type definition with the command below:

  • import { GenericParameter } from '@tunnelhub/sdk'

Check out the example below:

import { GenericParameter } from '@tunnelhub/sdk';
import { NoDeltaIntegrationFlow } from '@tunnelhub/sdk';

export default class Integration extends NoDeltaIntegrationFlow {
  private readonly parameters: { custom: GenericParameter[] };

  constructor(event: any, context: any) {
    super(event, context);
    this.parameters = event.parameters ?? {};

    const param = this.parameters?.custom?.find(param => param.name === 'customParam');
    if (!param) {
      throw new Error(`The parameter customParam is required`);
    }
  }
  /**
    ...
  **/
}

Accessing Conversion Tables

In your automation’s constructor, the event variable has all the data needed to instantiate the DataStore class from our SDK. You can import it into your project with the command below:

  • import DataStore from '@tunnelhub/sdk/src/classes/util/dataStore'

Check out the example below:

import { DataStore } from '@tunnelhub/sdk'
import { NoDeltaIntegrationFlow } from '@tunnelhub/sdk';

export default class Integration extends NoDeltaIntegrationFlow {
  private dataStore: DataStore;

  constructor(event: any, context: any) {
    super(event, context);

    this.dataStore = new DataStore(event);

    const conversionTable = await this.dataStore.getConversionTableItems('MY_CONVERSION_TABLE');
    const conversionItem = conversionCompany.find(value => value.fromValue === 'SearchValue');
    if(conversionItem){
        console.log('item converted', conversionItem.toValue);
    }
  }
  /**
    ...
  **/
}

Automated tests with Jest

All templates come with pre-defined basic tests using the Jest framework. As we use X-Ray and the SDK has several functions executed automatically, keeping all the mocks defined in the beforeAll block is very important. If you need to mock data from a from/to table, you can use the template below:

import { DataStore } from '@tunnelhub/sdk';

beforeAll(() => {
  jest.setTimeout(1800000);
  
  //default mocks

  const dataStore = jest.spyOn(DataStore.prototype as any, 'getConversionTableItems');
  dataStore.mockImplementation((args) => {
    switch(args) {
      case 'CONVERSION_TABLE_NAME':
        return[];
    }
  });
});

Building your project

As AWS requires a Javascript source code to execute, you need to transpile/bundle your project with all dependencies using a tool like webpack or esbuild and compress it to a zip file, saved on the path indicated in package.artifact property on tunnelhub.yml configuration file.

You can create your flow as you want, considering these requirements:

  • The tunnelhub.yml need to be on the bundle root

  • If you are using ECS_FARGATE runtime, all dependencies must be set as externals, and the package.json file must be on the bundle root because all dependencies will be installed during the build phase.

  • Source maps are optional but recommended for logging/debugging.

We recommend you to use esbuild for fast builds, and you can use the example below:

PreviousSequencesNextMonitoring

Last updated