Transfer and Share Files

Description

Move and share files by transferring them to a Guest Collection.

The source directory or file will be copied, and then a new permission will be created on the destination to give read-only access to a user or group.

Highlights

This flow verifies that the destination is a Guest Collection before starting the data transfer. This ensures that it will be possible to create a permission on the destination later in the flow. In GetDestinationInfo, the flow collects metadata about the collection, and in CheckDestinationCollectionType, it dispatches over that information. The flow jumps to a Fail state, FailBadDestinationCollectionType, if the check does not pass.

The input schema in this example also demonstrates how to accept collection and principal types. The "format": "globus-collection" annotation ensures that source and destination are treated as collections when using guided flow input in the Globus Web App. "format": "globus-principal" does the same for users and groups.

Source code

{
  "Comment": "Transfer files to a guest collection and set permissions.",
  "StartAt": "GetDestinationInfo",
  "States": {
    "GetDestinationInfo": {
      "Type": "Action",
      "ActionUrl": "https://transfer.actions.globus.org/collection_info",
      "Parameters": {
        "endpoint_id.$": "$.destination.id"
      },
      "ResultPath": "$.DestinationInfo",
      "Next": "CheckDestinationCollectionType"
    },
    "CheckDestinationCollectionType": {
      "Type": "Choice",
      "Choices": [
        {
          "Or": [
            {
              "Variable": "$.DestinationInfo.details.entity_type",
              "StringEquals": "GCP_guest_collection"
            },
            {
              "Variable": "$.DestinationInfo.details.entity_type",
              "StringEquals": "GCSv5_guest_collection"
            }
          ],
          "Next": "TransferFiles"
        }
      ],
      "Default": "FailBadDestinationCollectionType"
    },
    "TransferFiles": {
      "Type": "Action",
      "ActionUrl": "https://transfer.actions.globus.org/transfer",
      "Parameters": {
        "source_endpoint.$": "$.source.id",
        "destination_endpoint.$": "$.destination.id",
        "DATA": [
          {
            "DATA_TYPE": "transfer_item",
            "source_path.$": "$.source.path",
            "destination_path.$": "$.destination.path"
          }
        ]
      },
      "ResultPath": "$.TransferFiles",
      "Next": "SetPermission"
    },
    "SetPermission": {
      "Comment": "Grant read permission on the data to a Globus user or group",
      "Type": "Action",
      "ActionUrl": "https://transfer.actions.globus.org/manage_permission",
      "Parameters": {
        "endpoint_id.$": "$.destination.id",
        "path.$": "$.destination.path",
        "operation": "CREATE",
        "permissions": "r",
        "principal_type.$": "$.principal.type",
        "principal.$": "$.principal.id"
      },
      "ResultPath": "$.SetPermission",
      "End": true
    },
    "FailBadDestinationCollectionType": {
      "Comment": "Fail due to an incorrect destination collection type.",
      "Type": "Fail",
      "Cause": "NonGuestDestinationCollection",
      "Error": "The destination collection is not a guest collection, which is a requirement for this flow."
    }
  }
}

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "source",
    "destination",
    "principal"
  ],
  "propertyOrder": [
    "source",
    "destination",
    "principal"
  ],
  "properties": {
    "source": {
      "title": "Source",
      "type": "object",
      "format": "globus-collection",
      "additionalProperties": false,
      "required": [
        "id",
        "path"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "path": {
          "type": "string"
        }
      }
    },
    "destination": {
      "title": "Destination",
      "type": "object",
      "format": "globus-collection",
      "additionalProperties": false,
      "required": [
        "id",
        "path"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "path": {
          "type": "string"
        }
      }
    },
    "principal": {
      "type": "object",
      "format": "globus-principal",
      "title": "User or Group",
      "oneOf": [
        {
          "$ref": "#/definitions/identity-principal"
        },
        {
          "$ref": "#/definitions/group-principal"
        }
      ]
    }
  },
  "definitions": {
    "group-principal": {
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "type": {
          "type": "string",
          "enum": [
            "group"
          ]
        },
        "urn": {
          "type": "string",
          "pattern": "^urn:globus:groups:id:[0-9a-fA-F-]{36}$"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "additionalProperties": false
    },
    "identity-principal": {
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "type": {
          "type": "string",
          "enum": [
            "identity"
          ]
        },
        "urn": {
          "type": "string",
          "pattern": "^urn:globus:auth:identity:[0-9a-fA-F-]{36}$"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "additionalProperties": false
    }
  }
}

{
  "source": {
    "id": "6c54cade-bde5-45c1-bdea-f4bd71dba2cc",
    "path": "/~/source-directory"
  },
  "destination": {
    "id": "31ce9ba0-176d-45a5-add3-f37d233ba47d",
    "path": "/~/destination-directory"
  },
  "principal": {
    "id": "46bd0f56-e24f-11e5-a510-131bef46955c",
    "type": "identity",
    "urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c"
  }
}