Introduction
The Macrobond Chart Server delivers images of Macrobond charts in either PNG or SVG format. The server uses the same components as the Macrobond client application and will render exactly the same image over http as you would see in the client application. The server runs as a Windows Service.
The Macrobond Chart Server is a separately licensed solution.
This document refers to Macrobond Chart Server 1.28.101 or newer.
Requirements
Minimum requirements: 64-bit versions of Windows 10, Windows Server 2016 or newer, .NET Framework 4.7.2.
Installation
The Macrobond Chart Server is installed by running a Windows Installer script (MSI). Any previous version of the service will be replaced. The name of the Windows Service is 'Macrobond Chart Rendering Service'.
The chart server communicates with the Macrobond servers at: https://app1.macrobondfinancial.com, https://app2.macrobondfinancial.com and https://app3.macrobondfinancial.com.
The executables will be installed in:
%ProgramFiles%\Macrobond Financial\Chart Server
Working with Chart Server
Configuration
The file 'appsettings.Production.json' in the program directory contains settings for the service.
Anonymous access
To configure anonymous access set the username and password for the account that the service should use. Replace the value of these elements in the config file under ChartService:
"Username": "USERNAME GOES HERE",
"Password": "PASSWORD GOES HERE",
Anonymous requests are done to http://<server>:<port>/chartserver
Token authenticated access
This feature is currently not used by clients.
To configure token authenticated access set the token server uri by adding the following under ChartService:
"AuthenticationServer": "uri goes here",
Authenticated requests are done to http://<server>:<port>/chartserver2
To enable CORS add a list of uris by adding the following element under ChartService:
"Origins": [ "uri1", "uri2" ],
Host settings
You may want to change the port used for http communication. This is done in the file “hosting.json”. The default setting is:
"Urls": http://*:8088
The service must be restarted for the new settings to be used.
Addresses of Macrobond servers
Addresses of Macrobond backend servers to which the render service connects can be specified under ChartService:
"ServerList" : ["https://app2.macrobondfinancial.com/app/", "https://app1.macrobondfinancial.com/app/",
"https://app3.macrobondfinancial.com/app/"],
HTTP Proxy server
By default the Chart Server will communicate directly with Macrobond servers. To use explicitly configured server add this under ChartService:
"Communication": {
"ProxyUsage": 1,
"ProxyServerAddress": "http://address.of.the.proxy:port",
},
Cache policies
For best performance, series and documents are cached for up to three minutes. In some cases you might want to select a longer or shorter time. The time can be configured with these two settings in the appsettings.Production.json file. The time is specified in seconds. The value should never be set below 5 seconds, because the server will assume that data is cached at least.
Add the following to the ChartService section:
"CachePolicy": {
"entity.TimeSeries": 180,
"Document": 180
}
Additional series providers
Additional data providers can be configured for the Chart Server using a configuration file located here:
%ProgramData%\Macrobond Financial\Series Providers\config.xml
This is typically used to configure one or more SQL Providers. Here is a sample file that adds one SQL provider:
<?xml version="1.0" encoding="utf-8"?> <spdc:SeriesProviderDescriptorConfiguration xmlns:spdc="http://schemas.mbnd.eu/2010/SeriesProviderDescriptorConfiguration"> <spdc:Descriptor spdc:Prefix="ppp" spdc:Description="My SQL Database" spdc:TypeName="SqlSeriesProvider" spdc:ConfigPath="c:\path\MySqlConfig.xml" /> </spdc:SeriesProviderDescriptorConfiguration>
The server will read this file when started.
This configuration file uses the same format as the configuration file for the Macrobond application. It can be a good idea to use the config file from a computer where the Macrobond application is configured as desired as a template. You can find the configuration file used by the application here: %LOCALAPPDATA%\Macrobond Financial\Series Providers\config.xml
Logging
Logging generated by Chart Server is controlled by file log4net.config in %programfiles%\Macrobond Financial\Chart Server. By default logs are written to c:\Windows\ServiceProfiles\LocalService\appdata\local\temp\, which is accessible only from cmd with elevated privileges. Path to the log file can be changed by setting e.g.:
<file value="c:\temp\ChartServer.log" />
Please make sure that the destination folder exists and service account has permission to write to it, then restart the Chart Service.
Operations
renderpath
The 'renderpath' operation renders a Macrobond document, references by a path, as an image. The request has the following form:
renderpath?path={path}&presentation={presentation}&width={width}&height={height}&format={format}&dpi={dpi}&bkgcolor={bkgcolor}&useAnimation={useAnimation}&defaultAnimationDuration={defaultAnimationDuration}&defaultAnimationDelay={defaultAnimationDelay}
| {path} | The path of the document in the Macrobond store. You can find this path by selecting a chart in the File Open/Save dialog of the Macrobond application and then select Copy. This will copy the path as text to the clipboard. |
| {presentation} | If a document contains several presentations, this identifies which one that should be rendered. To use the default presentation, specify '00000000-0000-0000-0000-000000000000'. You can find the presentation identifier by selecting 'Copy' on the context menu of a presentation in the Analysis tree in the Macrobond client application.
|
| {width} | The width, in pixels, of the resulting image. This will not be used for Bar charts unless the Width mode is set to Fill for the chart in the Macrobond application. |
| {height} | The height, in pixels, of the resulting image. This will not be used for Bar charts where the height is always determined by the chart layout and content. |
| {format} | The image format to return. Can be either 'png' or 'svg'. |
| {dpi} | The resolution of the image expressed as dots per inch. A value of '96' will result in a scale 1:1. A higher value, such as '120' will render text and line widths larger. |
| {useAnimation} | If set to true, line graphs will be animated in SVG images and data popup labels showing the date and value on mouse hover is enabled. Optional. Default is false. Available in version 1.28 and later. |
| {defaultAnimationDuration} | The duration of animations in seconds. Optional. The default is 5. Available in version 1.28 and later. |
| {defaultAnimationDelay} |
The default delay between animations in seconds. Optional. The default is 0. Available in version 1.28 and later. |
Example:
In order to render the default chart of the following document
remotepublicfilestore/common/filestore/Thomas O/Sweden/GDP.mbnd
in the size 800x600, at 96 DPI, as a PNG and keeping any transparent areas, then the URL can look like this:
http://localhost:8088/chartserver/renderpath?path=remotepublicfilestore%2Fcommon%2Ffilestore%2FThomas%20O%2FSweden%2FGDP.mbnd&presentation=00000000-0000-0000-0000-000000000000&width=800&height=600&format=png&dpi=96
render
The 'render' operation renders a Macrobond document posted as XML. The XML format looks like this:
<r:RenderSpecification xmlns:r="http://schemas.mbnd.eu/2010/renderspec"> <r:ImageType>png</r:ImageType> <!-- Can be png or svg. The default is png. --> <r:XPixels>200</r:XPixels> <r:YPixels>125</r:YPixels> <r:XHimetric>10583</r:XHimetric> <r:YHimetric>6614</r:YHimetric> <r:AbacusDocument> <doc:CalculiDocument xmlns:doc="http://schemas.mbnd.eu/2009/calculidocument"> <!-- The Macrobond document specification --> </doc:CalculiDocument> </r:AbacusDocument> </r:RenderSpecification>
downloadpath
The 'downloadpath' downloads the Macrobond document specification referenced by a path. This specification is an XML document that be used in the 'render' operation. The request has the following form:
downloadpath?path={path}
| {path} | The path of the document in the Macrobond store. You can find this path by selecting a chart in the File Open/Save dialog of the Macrobond application and then select Copy. This will copy the path as text to the clipboard. |
listdirs
The 'listdirs' returns list of folders present in specified directory. This function, combined with the 'listfiles', can be used to implement a web-based chart selector. Returned output is in JSON format.
listdirs?path={path}
| {path} | The path within Macrobond storage. If the path is not specified, the root directories will be listed. |
Sub directories can be listed for directories where HasChildren is true by calling listdirs with the specified Path.
If HasChildren is not true, then this directory can contain files and the path can be passed to listfiles in order to list the files.
Example:
To get list of all folders located directly under Company Account call
http://localhost:8088/chartserver/listdirs?path=macrobond://remotepublicfilestore/common/filestore/
Output:
[ { "Name": "Folder A", "Path": "macrobond://remotepublicfilestore/common/filestore/Folder%20A/", "HasChildren": true }, { "Name": "FolderB", "Path": "macrobond://remotepublicfilestore/common/filestore/FolderB/" } ]
listfiles
The 'listfiles' returns files located in specified directory. Output is in JSON format.
listfiles?path={path}&ext=.extension
| {path} | The path within Macrobond storage. This is typically obtained from a listdir call. This parameter is obligatory. |
| {ext}
|
Defines what file types should be returned. A list of comma separated values can be specified. This parameter is obligatory. |
| { skipThumbnails} | Defines weather the response should contain base64 encoded thumbnails of the documents. Possible values: true, false. Default: false. |
Both parameters must be specified.
Example:
To get list of all files located directly under Company Account call
Sample output:
[ { "Name": "121 - Copy", "Path": "macrobond://remotepublicfilestore/common/filestore/121%20-%20Copy.mbnd", "Created": "2019-12-13T17:37:45Z", "LastModified": "2020-11-02T13:26:24Z", "LastSavedBy": "account name_of_person_who_last_modified_the_file", "CreatedBy": "account name of person that created the file", "ThumbnailPng": "base 64 encoded PNG with thumbnail of the chart" }, { "Name": "121", "Path": "macrobond://remotepublicfilestore/common/filestore/121.mbnd", "Created": "2018-03-31T14:35:40Z", "LastModified": "2020-11-05T07:36:31Z", "LastSavedBy": "account name_of_person_who_last_modified_the_file", "CreatedBy": "account name of person that created the file", "Comment": "Semiconduct export YoY", "Keywords": "export,prices", "ThumbnailPng": "base 64 encoded PNG with thumbnail of the chart" } ]
filemeta
The 'filemeta' returns meta data about a file. Output is in JSON format.
filemeta?path={path}
| {path} | The path within Macrobond storage. This is typically obtained from a listdir call. This parameter is obligatory. |
Example:
To get the file meta data for a file 'Document.mbnd' in the company store
Sample output:
{
"SeriesNames": [
"usnaac0169",
"pln"
],
"SeriesPrimaryNames": [
"usnaac0169",
"pln"
],
"LastSavedBy": "account name_of_person_who_last_modified_the_file",
"CreatedBy": "account name of person that created the file",
"Comment": "some comment",
"Keywords": "export,prices",
"ThumbnailPng": "base 64 encoded PNG with thumbnail of the chart"
}
documentinfo
The 'documentinfo' returns information about the charts in a document. Output is in JSON format.
documentinfo?path={path}
| {path} | The path within Macrobond storage. This is typically obtained from a listdir call. This parameter is obligatory. |
Example:
To get the document info for a file 'Document.mbnd' in the company store
Sample output:
{
"PrimaryPresentationId": "d65755be-17bb-4c83-a261-bab073f65308",
"Presentations": [
{
"Id": "24f01fe1-3a3b-4f54-874c-57b2385e08c9",
"Name": "Time chart"
},
{
"Id": "d65755be-17bb-4c83-a261-bab073f65308",
"IsPrimary": true,
"Name": "CPI"
},
{
"Id": "e3fb5084-e1a5-4afc-91dc-910358973692",
"Name": "Core CPI"
}
]
}
searchfiles
The 'searchfiles' returns list of files containing given search-string, located in specified directory and its direct and indirect sub-folders. Output is in JSON format.
searchfiles?path={path}&query={query}&ext={ext}&fields={fields}&skipThumbnails=true
| {path} | The path within Macrobond storage. This is typically obtained from a listdir call. This parameter is obligatory. |
| {ext}
|
Defines what file types should be returned. A list of comma separated values can be specified. This parameter is obligatory. |
| {query} | Text-search phrase. Only files containing it will be returned. Pass % symbol to match any files. This parameter is obligatory. |
| {fields} | List of comma-separated fields to be matched. Allowed values: FileName, Title, Keywords, Regions, Comment, SeriesNames, SeriesPrimaryNames. |
| { skipThumbnails} | Defines weather the response should contain base64 encoded thumbnails of the documents. Possible values: true, false. Default: false |
the fields, skipThumbnails parameters are optional.
Example:
To get list of all files located directly under Company Account call
http://localhost:8088/chartserver/searchfiles?path=macrobond://remotepublicfilestore/common/filestore/&skipThumbnails=true&ext=.mbnd&query=%