Globus Flows#

The Flows service allows users to create automation workflows (or, simply, “flows”). When a flow is started, it must be authorized to perform actions on the user’s behalf.

Because a running flow (or, simply, a “run”) can perform actions on the user’s behalf, the Globus SDK has two client classes that can interact with the Flows service: a FlowsClient and a SpecificFlowClient. They differ in what operations they can perform and, as a result, what scopes they require:

FlowsClient is able to create, update, and delete flows. It is also able to retrieve information about flows and runs.

Users must consent to allow the client application to administer flows and runs. See FlowsClient.scopes for a complete list of scopes.
SpecificFlowClient must be instantiated with a specific flow ID so it can construct the scope associated with the flow. It is then able to start that specific flow. If a run associated with the flow becomes inactive for any reason, it is able to resume the run, too.

Users must consent to allow the specific flow to perform actions on their behalf. The specific flow scope can be accessed via SpecificFlowClient.scopes.user after the SpecificFlowClient has been instantiated.

Applications that create and then start a flow would therefore need to use both classes.

Bases: BaseClient

Client for the Globus Flows API.

Methods

cancel_run()
create_flow()
delete_flow()
delete_run()
get_flow()
get_run()
get_run_definition()
get_run_logs(), paginated.get_run_logs()
list_flows(), paginated.list_flows()
list_runs(), paginated.list_runs()
update_flow()
update_run()

scopes#

Various scopes are available as attributes of this object. For example, access the manage_flows scope with

>>> FlowsClient.scopes.manage_flows

Supported Scopes

manage_flows
view_flows
run
run_status
run_manage

create_flow(title: str, definition: dict[str, Any], input_schema: dict[str, Any], subtitle: str | None = None, description: str | None = None, flow_viewers: list[str] | None = None, flow_starters: list[str] | None = None, flow_administrators: list[str] | None = None, keywords: list[str] | None = None, additional_fields: dict[str, Any] | None = 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

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

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

Example Usage

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"},
        },
    },
)

Example Response Data

{
  "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:51abb9ce-6e05-4ab1-9a09-9c524313827c"
  ],
  "flow_starters": [
    "all_authenticated_users",
    "urn:globus:auth:identity:d0a15d1b-28f5-42de-9463-b8b6540421b6"
  ],
  "flow_administrators": [
    "urn:globus:auth:identity:05d29dab-bd26-4510-9290-468972e8ac01"
  ]
}

API Info

See Create Flow in the API documentation for details.

get_flow(flow_id: UUID | str, *, query_params: dict[str, Any] | None = 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.

API Info

See Get Flow in the API documentation for details.

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. Multiple orderby values may be given as an iterable, e.g. orderby=["updated_at DESC", "title ASC"].

Example Usage

import json
import textwrap

from globus_sdk import FlowsClient

flows = FlowsClient(...)
my_frobulate_flows = flows.list_flows(
    filter_role="flow_owner",
    filter_fulltext="frobulate",
    orderby=("title ASC", "updated_at DESC"),
)
for flow_doc in my_frobulate_flows:
    print(f"Title: {flow_doc['title']}")
    print(f"Description: {flow_doc['description']}")
    print("Definition:")
    print(
        textwrap.indent(
            json.dumps(
                flow_doc["definition"],
                indent=2,
                separators=(",", ": "),
            ),
            "    ",
        )
    )
    print()

Paginated Usage

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.

API Info

See List Flows in the API documentation for details.

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

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

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

Example Usage

from globus_sdk import FlowsClient

flows = FlowsClient(...)
flows.update_flow(
    flow_id="581753c7-45da-43d3-ad73-246b46e7cb6b",
    keywords=["new", "overriding", "keywords"],
)

Example Response Data

{
  "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:51abb9ce-6e05-4ab1-9a09-9c524313827c"
  ],
  "flow_starters": [
    "all_authenticated_users",
    "urn:globus:auth:identity:d0a15d1b-28f5-42de-9463-b8b6540421b6"
  ],
  "flow_administrators": [
    "urn:globus:auth:identity:05d29dab-bd26-4510-9290-468972e8ac01"
  ]
}

API Info

See Update Flow in the API documentation for details.

delete_flow(flow_id: UUID | str, *, query_params: dict[str, Any] | None = 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.

API Info

See Delete Flow in the API documentation for details.

List all runs.

Parameters:

filter_flow_id (str, UUID, or iterable of str or UUID, optional) – One or more Flow IDs used to filter the results
marker (str, optional) – A pagination marker, used to get the next page of results.
query_params (dict, optional) – Any additional parameters to be passed through

Example Usage

flows = globus_sdk.FlowsClient(...)
for run in flows.list_runs():
    print(run["run_id"])

Example Response Data

{
  "runs": [
    {
      "run_id": "5b66f8ac-568e-11ee-92ba-0242ac110002",
      "action_id": "5b66f8ac-568e-11ee-92ba-0242ac110002",
      "completion_time": "2023-04-11T20:01:22.917000+00:00",
      "created_by": "urn:globus:auth:identity:5b66f942-568e-11ee-92ba-0242ac110002",
      "details": {
        "code": "FlowSucceeded",
        "description": "The Flow run reached a successful completion state",
        "output": {
          "HelloResult": {
            "action_id": "6RxDm1JOQnG2",
            "completion_time": "2023-04-11T20:01:22.340594+00:00",
            "creator_id": "urn:globus:auth:identity:5b66f942-568e-11ee-92ba-0242ac110002",
            "details": {
              "Hello": "World",
              "hello": "foo"
            },
            "display_status": "SUCCEEDED",
            "label": "My Cool Run",
            "manage_by": [
              "urn:globus:auth:identity:5b66f9c4-568e-11ee-92ba-0242ac110002"
            ],
            "monitor_by": [
              "urn:globus:groups:id:5b66fa3c-568e-11ee-92ba-0242ac110002"
            ],
            "release_after": null,
            "start_time": "2023-04-11T20:01:19.660251+00:00",
            "state_name": "RunHelloWorld",
            "status": "SUCCEEDED"
          },
          "input": {
            "echo_string": "foo",
            "sleep": 2
          }
        }
      },
      "display_status": "SUCCEEDED",
      "flow_id": "5b66f794-568e-11ee-92ba-0242ac110002",
      "flow_last_updated": "2023-04-11T20:00:06.524930+00:00",
      "flow_title": "My Cool Flow",
      "label": "My Cool Run",
      "manage_by": [
        "urn:globus:auth:identity:5b66f9c4-568e-11ee-92ba-0242ac110002"
      ],
      "monitor_by": [
        "urn:globus:groups:id:5b66fa3c-568e-11ee-92ba-0242ac110002"
      ],
      "run_managers": [
        "urn:globus:auth:identity:5b66f9c4-568e-11ee-92ba-0242ac110002"
      ],
      "run_monitors": [
        "urn:globus:groups:id:5b66fa3c-568e-11ee-92ba-0242ac110002"
      ],
      "run_owner": "urn:globus:auth:identity:5b66f942-568e-11ee-92ba-0242ac110002",
      "start_time": "2023-04-11T20:01:18.040416+00:00",
      "status": "SUCCEEDED",
      "tags": [
        "cool",
        "my"
      ],
      "user_role": "run_owner"
    }
  ],
  "limit": 20,
  "has_next_page": false,
  "marker": null
}

API Info

See List Runs in the API documentation for details.

Retrieve the execution logs associated with a run

These logs describe state transitions and associated payloads for a run

Parameters:

run_id (str or UUID, optional) – Run ID to retrieve logs for
limit (int, optional) – Maximum number of log entries to return (server default: 10) (value between 1 and 100 inclusive)
reverse_order (bool) – Return results in reverse chronological order (server default: false)
marker (str, optional) – Marker for the next page of results (provided by the server)
query_params (dict, optional) – Any additional parameters to be passed through

Paginated Usage

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.get_run_logs(...)

For more information, see how to make paginated calls.

Example Response Data

{
  "limit": 10,
  "has_next_page": false,
  "entries": [
    {
      "time": "2023-04-25T18:54:30.683000+00:00",
      "code": "FlowStarted",
      "description": "The Flow Instance started execution",
      "details": {
        "input": {}
      }
    },
    {
      "time": "2023-04-25T18:54:30.715000+00:00",
      "code": "ActionStarted",
      "description": "State SyncHelloWorld of type Action started",
      "details": {
        "state_name": "SyncHelloWorld",
        "state_type": "Action",
        "input": {
          "echo_string": "sync!"
        }
      }
    },
    {
      "time": "2023-04-25T18:54:31.850000+00:00",
      "code": "ActionCompleted",
      "description": "State SyncHelloWorld of type Action completed",
      "details": {
        "state_name": "SyncHelloWorld",
        "state_type": "Action",
        "output": {
          "action_id": "19NqhOnDlt2Y3",
          "completion_time": "2023-04-25T18:54:31.341170+00:00",
          "creator_id": "urn:globus:auth:identity:944cfbe8-60f8-474d-a634-a0c1ad543a54",
          "details": {
            "Hello": "World",
            "hello": "sync!"
          },
          "display_status": "SUCCEEDED",
          "label": null,
          "manage_by": [],
          "monitor_by": [],
          "release_after": null,
          "start_time": "2023-04-25T18:54:31.340484+00:00",
          "status": "SUCCEEDED",
          "state_name": "SyncHelloWorld"
        }
      }
    },
    {
      "time": "2023-04-25T18:54:31.913000+00:00",
      "code": "FlowSucceeded",
      "description": "The Flow Instance completed successfully",
      "details": {
        "output": {
          "action_id": "19NqhOnDlt2Y3",
          "completion_time": "2023-04-25T18:54:31.341170+00:00",
          "creator_id": "urn:globus:auth:identity:944cfbe8-60f8-474d-a634-a0c1ad543a54",
          "details": {
            "Hello": "World",
            "hello": "sync!"
          },
          "display_status": "SUCCEEDED",
          "label": null,
          "manage_by": [],
          "monitor_by": [],
          "release_after": null,
          "start_time": "2023-04-25T18:54:31.340484+00:00",
          "status": "SUCCEEDED",
          "state_name": "SyncHelloWorld"
        }
      }
    }
  ]
}

API Info

See Get Run Logs in the API documentation for details.

get_run(run_id: UUID | str, *, include_flow_description: bool | None = None, query_params: dict[str, Any] | None = None) → GlobusHTTPResponse[source]#

Retrieve information about a particular Run of a Flow

Parameters:

run_id (str or UUID) – The ID of the run to get
include_flow_description (bool, optional) – If set to true, the lookup will attempt to attach metadata about the flow to the run to the run response under the key “flow_description” (default: False)
query_params (dict, optional) – Any additional parameters to be passed through

Example Usage

from globus_sdk import FlowsClient

flows = FlowsClient(...)
flows.get_run("581753c7-45da-43d3-ad73-246b46e7cb6b")

Example Response Data

{
  "run_id": "5b66f8ac-568e-11ee-92ba-0242ac110002",
  "action_id": "5b66f8ac-568e-11ee-92ba-0242ac110002",
  "completion_time": "2023-04-11T20:01:22.917000+00:00",
  "created_by": "urn:globus:auth:identity:5b66f942-568e-11ee-92ba-0242ac110002",
  "details": {
    "code": "FlowSucceeded",
    "description": "The Flow run reached a successful completion state",
    "output": {
      "HelloResult": {
        "action_id": "6RxDm1JOQnG2",
        "completion_time": "2023-04-11T20:01:22.340594+00:00",
        "creator_id": "urn:globus:auth:identity:5b66f942-568e-11ee-92ba-0242ac110002",
        "details": {
          "Hello": "World",
          "hello": "foo"
        },
        "display_status": "SUCCEEDED",
        "label": "My Cool Run",
        "manage_by": [
          "urn:globus:auth:identity:5b66f9c4-568e-11ee-92ba-0242ac110002"
        ],
        "monitor_by": [
          "urn:globus:groups:id:5b66fa3c-568e-11ee-92ba-0242ac110002"
        ],
        "release_after": null,
        "start_time": "2023-04-11T20:01:19.660251+00:00",
        "state_name": "RunHelloWorld",
        "status": "SUCCEEDED"
      },
      "input": {
        "echo_string": "foo",
        "sleep": 2
      }
    }
  },
  "display_status": "SUCCEEDED",
  "flow_id": "5b66f794-568e-11ee-92ba-0242ac110002",
  "flow_last_updated": "2023-04-11T20:00:06.524930+00:00",
  "flow_title": "My Cool Flow",
  "label": "My Cool Run",
  "manage_by": [
    "urn:globus:auth:identity:5b66f9c4-568e-11ee-92ba-0242ac110002"
  ],
  "monitor_by": [
    "urn:globus:groups:id:5b66fa3c-568e-11ee-92ba-0242ac110002"
  ],
  "run_managers": [
    "urn:globus:auth:identity:5b66f9c4-568e-11ee-92ba-0242ac110002"
  ],
  "run_monitors": [
    "urn:globus:groups:id:5b66fa3c-568e-11ee-92ba-0242ac110002"
  ],
  "run_owner": "urn:globus:auth:identity:5b66f942-568e-11ee-92ba-0242ac110002",
  "start_time": "2023-04-11T20:01:18.040416+00:00",
  "status": "SUCCEEDED",
  "tags": [
    "cool",
    "my"
  ],
  "user_role": "run_owner"
}

API Info

See Get Run in the API documentation for details.

get_run_definition(run_id: UUID | str) → GlobusHTTPResponse[source]#

Get the flow definition and input schema at the time the run was started.

Parameters:: run_id (str or UUID) – The ID of the run to get

Example Usage

from globus_sdk import FlowsClient

flows = FlowsClient(...)
flows.get_run_definition("581753c7-45da-43d3-ad73-246b46e7cb6b")

Example Response Data

{
  "flow_id": "5feea933-a8c0-4e83-b4d2-ea0c405a6db3",
  "definition": {
    "States": {
      "no-op": {
        "End": true,
        "Type": "Pass"
      }
    },
    "StartAt": "no-op"
  },
  "input_schema": {}
}

API Info

See Get Run Definition in the API documentation for details.

cancel_run(run_id: UUID | str) → GlobusHTTPResponse[source]#

Cancel a run.

Parameters:: run_id (str or UUID) – The ID of the run to cancel

Example Usage

from globus_sdk import FlowsClient

flows = FlowsClient(...)
flows.cancel_run("581753c7-45da-43d3-ad73-246b46e7cb6b")

Example Response Data

{
  "run_id": "36ad9f9a-ad29-488f-beb4-c22ab729643a",
  "flow_id": "24bc4997-b483-4c25-a19c-64b0afc00743",
  "flow_title": "Multi Step Transfer",
  "flow_last_updated": "2020-09-01T17:59:20.711845+00:00",
  "start_time": "2020-09-12T15:00:20.711845+00:00",
  "status": "FAILED",
  "display_status": "FAILED",
  "details": {
    "time": "2023-06-12T23:04:42.121000+00:00",
    "code": "FlowCanceled",
    "description": "The Flow Instance was canceled by the user",
    "details": {}
  },
  "run_owner": "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
  "run_managers": [
    "urn:globus:auth:identity:7d6064ef-5368-473a-b15b-e99c3561aa9b"
  ],
  "run_monitors": [
    "urn:globus:auth:identity:58cf49f4-06ea-4b76-934c-d5c9f6c3ea9d",
    "urn:globus:auth:identity:57088a17-d5cb-4cfa-871a-c5cce48f2aec"
  ],
  "user_role": "run_owner",
  "label": "Transfer all of these files!",
  "tags": [
    "my-transfer-run",
    "jazz-fans"
  ],
  "search": {
    "task_id": "20ba91a8-eb90-470a-9477-2ad68808b276"
  }
}

API Info

See Cancel Run in the API documentation for details.

Update the metadata of a specific run.

Parameters:

run_id (str or UUID) – The ID of the run to update
label (Optional string (1 - 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)

Example Usage

from globus_sdk import FlowsClient

flows = FlowsClient(...)
flows.update_run(
    "581753c7-45da-43d3-ad73-246b46e7cb6b",
    label="Crunch numbers for experiment xDA202-batch-10",
)

Example Response Data

{
  "run_id": "36ad9f9a-ad29-488f-beb4-c22ab729643a",
  "flow_id": "24bc4997-b483-4c25-a19c-64b0afc00743",
  "flow_title": "Multi Step Transfer",
  "flow_last_updated": "2020-09-01T17:59:20.711845+00:00",
  "start_time": "2020-09-12T15:00:20.711845+00:00",
  "status": "ACTIVE",
  "display_status": "ACTIVE",
  "details": {
    "code": "FlowStarting",
    "description": "The Flow is starting execution",
    "details": {
      "input": {
        "source_endpoint_id": "7e1b8ec7-a606-4c23-96c7-a2d930a3a55f",
        "source_path": "/path/to/the/source/dir",
        "staging_endpoint_id": "d5049dd6-ce9c-4f9e-853f-c25069f369f8",
        "staging_path": "/path/to/the/staging/dir",
        "destination_endpoint_id": "f3bd0daf-be5a-4df8-b53f-76b932113b7c",
        "destination_path": "/path/to/the/dest/dir"
      }
    }
  },
  "run_owner": "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
  "run_managers": [
    "urn:globus:auth:identity:7d6064ef-5368-473a-b15b-e99c3561aa9b"
  ],
  "run_monitors": [
    "urn:globus:auth:identity:58cf49f4-06ea-4b76-934c-d5c9f6c3ea9d",
    "urn:globus:auth:identity:57088a17-d5cb-4cfa-871a-c5cce48f2aec"
  ],
  "user_role": "run_owner",
  "label": "Transfer all of these files!",
  "tags": [
    "my-transfer-run",
    "jazz-fans"
  ],
  "search": {
    "task_id": "20ba91a8-eb90-470a-9477-2ad68808b276"
  }
}

API Info

See Update Run in the API documentation for details.

delete_run(run_id: UUID | str) → GlobusHTTPResponse[source]#

Delete a run.

Parameters:: run_id (str or UUID) – The ID of the run to delete

Example Usage

from globus_sdk import FlowsClient

flows = FlowsClient(...)
flows.delete_run("581753c7-45da-43d3-ad73-246b46e7cb6b")

Example Response Data

{
  "run_id": "36ad9f9a-ad29-488f-beb4-c22ab729643a",
  "flow_id": "24bc4997-b483-4c25-a19c-64b0afc00743",
  "flow_title": "Multi Step Transfer",
  "flow_last_updated": "2020-09-01T17:59:20.711845+00:00",
  "start_time": "2020-09-12T15:00:20.711845+00:00",
  "status": "SUCCEEDED",
  "display_status": "SUCCEEDED",
  "details": {
    "code": "FlowSucceeded",
    "output": {},
    "description": "The Flow run reached a successful completion state"
  },
  "run_owner": "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
  "run_managers": [
    "urn:globus:auth:identity:7d6064ef-5368-473a-b15b-e99c3561aa9b"
  ],
  "run_monitors": [
    "urn:globus:auth:identity:58cf49f4-06ea-4b76-934c-d5c9f6c3ea9d",
    "urn:globus:auth:identity:57088a17-d5cb-4cfa-871a-c5cce48f2aec"
  ],
  "user_role": "run_owner",
  "label": "Transfer all of these files!",
  "tags": [
    "my-transfer-run",
    "jazz-fans"
  ],
  "search": {
    "task_id": "20ba91a8-eb90-470a-9477-2ad68808b276"
  }
}

API Info

See Delete Run in the API documentation for details.

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 BaseClient.

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

Methods

resume_run()
run_flow()

scopes: ScopeBuilder = <globus_sdk.services.flows.scopes.SpecificFlowScopesClassStub object>#: the scopes for this client may be present as a ScopeBuilder

run_flow(body: dict[str, Any], *, label: str | None = None, tags: list[str] | None = None, run_monitors: list[str] | None = None, run_managers: list[str] | None = None, additional_fields: dict[str, Any] | None = 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 (1 - 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)

API Info

See Run Flow in the API documentation for details.

resume_run(run_id: UUID | str) → GlobusHTTPResponse[source]#

Parameters:: run_id (str or UUID) – The ID of the run to resume

Example Usage

from globus_sdk import SpecificFlowClient

...
flow = SpecificFlowClient(flow_id, ...)
flow.resume_run(run_id)

Example Response Data

{
  "run_id": "36ad9f9a-ad29-488f-beb4-c22ab729643a",
  "flow_id": "24bc4997-b483-4c25-a19c-64b0afc00743",
  "flow_title": "Multi Step Transfer",
  "flow_last_updated": "2020-09-01T17:59:20.711845+00:00",
  "start_time": "2020-09-12T15:00:20.711845+00:00",
  "status": "ACTIVE",
  "display_status": "ACTIVE",
  "details": {
    "code": "FlowStarting",
    "description": "The Flow is starting execution",
    "details": {
      "input": {
        "source_endpoint_id": "7e1b8ec7-a606-4c23-96c7-a2d930a3a55f",
        "source_path": "/path/to/the/source/dir",
        "staging_endpoint_id": "d5049dd6-ce9c-4f9e-853f-c25069f369f8",
        "staging_path": "/path/to/the/staging/dir",
        "destination_endpoint_id": "f3bd0daf-be5a-4df8-b53f-76b932113b7c",
        "destination_path": "/path/to/the/dest/dir"
      }
    }
  },
  "run_owner": "urn:globus:auth:identity:b44bddda-d274-11e5-978a-9f15789a8150",
  "run_managers": [
    "urn:globus:auth:identity:7d6064ef-5368-473a-b15b-e99c3561aa9b"
  ],
  "run_monitors": [
    "urn:globus:auth:identity:58cf49f4-06ea-4b76-934c-d5c9f6c3ea9d",
    "urn:globus:auth:identity:57088a17-d5cb-4cfa-871a-c5cce48f2aec"
  ],
  "user_role": "run_owner",
  "label": "Transfer all of these files!",
  "tags": [
    "my-transfer-run",
    "jazz-fans"
  ],
  "search": {
    "task_id": "20ba91a8-eb90-470a-9477-2ad68808b276"
  }
}

API Info

See Resume Run 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.