Wouldn’t it be great if you and your customers could easily extend your app, adding new features and business rules, and do it all through simple scripting in an embedded editor within your product? In this post, I’ll show you how with the new Extend Starter plan.

Sign up

To get started, go sign up for the Extend Starter plan here by clicking on “SIGN UP”. Once you click the button, you’ll be taken to a login screen where you can login with a number of social providers, or you can sign up using an email address. Signing up is free for the first month. Once you’ve signed up, you’ll be taken to the account page where you’ll see your subscription information.

  • Extend Host URL: The URL for your Extend subscription.
  • Token: Your master token for Extend’s management API. You will need this in order to embed the editor.
  • Container Prefix: The prefix that all your container names must have. Containers in Extend are units of isolation for executing custom code, and generally map to either environments or tenants. With the starter plan you can specify up to 5 production containers*
  • Dev Container: The starter plan includes an extra dev container that you can use for development and prototyping. We’ll use this for running our sample.

Copy the Token and Dev Container as you’ll need them shortly.

Create your dev tenant token

The token provided to you is the master token for management of your Extend subscription and not for direct use by the application. To continue, you’ll need to first create a tenant token for the dev container.

	curl -X POST https://starter.auth0-extend.com/api/tokens/issue \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    --data '{"ten":"{DEV CONTAINER}"}'

In the sample command above, replace {TOKEN} and {DEV CONTAINER} with the values you copied from the account page. Save the result of this call to use as your tenant token.

Get the Extend one page sample.

The goextend Github org contains a simple one page extensible application, that uses Express on the backend and Vue.js on the frontend. You can use it quickly to see how Extend works. Clone or download the sample here. Once you’ve got the sample, go into the folder via a terminal and install it’s npm dependencies npm i.

Create an .env file.

The sample relies on some configuration. Create a new .env file, using the template below, replacing each placeholder (values in { }) with the values you copied previously.

EXTEND_CONTAINER={DEV CONTAINER}
EXTEND_TOKEN={TENANT TOKEN}
EXTEND_HOST=https://starter.auth0-extend.com

Run the app

Type npm start to run the app. Once you see that it is running, open your browser to “http://localhost:3000”. You’ll see the screen below.

The app allow specifying a customer name and lead value which will be saved to the server via the app’s API. In the Extension portion, you can author custom code in the editor that the app will execute whenever the record is saved.

Go modify the code so that it attaches a created timestamp to the entry and returns it back to the client.

module.exports = function(context, cb) {
  var entry = context.body;
  entry.created = new Date().toGMTString();
  cb(null, entry);
};

Click the editor’s Save button (in the toolbar). Now enter a customer name and click the blue “Save” button. Below you can see I entered “Glenn Block” and “1000000”, and I got back the created timestamp as expected.

Add Slack notifications

Now that you’ve got the timestamp working, you can add one more bit of customization. Our organization uses Slack heavily, let’s go modify the code to send a Slack message, to notify sales whenever a lead is created.

To do this, you’ll modify the code to use the slack-notify module. First click on the gear icon in the editor and select “NPM Modules”. Click “Add Module” and find slack-notify. Once you have added it close the modules pane.

Next, you’ll need an Incoming Webhook to be able to send to Slack. I created one that sends to a #leads channel. Rather than put it in the code, you can add it as a secret. One you have the url, click on the gear icon again and select ‘Secrets’. Add a new secret with the key of SLACK_URL and the value being the url. Close the secrets pane when done.

The last step is to update the code to send a notification to the channel. Replace the code in the editor with the following:

module.exports = function(context, cb) {
  var slack = require('slack-notify')(context.secrets.SLACK_URL);
  var entry = context.body;
  entry.created = new Date().toGMTString();
  slack.send(JSON.stringify(entry));
  cb(null, entry);
};

The new code first requires the slack-notify module passing into the constructor the SLACK_URL secret which conveniently provided via the context.secrets field. After the created date is sent, the notification is then sent.

Click the “Save” button in the app again, and you should see the notification sent to Slack. Wasn’t that easy?

These are just a few examples of the kind of use cases you can enable with Extend. The possiblities are endless.

How is Extend wired up?

There are 2 places within this demo application where Extend is used. First there is the Extend editor which is embedded in the UI. This is done with a few lines of code in index.handlebars

The editor uses the host, container and token information provided in the .env file. webtaskName specifies the name of the Webtask that the editor will be editing. The createIfNotExists setting will force a new Webtask to be created if none exists.

That covers the front end. The next place where Extend is used is is within app.js in the /saveCustomer endpoint which is invoked by the client whenever “Save” is clicked.

app.post('/saveCustomer', (req, res) => {
	let data = req.body;
	console.log('i was sent: '+JSON.stringify(data));

	// call extension
	let options = {
		method:'POST',
		url:extendURL +'saveLead',
		headers:{'Authorization':`Bearer ${extendToken}`},
		json:req.body
	};

	request(options, function(error, response, body) {
		if(error) throw new Error(error);
		res.end(JSON.stringify(body));
	});
});

To invoke extensions, your app simply makes an HTTP call. This code uses request to make an HTTP call to Extend to run the saveLead Webtask, passing in the entry that was sent from the client. It returns the JSON body that it receives directly back to the client.

It’s that easy to get started.

This is just the beginning

In this post you’ve seen the basics of how you can use the new Extend Starter plan to make an app customizable. Once Extend is in, you and your customers can use the rich editor to enable new use cases and features. What we’ve done today is just the tip of the iceberg of what you’ll be able to do with Extend!

So what are you waiting for? Go Extend!