Help Center

Menu

Building in Node.js

The platform supports the Node.js programming language for building integration components.

To help you create a component in Node.js, we have created a simple Petstore component in Node.js, which connects to the Petstore API and demonstrates multiple platform features.

Petstore component

Below is the structure of the Petstore Component in Node.js:

petstore-component-nodejs

├── component.json                                      (1)
├── lib                                                 (2)
│   ├── actions
│   │   ├── createPetWithGenerators.js
│   │   └── createPetWithPromise.js
│   ├── schemas                                             (3)
│   │   ├── createPet.in.json
│   │   ├── createPet.out.json
│   │   └── getPetsByStatus.out.json
│   └── triggers                                            (4)
│       ├── getPetsByStatusWithDynamicSelectModel.js
│       ├── getPetsByStatusWithGenerators.js
│       └── getPetsByStatusWithPromises.js
├── logo.png                                                (5)
├── package.json                                            (6)
└── verifyCredentials.js                                    (7)
1 The component.json file is the component descriptor interpreted by the platform to gather all the required information for presentation in the platform UI. For example, you can define the component’s title in the component descriptor and the component’s authentication mechanism. The descriptor is the only place to list the functionality provided by the component; the triggers and actions.
2 The lib directory, and its sub-directories; actions, schemas and triggers. The Node.js sources are in the lib/actions and lib/triggers sub-directories.
3 The JSON schemas defining the component’s metadata are in the lib/schemas sub-directory.
4 Triggers get defined in the component.json file.
5 If you have a logo for the component, you can place the file called logo.png in the component’s root directory. Typically the logo of the API vendor gets used as a component logo. If you did not provide any logo, the component would show a generic logo for your component.
6 The Node.js components for the platform are built by an NPM run-script, which checks the package.json configuration file, initializes the node and npm versions, and builds them.
7 The verifyCredentails.js file should contain the primary verification mechanism for all the Node.js components built for the platform.

All node.js components must use the following dependencies:

"dependencies": {
  "elasticio-sailor-nodejs": "^2.2.0",
  "elasticio-node": "^0.0.8"
}

Sailor is the Node.js SDK of the platform. It makes your component a citizen of the platform by providing a simple programming model for components and ensuring fluid communication with the platform.

Component descriptor

The component.json file is the component descriptor interpreted by the platform to gather all the required information about the component.

Below is the descriptor of the Petstore component:

{
  "title": "Petstore API (Node.js)",                                       (1)
  "description": "Component for the Petstore API",                         (2)
  "credentials": {                                                         (3)
    "fields": {
      "apiKey": {
        "label": "API key",
        "required": true,
        "viewClass": "TextFieldWithNoteView",
        "note": "Please use <b>secret</b> as API key."
      }
    }
  },
  "triggers": {                                                            (4)
    ...
    },
  "actions": {                                                             (5)
    ...
    }
  }
}
1 The component’s title.
2 The component’s description.
3 The fields ask the user to provide authentication. In this case, a single field is defined. The user inputs the API key for the Petstore API so that the component can communicate with the API on the user’s behalf. The verification process is in the verifyCredentails.js file.
4 This property defines the component’s triggers.
5 This property defines the component’s actions.

Triggers

This section covers how to define the triggers.

The example below demonstrates the triggers section from the component.json component descriptor file:

"triggers": {
    "getPetsByStatusWithGenerators": {                                  (1)
      "main": "./lib/triggers/getPetsByStatusWithGenerators.js",        (2)
      "type": "polling",                                                (3)
      "title": "Get Pets By Status With Generators",
      "fields": {                                                       (4)
        "status": {
          "label": "Pet Status",
          "required": true,
          "viewClass": "SelectView",
          "model": {
            "available": "Available",
            "pending": "Pending",
            "sold": "Sold"
          },
          "prompt": "Select Pet Status"
        }
      },
      "metadata": {
        "out": "./lib/schemas/getPetsByStatus.out.json"                 (5)
      }
    }
  }
1 The trigger with ID getPetsByStatusWithGenerators is implemented by the function described in the file of the same name.
2 Provide the path to the getPetsByStatusWithGenerators.js file.
3 The polling trigger type means the component wakes periodically to poll for changes in the Petstore API.
4 These fields define the triggers configuration.
5 The out-metadata is written to the getPetsByStatus.out.json file.

Actions

This section discusses the actions available to the component.

The example below demonstrates the actions section from the component.json descriptor file:

"actions": {
    "createPetWithPromise": {                                           (1)
      "main": "./lib/actions/createPetWithPromise.js",                  (2)
      "title": "Create a Pet With Promise",
      "metadata": {
        "in": "./lib/schemas/createPet.in.json",                        (3)
        "out": "./lib/schemas/createPet.out.json"                       (4)
      }
    }
  }
1 The action with ID createPetWithPromise gets implemented by the function described in the createPetWithPromise.js file.
2 Supply the path to the createPetWithPromise.js file. It is possible to define actions in the configuration fields (as shown in the triggers section). However, this component has none.
3 The metadata in file (createPet.in.json) is defined here.
4 The metadata out file (createPet.out.json) is defined here.

Verify Credentials

When creating a component, you may allow users to check entered credentials for validity during the integration flow creation.

This feature is useful when users need to type passwords, hostnames, IP addresses, and other details. Credential verification is an optional step, ensuring that the user flow is reliable and secure.

For a Node.js component, you can use any libraries or functionality at your disposal to authorize the user credentials. But for the platform to find and call your verification code, you have to make sure that:

  • Your component has a verifyCredentails.js file in the root of the folder structure

  • Your verifyCredentials.js file is a common.js module

  • It returns one function that accepts two parameters: credentials and cb (callback).

  • All the credentials for verification get passed through the credentials parameter, which is an object. This object can contain the properties that match or correspond to the account definition parameters from component.json.

Below is the skeleton structure for the verified credentials function. You can use it as a starting point to create a bespoke verifyCredentails.js:

// here you can place your variables

// This function gets called by the platform to verify credentials
module.exports = function verifyCredentials(credentials, cb) {
    // In credentials you will find what users entered in account form
    console.log('Credentials passed for verification %j', credentials)
    if (true) {
        // Verified
        return cb(null, {verified: true});
    } else {
       // Verification failed
       return cb(null , {verified: false});
    }
}

The use of any specific verification method is dependent on the project and the third-party API with which the credentials are communicated.

Discussing the many possible third-party API solutions is beyond the scope of this documentation.