Cinnamon - Data availability, quality & security

Key Principles

Similar principles as with the other APIs are relevant here.

Interface "PortfolioAvailablity"

Status	SPECIFIED
Usage & Contents	This interface delivers the current data availabiliy for all portfolios The usage is mainly to feed the Scheduler Service to automatically schedule reports when data get's available
Path	/portfolio/availability
Parameters	portfolioId (optional)	string	The id of the portfolio (or consolidation) in the data source
Example call	/portfolio/availability
Response structure	If the API can fulfill the request (response status code 200 = OK) the response must follow the below json-schema. 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 Schema { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://vcaire.ch/PortfolioAvailability.schema.json", "title": "Portfolio availability", "description": "Portfolio availability", "type": "object", "properties": { "request": { "$ref": "#/definitions/request" }, "availability": { "type": "array", "items": {"$ref": "#/definitions/portfolioAvailabilities"} } }, "required": ["request", "availability"], "definitions": { "request": { "type": "object", "properties": { "path": { "const": "/portfolio/availability" } }, "required": [ "path" ] }, "portfolioAvailabilities": { "type": "object", "properties": { "portfolioId": {"type": "string"}, "unpublished": { "$ref": "#/definitions/availability" }, "eventDriven": { "$ref": "#/definitions/availability" }, "signedOff": { "$ref": "#/definitions/availability" } }, "required": [ "portfolioId" ] }, "availability": { "type": "object", "properties": { "availabilityDate": {"type": "string", "format": "date"}, "quality": {"type": "string", "enum": ["no-errors", "Minor", "Major", "Critical", "Blocker", "Fatal"] } }, "required": [ "availabilityDate" ] } } }
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 etc. The body of the response should contain information about the reason of the error in plain text or as json object.
Consistency Rules	The following rules should be adhered to by any response and will eventually be checked when consuming a response: Consistency Rules * all portfolios available should be listed * the list of qualities should not include duplicates
Reporting Business Logic	Report scheduling logic (given orders, portfolios availability and existing executions)
Potential Problems	as only the newest date of availability for any quality is given, it can happen that the scheduler misses a past date where availability has also changed.

Interface "PortfolioQuality"

	SPECIFIED
Usage & Contents	This interface delivers the data quality of a single portfolio The usage is mainly to document the data issues for a portfolio with quality status "issues"
Path	/portfolio/quality
Parameters	portfolioId	string	The id of the portfolio (or consolidation) in the data source
Parameters	reportingDate	string (date)	The date, the reporing is produced for.
Example call	/portfolio/quality?portfolioId=E0002&reportingDate=2019-03-31
Response structure	If the API can fulfill the request (response status code 200 = OK) the response must follow the below json-schema. 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 Schema { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://vcaire.ch/PortfolioQuality.schema.json", "title": "Portfolio data quality", "description": "Portfolio data quality", "type": "object", "properties": { "request": { "$ref": "#/definitions/request" }, "riskstatus": { "type": "array", "items": { "$ref": "#/definitions/quality" }} }, "required": [ "request", "quality" ], "definitions": { "request": { "type": "object", "properties": { "path": { "const": "/portfolio/quality" }, "parameters": { "type": "object", "properties": { "portfolioId": { "type": "string" }, "reportingDate": { "type": "string", "format": "date" } }, "required": [ "portfolioId", "reportingDate" ], "additionalProperties": false } }, "required": [ "path", "parameters" ] }, "quality": { "type": "object", "properties": { "id": { "type": "string" }, "entity": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "description" ], "additionalProperties": true } } }
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 etc. The body of the response should contain information about the reason of the error in plain text or as json object.
Consistency Rules	The following rules should be adhered to by any response and will eventually be checked when consuming a response: Consistency Rules * id should be unique
Reporting Business Logic	None
Potential Problems

Interface "PortfolioByLocation"

Status	SPECIFIED
Usage & Contents	This interface delivers all portfolios of a location The usage is mainly to feed the Data Scope Service where the lists are tailored to represent a users data scope
Path	/portfolio/bylocation
Parameters	location	string	The id of the location GLOBAL (this location will deliver all the portfolios) CSCH CSSG CSHK CSIT
Example call	/portfolios?location=CSCH
Response structure	If the API can fulfill the request (response status code 200 = OK) the response must follow the below json-schema. 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 Schema { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://vcaire.ch/PortfolioByLocation.schema.json", "title": "Portfolios by Location", "description": "Portfolios by location", "type": "object", "properties": { "request": { "$ref": "#/definitions/request" }, "portfolios": { "$ref": "#/definitions/portfolios" } }, "required": ["request", "portfolios"], "definitions": { "request": { "type": "object", "properties": { "path": { "const": "/portfolio/bylocation" }, "parameters": { "type": "object", "location": { "type": "string" }, "required": [ "location" ] } }, "required": [ "path", "parameters" ] }, "portfolios": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } } }
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 locationId not found → 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.
Consistency Rules	The following rules should be adhered to by any response and will eventually be checked when consuming a response: Consistency Rules * Every portfolioId is a valid portfolio (e.g. returns data for /portfolio/masterdata) * The list of portfolios is a set (no duplicates)
Reporting Business Logic	Data scope calculation
Potential Problems

Interface "UserPortfolioRoles"

Status	SPECIFIED
Usage & Contents	This interface delivers all portfolio roles for a given user (e.g. if he is PM or CPM) The usage is mainly to feed the Data Scope Service tailor portfolio access
Path	/user/portfolioroles
Parameters	userId	string	The id of the user: example bmpi: marcus.braendle example CSAM: F883476
Example call	/user/portfolioroles?userId=marcus.braendle
Response structure	If the API can fulfill the request (response status code 200 = OK) the response must follow the below json-schema. 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 Schema { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://vcaire.ch/UserPortfolioRoles.schema.json", "title": "User portfolio roles ", "description": "User portfolio roles", "type": "object", "properties": { "request": { "$ref": "#/definitions/request" }, "portfolioroles": { "type": "array", "items": { "$ref": "#/definitions/portfolioroles" }} }, "required": ["request", "portfolioroles"], "definitions": { "request": { "type": "object", "properties": { "path": { "const": "/user/portfolioroles" }, "parameters": { "type": "object", "properties": { "userId": { "type": "string" } }, "required": [ "userId" ] } }, "required": [ "path", "parameters" ] }, "portfolioroles": { "type": "object", "properties": { "portfolioId": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } } } } }
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 userId not found → 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.
Consistency Rules	The following rules should be adhered to by any response and will eventually be checked when consuming a response: Consistency Rules * Every portfolioId is a valid portfolio (e.g. returns data for /portfolio/masterdata) * portfolioIds are unique within the response (no duplicates)
Reporting Business Logic	Data scope calculation
Potential Problems