Introduction

Aimed at reporting specialists, this page introduces concepts that can be used to utilize the full extent of Cinnamon’s parameters. This can be achieved by directly editing the JSON used internally to represent a report order.

Advanced mode

Introduction

The page https://bmpi.atlassian.net/wiki/pages/resumedraft.action?draftId=2796781569 covers the knowledge needed to set up the majority of orders. Expanding on that, this page teaches reporting specialists to fully take advantage of Cinnamon’s customizability by directly modifying the JSON representation of a report order.

Working with JSON in Report Orders

Usage of JSON format

Internally orders are represented in JSON format. The advanced mode and some specific parameters in default mode allow you to directly set parameters as JSON. The editor for this provides several features to help with the editing process. For example:

• Mismatched brackets, commas etc. are highlighted.

• Alt+Shift+F automatically formats the order.

• Extended search functionality. Click on the editor field to make sure it is focused. Then, press CTRL+F

• to make the search appear at the top

Additional parameters

Parameters*

When using starred parameters in a batch order (e.g. portfolioId*, reportLanguage*), the result is a cross product of all values for those parameters. However, you may only want some of those combinations. To allow this, parameters* contains sets of parameters, rather than single values. Each of those parameter sets is treated like a single starred parameter. As an example, consider fund factsheets for a specific share class. Here, you may want to hide a particular section for retail clients but not for professional investors. Using parameters*, you can set this hide parameter to true only for retail clients. If a value is set under parameters*, the advanced mode has a corresponding property parameters*. It is also possible to directly insert this property parameters* in advanced mode.

Batch Orders in Depth

In the JSON in the advanced mode, some properties in an order can be “starred“, i.e. postfixed with *. This is equivalent to selecting multiple values for a property in default mode. These are the properties that cause the batch orders to yield multiple reports. In most cases this can easily be set up using the default mode, for example when creating the same report for multiple portfolioIDs and languages. If a more detailed configuration is required, parameters* can be used. Parameters* contains an array of JSON objects:

Default mode

Advanced mode

• right of the editor field. There, you can not only make a simple search, but limit the search to match full words only, consider casing or even do a “regular expression” search.

If the order JSON is modified in a way that makes it invalid, e.g. by having mismatched brackets, Cinnamon will prevent you from saving the order.

Advanced mode

The advanced mode shows the full JSON representation of the order, and lets you edit it directly. It can be used both in the Ad Hoc ordering and Order Management UIs. To enter the advanced mode, click the tab advanced mode at the top in either of those screens. To exit, click on the tab default view. Any changes made in the advanced mode are immediately reflected in the default view and vice versa.

Below is the same order twice, once viewed using the default mode and once using the advanced mode:

Image Added

Image Added

Additional parameters

The setting “Additional parameters”, found in the default mode under Additional Settings > Other Customizations,contains a JSON of parameters that otherwise have no input field in the UI. This allows you to set arbitrary parameters. It is available both in the Ad Hoc and Report Order Management UIs. In the advanced mode, the parameters inserted using this setting can be found under parameters alongside the parameters that can be set in the UI. Conversely, if such an arbitrary parameter is added to parameters in the advanced mode, it will show up under Additional Parameters in default mode.

Parameters*

When using starred parameters in a batch order (e.g. portfolioId*, reportLanguage*), the result is a cross product of all values for those parameters. However, you may only want some of those combinations. To allow this, parameters* contains sets of parameters, rather than single values. Each of those parameter sets is treated like a single starred parameter. As an example, consider fund factsheets for a specific share class. Here, you may want to hide a particular section for retail clients but not for professional investors. Using parameters*, you can set this hide parameter to true only for retail clients. If a value is set under parameters*, the advanced mode has a corresponding property parameters*. It is also possible to directly insert this property parameters* in advanced mode.

As this is a setting specifically for batch orders, it is only available in the Report Order Management UI and when editing batch orders.

Image Added

Batch Orders in Depth

When editing batch orders, some properties in an order JSON can be “starred“, i.e. postfixed with *. This is equivalent to selecting multiple values for a property in default mode. These are the properties that cause the batch orders to yield multiple reports. In most cases this can easily be set up using the default mode, for example when creating the same report for multiple portfolioIDs and languages. If a more detailed configuration is required, parameters* can be used. Parameters* contains an array of JSON objects:

Parameters* (In Default Mode)	Advanced Mode
Code Block language json [ { "portfolioId": "2041", "showTWR": false }, { "portfolioId": "2044", "showTWR": true }, { "portfolioId": "

2041

2090", "showTWR":

false

true } ]

Code Block language json { "reportType": "sample_FOC_Report",

{

"outputFormat": "word",

"

portfolioId

orderType": "

2044

manual",

"

showTWR

parameters":

true

{

}, {

"

portfolioId

reportLanguage*":

"2090",

["en","de"], "

showTWR

reportingDate":

true

"2020-11-30" }

] Code Block

language	json

, "parameters*"

: [ { "portfolioId": "2041", "showTWR": false }, { "portfolioId": "2044", "showTWR": true }, { "portfolioId": "2090", "showTWR": true } ], "orderStatus": "active" }

There are three simple rules for batch orders: 

1. Any property name ending in a star * is an array which implies multiple (sub-)orders, with the (star-less) property iterated over its elements.

2. If both "parameters" and "parameters*" are present, each element of "parameters*" produces one orders with "parameters" merged in (or multiple ones, if sub-parameters are also starred) .

3. The orders and executions created correspond to the cross product of all properties ending in a star.

Examples: Different Kinds of Orders

Note: Since both parameters* and additional parameters are reflected in the advanced mode view, examples on this page are based on the advanced mode unless otherwise specified.

Ad hoc vs. stored orders

	Ad Hoc Order	Stored Order
Example	Code Block language json { "reportType": "sample_TwoPager", "outputFormat": "pdf", "parameters":{ "portfolioId": "E0002", "reportingDate": "2019-03-31", "reportLanguage": "en" } }	Code Block language json { "reportType": "sample_TwoPager", "outputFormat": "pdf", "orderType": "scheduled", "scheduling": { "availabilities": [ {"availability": "eventDriven"} ], "frequency": "monthly", "startDate": "2018-01-01" }, "parameters": { "reportLanguage*": ["de", "en"], "portfolioId*": ["E0002", "E0001"] }, "orderStatus": "active", "orderName": "E0002 monthly two pager EN" }
Created in	Ad Hoc Order UI	Report Order Management
Triggered by	User	User or automatically

Manual vs. Automatic Scheduling vs. Once

	Manual	Automatic	Once
Example	Code Block language json { "reportType": "sample_TwoPager", "outputFormat": "pdf", "orderType": "manual", "parameters": { "reportLanguage": "en", "portfolioId": "E0002" }, "orderStatus": "active", "orderName": "E0002 monthly two pager EN" }	Code Block language json { "reportType": "sample_TwoPager", "outputFormat": "pdf", "orderType": "scheduled", "scheduling": { "availabilities": [ {"availability": "eventDriven"} ], "frequency": "monthly", "startDate": "2018-01-01" }, "parameters": { "reportLanguage": "en", "portfolioId": "E0002" }, "orderStatus": "active", "orderName": "E0002 monthly two pager EN" }	Code Block language json { "reportType": "sample_TwoPager", "outputFormat": "pdf", "orderType": "scheduled", "scheduling": { "frequency": "daily", "startDate": "2018-01-01", "endDate": "2018-01-01" }, "parameters": { "reportLanguage": "en", "portfolioId": "E0002" }, "orderStatus": "active", "orderName": "E0002 monthly two pager EN" }
Created in	Report Order Management	Report Order Management	Report Order Management
Triggered by	User	Automatically when data of sufficient quality is available	Automatically on the requested date

Batch vs. Non-Batch

	Batch	Non-Batch
Example	Code Block language json { "reportType": "sample_TwoPager", "outputFormat": "pdf", "orderType": "scheduled", "scheduling": { "availabilities": [ {"availability": "eventDriven"} ], "frequency": "monthly", "startDate": "2018-01-01" }, "parameters": { "reportLanguage*": ["de", "en"], "portfolioId*": ["E0002", "E0001"] }, "orderStatus": "active", "orderName": "E0002 monthly two pager EN" } This order results in 4 reports; one for both portfolios in either language.	Code Block language json { "reportType": "sample_TwoPager", "outputFormat": "pdf", "orderType": "scheduled", "scheduling": { "availabilities": [ {"availability": "eventDriven"} ], "frequency": "monthly", "startDate": "2018-01-01" }, "parameters": { "reportLanguage": "en", "portfolioId": "E0002" }, "orderStatus": "active", "orderName": "E0002 monthly two pager EN" }
Created in	Report Order Management	Report Order Management
Triggered by	User or automatically	User or automatically

Examples: Configuring Batch Orders

Different parameters for each execution with parameters*

The below example creates six executions, with different parameters for each portfolio:

Use Case Fund Reporting: Create reports for one portfolio for multiple countries with the same order

The following order creates 3 x 3 executions with "jurisdiction" set to "ch", "eu" and "ru". (Hint: the parameter reportLanguage* is not to be confused with the multi-lingual reporting feature using availableLanguages)

{
  "reportType": "sample_FundFactSheet",
  "outputFormat": "html",
  "orderType": "manual",
  "parameters": {
    "reportLanguage*": ["en","de","fr"],
    "portfolioId": "F0001",
    "reportingDate": "2020-11-30",
    "jurisdiction*": ["ch", "eu", "ru"]
  },
  "orderStatus": "active"
}

Starring segmentations

• properties of object-type parameters (e.g. filterSegmentation.segments) can’t be used with a *

• non-atomic parameters (object or array, e.g. segmentations) can be used with *

{
  "reportType*": [ "fullReport", "shortReport" ],
  "outputFormat*": [ "pdf", "html" ],
  "orderType": "manual",
  "parameters": {
      "reportLanguage*": ["en","de"],
      "reportingDate": "2020-11-30",
      "filterSegmentation": {
        "id": "gugus",
        "segments": [],
        ""
      },
      "segmentations*": [
        [ "seg1", "seg2" ],
        [ "seg2", "seg3" ]
      ]
  },
  "orderStatus": "active",
  "orderId": "ORD00003"
}

Reference: Order Properties

These properties configure the general report order.

Order Level Parameters

These generic parameters configure the report to be produced. These core parameters are available for all versions of Cinnamon. More parameters are available depending on the Cinnamon solution used.

Scheduling Parameters

[
  {"availability": "eventDriven"},
  {"availability": "signedOff"}
]