Page Comparison

...

Table of Contents

maxLevel	2

Key Principles

Similar principles as with the other APIs are relevant here.

Interface "PortfolioAvailablity"

...

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)

stringThe id of the portfolio (or consolidation) in the data sourceExample 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.

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

Code Block

language	js
title	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.

Reporting Business Logic

Report scheduling logic (given orders, portfolios availability and existing executions)

Consistency Rules

The following rules should be adhered to by any response and will eventually be checked when consuming a response:

Consistency Rules

Code Block

language	js

titleConsistency 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"

StatuscolourGreentitleSpecified

Path

/portfolio/availability

Parameters

portfolioId (optional)

string

The id of the portfolio (or consolidation) in the data source

Example call

/portfolio/availability

Schema

Status

title	on request

Example

Status

title	on request

Interface "PortfolioQuality"

Status

colour	Green
title	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"
Reporting Business Logic	None
Consistency Rules	The following rules should be adhered to by any response and will eventually be checked when consuming a response: id should be unique
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.

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

Code Block

language	js
title	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:

Code Block

language	js
title	Consistency Rules

* id should be unique

Reporting Business Logic

None

Potential Problems

Interface "PortfolioByLocation"

Schema

Status

title	on request

Example

Status

title	on request

Interface "PortfolioByLocation"

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.

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

Code Block

language	js
theme	Confluence
title	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.

Reporting Business Logic

Data scope calculation

Consistency Rules

The following rules should be adhered to by any response and will eventually be checked when consuming a response:

Consistency Rules

Code Block

language	js

title

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 StatuscolourGreentitleSpecified

Path

/portfolio/bylocation

Parameters

location

string

The id of the location

GLOBAL (this location will deliver all the portfolios)
CH
SG
etc.

Example call

/portfolios?location=CH

Schema

Status

title	on request

Example

Status

title	on request

Interface "UserPortfolioRoles"

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.

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

Code Block

language	js
title	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.

Reporting Business Logic

Data scope calculation

Consistency Rules

The following rules should be adhered to by any response and will eventually be checked when consuming a response:

Consistency Rules

Code Block

language	js

titleConsistency 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

Path

/user/portfolioroles

Parameters

userId

string

The id of the user:

example bmpi: marcus.braendle
example CSAM: F883476

Example call

/user/portfolioroles?userId=james.bond

Schema

Status

title	on request

Example

Status

title	on request

Versions Compared

Old Version 1

New Version Current

Key

Key Principles

Interface "PortfolioAvailablity"

Consistency Rules

Interface "PortfolioQuality"

Interface "PortfolioQuality"

Interface "PortfolioByLocation"

Interface "PortfolioByLocation"

Consistency Rules

Interface "UserPortfolioRoles"

Interface "UserPortfolioRoles"

Consistency Rules