Cinnamon Reporting Data Interfaces (Version 1)

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

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.

InstrumentReturns

Returns for a list of instruments and for a given period

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)

Json (or XML)

• 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.

Json

• 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 "-")

schema and other checks

• 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)

mirrored in response

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

  • The path

  • All parameters passed

use response status codes

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.

HTTP / restful API

• Standard technology to communicate between services

• could also send XQuery execution but this would bring data hub technical design dependency to the report engine

gzip

• body of reply should be compressed

no 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)

/v1
/v2
/LATEST

• we propose to have only major versioning in the URL (minor versions should be neutral to clients by definition)

• we propose to add a /LATEST version

certificates

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

open

• 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)