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

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

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: `{ "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)