Welcome, Guest Login

Public Cloud Center

Building an Add-On

Last Updated: Apr 19, 2017 10:44AM EDT

This document is a step-by-step guide to turning your cloud service into a Xervo add-on.


You can start your add-on from a template using the dia init command. This will initialize a skeleton add-on manifest, which you will update for your application.

You will begin by implementing a provisioning API for your service, which Xervo will call when a customer installs your add-on. We provide dia, a command line tool to test your provider API implementation in your development environment. You will also create a JSON manifest document that defines how Xervo will access your API.

You will need to provide information to consumers of your add-on that show how to consume your service in a Node.js application. This may be in the form of a snippet added to the description of add-on in the add-ons portal or a link to your own, existing documentation.

Once you have tested your API in your development environment, you are ready to submit your add-on to Xervo to be built up and made available to the public.

The implementation of single sign on is optional. If your service requires additional configuration or access to a web-based admin panel for private resources, you will need to implement single sign on; otherwise, you can skip that step.

Getting Started

First, you will need to install some software to create your add-on manifest.


Your service can be written in any languages; however, you will need Node.js installed in order to use the dia command line tool. This means that Node.js will need to be installed in your development environment.

The Node.js installer is available for all platforms here.

1. Install Dia

Every step of this document will take place in your development environment. Calls from Xervo will be simulated using the dia module. Install dia using:

$ npm install --global dia

Run dia with no arguments (or with the --help option) for a reference of all available commands.

2. Run your development add-on

Launch the development version of your service. While building and testing your provisioning API, dia will simulate provision actions, which will require that your service is available to handle such requests.

3. Generate an add-on manifest

Your add-on manifest is a JSON document that describes your add-on. Create a skeleton manifest using the dia init command. This will provide you with a file in your local directory named addon-manifest.json with some default values.

Open the addon-manifest.json file in your editor.

  "id": "myaddon",
  "api": {
    "config_vars": [ "MYADDON_URL" ],
    "regions": [ "us" ],
    "password": "1264adf7736dc39361393f497cf2d6c8",
    "sso_salt": "2e51962ed94ef2f111b89189361222e8",
    "production": {
      "base_url": "https://yourapp.com/xervo/resources",
      "sso_url": "https://yourapp.com/sso/login"
    "test": {
      "base_url": "http://localhost:4567/xervo/resources",
      "sso_url": "http://localhost:4567/sso/login"

Start by changing the id field of your new manifest. For example if your service is called "Mongo-Matic" then use "mongomatic" for the id. This field must be unique. You will be alerted if it conflicts when submitting your add-on. Also note that you will be able to add a more human-friendly display name from the portal once your add-on is submitted.

Next, change the test and production URLs so that dia (and, later, Xervo) can access your service. The test URLs are where your service is running in your development environment.


When a Xervo customer installs your add-on, Xervo will make a REST call to your service to provision a private resource for their project.

This section is a hands-on guide to implementing and testing your provider API.

1. Test provision

Xervo will call your service with a POST request to your configured API production base_url defined in your addon-manifest.json. This request is expected to return a 200 response code along with an id and config object which contains the config variables defined in your addon-manifest.json.

$ dia test provision

The first thing that dia does is validate your manifest to ensure that the required fields are available. This needs to happen so that dia is able to make sure that the test URL is present before sending the provision request to your development environment. The provision request will show as follows in dia (this example shows a successful POST):

testing POST to http://localhost:4567/xervo/resources
  check authentication [PASS]
  check response [PASS]

A 200 response is expect along with an id from your services and a config object which includes values for the config_vars that you defined.

app.post('/xervo/resources', auth, function(req, res) {
  res.json(200, {
    id: 123,
    config: {
      'MYADDON_API_KEY': 'some-key',
      'MYADDON_URL': 'http://example.com'
    message: null

2. Authentication

Provider API routes must be protected by the HTTP basic authentication scheme. This authentication uses the id and password fields from your add-on manifest.

Notice that the previous example includes an express basicAuth middleware. This middleware works like so:

var auth = express.basicAuth('myaddon', '1264adf7736dc39361393f497cf2d6c8');

Dia will validate that your API is protected by basic authentication. Any request that does not use these credentials must return a 401 (not authorized) response status code.

3. Config vars

Your service can return any number of config vars but, in most cases, should only need one, a URL which is named after your service and ends with _URL.

Update your addon-manifest.json so that config_vars items start with the id of your add-on and ends with the correct suffix:

"config_vars": [ "MYADDON_URL", "MYADDON_API_KEY" ]

4. Deprovision

When a user removes an add-on, Xervo will make a DELETE request to your service to deprovision the resource. Implement an Express request handler like this:

app.delete('/xervo/resources/:id', auth, function(req, res) {
  // TODO: deprovision the resource with the specified :id.
  res.statusCode = 200;

Test that deprovision is working correctly using dia, you can also pass an id to use so that you can be sure that the deprovision request is deprovisioning the correct resource in your development environment.

$ dia test deprovision 123

5. Plan Changes

If your add-on offers multiple plans, you should allow for instant plan changes. When a user changes plans, Xervo will send a PUT request to your service. If the resource has changed location or credentials, you can include an updated config object in the response like you would with a provision response.

app.put('/xervo/resources/:id', auth, function(req, res) {
  // TODO: update plans for the specified :id.
  res.json(200, { message: null });

To test your plan change route:

$ dia test planchange 123 plan-name

This command will attempt to update the plan for resource 123 to “plan-name.”

In some cases, an add-on will be unable to support instant plan changes such as the case with large data migrations when changing plans. In such cases, you should do the following:

  • Respond with a 503 status code
  • Provide a custom message in the message response field
  • Include a link to your documentation on how to manually change plans

6. Exceptions

If your service is unable to fulfill requests, you should respond with a 503 status code with a custom message in the message field of the response body.

app.post('/xervo/resources', auth, function(req, res) {
  res.json(503, {
    message: 'We\'re undergoing maintenance. Be back at 16h00 EDT.'

This pattern can be used for provision (POST), deprovision (DELETE), and plan change (PUT) requests. All non-200 responses from your service are treated as errors by Xervo.

Next steps

Your server-side integration is complete. Your next step is to build the documentation that will be visible for your add-on in the market.

Creating consumer examples

You’ll need to provide a sample that demonstrates how Xervo projects will consume your service once your add-on is installed for users' projects. This example will most likely include the installation of your Node.js module from npm, including the module at runtime, and initializing the module using the environment variables to use your service.

As an example, a Mongo add-on would provide a URL connection string to the user's environment. Your example should include using a supported Node.js MongoDB driver to connect and use the provisioned MongoDB add-on:

var mongoose = require('mongoose');

var Cat = mongoose.model('Cat', { name: String });

var kitty = new Cat({ name: 'Zildjian' });
kitty.save(function (err) {
  if (err) throw;

Go to top

Contact Us

    Our Support Policy
    Submit a Support Request

  • Public Cloud Support Hours
    9am-5pm EST Mon-Fri
    Outside of these hours response times may be up to 24hrs.

    Submit a support ticket by clicking 'status and support' icon on the left side of this page.

seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found