team_reports.stone

namespace team

import common

alias NumberPerDay = List(UInt64?)

union TeamReportFailureReason
    temporary_error
        "We couldn't create the report, but we think this was a fluke. Everything should work if you try it again."
    many_reports_at_once
        "Too many other reports are being created right now. Try creating this report again once the others finish."
    too_much_data
        "We couldn't create the report. Try creating the report again with less data."

    example default
        many_reports_at_once = null


struct DateRange
    "Input arguments that can be provided for most reports."
    start_date common.Date?
        "Optional starting date (inclusive). If start_date is None or too long ago, this field will
         be set to 6 months ago."
    end_date common.Date?
        "Optional ending date (exclusive)."

union DateRangeError
    "Errors that can originate from problems in input arguments to reports."

struct StorageBucket
    "Describes the number of users in a specific storage bucket."
    bucket String
        "The name of the storage bucket.
        For example, '1G' is a bucket of users with storage size up to 1 Giga."
    users UInt64
        "The number of people whose storage is in the range of this storage bucket."

    example default
        bucket = "1G"
        users = 21


struct BaseDfbReport
    "Base report structure."
    start_date String
        "First date present in the results as 'YYYY-MM-DD' or None."

#
# get_storage
#

struct GetStorageReport extends BaseDfbReport
    "Storage Report Result.
    Each of the items in the storage report is an array of values, one value per day.
    If there is no data for a day, then the value will be None."

    total_usage NumberPerDay
        "Sum of the shared, unshared, and datastore usages, for each day."
    shared_usage NumberPerDay
        "Array of the combined size (bytes) of team members' shared folders, for each day."
    unshared_usage NumberPerDay
        "Array of the combined size (bytes) of team members' root namespaces, for each day."
    shared_folders NumberPerDay
        "Array of the number of shared folders owned by team members, for each day."
    member_storage_map List(List(StorageBucket))
        "Array of storage summaries of team members' account sizes.
        Each storage summary is an array of key, value pairs, where each pair describes
        a storage bucket.
        The key indicates the upper bound of the bucket and the value is the
        number of users in that bucket. There is one such summary per day.
        If there is no data for a day, the storage summary will be empty."

route reports/get_storage(DateRange, GetStorageReport, DateRangeError) deprecated
    "Retrieves reporting data about a team's storage usage."
    attrs
        auth = "team"
        scope = "team_info.read"

#
# get_activity
#

struct GetActivityReport extends BaseDfbReport
    "Activity Report Result.
    Each of the items in the storage report is an array of values, one value per day.
    If there is no data for a day, then the value will be None."

    adds NumberPerDay
        "Array of total number of adds by team members."
    edits NumberPerDay
        "Array of number of edits by team members.
        If the same user edits the same file multiple times this is counted as a single edit."
    deletes NumberPerDay
        "Array of total number of deletes by team members."
    active_users_28_day NumberPerDay
        "Array of the number of users who have been active in the last 28 days."
    active_users_7_day NumberPerDay
        "Array of the number of users who have been active in the last week."
    active_users_1_day NumberPerDay
        "Array of the number of users who have been active in the last day."
    active_shared_folders_28_day NumberPerDay
        "Array of the number of shared folders with some activity in the last 28 days."
    active_shared_folders_7_day NumberPerDay
        "Array of the number of shared folders with some activity in the last week."
    active_shared_folders_1_day NumberPerDay
        "Array of the number of shared folders with some activity in the last day."
    shared_links_created NumberPerDay
        "Array of the number of shared links created."
    shared_links_viewed_by_team NumberPerDay
        "Array of the number of views by team users to shared links created by the team."
    shared_links_viewed_by_outside_user NumberPerDay
        "Array of the number of views by users outside of the team to shared links created by the team."
    shared_links_viewed_by_not_logged_in NumberPerDay
        "Array of the number of views by non-logged-in users to shared links created by the team."
    shared_links_viewed_total NumberPerDay
        "Array of the total number of views to shared links created by the team."

route reports/get_activity(DateRange, GetActivityReport, DateRangeError) deprecated
    "Retrieves reporting data about a team's user activity."
    attrs
        auth = "team"
        scope = "team_info.read"

#
# get_membership
#

struct GetMembershipReport extends BaseDfbReport
    "Membership Report Result.
    Each of the items in the storage report is an array of values, one value per day.
    If there is no data for a day, then the value will be None."

    team_size NumberPerDay
        "Team size, for each day."
    pending_invites NumberPerDay
        "The number of pending invites to the team, for each day."
    members_joined NumberPerDay
        "The number of members that joined the team, for each day."
    suspended_members NumberPerDay
        "The number of suspended team members, for each day."
    licenses NumberPerDay
        "The total number of licenses the team has, for each day."



route reports/get_membership(DateRange, GetMembershipReport, DateRangeError) deprecated
    "Retrieves reporting data about a team's membership."
    attrs
        auth = "team"
        scope = "team_info.read"

#
# get_devices
#


struct DevicesActive
    "Each of the items is an array of values, one value per day.
    The value is the number of devices active within a time window, ending with that day.

    If there is no data for a day, then the value will be None."

    windows NumberPerDay
        "Array of number of linked windows (desktop) clients with activity."
    macos NumberPerDay
        "Array of number of linked mac (desktop) clients with activity."
    linux NumberPerDay
        "Array of number of linked linus (desktop) clients with activity."
    ios NumberPerDay
        "Array of number of linked ios devices with activity."
    android NumberPerDay
        "Array of number of linked android devices with activity."
    other NumberPerDay
        "Array of number of other linked devices (blackberry, windows phone, etc)
         with activity."
    total NumberPerDay
        "Array of total number of linked clients with activity."

struct GetDevicesReport extends BaseDfbReport
    "Devices Report Result. Contains subsections for different time ranges of activity.
    Each of the items in each subsection of the storage report is an array of values,
    one value per day.
    If there is no data for a day, then the value will be None."

    active_1_day DevicesActive
        "Report of the number of devices active in the last day."
    active_7_day DevicesActive
        "Report of the number of devices active in the last 7 days."
    active_28_day DevicesActive
        "Report of the number of devices active in the last 28 days."


route reports/get_devices(DateRange, GetDevicesReport, DateRangeError) deprecated
    "Retrieves reporting data about a team's linked devices."
    attrs
        auth = "team"
        scope = "team_info.read"