# 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.21.12 or newer.

# Requirements

Minimum requirements: 64-bit versions of Windows 7 or, Windows Server 2008 R2, .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

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 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,
},

### 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
}

### Updating from < 1.21.8

The previously used username and hosting configuration can be found in %ProgramFiles(x86)%\Macrobond Financial\Chart Server\Abacus.ChartServer.exe.config. After upgrading and moving the configuration to the new configuration files the %ProgramFiles(x86)%\Macrobond Financial\Chart Server directory can be removed.

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

## 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}
 {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. {bkgcolor} The color of the background which will be visible in case there are any transparent parts of the chart. The format is '#aarrggbb' where 'aa' is the hexadecimal value of the opacity (00 is transparent and 'ff' is opaque), 'rrggbb' are three hexadecimal values for red, green and blue.  If you want to keep transparent parts transparent, specify '#00ffffff'.

#### 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&bkgcolor=%2300ffffff

### 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:BackgroundColor>#FFFFFF</r:BackgroundColor>  <!--  If this element is not specified, use transparent background. -->
<r:AbacusDocument>
<doc:CalculiDocument xmlns:doc="http://schemas.mbnd.eu/2009/calculidocument">
<!-- The Macrobond document specification -->
</doc:CalculiDocument>
</r:AbacusDocument>
</r:RenderSpecification> 

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

#### 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

http://localhost:8088/chartserver/listfiles?path=macrobond://remotepublicfilestore/common/filestore/&ext=.mbnd

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"
}
] 

### 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=%