pathology/orchestrator/v1main/cohorts.proto

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package pathology.orchestrator.v1main;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";
import "pathology/orchestrator/v1main/slides.proto";
import "pathology/orchestrator/v1main/users.proto";

option java_package = "com.pathology.orchestrator.v1main";
option java_outer_classname = "CohortsProto";
option java_multiple_files = true;

// Metadata for a PathologyCohort.
message PathologyCohortMetadata {
  // Cohort name displayed on viewer.
  string display_name = 1 [(google.api.field_behavior) = REQUIRED];

  // Description of cohort.
  optional string description = 2;

  // Current stage of cohort.
  optional PathologyCohortLifecycleStage cohort_stage = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // True if cohort contains de-Identified data.
  optional bool is_deid = 4 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Specifies behavior constraints of cohort.
  optional PathologyCohortBehaviorConstraints cohort_behavior_constraints = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Timestamp of when cohort was last updated.
  optional google.protobuf.Timestamp update_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Defines permissible access for cohort.
  // Modifiable by cohort owners with SharePathologyCohort.
  optional PathologyCohortAccess cohort_access = 7;

  // Timestamp when inactive cohort expires.
  // Only populated if CohortLifecycleStage is suspended.
  optional google.protobuf.Timestamp expire_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Representation of a cohort or collection of slides.
message PathologyCohort {
  option (google.api.resource) = {
    type: "digitalpathology.googleapis.com/PathologyCohort"
    pattern: "pathologyUsers/{pathology_user}/pathologyCohorts/{pathology_cohort}"
  };

  // Resource name. Empty when creating.
  string name = 1 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyCohort"
  ];

  // Metadata for PathologyCohort.
  PathologyCohortMetadata cohort_metadata = 2
      [(google.api.field_behavior) = REQUIRED];

  // List of slides in cohort.
  repeated PathologySlide slides = 3 [(google.api.field_behavior) = OPTIONAL];

  // Users granted access to the cohort.
  // Modifiable by cohort owners with SharePathologyCohort.
  repeated PathologyUserAccess user_access = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Request for CreatePathologyCohort rpc.
message CreatePathologyCohortRequest {
  // Resource name of user that has created the cohort.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "digitalpathology.googleapis.com/PathologyCohort"
    }
  ];

  // Cohort to create.
  PathologyCohort pathology_cohort = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request for DeletePathologyCohort rpc.
message DeletePathologyCohortRequest {
  // Resource name for cohort to be deleted.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyCohort"
  ];

  // Deprecated. Link token to grant privileges.
  // (-- api-linter: core::0135::request-unknown-fields=disabled
  //     aip.dev/not-precedent: The link_token field is used to grant
  //     permissions on shared cohorts. --).
  string link_token = 2 [deprecated = true];
}

// Request for TransferDeIdPathologyCohort rpc.
message TransferDeIdPathologyCohortRequest {
  // Resource name of cohort to be transferred.
  // Ex. pathologyUsers/userId/pathologyCohorts/cohortId
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // DicomWebUrl of destination Dicom store for images.
  string dest_dicom_images = 2 [(google.api.field_behavior) = REQUIRED];

  // Unique display name for transferred cohort.
  string display_name_transferred = 3 [(google.api.field_behavior) = REQUIRED];

  // Description for transferred cohort.
  string description_transferred = 4 [(google.api.field_behavior) = OPTIONAL];

  // Email to receive a notification when export is complete.
  repeated string notification_emails = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Deprecated. SharingLink token to grant permissions.
  string link_token = 6 [deprecated = true];
}

// Response for TransferDeIdPathologyCohort rpc.
message TransferDeIdPathologyCohortResponse {
  // Status of transfer.
  optional google.rpc.Status status = 1;
}

// Deprecated. Request for ExportPathologyCohort rpc.
message ExportPathologyCohortRequest {
  // Resource name of cohort to be exported.
  // Ex. pathologyUsers/userId/pathologyCohorts/cohortId
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Path name of Cloud Storage bucket to export to.
  string gcs_dest_path = 2 [(google.api.field_behavior) = REQUIRED];

  // Email to receive a notification when export is complete.
  repeated string notification_emails = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Deprecated. SharingLink token to grant permissions.
  string link_token = 4 [deprecated = true];
}

// Response for ExportPathologyCohort rpc.
message ExportPathologyCohortResponse {
  // Status of export.
  optional google.rpc.Status status = 1;
}

// Request for GetPathologyCohort.
message GetPathologyCohortRequest {
  // Resource name of cohort to retrieve.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyCohort"
  ];

  // Specifies view of cohort returned.
  PathologyCohortView view = 2 [(google.api.field_behavior) = OPTIONAL];

  // Deprecated. Link token to grant privileges.
  // (-- api-linter: core::0131::request-unknown-fields=disabled
  //     aip.dev/not-precedent: The link_token field is used for accessing
  //     shared cohorts. --).
  string link_token = 3 [deprecated = true];
}

// Request for ListPathologyCohort.
message ListPathologyCohortsRequest {
  // Resource name of user that has created the cohort.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyUser"
  ];

  // Default is 20.
  int32 page_size = 2;

  // A page token, received from a ListPathologyCohorts call.
  string page_token = 3;

  // Specifies view of cohorts returned.
  PathologyCohortView view = 4;

  // Specifies access permission role to fetch cohorts for.
  // Corresponds to PathologyUserAccessRole. Default is owner.
  string filter = 5;
}

// Response for ListPathologyCohort.
message ListPathologyCohortsResponse {
  // Deprecated.
  repeated PathologyCohort owned_pathology_cohorts = 1 [deprecated = true];

  // Deprecated.
  repeated PathologyCohort editable_pathology_cohorts = 2 [deprecated = true];

  // Deprecated.
  repeated PathologyCohort view_only_pathology_cohorts = 3 [deprecated = true];

  // Token to get subsequent page if present.
  string next_page_token = 4;

  // List of pathology cohorts corresponding to request filter.
  repeated PathologyCohort pathology_cohorts = 5;
}

// Request for UpdatePathologyCohort.
// (-- api-linter: core::0134::request-unknown-fields=disabled
//     aip.dev/not-precedent: The link_token field is used for accessing
//     shared cohorts. The view specifies how the cohort will be returned. --).
message UpdatePathologyCohortRequest {
  // Cohort to update.
  PathologyCohort pathology_cohort = 1 [(google.api.field_behavior) = REQUIRED];

  // Specifies view of cohort returned.
  PathologyCohortView view = 2 [(google.api.field_behavior) = OPTIONAL];

  // List of fields to update.
  google.protobuf.FieldMask update_mask = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Deprecated. Link token to grant privileges.
  string link_token = 4 [deprecated = true];
}

// Request for UndeletePathologyCohort.
message UndeletePathologyCohortRequest {
  // Resource name of cohort to restore.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyCohort"
  ];

  // Deprecated. Link token to grant privileges.
  // (-- api-linter: core::0164::request-unknown-fields=disabled
  //     aip.dev/not-precedent: The link_token field is used to grant
  //     permissions on shared cohorts. --).
  string link_token = 2 [deprecated = true];
}

// Request for CopyPathologyCohort rpc.
message CopyPathologyCohortRequest {
  // Resource name of cohort to copy.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyCohort"
  ];

  // Unique display name for new copy of cohort.
  string display_name_copied = 2 [(google.api.field_behavior) = REQUIRED];

  // Description for new copy of cohort.
  string description_copied = 3 [(google.api.field_behavior) = OPTIONAL];

  // Deprecated. Link token to grant privileges.
  // (-- api-linter: core::0164::request-unknown-fields=disabled
  //     aip.dev/not-precedent: The link_token field is used to grant
  //     permissions on shared cohorts. --).
  string link_token = 4 [deprecated = true];

  // Specifies view of cohort returned.
  PathologyCohortView view = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Request for SavePathologyCohort rpc.
message SavePathologyCohortRequest {
  // Resource name of cohort to save.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyCohort"
  ];
}

// Response for SavePathologyCohort rpc.
message SavePathologyCohortResponse {}

// Request for SharePathologyCohort rpc.
message SharePathologyCohortRequest {
  // Resource name of cohort to share with users.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyCohort"
  ];

  // Users granted access to the cohort.
  // If specified, overwrites current user access permissions.
  repeated PathologyUserAccess user_access = 2
      [(google.api.field_behavior) = OPTIONAL];

  // If specified, overwrites current cohort access permissions.
  PathologyCohortAccess cohort_access = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Specifies view of cohort returned.
  PathologyCohortView view = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Request for UnsavePathologyCohort rpc.
message UnsavePathologyCohortRequest {
  // Resource name of cohort to unsave.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type =
        "digitalpathology.googleapis.com/PathologyCohort"
  ];
}

// Response for UnsavePathologyCohort rpc.
message UnsavePathologyCohortResponse {}

// Defines permissible access for the cohort.
enum PathologyCohortAccess {
  // Default value is restricted access.
  PATHOLOGY_COHORT_ACCESS_UNSPECIFIED = 0;
  // Cohort is restricted to direct access.
  PATHOLOGY_COHORT_ACCESS_RESTRICTED = 1;
  // Cohort can be edited by any user with the link.
  PATHOLOGY_COHORT_ACCESS_OPEN_EDIT = 2;
  // Cohort can be viewed by any user with the link.
  PATHOLOGY_COHORT_ACCESS_OPEN_VIEW_ONLY = 3;
}

// Provides constraints on the permissible actions for the cohort.
enum PathologyCohortBehaviorConstraints {
  // Default value is fully functional.
  PATHOLOGY_COHORT_BEHAVIOR_CONSTRAINTS_UNSPECIFIED = 0;
  // All actions are permitted on cohort.
  PATHOLOGY_COHORT_BEHAVIOR_CONSTRAINTS_FULLY_FUNCTIONAL = 1;
  // Deprecated.
  // Cohort cannot be exported. Other actions are permitted.
  PATHOLOGY_COHORT_BEHAVIOR_CONSTRAINTS_CANNOT_BE_EXPORTED = 2
      [deprecated = true];
}

// Specifies the current lifecycle stage of the cohort.
enum PathologyCohortLifecycleStage {
  // Default value is active.
  PATHOLOGY_COHORT_LIFECYCLE_STAGE_UNSPECIFIED = 0;
  // Cohort is visible to users and can be queried, viewed, modified.
  PATHOLOGY_COHORT_LIFECYCLE_STAGE_ACTIVE = 1;
  // Cohort has been deleted and is hidden from users.
  PATHOLOGY_COHORT_LIFECYCLE_STAGE_SUSPENDED = 2;
  // Cohort is in creation process in an operation and not yet available.
  PATHOLOGY_COHORT_LIFECYCLE_STAGE_UNAVAILABLE = 3;
}

// Specifies the view for PathologyCohorts returned.
enum PathologyCohortView {
  // Default view includes slides.
  PATHOLOGY_COHORT_VIEW_UNSPECIFIED = 0;
  // Contains cohort metadata only.
  PATHOLOGY_COHORT_VIEW_METADATA_ONLY = 1;
  // Contains full cohort with slides.
  PATHOLOGY_COHORT_VIEW_FULL = 2;
}