Globus Flows#

class globus_sdk.FlowsClient(*, environment: Optional[str] = None, base_url: Optional[str] = None, authorizer: Optional[GlobusAuthorizer] = None, app_name: Optional[str] = None, transport_params: Optional[dict[str, Any]] = None)[source]#

Bases: BaseClient

Client for the Globus Flows API.

Methods

scopes: ScopeBuilder | None = <globus_sdk.scopes.data._FlowsScopeBuilder object>#

the scopes for this client may be present as a ScopeBuilder

create_flow(title: str, definition: dict[str, Any], input_schema: dict[str, Any], subtitle: Optional[str] = None, description: Optional[str] = None, flow_viewers: Optional[list[str]] = None, flow_starters: Optional[list[str]] = None, flow_administrators: Optional[list[str]] = None, keywords: Optional[list[str]] = None, additional_fields: Optional[dict[str, Any]] = None) GlobusHTTPResponse[source]#

Create a Flow

Parameters:
  • title (str (1 - 128 characters)) – A non-unique, human-friendly name used for displaying the flow to end users.

  • definition (dict) – JSON object specifying flows states and execution order. For a more detailed explanation of the flow definition, see Authoring Flows

  • input_schema (dict) – A JSON Schema to which Flow Invocation input must conform

  • subtitle (str (0 - 128 characters), optional) – A concise summary of the flow’s purpose.

  • description (str (0 - 4096 characters), optional) – A detailed description of the flow’s purpose for end user display.

  • flow_viewers (list[str], optional) –

    A set of Principal URN values, or the value “public”, indicating entities who can view the flow

    Example Values
    [ "public" ]
    
    [
        "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
        "urn:globus:groups:id:c1dcd951-3f35-4ea3-9f28-a7cdeaf8b68f"
    ]
    

  • flow_starters (list[str], optional) –

    A set of Principal URN values, or the value “all_authenticated_users”, indicating entities who can initiate a Run of the flow

    Example Values
    [ "all_authenticated_users" ]
    
    [
        "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
        "urn:globus:groups:id:c1dcd951-3f35-4ea3-9f28-a7cdeaf8b68f"
    ]
    

  • flow_administrators (list[str], optional) –

    A set of Principal URN values indicating entities who can perform administrative operations on the flow (create, delete, update)

    Example Values
    [
        "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
        "urn:globus:groups:id:c1dcd951-3f35-4ea3-9f28-a7cdeaf8b68f"
    ]
    

  • keywords (list[str] (0 - 1024 items), optional) – A set of terms used to categorize the flow used in query and discovery operations

  • additional_fields (dict of str -> any, optional) – Additional Key/Value pairs sent to the create API

from globus_sdk import FlowsClient

...
flows = FlowsClient(...)
flows.create_flow(
    title="my-cool-flow",
    definition={
        "StartAt": "the-one-true-state",
        "States": {"the-one-true-state": {"Type": "Pass", "End": True}},
    },
    input_schema={
        "type": "object",
        "properties": {
            "input-a": {"type": "string"},
            "input-b": {"type": "number"},
            "input-c": {"type": "boolean"},
        },
    },
)
{
  "id": "24bc4997-b483-4c25-a19c-64b0afc00743",
  "definition": {
    "States": {
      "Transfer1": {
        "Next": "Transfer2",
        "Type": "Action",
        "Comment": "Initial Transfer from Campus to DMZ",
        "ActionUrl": "https://actions.globus.org/transfer/transfer",
        "Parameters": {
          "transfer_items": [
            {
              "recursive": true,
              "source_path.$": "$.source_path",
              "destination_path.$": "$.staging_path"
            }
          ],
          "source_endpoint_id.$": "$.source_endpoint_id",
          "destination_endpoint_id.$": "$.staging_endpoint_id"
        },
        "ResultPath": "$.Transfer1Result",
        "ActionScope": "https://auth.globus.org/scopes/actions.globus.org/transfer/transfer"
      },
      "Transfer2": {
        "End": true,
        "Type": "Action",
        "Comment": "Transfer from DMZ to dataset repository",
        "ActionUrl": "https://actions.globus.org/transfer/transfer",
        "Parameters": {
          "transfer_items": [
            {
              "recursive": true,
              "source_path.$": "$.staging_path",
              "destination_path.$": "$.destination_path"
            }
          ],
          "source_endpoint_id.$": "$.staging_endpoint_id",
          "destination_endpoint_id.$": "$.destination_endpoint_id"
        },
        "ResultPath": "$.Transfer2Result",
        "ActionScope": "https://auth.globus.org/scopes/actions.globus.org/transfer/transfer"
      }
    },
    "Comment": "Two step transfer",
    "StartAt": "Transfer1"
  },
  "input_schema": {
    "type": "object",
    "required": [
      "source_endpoint_id",
      "source_path",
      "staging_endpoint_id",
      "staging_path",
      "destination_endpoint_id",
      "destination_path"
    ],
    "properties": {
      "source_path": {
        "type": "string"
      },
      "staging_path": {
        "type": "string"
      },
      "destination_path": {
        "type": "string"
      },
      "source_endpoint_id": {
        "type": "string"
      },
      "staging_endpoint_id": {
        "type": "string"
      },
      "destination_endpoint_id": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globus_auth_scope": "https://auth.globus.org/scopes/24bc4997-b483-4c25-a19c-64b0afc00743/flow_24bc4997_b483_4c25_a19c_64b0afc00743_user",
  "synchronous": false,
  "log_supported": true,
  "types": [
    "Action"
  ],
  "api_version": "1.0",
  "title": "Multi Step Transfer",
  "subtitle": "",
  "description": "",
  "keywords": [
    "two",
    "hop",
    "transfer"
  ],
  "principal_urn": "urn:globus:auth:identity:24bc4997-b483-4c25-a19c-64b0afc00743",
  "globus_auth_username": "24bc4997-b483-4c25-a19c-64b0afc00743@clients.auth.globus.org",
  "created_at": "2020-09-01T17:59:20.711845+00:00",
  "updated_at": "2020-09-01T17:59:20.711845+00:00",
  "user_role": "flow_starter",
  "created_by": "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
  "visible_to": [],
  "runnable_by": [],
  "administered_by": [],
  "action_url": "https://flows.globus.org/flows/24bc4997-b483-4c25-a19c-64b0afc00743",
  "flow_url": "https://flows.globus.org/flows/24bc4997-b483-4c25-a19c-64b0afc00743",
  "flow_owner": "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
  "flow_viewers": [
    "public",
    "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150"
  ],
  "flow_starters": [
    "all_authenticated_users",
    "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150"
  ],
  "flow_administrators": [
    "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150"
  ]
}

External Documentation

See Create Flow in the API documentation for details.

get_flow(flow_id: Union[UUID, str], *, query_params: Optional[dict[str, Any]] = None) GlobusHTTPResponse[source]#

Retrieve a Flow by ID

Parameters:
  • flow_id (str or UUID) – The ID of the Flow to fetch

  • query_params (dict, optional) – Any additional parameters to be passed through as query params.

External Documentation

See Get Flow in the API documentation for details.

list_flows(*, filter_role: Optional[str] = None, filter_fulltext: Optional[str] = None, orderby: Optional[str] = None, marker: Optional[str] = None, query_params: Optional[dict[str, Any]] = None) IterableFlowsResponse[source]#

List deployed Flows

Parameters:
  • filter_role (str, optional) – A role name specifying the minimum permissions required for a Flow to be included in the response.

  • filter_fulltext (str, optional) – A string to use in a full-text search to filter results

  • orderby (str, optional) – A criterion for ordering flows in the listing

  • marker (str, optional) – A marker for pagination

  • query_params (dict, optional) – Any additional parameters to be passed through as query params.

Role Values

The valid values for role are, in order of precedence for filter_role:

  • flow_viewer

  • flow_starter

  • flow_administrator

  • flow_owner

For example, if flow_starter is specified then flows for which the user has the flow_starter, flow_administrator or flow_owner roles will be returned.

OrderBy Values

Values for orderby consist of a field name, a space, and an ordering mode – ASC for “ascending” and DESC for “descending”.

Supported field names are

  • id

  • scope_string

  • flow_owners

  • flow_administrators

  • title

  • created_at

  • updated_at

For example, orderby="updated_at DESC" requests a descending sort on update times, getting the most recently updated flow first.

This method supports paginated access. To use the paginated variant, give the same arguments as normal, but prefix the method name with paginated, as in

client.paginated.list_flows(...)

For more information, see how to make paginated calls.

External Documentation

See List Flows in the API documentation for details.

update_flow(flow_id: Union[UUID, str], *, title: Optional[str] = None, definition: Optional[dict[str, Any]] = None, input_schema: Optional[dict[str, Any]] = None, subtitle: Optional[str] = None, description: Optional[str] = None, flow_owner: Optional[str] = None, flow_viewers: Optional[list[str]] = None, flow_starters: Optional[list[str]] = None, flow_administrators: Optional[list[str]] = None, keywords: Optional[list[str]] = None, additional_fields: Optional[dict[str, Any]] = None) GlobusHTTPResponse[source]#

Update a Flow

Only the parameter flow_id is required. Any fields omitted from the request will be unchanged

Parameters:
  • flow_id (str or UUID) – The ID of the Flow to fetch

  • title (str (1 - 128 characters), optional) – A non-unique, human-friendly name used for displaying the flow to end users.

  • definition (dict, optional) –

    JSON object specifying flows states and execution order. For a more detailed explanation of the flow definition, see Authoring Flows

  • input_schema (dict, optional) – A JSON Schema to which Flow Invocation input must conform

  • subtitle (str (0 - 128 characters), optional) – A concise summary of the flow’s purpose.

  • description (str (0 - 4096 characters), optional) – A detailed description of the flow’s purpose for end user display.

  • flow_owner (str, optional) – An Auth Identity URN to set as flow owner; this must match the Identity URN of the entity calling update_flow

  • flow_viewers (list[str], optional) –

    A set of Principal URN values, or the value “public”, indicating entities who can view the flow

    Example Values
    [ "public" ]
    
    [
        "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
        "urn:globus:groups:id:c1dcd951-3f35-4ea3-9f28-a7cdeaf8b68f"
    ]
    

  • flow_starters (list[str], optional) –

    A set of Principal URN values, or the value “all_authenticated_users”, indicating entities who can initiate a Run of the flow

    Example Values
    [ "all_authenticated_users" ]
    
    [
        "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
        "urn:globus:groups:id:c1dcd951-3f35-4ea3-9f28-a7cdeaf8b68f"
    ]
    

  • flow_administrators (list[str], optional) –

    A set of Principal URN values indicating entities who can perform administrative operations on the flow (create, delete, update)

    Example Value
    [
        "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
        "urn:globus:groups:id:c1dcd951-3f35-4ea3-9f28-a7cdeaf8b68f"
    ]
    

  • keywords (list[str] (0 - 1024 items), optional) – A set of terms used to categorize the flow used in query and discovery operations

  • additional_fields (dict of str -> any, optional) – Additional Key/Value pairs sent to the create API

from globus_sdk import FlowsClient

...
flows = FlowsClient(...)
flows.update_flow(
    flow_id="581753c7-45da-43d3-ad73-246b46e7cb6b",
    keywords=["new", "overriding", "keywords"]
)
{
  "id": "24bc4997-b483-4c25-a19c-64b0afc00743",
  "definition": {
    "States": {
      "Transfer1": {
        "Next": "Transfer2",
        "Type": "Action",
        "Comment": "Initial Transfer from Campus to DMZ",
        "ActionUrl": "https://actions.globus.org/transfer/transfer",
        "Parameters": {
          "transfer_items": [
            {
              "recursive": true,
              "source_path.$": "$.source_path",
              "destination_path.$": "$.staging_path"
            }
          ],
          "source_endpoint_id.$": "$.source_endpoint_id",
          "destination_endpoint_id.$": "$.staging_endpoint_id"
        },
        "ResultPath": "$.Transfer1Result",
        "ActionScope": "https://auth.globus.org/scopes/actions.globus.org/transfer/transfer"
      },
      "Transfer2": {
        "End": true,
        "Type": "Action",
        "Comment": "Transfer from DMZ to dataset repository",
        "ActionUrl": "https://actions.globus.org/transfer/transfer",
        "Parameters": {
          "transfer_items": [
            {
              "recursive": true,
              "source_path.$": "$.staging_path",
              "destination_path.$": "$.destination_path"
            }
          ],
          "source_endpoint_id.$": "$.staging_endpoint_id",
          "destination_endpoint_id.$": "$.destination_endpoint_id"
        },
        "ResultPath": "$.Transfer2Result",
        "ActionScope": "https://auth.globus.org/scopes/actions.globus.org/transfer/transfer"
      }
    },
    "Comment": "Two step transfer",
    "StartAt": "Transfer1"
  },
  "input_schema": {
    "type": "object",
    "required": [
      "source_endpoint_id",
      "source_path",
      "staging_endpoint_id",
      "staging_path",
      "destination_endpoint_id",
      "destination_path"
    ],
    "properties": {
      "source_path": {
        "type": "string"
      },
      "staging_path": {
        "type": "string"
      },
      "destination_path": {
        "type": "string"
      },
      "source_endpoint_id": {
        "type": "string"
      },
      "staging_endpoint_id": {
        "type": "string"
      },
      "destination_endpoint_id": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globus_auth_scope": "https://auth.globus.org/scopes/24bc4997-b483-4c25-a19c-64b0afc00743/flow_24bc4997_b483_4c25_a19c_64b0afc00743_user",
  "synchronous": false,
  "log_supported": true,
  "types": [
    "Action"
  ],
  "api_version": "1.0",
  "title": "Multi Step Transfer",
  "subtitle": "Specifically, in two steps",
  "description": "Transfer from source to destination, stopping off at staging",
  "keywords": [
    "two",
    "hop",
    "transfer"
  ],
  "principal_urn": "urn:globus:auth:identity:24bc4997-b483-4c25-a19c-64b0afc00743",
  "globus_auth_username": "24bc4997-b483-4c25-a19c-64b0afc00743@clients.auth.globus.org",
  "created_at": "2020-09-01T17:59:20.711845+00:00",
  "updated_at": "2020-09-01T17:59:20.711845+00:00",
  "user_role": "flow_starter",
  "created_by": "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
  "visible_to": [],
  "runnable_by": [],
  "administered_by": [],
  "action_url": "https://flows.globus.org/flows/24bc4997-b483-4c25-a19c-64b0afc00743",
  "flow_url": "https://flows.globus.org/flows/24bc4997-b483-4c25-a19c-64b0afc00743",
  "flow_owner": "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
  "flow_viewers": [
    "public",
    "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150"
  ],
  "flow_starters": [
    "all_authenticated_users",
    "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150"
  ],
  "flow_administrators": [
    "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150"
  ]
}

External Documentation

See Update Flow in the API documentation for details.

delete_flow(flow_id: Union[UUID, str], *, query_params: Optional[dict[str, Any]] = None) GlobusHTTPResponse[source]#

Delete a Flow

Parameters:
  • flow_id (str or UUID, optional) – The ID of the flow to delete

  • query_params (dict, optional) – Any additional parameters to be passed through as query params.

External Documentation

See Delete Flow in the API documentation for details.

class globus_sdk.SpecificFlowClient(flow_id: Union[UUID, str], *, environment: Optional[str] = None, authorizer: Optional[GlobusAuthorizer] = None, app_name: Optional[str] = None, transport_params: Optional[dict[str, Any]] = None)[source]#

Bases: BaseClient

Client for interacting with a specific Globus Flow through the Flows API.

Unlike other client types, this must be provided with a specific flow id. All other

arguments are the same as those for ~globus_sdk.BaseClient.

Parameters:

flow_id (str or uuid) – The generated UUID associated with a flow

Methods

run_flow(body: dict[str, Any], *, label: Optional[str] = None, tags: Optional[list[str]] = None, run_monitors: Optional[list[str]] = None, run_managers: Optional[list[str]] = None, additional_fields: Optional[dict[str, Any]] = None) GlobusHTTPResponse[source]#
Parameters:
  • body (json dict) – The input json object handed to the first flow state. The flows service will validate this object against the flow’s supplied input schema.

  • label (Optional string (0 - 64 chars)) – A short human-readable title

  • tags (Optional list of strings) – A collection of searchable tags associated with the run. Tags are normalized by stripping leading and trailing whitespace, and replacing all whitespace with a single space.

  • run_monitors (Optional list of strings) – A list of authenticated entities (identified by URN) authorized to view this run in addition to the run owner

  • run_managers (Optional list of strings) – A list of authenticated entities (identified by URN) authorized to view & cancel this run in addition to the run owner

  • additional_fields (Optional dictionary) – Additional Key/Value pairs sent to the run API (this parameter is used to bypass local sdk key validation helping)

External Documentation

See Run Flow in the API documentation for details.

Client Errors#

When an error occurs, a FlowsClient will raise a FlowsAPIError.

class globus_sdk.FlowsAPIError(r: Response, *args: Any, **kwargs: Any)[source]#

Bases: GlobusAPIError

Error class to represent error responses from Flows.