☰
Navigation :

Server

Server

The Web SDK editor relies on the Web SDK server. This server can provide web services for:

  1. Licensing
  2. Delivering diagram templates to the client
  3. Converting diagrams created by Windows versions of our products to SVG diagrams
  4. Converting SVG diagrams to PNG or JPEG images

The server can also deliver HTML pages that include samples, documentation, and configuration information.

View Example Configurations

Setup Instructions

  1. Run the WebSDK_<version>.exe for the Web SDK.
  2. When prompted, activate the product by entering your license ID and password.
  3. When the installation is complete, the server will be running as a Windows service. To view the installed samples open http://localhost:3000 in a web browser.

Configuration

The configuration file for the server is located at <Program Data>\Web SDK <version>\config.json. This file contains settings that control the behavior of the server. These settings are applied when the server is started. When you change the server configuration file, your changes will not be applied until you restart the server.

The settings in the server configuration file include:

Setting Type Default Value Description
hostname String 0.0.0.0 The interface(s) the server will listen on. This must be either a host name that resolves to the address of an interface on the host, the address of an interface on the host, or the value “0.0.0.0” which will cause the server to listen on all interfaces on the host machine.
port Integer 3000 or 443 The port the server will listen on. The default port is 443 if the ssl setting is provided.
compression Boolean true If set to true, the web server will compress outbound content.
valid-origins Array.<String> (request origins) or String (regular expression) Controls cross-origin access to the REST services. This is either a list of valid request origins as an array of strings or a regular expression as a string that request origins must match to be considered.

The origin is the domain name of your server that hosts the “client” resources in the root of the Web SDK install folder. (The domain and protocol in the browser address when serving your application)

View Examples
main Boolean true Set this option to false:w to disable the samples, documentation and configuration info served from http://localhost:3000. If set to false navigating to http://localhost:3000 will return a 404 error. The REST services will still be available and function properly. If this option is set to false, the samples and documentation options will be ignored. We recommend setting this option to false in production environments.
samples Boolean true If set to true, the editor sample pages will be enabled.
documentation Boolean true If set to true, the documentation pages will be enabled.
drawService Boolean true If set to true, the draw service routes will be enabled.
templateService Boolean true If set to true, the template service routes will be enabled.
rasterizerService Boolean false If set to true, the rasterizer service route will be enabled.
maxLogSize Integer 5000000 (5 MB) The maximum size of a log in characters. When this threshold is reached, the log will be closed and archived.
maxLogCount Integer 30 The maximum number of log files to keep. This includes the current log file and any archived log files. When this threshold is reached, the oldest archived log files will be discarded.
logDir String logs The directory where the log files will be created. This can be a relative or absolute path. If a relative path is specified, the log directory is relative to the server’s Program Data folder <Program Data>\Web SDK <version>. The log directory will be created if it does not exist.
cacheTimeout Integer > 0 or String 1000 Specifies a max-age in milliseconds for http caching of static content. This can also be a string accepted by the nodejs ms module.
ssl Object Defines the server’s SSL configuration. Valid values will have the form: { key: "<key file path>", cert: "<cert file path>" }
tempFileAutoDelete Boolean true If true, temp files will be automatically deleted.
RESTServiceUrl String /REST The root URL of the REST services for the samples and hosted editor.
customTemplates Boolean false When this option is true, custom templates will be presented to users when they choose to “Start with a Template” in the diagram editor. When this option is false, the default templates included with the Web SDK will be used.

Note that this option is only relevant when the Template Service is enabled (the option templateService is true).

View Example
customTemplatesDir String When specified, this must be the path of a directory. The template files in this directory will be loaded by the server at startup and presented to users when they choose to “Start with a Template” in the diagram editor. If a relative path is specified, it is relative to the server’s Program Data folder (<Program Data>\Web SDK <version>).

The structure of this directory is determined by the value of the customTemplatesLocales option. When more than one template locale is specified, this directory must contain a subdirectory with a name matching the locale.

When this option is not specified and the customTemplates option is true, custom templates must be loaded by using the Template Import Utility.

Note that this option is only relevant when the Template Service is enabled (the option templateService is true) and when the option customTemplates is true.

View Example
customTemplatesLocales String [“en-US”] When specified, this must be an array of locale strings. These are the locales for which we have distinct custom templates. At least one locale must be defined.

The first locale specified is the default locale. Templates for this locale will be used when templates are requested for a locale that is not specified.

The structure of the custom template directory is determined by this option. When one locale is specified, the directory will contain templates for that locale only. When more than one locale is specified, the custom template directory must contain subdirectories with names matching each locale. Each of these subdirectories will contain the templates for the corresponding locale.

Note that this option is only relevant when the Template Service is enabled (the option templateService is true), the option customTemplates is true, and customTemplatesDir is defined.

customTemplatesWatchDir Boolean true When true, the custom template directory specified by the option customTemplateDir will be continuously watched for template file updates. I.E, when template files in this directory are added, updated, renamed, or deleted, the templates delivered to users by the server will be updated.

Note that this option is only relevant when the Template Service is enabled (the option templateService is true), the option customTemplates is true, and customTemplatesDir is defined.

View Example
rasterizeLifetimeRequests Integer > 0 75 The target maximum number of requests handled by an instance of the rasterizer service. When this number is exceeded the rasterizer instance will be retired and a new instance started.
rasterizeLifetimeSeconds Integer > 0 3600 The target lifetime of a rasterizer service instance in seconds. When a rasterizer’s lifetime exceeds this value it will be retired and a new instance started.
rasterizeMaxActiveRequests Integer > 0 3 The maximum number of concurrent rasterize requests.
rasterizeMaxRequestDelay Integer > 0 5000 The target maximum execution time in milliseconds for rasterize requests. When the server is busy and is unlikely to meet this goal, it will reject rasterize requests.
rasterizeMaxWidthHeight Integer 0 < value <= 10,000 4000 The maximum width/height for rasterize requests in pixels.
rasterizeRenderTasks Integer >= 2 2 The number of processes in the rasterizer task pool. Increasing this value may improve rasterization performance when there are many simultaneous requests.
rasterizeTcpPortRange Numeric Array [2011, 2032] A 2 element array defining the range of TCP ports available for use by the rasterizer. The range must encompass at least 4 port numbers.
rasterizeTimeout Integer > 0 15000 Timeout for rasterize requests in milliseconds.
rasterizeDefaultWidth Integer 0 < value <= rasterizeMaxWidthHeight 1200 The default width for rasterize requests in pixels.
rasterizeDefaultHeight Integer 0 < value <= rasterizeMaxWidthHeight 1200 The default height for rasterize requests in pixels.
rasterizeDefaultMargin Integer 0 < value <= 1/2 of max( rasterizeDefaultWidth, rasterizeDefaultHeight) 10 The default margin for rasterize requests in pixels.
rasterizeDefaultImageQuality Number 0 < value <= 1.0 0.75 The default JPEG image quality for rasterize requests.
rasterizeDefaultFormat String ‘image/png’ or ‘image/jpeg’ ‘image/png’ The default image format for rasterize requests.
rasterizeVerboseLog Boolean false Include more verbose content in the rasterizer log?

Other Considerations

SSL: The standard web server functionality of Node.js is used in the server. There are many optional features and settings available which can be referenced in the Node.js documentation here.

Operation Behind a Reverse Proxy: The web service does not keep state and generally does not require special treatment.

Load Balancing: To assist with load balancing, a status end-point is provided at /status which always returns a 200 status code and the text “OK” when the server is running.

Examples

“valid-origins” Examples

Array of Strings

Each entry in the array is a distinct domain and protocol that will be allowed to make REST requests to the Web SDK server.

Note: If you are using the standard “http” and “https” protocols, do not include the port number after the domain (i.e :80, :443).

"valid-origins": [
"http://your.app.example",
"https://your.app2.example"
]

Regular Expression (String)

Note: As the regular expression value is a string, backslashes must be escaped.

In this example, the server will allow REST requests from any domain that ends with “.example.com” that uses the “https” protocol.

"valid-origins": "^https:\\/\\/.*\\.example\\.com$"

Custom Templates Example

The following example demonstrates how to configure the server to use custom templates.

{
    "templateService": true,
    "customTemplates": true,
    "customTemplatesDir": "C:\\path\\to\\customTemplates",
    "customTemplatesWatchDir": true,
    "valid-origins": [
        "http://localhost:3000"
    ]
}

Note: Make sure all backslashes are escaped in the customTemplatesDir path.