Node.js is one of the supported languages that can be used to build a component to run on elastic.io platform.

To get you started we have created a Petstore component which you can use to write your own one.

node.js component structure overview

File Name Type Required Description
logo.png image suggested Logo of your component
component.json
JSON Yes Description of the component structure
package.json JSON Yes description of the package
verifyCredentials.js JavaScript suggested the main function to verify the credentials
lib directory suggested main component directory


The file called logo.png should be present in the component. We include a generic hello world logo to be replaced for customisation. If the logo is not included or removed a replacement will be added from our system as a placeholder and most likely will not be adequate for your needs. Therefore, we suggest you add a descriptive logo for your component.

Here are the requirements for the logo file:

  • Do not change the name logo.png (PNG format)
  • The logo should have 64 x 64 pixels dimension

component.json

In component.json we practically describe the main blocks of your component. This configuration file should include the title of your component along with the description and the method of credential verification if any.

It should also include the information and dependencies of a trigger(s) and action(s) that your component has.

At least one trigger or action should be present: Please note that your component.json file should describe at least one trigger or action. This is the minimum that you should have.

{
  "title": "Petstore API (Node.js)",
  "description": "elastic.io component for the Petstore API",
  "docsUrl": "https://github.com/elasticio/petstore-component-nodejs",
  "credentials": {
    "fields": {
      "apiKey": {
        "label": "API key",
        "required": true,
        "viewClass": "TextFieldWithNoteView",
        "note": "Please use <strong>elasticio</strong> as API key. For more details see <a href="https://petstore.elastic.io/docs/">Petstore API docs</a>."
      }
    }
  },
  "triggers": {
    "getPetsByStatusWithGenerators": {
      "main": "./lib/triggers/getPetsByStatusWithGenerators.js",
      "type": "polling",
      "title": "Get Pets By Status With Generators",
      "fields": {
        "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"
      }
    },
    "getPetsByStatusWithPromises": {
      "main": "./lib/triggers/getPetsByStatusWithPromises.js",
      "type": "polling",
      "title": "Get Pets By Status With Promises",
      "fields": {
        "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"
      }
    },
    "getPetsByStatusWithDynamicSelectModel": {
      "main": "./lib/triggers/getPetsByStatusWithDynamicSelectModel.js",
      "type": "polling",
      "title": "Get Pets By Status With Dynamic Select Model",
      "fields": {
        "status": {
          "label": "Pet Status",
          "required": true,
          "viewClass": "SelectView",
          "model": "getStatusModel",
          "prompt": "Select Pet Status"
        }
      },
      "metadata": {
        "out": "./lib/schemas/getPetsByStatus.out.json"
      }
    }
  },
  "actions": {
    "createPetWithPromise": {
      "main": "./lib/actions/createPetWithPromise.js",
      "title": "Create a Pet With Promise",
      "metadata": {
        "in": "./lib/schemas/createPet.in.json",
        "out": "./lib/schemas/createPet.out.json"
      }
    },
    "createPetWithGenerators": {
      "main": "./lib/actions/createPetWithGenerators.js",
      "title": "Create a Pet With Generators",
      "metadata": {
        "in": "./lib/schemas/createPet.in.json",
        "out": "./lib/schemas/createPet.out.json"
      }
    }
  }
}

package.json

In package.json we describe the component, the author and the dependencies that this component should have in order to be correctly deployed into our system.

  "name": "@elasticio/petstore-component-nodejs",
  "version": "0.0.1",
  "description": "elastic.io component for the Petstore API",
  "scripts": {
    "test": "exit 0"
  },
  "repository": {
    "type": "git",
    "url": "git@github.com:elasticio/petstore-component-nodejs.git"
  },
  "author": "elastic.io GmbH",
  "license": "BSD-2-Clause",
  "engines": {
    "node": "6.4.0"
  },
  "dependencies": {
    "elasticio-sailor-nodejs": "2.0.1",
    "elasticio-node": "0.0.7",
    "co": "4.6.0",
    "request": "2.76.0",
    "request-promise": "4.1.1"
  }
}

For example when we have a new release of elasticio-sailor-nodejs the change needs to be reflected also here for a proper deployment.

New releases will be communicated: In a case when we update any core package we will inform you in advance so that you can make all the necessary changes and tests to ensure uninterrupted executions.

verifyCredentials.js

When creating an elastic.io 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-in passwords, hostnames, IP addresses, etc. Credentials verification is an optional step which however makes the overall user flow much more reliable and usable.

For node.js component you can use any libraries and/or functionality at your disposal to validate user's credentials, however, for the platform to find and call your verification code you have to satisfy following assumptions:

  • Your component should have a verifyCredentails.js file in the root of the folder structure
  • Your file verifyCredentials.js should be a common.js module
  • It should return only one function that will accept two parameters
    • credentials and
    • cb (callback).
  • All the credentials for verification will be passed through credentials parameter which is an object. This object can contain the properties that match or correspond to the account definition from the component.json.

Here is the skeleton structure for the verify Credentials which can be used as a starting point to write your own verifyCredentails.js:

// here you can place your variables

// This function will be 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});
    }
}

To use one or the other specific type of verification method is dependent on the project and the third party API that is being communicated the credentials with. Therefore, it is not the scope of this documentation to go into details of every possible solution for your chosen third party API.

lib

This is the directory which contains the core files of the component. These files are referred from component.json directly. This structure and the naming is entirely optional and can be altered if you prefer different hierarchy. However, if you decide to change it here don't forget to describe it in component.json as well for a basic consistency.

The structure of the lib directory is presented below along with the links to the example functions and configuration files:

  • actions - the part you would tend to put the Action functions.   
    • createPetWithGenerators.js
    • createPetWithPromise.js
  • schemas - this is the place where you describe the format of the Action and Trigger functions   
    • createPet.in.json
    • createPet.out.json
    • getPetsByStatus.out.json
  • triggers - the part you would put the Trigger functions   
    • getPetsByStatusWithDynamicSelectModel.js
    • getPetsByStatusWithGenerators.js
    • getPetsByStatusWithPromises.js