Introduction into components

What is a component?

A component is a small piece of code that is responsible to interact with an external API. Components are bundled into libraries which may be deployed into elastic.io runtime. In this tutorial you will be introduced into components, libraries and elastic.io command-line interface. Let's start by exploring the nature of an component.

Writing a simple Hello, world component

Components are implemented as node.js modules. The following example demonstrates how a simple Hello, world! component might look like.

exports.process = function (msg, cfg, next, snapshot) {

    console.log(msg);

    next(null, msg);
};

As you can see, the component exports a single function named process. The function may take up to 4 paramaters:

1. message to process
2. component's configuration
3. callback function to be invoked when the component finished its work
4. optional snapshot parameter which is used by a component for deduplication

We will cover deduplication later. For now we concentrate on the first three parameters.

Our Hello, world! component listed above is printing the incoming message and passes it through to the callback named next. This results in the invocation of the next component in the integration task. The next callback may take up to 3 parameters:

1. error occurred
2. message to be processed
3. snapshot to be persisted

In the example above, the component just passes the received message to the next component by invoking:

next(null, msg);

Component libraries

As already mentioned, components may be bundled into component libraries. A component library is just a node.js project that must have the following structure:

components
  - lib
     - hello
        - hello.js
        - component.json
     - fubar
        - fubar.js
        - component.json
  - package.json

The package.json file is a package descriptor for the node.js module. For more details please read here. The lib folder is used to place components. Each sub-folder in this folder is interpreted as a component folder. For example, in the example above the library contains two components hello and fubar.

A component folder acts as component id inside the library it is bundled into. This folder is expected to contain a component descriptor file named component.json. We will cover this file later.

The hello.js file is the component's node.js module that exports the component's process function. This is where you implement the component's logic.

Installing elastic.io command-line interface

Now that you have been briefly introduced into components, let's see how to create and execute a component from a command line. For this purpose you need to install elastic.io command-line interface, as shown in example below.

  npm install elasticio-cli -g

In order to check if the installation was successful, just type in your terminal:

etest

You should see an output like this:

  Usage: etest [options]

  Options:

    -h, --help              output usage information
    -V, --version           output the version number
    -c, --component   Path to component file. May be relative or absolute.
    -f, --fixture      Fixture key to run the component with

How to create a component library?

Now that the installation finished successfully, let's create your first component library. This is done with the elib command, as shown in the following example.

elib
Please enter library name: demo-lib
Please enter library description: My first component library
About to create library 'demo-lib'
Library's description: My first component library
Folder ./demo-lib created
Folder ./demo-lib/lib/ created
File ./demo-lib/package.json created

The command asks you to provide library's name and description. Your empty lib is created.

How to create a component?

Next we can create an empty component. First let's change to the library's directory

cd demo-lib/

Now we can create a component using ecomp command, as shown in the following example.

igor-drobiazkos-macbook-pro:demo-lib igor$ ecomp
Please enter component id: hello-world
Please enter component title: Hello World Component
Please enter component description: Lorem ipsum
About to create component 'hello-world'
Component's title: Hello World Component
Component's description: Lorem ipsum
Folder ./lib/hello-world created
File ./lib/hello-world/component.json created

The component asks you to provide component's id, title and description.

How to execute a component?

Now let me show you how to execute your component. This is accomplished with test fixtures. What is a fixture? A fixture is just a JSON object just is used to provide values for component's process function inside a test.

Now let's create a test fixture by creating a test sub-folder in component's folder and placing a file named fixture.json in it, such as shown in the following example.

{
    "fixtures":{
        "success":{
            "msg":{
                "headers":{},
                "body":{}
            },
            "cfg":{
                "calendarId":"{{google_calendar_id}}",
                "oauth":{
                    "expires_in":3600,
                    "token_type":"Bearer",
                    "refresh_token":"{{google_refresh_token}}",
                    "access_token":"{{google_access_token}}"
                }
            }
        }
    },
    "env":{
        "GOOGLE_APP_ID":"{{GOOGLE_APP_ID}}",
        "GOOGLE_APP_SECRET":"{{GOOGLE_APP_SECRET}}"
    }
}

The content of the file is a JSON object which may have two keys:

• fixtures: named fixtures
• env: [http://nodejs.org/api/process.html#process_process_env](user environment variables).

The only fixture in example above is named success. This fixture defines a message and configuration to be passed to component's process function. Please note that the the component's configuration may contain sensible data, such as API keys or OAuth tokes, which must not be placed inside fixture files. Instead they should be replaced by variables with following syntax:

{{variable}}

The variable values can be store in a file named elastic.json which is located from your user's home directory. For example on my Mac the file is located at /Users/igor/elastic.json. This file is again a JSON file containing all the secret values. Soon we will support encryption.

{
    "google_calendar_id":"fubar@acme.org",
    "google_refresh_token":"very-secret-refresh-token",
    "google_access_token":"very-secret-access-token",
}

Now that you have a fixture prepared, you can execute your component as shown below.

  etest -c lib/hello_world/hello.js -x success

The etest command takes 2 arguments:

• -c: path to the component's file exporting the process function
• -f: fixture name to be used for component execution