Cinnamon Reporting Data Interface (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

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)

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

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)

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

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

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

  • The path

  • All parameters passed

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.

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

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

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

• 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

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

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