Versions Compared

Old Version 1

changes.mady.by.user Marcus Brändle

Saved on

compared with

New Version 2

changes.mady.by.user Marcus Brändle

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
maxLevel2

...

Status
Status
colourGreen
titleSpecified
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 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.

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
languagejs
titleJson 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:

Code Block
languagejs
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.

...


Status
colourGreen
titleSpecified
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

stringThe id of the portfolio (or consolidation) in the data source
reportingDatestring (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
languagejs
titleJson 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
languagejs
titleConsistency Rules
* id should be unique


Reporting Business Logic
  • None
Potential Problems

...

Status
Status
colourGreen
titleSpecified
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
languagejs
themeConfluence
titleJson 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:

Code Block
languagejs
titleConsistency 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

...

Status
Status
colourGreen
titleSpecified
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
languagejs
titleJson 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:

Code Block
languagejs
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

...