How to Create a REST Extension

The REST Extension allows you to write the code that translates data into a visual using the VisualScript SDK in the language of your choice, running as a web service on the host of your choice. All you need to do is provide a REST endpoint that returns VSON to SmartDraw to render as a visual. VSON is a markup language that translates data into a diagram. The REST Extension configuration dialog lets you use a UI builder to create an end-user UI for input, but the code that generates the VSON is hosted elsewhere.

Configuring a REST Endpoint Extension

To add an extension that uses a REST Endpoint, go to the Extensions category in the SmartDraw Template Dialog and click on the "Create an Extension" icon. You'll be presented with a choice about the type of extension you want to create in the "Choose Extension Type" dialog.

Choose the REST Extension option.

In the REST Extension configuration dialog, you can give your extension a name and point to the url that will pass SmartDraw VisualScript markup (VSON).

The description you add will show in the dialog an end user sees when running the extension.

Passing Parameters to the EndPoint

There are three ways to pass parameters to the REST endpoint.

The URL

You can pass parameters to this URL using the UI Builder syntax.

https://myurl?variable1={{variable1}}&variable2={{variable2}}

Using this syntax for variables creates a form that the end user will see allowing them to input values for these variables. Adding them also shows them at the bottom of the dialog allowing you to set defaults and a description.

You can see what the end user form will look like by clicking the "Preview Form" button at the bottom of the dialog.

Additional Headers

You can use the same syntax in the Additional Headers section, which are also passed to the EndPoint.

These fields are also added to any end user form.

Message Body

If you change the mode of the call to POST instead of GET, you can also pass a message body to the endpoint. Again, you can use the UI builder to prompt for user input. In the example below, we format a JSON string using the UI Builder.

Sharing a REST Endpoint Extension

Creating a REST EndPoint extension adds a new icon to your Extensions category with the name that you assigned to it. If you (as the author) click on this you see the configuration dialog. You can run it or change the configuration.

You may want to share this extension with others so your team can use it to generate visuals from the same data.

Right click on the Extension icon and choose "Share". This copies a share URL to the clipboard. Paste this into an email and send it to anyone you want to be able to use it. If the user clicks on the link the icon for the extension will appear in their Extensions dialog.

Please note that sharing is only allowed between users that share the same SmartDraw Enterprise Site License.

Running a Shared Extension

When a user runs a shared extension by clicking on the extension's icon, they don't see the configuration dialog. They'll see the end user dialog you created with the UI builder above:

Writing a REST Endpoint

The REST Extension needs to hook into REST Endpoint API that returns VSON. VSON lets you turn data into a visual that SmartDraw can render as a diagram. You may use the language and host of your choice when writing a REST endpoint that returns VSON.

You can build VSON as native JSON, but its much easier to use the VisualScript SDK. SDK's are available for C# and Java.

Get the SDK here.