API Documentation
Toggle TOC panel
<access-service>/api/v1/organisations/{orgGroupId}/statistics/plans

URL structure

1 https://access-service.xy-company.com/api/v1/organisations/{orgGroupId}/statistics/plans

where {orgGroupId} is the ID of an organization.

Supported methods and overview

  • GET - retrieves a summary of information about all plans within an organization (specified by orgGroupId) and Covata users with the Originator role which have been assigned to each plan.

Detailed description

This API endpoint retrieves a summary of information about all plans within an organization (specified by orgGroupId) and Covata users with the Originator role which have been assigned to each plan.

All current plans within an organization (see <access-service>/api/v1/organisations/{orgGroupId}/plans for more information) are returned in the response to this API endpoint.

Supported roles and conditions

This API endpoint supports the following Covata user roles (as described in the Organization Administrator's Guide):

  • Organization administrator - when this user is a member of the organization whose ID is specified by {orgGroupId} in the request's URL.

The Covata Platform's resources available to one of these Covata users (above) is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

  • Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

Optional parameters

The following optional parameters can be sent in the URL of the GET request:

  • limit - A value from 0 to any positive integer, representing the maximum number of items to be returned in the response from the Covata Platform, where an individual item is information about a plan in an organization (specified by orgGroupId). If this parameter is omitted, then its value is 0 by default, which imposes no limit on the number of items returned.
  • offset - A value representing the count order of all retrievable items (i.e. organization plan information) from the Covata Platform returned in the response. Calls to this API endpoint could amount to potentially unmanagable numbers of items being returned from the Covata Platform. Since the order of these items in the response could differ significantly, based on the values of the orderBy and sortBy parameters below, this offset parameter provides pagination for items returned in responses, allowing items to be retrieved from any count greater than 0 (i.e. the first item returned in a response). If this parameter is omitted, then its value is 0 by default.
  • orderBy - An enumeration (enum) value representing the order in which items (organization plan information) are returned in the response. This parameter orders items according to the value of the sortBy parameter specified below. Ordering items can be in either ascending alphanumeric order (by specifying the value ASC for this parameter) or descending order (by specifying the value DESC). If this parameter is omitted, then its value is ASC by default.
  • sortBy - An enum value representing the field (i.e. member) of a retrieved item by which items (i.e. an organization's plans) returned in the response will be sorted. Valid field values for this parameter include:
    • name - the plan's name,
    • description - the description of the plan's quota and
    • quota - the amount of the plan's quota.
    These enum values can also be specified using uppercase characters. If this parameter is omitted, then its value is name by default.
    Example (GET request - retrieving information about all configured plans in an organization on the Covata Platform sorted alphabetically by name):
    1 https://access-service.xy-company.com/api/v1/organisations/749418071827214336/statistics/plans?sortBy=name&orderBy=ASC

Note:

  • Calling this method without any parameters retrieves a list of all plans configured for the organization (specified by orgGroupId).
  • A bug currently exists, which prevents orderBy and sortBy from having any effect on the output. This bug will be addressed in a future Covata Platform version. Therefore, for the time being, these parameters can be omitted from requests to this endpoint.

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful requests only, a JSON-formatted response containing the following members is also returned:

  • item - An array containing information about each existing plan configured for this organization (specified by {orgGroupId} in the request's URL). Each element of this array contains information about one of these plans and is represented as an object, containing the following members:
    • id - The ID of the plan.
    • name - The name of the plan.
    • quota - The plan's quota (in mebibytes/MiB).
    • originatorsCount - The number of Covata users with the Originator role (in this organization) who have been assigned this plan.
    • percentageOfAllOriginators - The percentage of all users with the Originator role (in this organization) who have been assigned this plan.
    • unusedPlanQuotaOriginatorsCount - The number of users who have been assigned this plan but have not used any storage allocated by this plan's quota.
    • usedPlanQuotaOriginatorsCount - The number of users who have been assigned this plan and have used storage allocated by this plan's quota.
    • exceededPlanQuotaOriginatorsCount - The number of users who have been assigned this plan but have exceeded the plan's quota.
  • count - The maximum number of items (i.e. plans) that can be returned in the response.
  • offset - The value of the offset which had been used in the request to this endpoint.
    Example (response):
    {
    "items": [{
    "id": "756753535244587008",
    "name": "Temporary Staff Originators",
    "quota": "4096",
    "originatorsCount": 0,
    "percentageOfAllOriginators": 0.0,
    "unusedPlanQuotaOriginatorsCount": 0,
    "usedPlanQuotaOriginatorsCount": 0,
    "exceededPlanQuotaOriginatorsCount": 0
    }, {
    "id": "749419742544326656",
    "name": "Staff Originators",
    "quota": "10240",
    "originatorsCount": 1,
    "percentageOfAllOriginators": 100.0,
    "unusedPlanQuotaOriginatorsCount": 0,
    "usedPlanQuotaOriginatorsCount": 1,
    "exceededPlanQuotaOriginatorsCount": 0
    }],
    "count": "2",
    "offset": "0"
    }