Skip to main content
Skip table of contents

Cinnamon Reporting Data Interface (Version 1)

This page tree gives an overview about Cinnamon’s (current) interface for data consumption

The following data interfaces are proposed to allow for the production of full-fledged fund and mandate reports.

Interfaces Overview

Interface

Usage

PortfolioMasterData

To control the contents of a mandate report, several master data points are needed (valid at the given reporting data):

  • client / portfolio / pm name

  • mandate / performance start dates

  • benchmark / strategy definition

  • etc.

PortfolioFundData

  • Additional master data for funds (e.g. sales registrations, shareclasses, cost transparency, etc.)

PortfolioValuation

Interface to deliver portfolio valuation data (valid at the reporting date) to produce:

  • asset allocation breakdowns along several segmentations

  • position lists (full, top-n) with details like CUSIP, ISIN, Valor, Instrument Name etc. 

BenchmarkValuation

Interface to deliver benchmark valuation data (valid at the reporting date) to produce:

  • asset allocation breakdowns along several segmentations

  • comparison of portfolio weights to benchmark weights 

PortfolioReturns

One or multiple interfaces to deliver performance / return data:

  • for a given period

  • for the portfolio as well as the associated / chosen benchmark

  • on portfolio level vs. on segment / instrument level

InstrumentReturns

Returns for a list of instruments and for a given period

PortfolioAttributions

Interfaces that return data about the source and decomposition of performance.

PortfolioRiskExPost

Ex post risk figures

PortfolioRiskExAnte

Interface that return data about the ex-ante risk and risk decomposition of the portfolio.

PortfolioRiskStatus

  • the portfolios current risk status (CSAM specific calculation based on past returns)

PortfolioProfitLoss

P&L figures on portfolio level

PortfolioTransactions

List of transactions

PortfolioProjectedCashflows

Projected Cashflows

PortfolioGuidelineAnalysis

  • information about guideline checking (BVV2, investment restrictions) etc.

Segmentations

Interface to fetch all base segmentations from the DWH

Data availability, quality & security

Interfaces to support a data-driven report production and allow transparency of data quality within reports, e.g.

  • get list of portfolios with their last status per quality level (unpublished vs. signed-off)

  • get lists of portfolios to be authorised for local reporting specialists (e.g. SG-based)


Technological Aspects

Aspect

Discussion

Structured Files

  • Cinnamon ideally consumes structured files (Json or XML) instead of flat files (csv)

  • Wherever adding to the understandability of data, structuring should be used

  • Examples are

    • Flexible number of breakdown segments should not be deliverd as normal tags but listed by abstract <segment> tag

    • Flexible numbers of measures

    • Flexible number of legs, unbundling instruments

    • Groups of fields that can be reused between portfolio and benchmark data or between calls

    • etc.

High-level structure

If the API can fulfill the request (response status code 200 = OK) the response must have the following high-level structure and must follow the respective (json-) schema:

JS
{
    "request": { ... },
    "dataVersioning": {...},
    "data": [ ... ]
}
  • The request part of the response has to match the path and parameters used in the API call/request

  • The (json) schema currently excludes the schema for dataVersioning (should be designed by CSAM)

Data format

  • Json is more compact then XML and most easily consumed at reporting engine side (but we can also consume XML)

  • please only use JavaScript compatible identifiers (e.g. no "-")

Data validations

  • Cinnamon will check the response against the agreed schema (e.g. json-schema) as well as do additional data validity checks (e.g. monthly returns should not miss a month within the defined period)

Request & Parameters

  • The full API request is mirrored in the response including:

    • The path

    • All parameters passed

Error handling

If the request can't be fulfilled an appropriate response status code (4xx or 5xx) must be used. Possible errors could be

  • bad request structure → expected status = 400

  • portfolioId not found or reportingDate in future → expected status = 404

  • etc.

The body of the response should contain information about the reason of the error in plain text or as json object.

Network Protocol

  • Cinnamon uses HTTPS / restful API to access the datasource (other protocols on request)

Compression

  • The body of response can be compressed (e.g. gzip)

Paging

  • While many UI-oriented rest-interfaces do paging, we don't propose paging because

    • a batch reporting mechanism can't work without the complete response (some responses like valuations are hierarchical by nature)

    • Cinnamon has proven to work even with large response sizes (~1GB)

Interface Versioning

  • we propose to have only major API versioning in the URL (minor versions should be neutral to clients by definition), e.g. /v1 or /v2

  • we propose to add a /LATEST version for Cinnamon to access the API by a constant URL

Security

  • The Cinnamon server will authenticate itself to the data source by a server certificate (other methods on request)

Data Versioning

  • Additional metadata should be added to the result that uniquely depict the timestamp/version of the data (for data lineage reasons)

  • The report engine will not consider this information in process the data (e.g. business logic)

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.