Python SDK Reference#

The Globus Automate Client package provides a Python SDK for interfacing with and invoking Globus actions and flows. Below, we provide information on helper functions available for creating authenticated action and flow clients as well as documentation on the methods available to those clients.

Actions Client#

class globus_automate_client.action_client.ActionClient(*args, **kwargs)#

Parameters

args (Any) –
kwargs (Any) –

Return type

Any

property action_scope: str#: This property can be used to determine an ActionClient’s action_scope. Internally, this property will introspect the Action Provider at the URL for which the ActionClient was created. If the Action Provider is not public, a valid Globus Authorizer will have to have been provided on initialization to the ActionClient. Otherwise, this call will fail.

introspect(**_)#

Introspect the details of an Action Provider to discover information such as its expected action_scope, its input_schema, and who to contact when there’s trouble.

Return type: globus_sdk.GlobusHTTPResponse

run(body, request_id=None, manage_by=None, monitor_by=None, label=None, tags=None, force_path=None, **kwargs)#

Invoke the Action Provider to execute an Action with the given parameters.

Parameters

body (Mapping[str, Any]) – The Action Provider specific input required to execute an Action payload
request_id (Optional[str]) – An optional identifier that serves to de-duplicate requests to the Action Provider
manage_by (Optional[Iterable[str]]) – A series of Globus identities which may alter this Action’s execution. The principal value is the user’s or group’s UUID prefixed with either ‘urn:globus:groups:id:’ or ‘urn:globus:auth:identity:’
monitor_by (Optional[Iterable[str]]) – A series of Globus identities which may view the state of this Action. The principal value is the user’s or group’s UUID prefixed with either ‘urn:globus:groups:id:’ or ‘urn:globus:auth:identity:’
force_path (Optional[str]) – A URL to use for running this action, ignoring any previous configuration
label (Optional[str]) – Set a label for the Action that is run.
tags (Optional[List[str]]) – A list of tags to associate with the Run.
run_monitors – May be used as an alias for monitor_by
run_managers – May be used as an alias for manage_by

Return type

globus_sdk.GlobusHTTPResponse

status(action_id)#

Query the Action Provider for the status of executed Action

Parameters: action_id (str) – An identifier that uniquely identifies an Action executed on this Action Provider.
Return type: globus_sdk.GlobusHTTPResponse

get_definition(action_id)#

Get the flow definition for a given run ID.

Parameters: action_id (str) – An identifier that uniquely identifies an Action executed on this Action Provider.
Return type: globus_sdk.GlobusHTTPResponse

resume(action_id)#

Resume an INACTIVE action. Corrective action must have been taken prior to invoking this method, including the possibility of consenting to additional permissions and using tokens issued by those consents when creating this client. These consents would commonly be required when an Action is INACTIVE and shows the code ConsentRequired.

Parameters: action_id (str) – An identifier that uniquely identifies an Action executed on this Action Provider.
Return type: globus_sdk.GlobusHTTPResponse

cancel(action_id)#

Cancel a currently executing Action on an Action Provider

Parameters: action_id (str) – An identifier that uniquely identifies an Action executed on this Action Provider.
Return type: globus_sdk.GlobusHTTPResponse

release(action_id)#

Remove the history of an Action’s execution from an Action Provider

Parameters: action_id (str) – An identifier that uniquely identifies an Action executed on this Action Provider.
Return type: globus_sdk.GlobusHTTPResponse

log(action_id, limit=10, reverse_order=False, marker=None, per_page=None)#

Retrieve an Action’s execution log history. Not all Action Providers support this operation.

Parameters

action_id (str) – An identifier that uniquely identifies an Action executed on this Action Provider.
limit (int) – A integer specifying how many log records to return
reverse_order (bool) – Display the Action states in reverse- chronological order
marker (Optional[str]) – A pagination_token indicating the page of results to return and how many entries to return. Not all ActionProviders will support this parameter.
per_page (Optional[int]) – The number of results to return per page. If supplied a pagination_token, this parameter has no effect. Not all ActionProviders will support this parameter.

Return type

globus_sdk.GlobusHTTPResponse

classmethod new_client(action_url, authorizer, http_timeout=10)#

Classmethod to simplify creating an ActionClient. Use this method when attemping to create an ActionClient with pre-existing credentials or authorizers.

Parameters

action_url (str) – The url at which the target Action Provider is located.
authorizer (Optional[globus_sdk.authorizers.GlobusAuthorizer]) – The authorizer to use for validating requests to the Action Provider.
http_timeout (int) – The amount of time to wait for connections to the Action Provider to be made.

Return type

_ActionClient

Examples

>>> auth = ...
>>> url = "https://actions.globus.org/hello_world"
>>> ac = ActionClient.new_client(url, auth)
>>> print(ac.run({"echo_string": "Hello from SDK"}))

Flows Client#

class globus_automate_client.flows_client.FlowsClient(*args, **kwargs)#

This is a specialized type of the Globus Auth service’s BaseClient used to interact with the Globus Flows service. Any keyword arguments given are passed through to the BaseClient constructor.

Parameters

args (Any) –
kwargs (Any) –

Return type

Any

use_temporary_authorizer(authorizer)#

Temporarily swap out the authorizer instance variable.

This is a context manager. Use it like this:

authorizer = self._get_authorizer_for_flow(...)
with self.alternate_authorizer(authorizer):
    ...

deploy_flow(flow_definition, title, subtitle=None, description=None, keywords=(), flow_viewers=(), flow_starters=(), flow_administrators=(), subscription_id=None, input_schema=None, validate_definition=True, validate_schema=True, dry_run=False, **kwargs)#

Deploys a Flow definition to the Flows service, making the Flow available for execution on the Globus Automate Flows Service.

Parameters

flow_definition (Mapping[str, Any]) – A mapping corresponding to a Globus Flows definition.
title (str) – A simple, human-readable title for the deployed Flow
subtitle (Optional[str]) – A longer, more verbose title for the deployed Flow
description (Optional[str]) – A long form explanation of the Flow’s purpose or usage
keywords (Iterable[str]) – A series of words which may help categorize or make the Flow discoverable
flow_viewers (Iterable[str]) – A series of Globus identities which may discover and view the Flow definition
flow_starters (Iterable[str]) – A series of Globus identities which may run an instance of this Flow
flow_administrators (Iterable[str]) – A series of Globus identities which may update this Flow’s definition
subscription_id (Optional[str]) – The Globus Subscription which will be used to make this flow managed.
input_schema (Optional[Mapping[str, Any]]) – A mapping representing the JSONSchema used to validate input to this Flow. If not supplied, no validation will be done on input to this Flow.
validate_definition (bool) – Set to True to validate the provided flow_definition before attempting to deploy the Flow.
validate_schema (bool) – Set to True to validate the provided input_schema before attempting to deploy the Flow.
dry_run (bool) – Set to True to test whether the Flow can be deployed successfully.

Return type

globus_sdk.GlobusHTTPResponse

update_flow(flow_id, flow_definition=None, title=None, subtitle=None, description=None, keywords=None, flow_viewers=None, flow_starters=None, flow_administrators=None, subscription_id=None, input_schema=None, validate_definition=True, validate_schema=True, **kwargs)#

Updates a deployed Flow’s definition or metadata. This method will preserve the existing Flow’s values for fields which are not submitted as part of the update.

Parameters

flow_id (str) – The UUID for the Flow that will be updated
flow_definition (Optional[Mapping[str, Any]]) – A mapping corresponding to a Globus Flows definition
title (Optional[str]) – A simple, human-readable title for the deployed Flow
subtitle (Optional[str]) – A longer, more verbose title for the deployed Flow
description (Optional[str]) – A long form explanation of the Flow’s purpose or usage
keywords (Optional[Iterable[str]]) – A series of words which may help categorize or make the Flow discoverable
flow_viewers (Optional[Iterable[str]]) – A series of Globus identities which may discover and view the Flow definition
flow_starters (Optional[Iterable[str]]) – A series of Globus identities which may run an instance of this Flow
flow_administrators (Optional[Iterable[str]]) – A series of Globus identities which may update this Flow’s definition
subscription_id (Optional[str]) – The Globus Subscription which will be used to make this flow managed.
input_schema (Optional[Mapping[str, Any]]) – A mapping representing the JSONSchema used to validate input to this Flow. If not supplied, no validation will be done on input to this Flow.
validate_definition (bool) – Set to True to validate the provided flow_definition before attempting to update the Flow.
validate_schema (bool) – Set to True to validate the provided input_schema before attempting to update the Flow.

Return type

globus_sdk.GlobusHTTPResponse

get_flow(flow_id, **kwargs)#

Retrieve a deployed Flow’s definition and metadata

Parameters: flow_id (str) – The UUID identifying the Flow for which to retrieve details
Return type: globus_sdk.GlobusHTTPResponse

list_flows(roles=None, marker=None, per_page=None, filters=None, orderings=None, role=None, **kwargs)#

Display all deployed Flows for which you have the selected role(s)

Parameters

roles (Optional[Iterable[str]]) –

Deprecated since version 0.12: Use role instead

See description for role parameter. Providing multiple roles behaves as if only a single role value is provided and displays the equivalent of the most permissive role.
role (Optional[str]) –
A role value specifying the minimum role-level permission which will be displayed based on the follow precedence of role values:
- flow_viewer
- flow_starter
- flow_administrators
- flow_owner
Thus, if, for example, flow_starter is specified, flows for which the user has the flow_starter, flow_administrator or flow_owner roles will be returned.
marker (Optional[str]) – A pagination_token indicating the page of results to return and how many entries to return. This is created by the Flows service and returned by operations that support pagination.
per_page (Optional[int]) – The number of results to return per page. If supplied a pagination_token, this parameter has no effect.
filters (Optional[dict]) – A filtering criteria to apply to the resulting Flow listing. The keys indicate the filter, the values indicate the pattern to match. The returned data will be the result of a logical AND between the filters. Patterns may be comma separated to produce the result of a logical OR.
orderings (Optional[dict]) – An ordering criteria to apply to the resulting Flow listing. The keys indicate the field to order on, and the value can be either ASC, for ascending order, or DESC, for descending order. The first ordering criteria will be used to sort the data, subsequent ordering criteria will be applied for ties. Note: To ensure orderings are applied in the correct order, use an OrderedDict if trying to apply multiple orderings.

Return type

globus_sdk.GlobusHTTPResponse

delete_flow(flow_id, **kwargs)#

Remove a Flow definition and its metadata from the Flows service

Parameters: flow_id (str) – The UUID identifying the Flow to delete
Return type: globus_sdk.GlobusHTTPResponse

scope_for_flow(flow_id)#

Returns the scope associated with a particular Flow

Parameters: flow_id (str) – The UUID identifying the Flow’s scope to lookup
Return type: str

run_flow(flow_id, flow_scope, flow_input, run_managers=None, run_monitors=None, dry_run=False, label=None, tags=None, **kwargs)#

Run an instance of a deployed Flow with the given input.

Parameters

flow_id (str) – The UUID identifying the Flow to run
flow_scope (Optional[str]) – The scope associated with the Flow flow_id. If not provided, the SDK will attempt to perform an introspection on the Flow to determine its scope automatically
flow_input (Mapping) – A Flow-specific dictionary specifying the input required for the Flow to run.
run_managers (Optional[Iterable[str]]) – A series of Globus identities which may alter this Flow instance’s execution. The principal value is the user’s or group’s UUID prefixed with either ‘urn:globus:groups:id:’ or ‘urn:globus:auth:identity:’
run_monitors (Optional[Iterable[str]]) – A series of Globus identities which may view this Flow instance’s execution state. The principal value is the user’s or group’s UUID prefixed with either ‘urn:globus:groups:id:’ or ‘urn:globus:auth:identity:’
label (Optional[str]) – An optional label which can be used to identify this run
tags (Optional[List[str]]) – Tags that will be associated with this Run.
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.
dry_run (bool) – Set to True to test what will happen if the Flow is run without actually running the Flow.

Return type

globus_sdk.GlobusHTTPResponse

flow_action_status(flow_id, flow_scope, flow_action_id, **kwargs)#

Determine the status for an Action that was launched by a Flow

Parameters

flow_id (str) – The UUID identifying the Flow which triggered the Action
flow_scope (Optional[str]) – The scope associated with the Flow flow_id. If not provided, the SDK will attempt to perform an introspection on the Flow to determine its scope automatically
flow_action_id (str) – The ID specifying which Action’s status to query
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.

Return type

globus_sdk.GlobusHTTPResponse

get_flow_definition_for_run(flow_id, flow_scope, flow_action_id, **kwargs)#

Determine the status for an Action that was launched by a Flow

Parameters

flow_id (str) – The UUID identifying the Flow which triggered the Action
flow_scope (Optional[str]) – The scope associated with the Flow flow_id. If not provided, the SDK will attempt to perform an introspection on the Flow to determine its scope automatically
flow_action_id (str) – The ID specifying which Action’s status to query
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.

Return type

globus_sdk.GlobusHTTPResponse

flow_action_resume(flow_id, flow_scope, flow_action_id, **kwargs)#

Resume a Flow Action which is in an INACTIVE state.

Parameters

flow_id (str) – The UUID identifying the Flow which triggered the Action
flow_scope (Optional[str]) – The scope associated with the Flow flow_id. If not provided, the SDK will attempt to perform an introspection on the Flow to determine its scope automatically.
flow_action_id (str) – The ID specifying the Action with an INACTIVE status we want to resume.
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.

Return type

globus_sdk.GlobusHTTPResponse

flow_action_release(flow_id, flow_scope, flow_action_id, **kwargs)#

Remove the execution history for an Action that was launched by a Flow

Parameters

flow_id (str) – The UUID identifying the Flow which launched the Action
flow_scope (Optional[str]) – The scope associated with the Flow flow_id. If not provided, the SDK will attempt to perform an introspection on the Flow to determine its scope automatically
flow_action_id (str) – The ID specifying the Action to release
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.

Return type

globus_sdk.GlobusHTTPResponse

flow_action_cancel(flow_id, flow_scope, flow_action_id, **kwargs)#

Cancel the execution of an Action that was launched by a Flow

Parameters

flow_id (str) – The UUID identifying the Flow which launched the Action
flow_scope (Optional[str]) – The scope associated with the Flow flow_id. If not provided, the SDK will attempt to perform an introspection on the Flow to determine its scope automatically
flow_action_id (str) – The ID specifying the Action we want to cancel
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.

Return type

globus_sdk.GlobusHTTPResponse

enumerate_runs(roles=None, statuses=None, marker=None, per_page=None, filters=None, orderings=None, role=None, **kwargs)#

Retrieve a listing of Runs the caller has access to. This operation requires the supplied Authorizer to have the RUN_STATUS_SCOPE.

Parameters

statuses (Optional[Iterable[str]]) –
A list of statuses used to filter the Actions that are returned by the listing. Returned Actions are guaranteed to have one of the specified statuses. Valid values are:
- SUCCEEDED
- FAILED
- ACTIVE
- INACTIVE
roles (Optional[Iterable[str]]) –

Deprecated since version 0.12: Use role instead

See description for role parameter. Providing multiple roles behaves as if only a single role value is provided and displays the equivalent of the most permissive role.
role (Optional[str]) –
A role value specifying the minimum role-level permission on the runs which will be returned based on the follow precedence of role values:
- run_monitor
- run_manager
- run_owner
Thus, if, for example, run_manager is specified, runs for which the user has the run_manager, or run_owner roles will be returned.
marker (Optional[str]) – A pagination_token indicating the page of results to return and how many entries to return. This is created by the Flows service and returned by operations that support pagination.
per_page (Optional[int]) – The number of results to return per page. If supplied a pagination_token, this parameter has no effect.
filters (Optional[dict]) – A filtering criteria to apply to the resulting Action listing. The keys indicate the filter, the values indicate the pattern to match. The returned data will be the result of a logical AND between the filters. Patterns may be comma separated to produce the result of a logical OR.
orderings (Optional[dict]) – An ordering criteria to apply to the resulting Action listing. The keys indicate the field to order on, and the value can be either ASC, for ascending order, or DESC, for descending order. The first ordering criteria will be used to sort the data, subsequent ordering criteria will be applied for ties. Note: To ensure orderings are applied in the correct order, use an OrderedDict if trying to apply multiple orderings.

Return type

globus_sdk.GlobusHTTPResponse

enumerate_actions(**kwargs)#

An alias for enumerate_runs

Return type: globus_sdk.GlobusHTTPResponse

list_flow_actions(**kwargs)#

An alias for list_flow_runs

Return type: globus_sdk.GlobusHTTPResponse

list_flow_runs(flow_id=None, flow_scope=None, statuses=None, roles=None, marker=None, per_page=None, filters=None, orderings=None, role=None, **kwargs)#

List all Runs for a particular Flow.

If no flow_id is provided, all runs for all Flows will be returned.

Parameters

flow_id (Optional[str]) – The UUID identifying the Flow which launched the Run. If not provided, all runs will be returned regardless of which Flow was used to start the Run (equivalent to enumerate_runs).
flow_scope (Optional[str]) – The scope associated with the Flow flow_id. If not provided, the SDK will attempt to perform an introspection on the Flow to determine its scope automatically
statuses (Optional[Iterable[str]]) – The same as in enumerate_runs.
roles (Optional[Iterable[str]]) –

Deprecated since version 0.12: Use role instead

The same as in enumerate_runs.
marker (Optional[str]) – The same as in enumerate_runs.
per_page (Optional[int]) – The same as in enumerate_runs.
filters (Optional[dict]) – The same as in enumerate_runs.
orderings (Optional[dict]) – The same as in enumerate_runs.
role (Optional[str]) – The same as in enumerate_runs.
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.

Return type

globus_sdk.GlobusHTTPResponse

flow_action_update(action_id, run_managers=None, run_monitors=None, tags=None, label=None, **kwargs)#

Update a Flow Action.

Parameters

action_id (str) – The UUID identifying the Action to update
run_managers (Optional[Sequence[str]]) – A list of Globus Auth URNs which will have the ability to alter the execution of the Action. Supplying an empty list will remove all existing managers.
run_monitors (Optional[Sequence[str]]) – A list of Globus Auth URNs which will have the ability to view the execution of the Action. Supplying an empty list will remove all existing monitors.
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.
tags (Optional[Sequence[str]]) – A list of tags to apply to the Run.
label (Optional[str]) – A label to apply to the Run.

Return type

globus_sdk.GlobusHTTPResponse

update_runs(run_ids, add_tags=None, remove_tags=None, set_tags=None, add_run_managers=None, remove_run_managers=None, set_run_managers=None, add_run_monitors=None, remove_run_monitors=None, set_run_monitors=None, status=None, **kwargs)#

Update a Flow Action.

Parameters

run_ids (Iterable[str]) – A list of Run ID’s to query.
set_tags (Optional[Iterable[str]]) –
A list of tags to set on the specified Run ID’s.

If the list is empty, all tags will be deleted from the specified Run ID’s.

Note

The set_tags, add_tags, and remove_tags arguments are mutually exclusive.
add_tags (Optional[Iterable[str]]) –
A list of tags to add to each of the specified Run ID’s.

Note

The set_tags, add_tags, and remove_tags arguments are mutually exclusive.
remove_tags (Optional[Iterable[str]]) –
A list of tags to remove from each of the specified Run ID’s.

Note

The set_tags, add_tags, and remove_tags arguments are mutually exclusive.
set_run_managers (Optional[Iterable[str]]) –
A list of Globus Auth URN’s to set on the specified Run ID’s.

If the list is empty, all Run managers will be deleted from the specified Run ID’s.

Note

The set_run_managers, add_run_managers, and remove_run_managers arguments are mutually exclusive.
add_run_managers (Optional[Iterable[str]]) –
A list of Globus Auth URN’s to add to each of the specified Run ID’s.

Note

The set_run_managers, add_run_managers, and remove_run_managers arguments are mutually exclusive.
remove_run_managers (Optional[Iterable[str]]) –
A list of Globus Auth URN’s to remove from each of the specified Run ID’s.

Note

The set_run_managers, add_run_managers, and remove_run_managers arguments are mutually exclusive.
set_run_monitors (Optional[Iterable[str]]) –
A list of Globus Auth URN’s to set on the specified Run ID’s.

If the list is empty, all Run monitors will be deleted from the specified Run ID’s.

Note

The set_run_monitors, add_run_monitors, and remove_run_monitors arguments are mutually exclusive.
add_run_monitors (Optional[Iterable[str]]) –
A list of Globus Auth URN’s to add to each of the specified Run ID’s.

Note

The set_run_monitors, add_run_monitors, and remove_run_monitors arguments are mutually exclusive.
remove_run_monitors (Optional[Iterable[str]]) –
A list of Globus Auth URN’s to remove from each of the specified Run ID’s.

Note

The set_run_monitors, add_run_monitors, and remove_run_monitors arguments are mutually exclusive.
status (Optional[str]) – A status to set for all specified Run ID’s.
kwargs –
Any additional keyword arguments passed to this method are passed to the Globus BaseClient.

If an “authorizer” keyword argument is passed, it will be used to authorize the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.

Raises

ValueError – If more than one mutually-exclusive argument is provided. For example, if set_tags and add_tags are both specified, or if add_run_managers and remove_run_managers are both specified.

Return type

globus_sdk.GlobusHTTPResponse

flow_action_log(flow_id, flow_scope, flow_action_id, limit=10, reverse_order=False, marker=None, per_page=None, **kwargs)#

Retrieve an Action’s execution log history for an Action that was launched by a specific Flow.

Parameters

flow_id (str) – The UUID identifying the Flow which launched the Action
flow_scope (str) – The scope associated with the Flow flow_id. If not provided, the SDK will attempt to perform an introspection on the Flow to determine its scope automatically
flow_action_id (str) – The ID specifying which Action’s history to query
limit (int) – An integer specifying the maximum number of records for the Action’s execution history to return.
reverse_order (bool) – An indicator for whether to retrieve the records in reverse-chronological order.
marker (Optional[str]) – A pagination_token indicating the page of results to return and how many entries to return. This is created by the Flows service and returned by operations that support pagination.
per_page (Optional[int]) – The number of results to return per page. If supplied a pagination_token, this parameter has no effect.
kwargs – Any additional kwargs passed into this method are passed onto the Globus BaseClient. If there exists an “authorizer” keyword argument, that gets used to run the Flow operation. Otherwise, the authorizer_callback defined for the FlowsClient will be used.

Return type

globus_sdk.GlobusHTTPResponse

classmethod new_client(client_id, authorizer_callback, authorizer, base_url=None, http_timeout=10)#

Classmethod to simplify creating an FlowsClient. Use this method when attemping to create a FlowsClient with pre-existing credentials or authorizers. This method is useful when creating a FlowClient for interacting with a Flow without wanting to launch an interactive login process.

Parameters

client_id (str) – The client_id to associate with this FlowsClient.
authorizer_callback (Callable[[...], Union[globus_sdk.AccessTokenAuthorizer, globus_sdk.RefreshTokenAuthorizer, globus_sdk.ClientCredentialsAuthorizer]]) – A callable which is capable of returning an authorizer for a particular Flow. The callback should accept three keyword-args: flow_url, flow_scope, client_id. Using some, all, or none of these args, the callback should return a GlobusAuthorizer which provides access to the targetted Flow.
authorizer (Optional[globus_sdk.authorizers.GlobusAuthorizer]) – The authorizer to use for validating requests to the Flows service. This authorizer is used when interacting with the Flow’s service, it is not used for interactive with a particular flow. Therefore, this authorizer should grant consent to the MANAGE_FLOWS_SCOPE. For interacting with a particular flow, set the authorizer_callback parameter.
base_url (Optional[str]) – The url at which the target Action Provider is located.
http_timeout (int) – The amount of time to wait for connections to the Action Provider to be made.

Return type

_FlowsClient

Examples

>>> def cli_authorizer_callback(**kwargs):
        flow_url = kwargs["flow_url"]
        flow_scope = kwargs["flow_scope"]
        client_id = kwargs["client_id"]
        return get_cli_authorizer(flow_url, flow_scope, client_id)
>>> action_url = "https://actions.globus.org/hello_world"
>>> client_id = "00000000-0000-0000-0000-000000000000"
>>> auth = ...
>>> fc = FlowsClient.new_client(client_id, cli_authorizer_callback, auth)
>>> print(fc.list_flows())

Helpers#

If you’re running the SDK locally in a secure location, you can use the provided convenience functions, create_action_client and create_flows_client, to create authenticated ActionClient and FlowsClient instances. These helpers share functionality with the globus-automate CLI to handle loading and storing Globus Auth tokens on the local filesystem. They will also trigger interactive logins when additional consents are required to interact with actions or flows.

globus_automate_client.create_action_client(action_url, action_scope=None, client_id='e6c75d97-532a-4c88-b031-8584a319fa3e')#

A helper function to handle creating a properly authenticated ActionClient which can operate against Globus Action Provider Interface compliant Action Providers. This helper will create an ActionClient by searching for and storing tokens on the local filesystem, potentially triggering a log-in flow if the requested tokens are not found locally.

Given the action_url for a specific ActionProvider, this function will attempt to create a valid ActionClient for interacting with that ActionProvider. If the action_scope is not provided, this function will attempt to discover the action_scope by querying the target Action Provider’s introspection endpoint. If the Action Provider is not configured to allow public, unauthenticated access to its introspection endpoint, the action_scope will be non-discoverable and authentication will fail.

With the action_scope available, the function will search for a valid token in the local filesystem cache. In the event that tokens for the scope cannot be loaded, an interactive login will be triggered. Once tokens have been loaded, an Authorizer is created and used to instantiate the ActionClient which can be used for operations against that Action Provider.

Parameters

action_url (str) – The URL address at which the target Action Provider exists
action_scope (Optional[str]) – The target Action Provider’s Globus Auth Scope used for authenticating access to it
client_id (str) – The ID for the Native App Auth Client which will be triggering the login flow for this ActionClient

Return type

ActionClient

Examples

>>> from globus_automate_client import create_action_client
>>> # Create an ActionClient for the HelloWorld Action
>>> ac = create_action_client("https://actions.globus.org/hello_world")
>>> # Run an Action and check its results
>>> resp = ac.run({"echo_string": "Hello from SDK"})
>>> assert resp.data["status"] == "SUCCEEDED"

globus_automate_client.create_flows_client(client_id='e6c75d97-532a-4c88-b031-8584a319fa3e', base_url='https://flows.globus.org', scope='https://auth.globus.org/scopes/eec9b274-0c81-4334-bdc2-54e90e689b9a/manage_flows', *, authorizer=None, authorizer_callback=<function cli_authorizer_callback>, http_timeout=10)#

A helper function to handle creating a properly authenticated FlowsClient which can operate against the Globus Automate Flows service. This function will attempt to load tokens for the MANAGE_FLOWS_SCOPE``from the local filesystem, triggering a log-in if the requested tokens are not found locally. Once tokens have been loaded, an Authorizer is created and used to instantiate the ``FlowsClient. Attempts to interact with a specific Flow will similarly search for valid tokens in the local cache, triggering an interactive log-in if they cannot be found.

Parameters

scope (str) – The Globus Auth scope to which the FlowsClient should be created with consents to
client_id (str) – The Globus ID to associate with this instance of the FlowsClient
base_url (str) – The URL at which the Globus Automate Flows service is located
authorizer (Optional[globus_sdk.authorizers.GlobusAuthorizer]) – An authorizer providing access to the Flows service. If not provided, it will be created using the authorizer_callback
authorizer_callback (Callable) – A callback used to dynamically return GlobusAuthorizers. If not provided, the Globus Automate CLI callback will be used which triggers interactive logins and stores tokens locally
http_timeout (int) – Close any requests taking longer than this parameter’s value

Return type

FlowsClient

Examples

>>> from globus_automate_client import create_flows_client
>>> # Create an authenticated FlowsClient that can run operations against the Flows
>>> # service
>>> fc = create_flows_client()
>>> # Get a listing of runnable, deployed flows
>>> available_flows = fc.list_flows(["runnable_by"])
>>> for flow in available_flows.data["flows"]:
>>>     print(flow)

Examples#

Non-interactive Operations#

There are plenty of scenarios in which the create_action_client and create_flows_client helper functions should NOT be used, included in those are:

The SDK is being run on a platform without access to the local filesystem (or it is preferable not to write to the local filesystem).
You do not want to (or cannot) trigger interactive logins during execution.
The SDK is being used as part of another service or in a pipeline

In this case, you’ll need to create the clients using the new_client classmethod attached to each client. When creating an ActionClient, you’ll need to create and supply the appropriate GlobusAuthorizer for the action.

When creating a FlowsClient, you’ll need to create a GlobusAuthorizer with access to the MANAGE_FLOWS_SCOPE. This authorizer will be used to authenticate interactions against the Flows API, such as creating a new Flow, updating an existing Flow, or deleting an old Flow. Additionally, you’ll need to create a callback that accepts three keyword-arguments, flow_url, flow_scope and client_id and returns a GlobusAuthorizer that will be used to provide access to specific Flows. This authorizer allows the SDK to run operations against the Flow, such as running a Flow and checking an execution’s status.

The example below shows an example defining the callback used to create a GlobusAuthorizer by pulling tokens from environment variables.

import os

from globus_sdk import AccessTokenAuthorizer

from globus_automate_client import FlowsClient
from globus_automate_client.cli.auth import CLIENT_ID
from globus_automate_client.flows_client import AllowedAuthorizersType


def authorizer_retriever(
    flow_url: str, flow_scope: str, client_id: str
) -> AllowedAuthorizersType:
    """
    This callback will be called when attempting to interact with a
    specific Flow. The callback will receive the Flow url, Flow scope, and
    client_id and can choose to use some, all or none of the kwargs. This is
    expected to return an Authorizer which can be used to make authenticated
    calls to the Flow.

    The method used to acquire valid credentials is up to the user. Here, we
    naively create an Authorizer using the same token everytime.
    """
    flow_token = os.environ.get("MY_ACCESS_TOKEN", "")
    return AccessTokenAuthorizer(flow_token)


# Create an AccessTokenAuthorizer using a token that has consents to the
# MANAGE_FLOWS_SCOPE. This lets the FlowsClient perform operations against the
# Flow's service i.e. create flow, update a flow, delete a flow
flows_service_token = os.environ.get("MANAGE_FLOWS_SCOPED_TOKEN", "")
flows_service_authorizer = AccessTokenAuthorizer(flows_service_token)

fc = FlowsClient.new_client(
    client_id=CLIENT_ID,
    authorizer=flows_service_authorizer,
    authorizer_callback=authorizer_retriever,
)

my_flows = fc.list_flows()
print(my_flows)

# When running a specific Flow, the authorizer_retriever callback is called
# internally to make the authenticated call to the Flow
running_flow = fc.run_flow(
    "1e6b4406-ee3d-4bc5-9198-74128e108111", None, {"echo_string": "hey"}
)
print(running_flow)

# It's possible to create an Authorizer and pass it as a kwarg to the flow
# operation. This usage will not use the authorizer_callback:
running_flow_2 = fc.run_flow(
    "1e6b4406-ee3d-4bc5-9198-74128e108111",
    None,
    {"echo_string": "hey"},
    authorizer=AccessTokenAuthorizer("..."),
)
print(running_flow_2)