Coding

TunnelHub.io
Search…
What is TunnelHub?
Configuring AWS Account
Guides
Creating your first automation
Fundamentals
API Management
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 @4success/tunnelhub-cli
If you are using Yarn, run:
yarn global add @4success/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. When running, you will be prompted for three pieces of information:
Company ID
User
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 -g @4success/tunnelhub-sdk
If you are using Yarn, run:
yarn global add @4success/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 '@4success/tunnelhub-sdk/src/types/data'
Check out the example below:
import { TunnelHubSystem } from '@4success/tunnelhub-sdk/src/types/data'
import { NoDeltaIntegrationFlow } from '@4success/tunnelhub-sdk/src/classes/flows/noDeltaIntegrationFlow';
​
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 '@4success/tunnelhub-sdk'
Check out the example below:
import { GenericParameter } from '@4success/tunnelhub-sdk';
import { NoDeltaIntegrationFlow } from '@4success/tunnelhub-sdk/src/classes/flows/noDeltaIntegrationFlow';
​
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 '@4success/tunnelhub-sdk/src/classes/util/dataStore'
Check out the example below:
import DataStore from '@4success/tunnelhub-sdk/src/classes/util/dataStore'
import { NoDeltaIntegrationFlow } from '@4success/tunnelhub-sdk/src/classes/flows/noDeltaIntegrationFlow';
​
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 '@4success/tunnelhub-sdk/src/classes/util/dataStore';
​
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:
Fundamentals - Previous
Conversion tables
Next - Fundamentals
Monitoring
Last modified 23d ago
Copy link
Outline
TunnelHub CLI (Command Line Interface)
TunnelHub SDK
Automated tests with Jest
Building your project