StatPro Revolution Web API


The Portfolios Resource


Overview

The Portfolios resource represents the identified user's collection of portfolios. Portfolios in the collection can include those that are owned by the user, and those that are owned by other users and currently shared to the identified user.

Portfolios that have been configured to be alternative settings portfolios and are set to be a reporting component will be excluded from the portfolios collection and are instead accessible through the parent portfolio via a Portfolio Reporting Components resource.

Requests for the Portfolios resource always contain information regarding how the user's portfolios are to be filtered, ordered and sliced before being returned in a response. These instructions may be supplied by the client application (when using a link whose link relation is portfolios-query), or by the service itself when emitting a non-query link (e.g. a link to the next page of portfolios).

The underlying collection is first filtered. The filtered set is then ordered. Finally the ordered set is sliced by skipping N portfolios and taking M portfolios. If not all of the ordered set is returned in a response, and if N is a multiple of M (e.g. skip 8, take 4), then the portfolios in the resource representation are paged. A paged collection will include links to the first and last pages, and optionally to the previous and/or next pages.

If no filtering, ordering and slicing information is contained in a request, then defaults are used:- no filtering; ordered by name; take a maximum of 100 portfolios. Note that the web service imposes a maximum 'take limit' of 100 portfolios for all requests for the resource: it is not possible to retrieve more than 100 portfolios in any one response. If the ordering is unspecified by the request, then the web service will apply its own ordering.

An additional filtering option is provided via an optional query string titled includePublishedPortfolios which can be specified as true to include all portfolios or false to include all portfolios which have been shared with at least view rights.

For more information on filtering, ordering and slicing, refer to the documentation for the portfolios-query link relation.

The resource representation includes the name, unique identifier, code and owner name of each portfolio, as well as links to the portfolio's accessible analyses. Most typically this is the portfolio's default Portfolio Analysis resource. All portfolios will contain a link to the portfolio's default Portfolio Analysis resource if the portfolio has been shared with at least view rights (i.e. if includePublishedPortfolios is not specified or specified as false, the resulting collection of portfolios will all contain a default analysis). If the portfolio has been shared with publish rights, then only the Signed-Off Portfolio Analysis is accessible and only if results have been signed-off in the website. By following the link to a portfolio analysis, a client application is able to get more information about the portfolio, information about its analysis, and (if available) analysis results data.

Some portfolios will optionally include a link to a Compliance Portfolio Analysis resource if they have been activated for Compliance. By activating this link it will be possible to get information about the compliance analysis settings for the portfolio and (if available) access the compliance results data. Portfolios which have had results proposed for sign-off or results previously signed-off will also include links to an Awaiting Sign-Off Portfolio Analysis and/or a Signed-Off Portfolio Analysis. Following these links allows client applications to extract the results data relating to these analyses (if available). If a portfolio is a parent portfolio of some alternative settings portfolios, then an additional link to related Portfolio Reporting Components is made available.

NOTE: It is possible for no analysis links to be made available if a portfolio has only been shared with publish rights and no results have yet been signed off.


Portfolio Accessibility

Whenever a portfolio is accessible to a user then it will be accessible to them with an associated permission level. The following permission levels exist (from lowest to highest permissions):

So as the permission level of a portfolio gets higher, the more analysis types that are accessible through the Portfolios resource.

Portfolios may be visible to the authenticated user for a variety of reasons:

  • They may have created (and thus own) the portfolios and in which case they implicitly have Edit rights to such portfolios.
  • They may have been granted specific permissions via their role within the Revolution website. There are specific permissions that allows users to view and/or edit portfolios within their organization. If the authenticated user is in a role that possesses the permission This role can view all portfolios, benchmarks and classifiers in their organization then they will have View rights of all portfolios within their organization. If their role grants them the permission This role can edit and delete any portfolio, custom benchmark or custom classifier in their organization then they will have Edit rights of all portfolios within their organization.
  • They may have been shared the portfolio either directly or via a business group. In this instance portfolios are explicitly assigned one of the above three permission levels by the proposer of the share.

Media types

The Portfolios resource is exposed via XML and JSON representations, which have the following media type names:-

application/vnd.statpro.revolution.api.portfolios+json

application/vnd.statpro.revolution.api.portfolios+xml

When a response is received from the web service with status 200 (= OK), the fact that the response contains a Portfolios resource representation is indicated by the presence of one of these two response headers:-

Content-Type: application/vnd.statpro.revolution.api.portfolios+json; charset=utf-8

Content-Type: application/vnd.statpro.revolution.api.portfolios+xml; charset=utf-8


Related resources

The Portfolios resource links to the Service, Portfolio Analysis, Compliance Portfolio Analysis, Awaiting Sign-Off Portfolio Analysis, Signed-Off Portfolio Analysis and Portfolio Reporting Components resources. It also links to itself in a variety of different ways. To do so, its resource representations use link relations:-

  • service
  • self
  • first
  • next
  • prev
  • last
  • portfolios-query
  • default-portfolio-analysis
  • compliance-portfolio-analysis
  • awaiting-signoff-portfolio-analysis
  • signedoff-portfolio-analysis
  • portfolio-reporting-components

The service link relation identifies the Service resource link.

The self link relation identifies the Portfolios resource link, in which the representation is the same as the one that has been currently retrieved (so long as the underlying data on the server hasn't changed).

The first and last link relations are present only if the retrieved collection is paged. They identify the first and last pages in the collection (at the time when the resource representation was generated).

The next and prev link relations are present only if the retrieved collection is paged and there is a next page and/or previous page in the collection (at the time when the resource representation was generated).

The portfolios-query link relation identifies the resource link that allows a fresh query for portfolios to be made. The fact that the link relation ends with "-query" indicates that a client-specified query must be made for portfolios, when using this link. This is done by replacing all the text-replacement parts of the link's query string (such as {filter}) with values. Specifying invalid values will result in a 400 (= Bad Request) response. All the text replacement parts of the query string can be replaced with the empty string. To apply filtering, ordering and slicing according to a subset of the ODATA system query options syntax, please refer to the portfolios-query link relation's documentation page.

The default-portfolio-analysis link relation is an optional link that identifies the default Portfolio Analysis resource for a portfolio in the collection. The only time a portfolio will not return this link is if the portfolio has been shared to the user with publish rights from the Revolution websites' sharing screen (See the section on Portfolio Accessibility for further details). The Portfolio Analysis resource contains extra information about a portfolio, contains analysis-specific information, and also affords access to analysis results data (contained in other resources). Note that a portfolio's default portfolio analysis is the main one that is used in the Revolution desktop website.

Each default-portfolio-analysis link's URI contains query string lastSuccessful=false. This tells the web service to return the latest version of the default portfolio analysis, regardless of its status (e.g. it may still be in progress, or it may have failed). A client application may change the value of this query string to true (i.e. lastSuccessful=true) to request the last successful version, if available. The last-successful version will contain analysis results data, whereas the latest version, if still in progress or if failed, will not. For more details please refer to the default-portfolio-analysis link relation's documentation page.

The compliance-portfolio-analysis link relation will only be included if the portfolio has been activated for Compliance. This link identifies the compliance portfolio analysis resource containing information about the settings used for compliance and also provides access to the compliance results. Unlike the default-portfolio-analysis there is only one version of the compliance portfolio analysis that can be retrieved. For further details please refer to the compliance-portfolio-analysis link relation's documentation page.

The awaiting-signoff-portfolio-analysis link relation will only be included if the portfolio has some results that have been proposed for sign-off via the Portfolio Sign-off Dashboard within the Revolution website. It identifies details of the Awaiting Sign-Off Portfolio Analysis resource which contains analysis specific information and allows further access to the results relating to the awaiting sign-off analysis (if available). For further details please refer to the awaiting-signoff-portfolio-analysis link relation's documentation page.

The signoff-portfolio-analysis link relation will only be included if the portfolio has some results that have been previously signed off via the Portfolio Sign-off Dashboard within the Revolution website. It identifies details of the Signed-Off Portfolio Analysis resource which contains analysis specific information and allows further access to the results relating to the signed-off analysis (if available). For further details please refer to the signedoff-portfolio-analysis link relation's documentation page.

The portfolio-reporting-components link relation will only be included if the portfolio is a parent portfolio of one or more child alternative settings portfolios. Following such a link will allow access to the non-paged set of child portfolios and their related analyses (and results if available).

All related resources are accessed using the HTTP GET method.


Update history

  • New optional property called parentPortfolioId for Alternative Settings portfolios indicating the identifier of their parent portfolio - June 2017
  • New optional portfolio properties added for description, inception date, close date and public open date - February 2016
  • Additional portfolio properties for portfolio identifiers, reporting tags, calculation type and calculation context have been added to the resource representation - February 2015
  • awaiting-signoff-portfolio-analysis, signoff-portfolio-analysis and portfolio-reporting-components link relations added - December 2014
  • compliance-portfolio-analysis link relation added - September 2014
  • eula link relation removed - September 2013
  • Initial Version - February 2013

Annotated Representation (JSON)

Legend

{
  "portfolios": {
    "links": {
      "service": {
        "rel": "service",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.service+json"
      },
      "self": {
        "rel": "self",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.portfolios+json"
      },
      "next": {
        "rel": "next",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.portfolios+json"
      },
      "prev": {
        "rel": "prev",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.portfolios+json"
      },
      "first": {
        "rel": "first",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.portfolios+json"
      },
      "last": {
        "rel": "last",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.portfolios+json"
      },
      "portfoliosQuery": {
        "rel": "portfolios-query",
        "href": "...?$filter={filter}&$orderby={orderby}&$skip={skip}&$top={top}&includePublishedPortfolios=false&portfolioClassifierCode=",
        "type": "application/vnd.statpro.revolution.api.portfolios+json"
      }
    },
    "filteredCount": 16,
    "pageNumber": 2,
    "pageCount": 4,
    "items": [
      {
        "name": "Portfolio 5",
        "id": "df5e9afb-7725-40a4-996b-3aa65655675e",
        "code": "P5",
        "owner": "John Smith",
        "calculationType": "Standard",
        "calculationContext": "Daily",
        "shareClassCode": "DEFAULTSHARECLASS",
        "primaryReturnDefinitionId": 1,
        "description": "Portfolio 5 Description",
        "inceptionDate": "2014-09-01",
        "closeDate": "2015-11-30",
        "publicOpeningDate": "2014-10-01",
        "identifiers": {
          "isin": "GB0123456789",
          "characteristic1": "963923",
          "characteristic2": "968377",
          "characteristic3": "CH9643"
        },
        "reportingTag": {
          "group": "Default",
          "name": "TDSL By Country"
        },
        "links": {
          "defaultAnalysis": {
            "rel": "default-portfolio-analysis",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-analysis+json"
          },
          "portfolioShareClasses": {
            "rel": "portfolio-share-classes",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-share-classes+json"
          }
        }
      },
      {
        "name": "Portfolio 6",
        "id": "ae95e6a2-f403-4258-99ec-cf4c7e53fa55",
        "code": "P6",
        "owner": "John Smith",
        "calculationType": "Model",
        "calculationContext": "Daily",
        "shareClassCode": "Capitalized",
        "primaryReturnDefinitionId": 2,
        "identifiers": {
          "isin": "XY0123456789"
        },
        "links": {
          "defaultAnalysis": {
            "rel": "default-portfolio-analysis",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-analysis+json"
          },
          "complianceAnalysis": {
            "rel": "compliance-portfolio-analysis",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.compliance-portfolio-analysis+json"
          },
          "portfolioShareClasses": {
            "rel": "portfolio-share-classes",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-share-classes+json"
          }
        }
      },
      {
        "name": "Portfolio 7",
        "id": "e61f4e42-a6bd-4318-b18c-ba663d8b4fb8",
        "code": "P7",
        "owner": "John Smith",
        "calculationType": "Standard",
        "calculationContext": "Daily",
        "shareClassCode": "Capitalized",
        "primaryReturnDefinitionId": 2,
        "links": {
          "defaultAnalysis": {
            "rel": "default-portfolio-analysis",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-analysis+json"
          },
          "awaitingSignOffAnalysis": {
            "rel": "awaiting-signoff-portfolio-analysis",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.awaiting-signoff-portfolio-analysis+json"
          },
          "signedOffAnalysis": {
            "rel": "signedoff-portfolio-analysis",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.signedoff-portfolio-analysis+json"
          },
          "portfolioReportingComponents": {
            "rel": "portfolio-reporting-components",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-reporting-components+json"
          },
          "portfolioShareClasses": {
            "rel": "portfolio-share-classes",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-share-classes+json"
          }
        }
      },
      {
        "name": "Portfolio 8",
        "id": "19dc95ab-a368-45d9-9220-c87db3ab2d72",
        "code": "P8",
        "owner": "John Smith",
        "calculationType": "AlternativeSettings",
        "calculationContext": "OnDemand",
        "shareClassCode": "Capitalized",
        "primaryReturnDefinitionId": 2,
        "parentPortfolioId": "8598dac5-9375-4036-ac73-b1860e785eb3",
        "links": {
          "defaultAnalysis": {
            "rel": "default-portfolio-analysis",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-analysis+json"
          },
          "portfolioShareClasses": {
            "rel": "portfolio-share-classes",
            "href": "...",
            "type": "application/vnd.statpro.revolution.api.portfolio-share-classes+json"
          }
        }
      }
    ]
  }
}


Annotated Representation (XML)

Legend

<?xml version="1.0" encoding="utf-8"?>
<portfolios xmlns="http://statpro.com/2012/Revolution">
  <link rel="service"
        href="..."
        type="application/vnd.statpro.revolution.api.service+xml" />
  <link rel="self"
        href="..."
        type="application/vnd.statpro.revolution.api.portfolios+xml" />
  <link rel="next"
        href="..."
        type="application/vnd.statpro.revolution.api.portfolios+xml" />
  <link rel="prev"
        href="..."
        type="application/vnd.statpro.revolution.api.portfolios+xml" />
  <link rel="first"
        href="..."
        type="application/vnd.statpro.revolution.api.portfolios+xml" />
  <link rel="last"
        href="..."
        type="application/vnd.statpro.revolution.api.portfolios+xml" />
  <link rel="portfolios-query"
        href="...?$filter={filter}&amp;$orderby={orderby}&amp;$skip={skip}&amp;$top={top}&amp;includePublishedPortfolios=false&amp;portfolioClassifierCode="
        type="application/vnd.statpro.revolution.api.portfolios+xml" />
  <filteredCount>16</filteredCount>
  <pageNumber>2</pageNumber>
  <pageCount>4</pageCount>
  <portfolio>
    <name>Portfolio 5</name>
    <id>df5e9afb-7725-40a4-996b-3aa65655675e</id>
    <code>P5</code>
    <owner>John Smith</owner>
    <calculationType>Standard</calculationType>
    <calculationContext>Daily</calculationContext>
    <shareClassCode>DEFAULTSHARECLASS</shareClassCode>
    <primaryReturnDefinitionId>1</primaryReturnDefinitionId>
    <description>Portfolio 5 Description</description>
    <inceptionDate>2014-09-01</inceptionDate>
    <closeDate>2015-11-30</closeDate>
    <publicOpenDate>2014-10-01</publicOpenDate>
    <identifiers>
      <isin>GB0123456789</isin>
      <characteristic1>963923</characteristic1>
      <characteristic2>968377</characteristic2>
      <characteristic3>CH9643</characteristic3>
    </identifiers>
    <reportingTag>
      <group>Default</group>
      <name>TDSL By Country</name>
    </reportingTag>
    <link rel="default-portfolio-analysis"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-analysis+xml" />
    <link rel="portfolio-share-classes"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-share-classes+xml" />
  </portfolio>
  <portfolio>
    <name>Portfolio 6</name>
    <id>ae95e6a2-f403-4258-99ec-cf4c7e53fa55</id>
    <code>P6</code>
    <owner>John Smith</owner>
    <calculationType>Model</calculationType>
    <calculationContext>Daily</calculationContext>
    <shareClassCode>Capitalized</shareClassCode>
    <primaryReturnDefinitionId>2</primaryReturnDefinitionId>
    <identifiers>
      <isin>XY0123456789</isin>
    </identifiers>
    <link rel="default-portfolio-analysis"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-analysis+xml" />
    <link rel="compliance-portfolio-analysis"
          href="..."
          type="application/vnd.statpro.revolution.api.compliance-portfolio-analysis+xml" />
    <link rel="portfolio-share-classes"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-share-classes+xml" />
  </portfolio>
  <portfolio>
    <name>Portfolio 7</name>
    <id>e61f4e42-a6bd-4318-b18c-ba663d8b4fb8</id>
    <code>P7</code>
    <owner>John Smith</owner>
    <calculationType>Standard</calculationType>
    <calculationContext>Daily</calculationContext>
    <shareClassCode>Capitalized</shareClassCode>
    <primaryReturnDefinitionId>2</primaryReturnDefinitionId>
    <link rel="default-portfolio-analysis"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-analysis+xml" />
    <link rel="awaiting-signoff-portfolio-analysis"
          href="..."
          type="application/vnd.statpro.revolution.api.awaiting-signoff-portfolio-analysis+xml" />
    <link rel="signedoff-portfolio-analysis"
          href="..."
          type="application/vnd.statpro.revolution.api.signedoff-portfolio-analysis+xml" />
    <link rel="portfolio-reporting-components"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-reporting-components+xml" />
    <link rel="portfolio-share-classes"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-share-classes+xml" />
  </portfolio>
  <portfolio>
    <name>Portfolio 8</name>
    <id>19dc95ab-a368-45d9-9220-c87db3ab2d72</id>
    <code>P8</code>
    <owner>John Smith</owner>
    <calculationType>AlternativeSettings</calculationType>
    <calculationContext>OnDemand</calculationContext>
    <shareClassCode>Capitalized</shareClassCode>
    <primaryReturnDefinitionId>2</primaryReturnDefinitionId>
    <parentPortfolioId>8598dac5-9375-4036-ac73-b1860e785eb3</parentPortfolioId>
    <link rel="default-portfolio-analysis"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-analysis+xml" />
    <link rel="portfolio-share-classes"
          href="..."
          type="application/vnd.statpro.revolution.api.portfolio-share-classes+xml" />
  </portfolio>
</portfolios>


Last updated: December 2014


To Top