How to Create a REST Extension

The REST Extension allows you to write the code that translates data into VisualScript 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 a string of VisualScript markup to SmartDraw to render as 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 VisualScript 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. This presents 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.

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

Choose a rest 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.

Configure your rest extension

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

End user form preview

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.

REST headers

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.

REST message body

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.

Share your extension

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:

End user form for extension

Writing a REST Endpoint

You may use the language and host of your choice when writing a REST endpoint. Here's an example in C#

[OperationContract]

        [WebGet(UriTemplate = "/JiraIssue/?issueid={issueid}", ResponseFormat = WebMessageFormat.Json)]

        public Stream JiraIssue(string issueid)

        {

        var myData=QueryLinkedIssues(issueid);  //get the linked issues to this issue

        var myIssues=SortLinkedIssues(myData) ;  //sort the issues into blocking and blocked by

        var myVSDocument=FormatTree(myIssues);  //build a tree representation of the issues as a VisualScript Document object

        var output=myVSDocument.toJSON();     //turn the object into a  JSON string

        return new MemoryStream(System.Text.Encoding.UTF8.GetBytes(output));  //this returns a raw JSON string as expected by the caller.

        }

The endpoint must return a raw JSON string in VisualScript format. SmartDraw will translate this into a document.