Component Descriptor Structure

Each integration component developed for elastic.io platform must have a component descriptor file called component.json in its root folder, as shown below. It describes the component structure and tells the platform what functions are available, what credentials are necessary to run your component on the elastic.io platform, etc.

├── component.json                                          (1)
├── lib
│   ├── actions
│   ├── schemas
│   └── triggers
├── logo.png
├── package.json
└── verifyCredentials.js

The example above shows the structure of a Node.js component. The components written in Java programming language have a different structure but the components descriptor must again be located in the root folder of the component (1). Read our introductory guides about building components in Java or Node.js for the elastic.io platform. Here we will concentrate on providing an in-depth reference about the structure and the objects which you can use to describe different parts of any component.

Descriptor Structure

Let’s explore the structure of the component.json in the following table. As you can see there are simple properties such as title and nested objects such as credentials. You can follow the links to see details about of the nested objects.

Let’s explore an example of a component descriptor:

{
  "title": "Title of the component",
  "description": "The description of the component",
  "envVars": { },
  "credentials": { },
  "triggers": { },
  "actions": { }
}

As we have presented the information in the table above, only title and description are required properties here.

Note You must declare at least one function, either in triggers or actions for the component to function properly.

envVars Object

The envVars object defines the environment variables for the component configuration. Every environment variable defined in the component.json file must have the following properties:

The environment variable naming follows a standard UNIX/Linux Shell variable definitions. As a guidance, variable name must begin with an alphanumeric or alpha character, followed by one or more alphanumeric or underscore (_) characters. Avoid using reserved words like (if, else, elif, do, done …). Here is an example of envVars object implemented in the Salesforce Component:

{
  "envVars": {
    "SALESFORCE_KEY": {
      "required": true,
      "description": "Your Salesforce OAuth client key"
    },
    "SALESFORCE_SECRET": {
      "required": true,
      "description": "Your Salesforce OAuth client secret"
    }
  }
}

Credentials Object

The Credentials Object specifies how a user can grant a component the access to his protected resources using API. This is accomplished by defining fields used to gather authentication related data from the user.

Let’s explore an example from the Petstore API (Node.js) component. The client authenticated with the Petstore API using an API key which is sent via an HTTP header. That’s why it is sufficient to define in the credentials object a single field to gather the API key from the user, as shown below.

{
  "credentials": {
    "fields": {
      "apiKey": {
        "label": "API key",
        "required": true,
        "viewClass": "TextFieldView",
        "note": "Please use <b>secret</b> as API key"
      }
    }
  }
}

In the example above the apiKey field is used to gather user’s API key.

The view of the field is defined as TextFieldView which tells the platform to present it in the UI as a simple input field where a user must enter his API key. Please read more details on field types here.

The value of this field will be provided to the component at the runtime.

OAuth1

Specifies OAuth 1.0 specific details of the API used by the component. For more details about Authenticating with OAuth 1.0 refer to the OAuth 1.0 specification standard.

Here is an example implementation of OAuth1 in the Credentials Object:

{
  "credentials" : {
    "fields": {
      "oauth": {
        "viewClass":"OAuthFieldView",
        "label":"Twitter Account",
        "required" : true
      }
    },
    "oauth1":{
      "consumer_key":"",
      "consumer_secret":"",
      "request_token_uri":"https://api.twitter.com/oauth/request_token",
      "auth_uri":"https://api.twitter.com/oauth/authorize",
      "access_token_uri":"https://api.twitter.com/oauth/access_token"
    }
  }
}

In case of OAuth1 Authentication we must use fields and oauth1 objects together. The fields object defines the input field type and the oauth1 object provides the configuration. Please note that the viewClass property of the field must be set to OAuthFieldView.

OAuth2

Specifies OAuth 2.0 specific details of the API used by the component. For more details about Authenticating with OAuth 2.0 please read the OAuth 2.0 specification.

Here is an example of OAuth2 implementation in Google Spreadsheets component:

{
  "oauth2":{
    "client_id":"",
    "client_secret":"",
    "auth_uri":"https://accounts.google.com/o/oauth2/v2/auth",
    "token_uri":"https://www.googleapis.com/oauth2/v4/token",
    "scopes": [
      "https://spreadsheets.google.com/feeds"
    ],
    "access_type": "offline",
    "prompt": "consent"
  }
}

Please note that the properties access_type and prompt above are specific to Google. They are not defined in the OAuth2 specification.

Sometimes you will need to access values in the oauth2 properties you gathered from the user using fields, as for example is done in the Salesforce component. The following example demonstrates how to do that.

{
  "credentials" : {
    "fields":{
      "prodEnv" : {
        "label":"Environment",
        "viewClass":"SelectView",
        "required":true,
        "model":{
          "test":"Sandbox",
          "login":"Production"
        },
        "prompt":"Select environment"
      },
      "oauth":{
        "label":"Authentication",
        "viewClass":"OAuthFieldView",
        "required": true
      }
    },
    "oauth2":{
      "client_id":"SALESFORCE_KEY",
      "client_secret":"SALESFORCE_SECRET",
      "auth_uri":"https://prodEnv.salesforce.com/services/oauth2/authorize",
      "token_uri":"https://prodEnv.salesforce.com/services/oauth2/token"
   }
 }
}

In the example above the value of the prodEnv field is used to define the auth_uri and token_uri properties.

The auth_url property can take additional query parameters as shown below:

{
  "oauth2": {
    "auth_uri": "https://login.windows.net/common/oauth2/authorize?resource=RESOURCSE",
    "token_uri": "https://login.windows.net/common/oauth2/token"
  }
}

Triggers Object

The Triggers Object is used to expose component’s triggers. The properties of this object are used as unique trigger names.

Here is an example of a trigger definition in the component.json where the type is included and specified as polling:

{
  "queryTrigger": {
    "title": "SOQL Query",
    "main": "./lib/triggers/query.js",
    "type":"polling",
    "metadata": {
      "out": {}
    },
    "fields": {
      "query": {
        "label": "SOQL Query",
        "required": true,
        "viewClass": "TextAreaView"
      }
    }
  }
}

Actions Object

The Actions Object is used to expose component’s actions. The properties of this object are used as unique action names.

Here is an example of action object implementation in the component.json:

{
  "queryAction": {
    "title": "Query",
    "main": "./lib/actions/query.js",
    "metadata": {
      "in": {
      "type": "object",
      "properties": {
        "query": {
          "maxLength": "20000",
          "title": "SOQL Query",
          "type": "string",
          "required": "true"
        }
      }
    },
    "out": {}
  }
}
}

Fields Object

The Fields Object specifies how to render an input field used to collect the input from a user that is required for a component to work properly.

For example, fields object is used for providing credentials to authenticate with the given API or to configure a trigger/action with some parameters:

Any object implementation is directly connected with one or several View Class definitions, therefore it is advisable to check them as well.

JSONSchema References

You can use JSONSchema references in Component metadata. Basically, it allows you to avoid repetitive coding by referencing certain keys called definitions. Let’s take Email Component as an example. Here you can see three address fields To, Cc and Bcc:

{
  "actions": {
    "send": {
      "main": "./send.js",
      "title": "Send Mail",
      "metadata": {
        "in": {
          "type": "object",
          "properties": {
            "to": {
              "title": "To",
              "type": "string",
              "required": true
            },
            "cc": {
              "title": "Cc",
              "type": "string",
              "required": false
            },
            "bcc": {
              "title": "Bcc",
              "type": "string",
              "required": false
            }
          }
        }
      }
    }
  }
}

The thing about them is that they are basically the same element. So what you can do is add a definition for address fields, and just refer to it every time you need one. Here is how it will look like:

{
  "definitions": {
    "addressfields": {
      "type": "object",
      "properties": {
        "To":           { "type": "string" },
        "Cc":           { "type": "string" },
        "Bcc":          { "type": "string" }
      },
      "required": ["To"]
    }
  }
}

When you need to refer to this definition from elsewhere using the $ref keyword:

{ "$ref": "#/definitions/addressfields" }

So if we go back to our initial Email Component, with a set reference it will look like this:

{
  "actions": {
    "send": {
      "main": "./send.js",
      "title": "Send Mail",
      "metadata": {
        "in": {
          "type": "object",
          "properties": {
            "$ref": "#/definitions/addressfields"
          }
        }
      }
    }
  }
}

IMPORTANT: We do not support referencing by $id and referencing external schemas at the moment.