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.

class globus_sdk.FlowsClient(*, environment=None, base_url=None, app=None, app_scopes=None, authorizer=None, app_name=None, transport_params=None)[source]

Bases: BaseClient

Client for the Globus Flows API.

Parameters:

  • app (GlobusApp | None) – A GlobusApp which will be used for handling authorization and storing and validating tokens. Passing an app will automatically include a client’s default scopes in the app’s scope requirements unless specific app_scopes are given. If app_name is not given, the app’s app_name will be used. Mutually exclusive with authorizer.

  • app_scopes (list[Scope] | None) – Optional list of Scope objects to be added to app’s scope requirements instead of default_scope_requirements. Requires app.

  • authorizer (GlobusAuthorizer | None) – A GlobusAuthorizer which will generate Authorization headers. Mutually exclusive with app.

  • app_name (str | None) – Optional “nice name” for the application. Has no bearing on the semantics of client actions. It is just passed as part of the User-Agent string, and may be useful when debugging issues with the Globus Team. If both``app`` and app_name are given, this value takes priority.

  • base_url (str | None) – The URL for the service. Most client types initialize this value intelligently by default. Set it when inheriting from BaseClient or communicating through a proxy. This value takes precedence over the class attribute of the same name.

  • transport_params (dict[str, t.Any] | None) – Options to pass to the transport for this client

Methods

scopes

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

>>> FlowsClient.scopes.all

Supported Scopes

  • all

  • manage_flows

  • run

  • run_manage

  • run_status

  • view_flows

create_flow(title, definition, input_schema, subtitle=MISSING, description=MISSING, flow_viewers=MISSING, flow_starters=MISSING, flow_administrators=MISSING, run_managers=MISSING, run_monitors=MISSING, keywords=MISSING, subscription_id=MISSING, additional_fields=None)[source]

Create a flow

Parameters:

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

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

  • input_schema (dict[str, Any]) – A JSON Schema to which flow run input must conform

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

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

  • flow_viewers (list[str] | MissingType) –

    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] | MissingType) –

    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] | MissingType) –

    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"
]

  • run_managers (list[str] | MissingType) –

    A set of Principal URN values indicating entities who can perform management operations on the flow’s runs.

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

  • run_monitors (list[str] | MissingType) –

    A set of Principal URN values indicating entities who can monitor the flow’s runs.

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

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

  • subscription_id (UUID | str | None | MissingType) – The ID of the subscription to associate with the flow, marking as a subscription tier flow.

  • additional_fields (dict[str, Any] | None) – Additional Key/Value pairs sent to the create API

Return type:

GlobusHTTPResponse

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: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"
  ],
  "run_managers": [
    "urn:globus:auth:identity:276721c8-51f3-11f0-b2c3-1695673a3ead"
  ],
  "run_monitors": [
    "urn:globus:auth:identity:27672236-51f3-11f0-b2c3-1695673a3ead"
  ]
}

See Create Flow in the API documentation for details.

get_flow(flow_id, *, query_params=None)[source]

Retrieve a flow by ID

Parameters:

  • flow_id (UUID | str) – The ID of the flow to fetch

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

GlobusHTTPResponse

See Get Flow in the API documentation for details.

list_flows(*, filter_role=MISSING, filter_roles=MISSING, filter_fulltext=MISSING, orderby=MISSING, marker=MISSING, query_params=None)[source]

List deployed flows

Parameters:

  • filter_role (str | MissingType) – (deprecated) A role name specifying the minimum permissions required for a flow to be included in the response. Mutually exclusive with filter_roles.

  • filter_roles (Iterable[str] | str | MissingType) – A list of role names specifying the roles the user must have for a flow to be included in the response. Mutually exclusive with filter_role.

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

  • orderby (Iterable[str] | str | MissingType) – A criterion for ordering flows in the listing

  • marker (str | MissingType) – A marker for pagination

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

IterableFlowsResponse

Role Filters

filter_roles accepts a list of roles which are used to filter the results to flows where the caller has any of the specified roles.

The valid role values are:

  • flow_viewer

  • flow_starter

  • flow_administrator

  • flow_owner

  • run_monitor

  • run_manager

Note

The deprecated filter_role parameter has similar behavior.

filter_role accepts exactly one role name, and filters to flows where the caller has the specified role or a strictly weaker role. For example, filter_role="flow_administrator" will include flows where the caller has the flow_starter role.

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"].

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

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.

See List Flows in the API documentation for details.

update_flow(flow_id, *, title=MISSING, definition=MISSING, input_schema=MISSING, subtitle=MISSING, description=MISSING, flow_owner=MISSING, flow_viewers=MISSING, flow_starters=MISSING, flow_administrators=MISSING, run_managers=MISSING, run_monitors=MISSING, keywords=MISSING, subscription_id=MISSING, additional_fields=None)[source]

Update a flow

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

Parameters:

  • flow_id (UUID | str) – The ID of the flow to fetch

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

  • definition (dict[str, Any] | MissingType) –

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

  • input_schema (dict[str, Any] | MissingType) – A JSON Schema to which flow run input must conform

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

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

  • flow_owner (str | MissingType) – 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] | MissingType) –

    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] | MissingType) –

    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] | MissingType) –

    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"
]

  • run_managers (list[str] | MissingType) –

    A set of Principal URN values indicating entities who can perform management operations on the flow’s runs.

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

  • run_monitors (list[str] | MissingType) –

    A set of Principal URN values indicating entities who can monitor the flow’s runs.

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

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

  • subscription_id (UUID | str | Literal['DEFAULT'] | ~globus_sdk._missing.MissingType) – A subscription ID to assign to the flow.

  • additional_fields (dict[str, Any] | None) – Additional Key/Value pairs sent to the create API

Return type:

GlobusHTTPResponse

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: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"
  ],
  "run_managers": [
    "urn:globus:auth:identity:276721c8-51f3-11f0-b2c3-1695673a3ead"
  ],
  "run_monitors": [
    "urn:globus:auth:identity:27672236-51f3-11f0-b2c3-1695673a3ead"
  ],
  "subscription_id": "00000000-3ba7-456e-9df7-fc40028f3331"
}

See Update Flow in the API documentation for details.

delete_flow(flow_id, *, query_params=None)[source]

Delete a flow

Parameters:

  • flow_id (UUID | str) – The ID of the flow to delete

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

GlobusHTTPResponse

See Delete Flow in the API documentation for details.

validate_flow(definition, input_schema=MISSING)[source]

Validate a flow

Parameters:

  • definition (dict[str, Any]) –

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

  • input_schema (dict[str, Any] | MissingType) – A JSON Schema to which flow run input must conform

Return type:

GlobusHTTPResponse

from globus_sdk import FlowsClient

...
flows = FlowsClient(...)
flows.validate_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"},
        },
    },
)

{
  "scopes": {
    "User": [
      "urn:globus:auth:scope:transfer.api.globus.org:all"
    ]
  }
}

See Validate Flow in the API documentation for details.

list_runs(*, filter_flow_id=MISSING, filter_roles=MISSING, marker=MISSING, query_params=None)[source]

List all runs.

Parameters:
Return type:

IterableRunsResponse

Filter Roles Values

The valid values for role are:

  • run_owner

  • run_manager

  • run_monitor

  • flow_run_manager

  • flow_run_monitor

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

{
  "runs": [
    {
      "run_id": "27671ffc-51f3-11f0-b2c3-1695673a3ead",
      "action_id": "27671ffc-51f3-11f0-b2c3-1695673a3ead",
      "completion_time": "2023-04-11T20:01:22.917000+00:00",
      "created_by": "urn:globus:auth:identity:2767207e-51f3-11f0-b2c3-1695673a3ead",
      "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:2767207e-51f3-11f0-b2c3-1695673a3ead",
            "details": {
              "Hello": "World",
              "hello": "foo"
            },
            "display_status": "SUCCEEDED",
            "label": "My Cool Run",
            "manage_by": [
              "urn:globus:auth:identity:276720f6-51f3-11f0-b2c3-1695673a3ead"
            ],
            "monitor_by": [
              "urn:globus:groups:id:27672164-51f3-11f0-b2c3-1695673a3ead"
            ],
            "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": "27671e76-51f3-11f0-b2c3-1695673a3ead",
      "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:276720f6-51f3-11f0-b2c3-1695673a3ead"
      ],
      "monitor_by": [
        "urn:globus:groups:id:27672164-51f3-11f0-b2c3-1695673a3ead"
      ],
      "run_managers": [
        "urn:globus:auth:identity:276720f6-51f3-11f0-b2c3-1695673a3ead"
      ],
      "run_monitors": [
        "urn:globus:groups:id:27672164-51f3-11f0-b2c3-1695673a3ead"
      ],
      "run_owner": "urn:globus:auth:identity:2767207e-51f3-11f0-b2c3-1695673a3ead",
      "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
}

See List Runs in the API documentation for details.

get_run_logs(run_id, *, limit=MISSING, reverse_order=MISSING, marker=MISSING, query_params=None)[source]

Retrieve the execution logs associated with a run

These logs describe state transitions and associated payloads for a run

Parameters:

  • run_id (UUID | str) – Run ID to retrieve logs for

  • limit (int | MissingType) – Maximum number of log entries to return (server default: 10) (value between 1 and 100 inclusive)

  • reverse_order (bool | MissingType) – Return results in reverse chronological order (server default: false)

  • marker (str | MissingType) – Marker for the next page of results (provided by the server)

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through

Return type:

IterableRunLogsResponse

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.

{
  "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"
        }
      }
    }
  ]
}

See Get Run Logs in the API documentation for details.

get_run(run_id, *, include_flow_description=MISSING, query_params=None)[source]

Retrieve information about a particular run of a flow

Parameters:

  • run_id (UUID | str) – The ID of the run to get

  • include_flow_description (bool | MissingType) – 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[str, Any] | None) – Any additional parameters to be passed through

Return type:

GlobusHTTPResponse

from globus_sdk import FlowsClient

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

{
  "run_id": "27671ffc-51f3-11f0-b2c3-1695673a3ead",
  "action_id": "27671ffc-51f3-11f0-b2c3-1695673a3ead",
  "completion_time": "2023-04-11T20:01:22.917000+00:00",
  "created_by": "urn:globus:auth:identity:2767207e-51f3-11f0-b2c3-1695673a3ead",
  "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:2767207e-51f3-11f0-b2c3-1695673a3ead",
        "details": {
          "Hello": "World",
          "hello": "foo"
        },
        "display_status": "SUCCEEDED",
        "label": "My Cool Run",
        "manage_by": [
          "urn:globus:auth:identity:276720f6-51f3-11f0-b2c3-1695673a3ead"
        ],
        "monitor_by": [
          "urn:globus:groups:id:27672164-51f3-11f0-b2c3-1695673a3ead"
        ],
        "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": "27671e76-51f3-11f0-b2c3-1695673a3ead",
  "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:276720f6-51f3-11f0-b2c3-1695673a3ead"
  ],
  "monitor_by": [
    "urn:globus:groups:id:27672164-51f3-11f0-b2c3-1695673a3ead"
  ],
  "run_managers": [
    "urn:globus:auth:identity:276720f6-51f3-11f0-b2c3-1695673a3ead"
  ],
  "run_monitors": [
    "urn:globus:groups:id:27672164-51f3-11f0-b2c3-1695673a3ead"
  ],
  "run_owner": "urn:globus:auth:identity:2767207e-51f3-11f0-b2c3-1695673a3ead",
  "start_time": "2023-04-11T20:01:18.040416+00:00",
  "status": "SUCCEEDED",
  "tags": [
    "cool",
    "my"
  ],
  "user_role": "run_owner"
}

See Get Run in the API documentation for details.

get_run_definition(run_id)[source]

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

Parameters:

run_id (UUID | str) – The ID of the run to get

Return type:

GlobusHTTPResponse

from globus_sdk import FlowsClient

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

{
  "flow_id": "56a8b4a4-4945-402f-88fb-250716abaaec",
  "definition": {
    "States": {
      "no-op": {
        "End": true,
        "Type": "Pass"
      }
    },
    "StartAt": "no-op"
  },
  "input_schema": {}
}

See Get Run Definition in the API documentation for details.

cancel_run(run_id)[source]

Cancel a run.

Parameters:

run_id (UUID | str) – The ID of the run to cancel

Return type:

GlobusHTTPResponse

from globus_sdk import FlowsClient

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

{
  "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"
  }
}

See Cancel Run in the API documentation for details.

update_run(run_id, *, label=MISSING, tags=MISSING, run_monitors=MISSING, run_managers=MISSING, additional_fields=None)[source]

Update the metadata of a specific run.

Parameters:

  • run_id (UUID | str) – The ID of the run to update

  • label (str | MissingType) – A short human-readable title (1 - 64 chars)

  • tags (list[str] | MissingType) – 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 (list[str] | MissingType) – A list of authenticated entities (identified by URN) authorized to view this run in addition to the run owner

  • run_managers (list[str] | MissingType) – A list of authenticated entities (identified by URN) authorized to view & cancel this run in addition to the run owner

  • additional_fields (dict[str, Any] | None) – Additional Key/Value pairs sent to the run API (this parameter is used to bypass local sdk key validation helping)

Return type:

GlobusHTTPResponse

from globus_sdk import FlowsClient

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

{
  "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"
  }
}

See Update Run in the API documentation for details.

delete_run(run_id)[source]

Delete a run.

Parameters:

run_id (UUID | str) – The ID of the run to delete

Return type:

GlobusHTTPResponse

from globus_sdk import FlowsClient

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

{
  "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"
  }
}

See Delete Run in the API documentation for details.

class globus_sdk.SpecificFlowClient(flow_id, *, environment=None, app=None, app_scopes=None, authorizer=None, app_name=None, transport_params=None)[source]

Bases: BaseClient

Client for interacting with a specific flow through the Globus 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 (UUIDLike) – The generated UUID associated with a flow

  • app (GlobusApp | None) – A GlobusApp which will be used for handling authorization and storing and validating tokens. Passing an app will automatically include a client’s default scopes in the app’s scope requirements unless specific app_scopes are given. If app_name is not given, the app’s app_name will be used. Mutually exclusive with authorizer.

  • app_scopes (list[Scope] | None) – Optional list of Scope objects to be added to app’s scope requirements instead of default_scope_requirements. Requires app.

  • authorizer (GlobusAuthorizer | None) – A GlobusAuthorizer which will generate Authorization headers. Mutually exclusive with app.

  • app_name (str | None) – Optional “nice name” for the application. Has no bearing on the semantics of client actions. It is just passed as part of the User-Agent string, and may be useful when debugging issues with the Globus Team. If both``app`` and app_name are given, this value takes priority.

  • base_url – The URL for the service. Most client types initialize this value intelligently by default. Set it when inheriting from BaseClient or communicating through a proxy. This value takes precedence over the class attribute of the same name.

  • transport_params (dict[str, t.Any] | None) – Options to pass to the transport for this client

Methods

scopes: SpecificFlowScopes = <globus_sdk.scopes.data.flows._SpecificFlowScopesClassStub object>

the scopes for this client may be present as a ScopeCollection

property default_scope_requirements: list[Scope]

Scopes that will automatically be added to this client’s app’s scope_requirements during _finalize_app.

For clients with static scope requirements this can just be a static value. Clients with dynamic requirements should use @property and must return sane results while the Base Client is being initialized.

add_app_transfer_data_access_scope(collection_ids)[source]

Add a dependent data_access scope for one or more given collection_ids to this client’s GlobusApp, under the Transfer all scope. Useful for preventing ConsentRequired errors when starting or resuming runs of flows that use Globus Connect Server mapped collection(s).

Warning

This method must only be used on collection_ids for non-High-Assurance GCS Mapped Collections.

Use on other collection types, e.g., on GCP Mapped Collections or any form of Guest Collection, will result in “Unknown Scope” errors during the login flow.

Returns self for chaining.

Raises GlobusSDKUsageError if this client was not initialized with an app.

Parameters:

collection_ids (UUID | str | Iterable[UUID | str]) – a collection ID or an iterable of IDs.

Return type:

Self

flow_id = ...
COLLECTION_ID = ...
app = UserApp("myapp", client_id=NATIVE_APP_CLIENT_ID)
client = SpecificFlowClient(FLOW_ID, app=app).add_app_transfer_data_access_scope(
    COLLECTION_ID
)

client.run_flow({"collection": COLLECTION_ID})
run_flow(body, *, label=MISSING, tags=MISSING, activity_notification_policy=MISSING, run_monitors=MISSING, run_managers=MISSING, additional_fields=None)[source]
Parameters:

  • body (dict[str, Any]) – 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 (str | MissingType) – A short human-readable title (1 - 64 chars)

  • tags (list[str] | MissingType) – 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.

  • activity_notification_policy (dict[str, Any] | RunActivityNotificationPolicy | MissingType) – A policy document which declares when the run will send notification emails. By default, notifications are only sent when a run status changes to "INACTIVE".

  • run_monitors (list[str] | MissingType) – A list of authenticated entities (identified by URN) authorized to view this run in addition to the run owner

  • run_managers (list[str] | MissingType) – A list of authenticated entities (identified by URN) authorized to view & cancel this run in addition to the run owner

  • additional_fields (dict[str, Any] | None) – Additional Key/Value pairs sent to the run API (this parameter is used to bypass local sdk key validation helping)

Return type:

GlobusHTTPResponse

See Run Flow in the API documentation for details.

resume_run(run_id)[source]
Parameters:

run_id (UUID | str) – The ID of the run to resume

Return type:

GlobusHTTPResponse

from globus_sdk import SpecificFlowClient

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

{
  "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"
  }
}

See Resume Run in the API documentation for details.

validate_run(body, *, label=MISSING, tags=MISSING, run_monitors=MISSING, run_managers=MISSING, activity_notification_policy=MISSING, additional_fields=None)[source]
Parameters:

  • body (dict[str, Any]) – The parameters to validate against the flow’s input schema.

  • label (str | MissingType) – A short human-readable title.

  • tags (list[str] | MissingType) – 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 (list[str] | MissingType) – A list of Globus Auth principals (identified by URN) authorized to monitor this run (in addition to the run owner).

  • run_managers (list[str] | MissingType) – A list of Globus Auth principals (identified by URN) authorized to manage this run (in addition to the run owner).

  • activity_notification_policy (dict[str, Any] | RunActivityNotificationPolicy | MissingType) – A policy document which declares when the Flows service will send notification emails regarding the run’s activity.

  • additional_fields (dict[str, Any] | None) – Additional key/value pairs sent to the run API. This parameter can be used to bypass SDK parameter validation.

Return type:

GlobusHTTPResponse

from globus_sdk import SpecificFlowClient

...
flow = SpecificFlowClient(flow_id, ...)
flow.validate_run(body={"param": "value"})

{
  "message": "validation successful"
}

Client Errors

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

class globus_sdk.FlowsAPIError(r, *args, **kwargs)[source]

Bases: GlobusAPIError

Error class to represent error responses from Flows.

Helper Objects

RunActivityNotificationPolicy objects encode the data for activity_notification_policy when run_flow is called. Using the helper object allows you to have typing-time validation of your data when calling this API.

class globus_sdk.RunActivityNotificationPolicy(status=MISSING)[source]

Bases: GlobusPayload

A notification policy for a run, determining when emails will be sent.

Parameters:

status (list[t.Literal['INACTIVE', 'SUCCEEDED', 'FAILED']] | MissingType) – A list of statuses which will trigger notifications. When the run’s status changes, it is evaluated against this list. If the new status matches the policy, an email is sent.

Responses

class globus_sdk.IterableFlowsResponse(response, client=None, *, iter_key=None)[source]

Bases: IterableResponse

An iterable response containing a “flows” array.