Documentation Powered by ReDoc

Globus Flows API (2023.08.18)

Download OpenAPI specification:Download

Globus Support: support@globus.org URL: https://support.globus.org/hc/en-us/requests/new Terms of Service

This is the Globus Flows API description.

Flows

Deploy a Flow

Deploy a Flow and its schema.

Authorizations:
None
Request Body schema: application/json
required
object (FlowDefinition)
title
string [ 1 .. 128 ] characters

A non-unique, human-friendly name used for displaying the provider to end users.

subtitle
string [ 1 .. 128 ] characters

A concise summary of the provider’s purpose.

description
string [ 1 .. 4096 ] characters

A detailed description of the provider for end user display.

keywords
Array of strings

A set of terms used to categorize the provider which may be used in query and discovery operations. Maximum total length of all keywords is 1024 characters.

flow_viewers
Array of strings (PrincipalURN_or_public) unique

A set of Principal URN values, or the value "public" indicating the identity of users who can view the provider description via introspection or when indexed in any provider catalog service.

flow_starters
Array of strings (PrincipalURN_or_all_authenticated_users) unique

A set of Principal URN values, or the value "all_authenticated_users" indicating the identity of users who can use the /run operation to initiate an action on the provider.

flow_administrators
Array of strings (PrincipalURN) unique

The set of Principal URN values of users who may perform administrative operations, including updating the description itself, on the provider.

input_schema
object

A published JSON Schema which input to the Flow must conform to.

subscription_id
string <uuid>

A subscription_id associated with this Flow. If no subscription_id is present, the Flow may be accepted, but may have limits on how long or how much it can be used.

Responses

Request samples

Content type
application/json
{
  • "definition": {
    },
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "input_schema": { },
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "definition": {
    },
  • "input_schema": { },
  • "globus_auth_scope": "http://example.com",
  • "globus_auth_scopes_by_RunAs": [],
  • "user_role": "flow_viewer",
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "flow_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "synchronous": true,
  • "log_supported": true,
  • "types": [
    ],
  • "api_version": "1.0",
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "principal_urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "globus_auth_username": "string",
  • "flow_url": "http://example.com",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Retrieve all Flows

Query the Flows service for a listing of Flows available to a user according to the permissions (role) they have on the Flow.

Authorizations:
None
query Parameters
marker
string

An opaque token used to iterate through pages of returned Flows. If provided, all other query arguments will be ignored. The marker encodes all state in a given query, therefore it's unnecessary to provide query arguments once an initial marker has been received.

per_page
integer [ 1 .. 50 ]
Default: 20
Example: per_page=50

The number of results to return in a single paged response.

page
integer >= 1
Default: 1
Example: page=2

The page of results to return.

filter_roles
Array of strings
Deprecated
Default: "flow_owner,flow_viewers,flow_starters,flow_administrators"
Items Enum: "flow_owner" "flow_viewers" "flow_starters" "flow_administrators"
Example: filter_roles=flow_owner,flow_viewers

Return Flows for which the user has the supplied role. The role the user has on the Flow dictates the operations they can perform. If multiple roles are specified, the user will have at least one of the specified roles on each Flow returned.

filter_role
string
Enum: "flow_viewer" "flow_starter" "flow_administrator" "flow_owner"
Example: filter_role=flow_starter

Return Flows for which the user has the provided role. The role the user has on the Flow dictates the operations they can perform. Roles are cumulative in the sense that having, for example, the "flow_starter" role also implies having the "flow_viewer" role. Thus, specifying "flow_starter" will also include all Flows for which the user has "flow_viewer" role as well. If not provided, only Flows for which the caller has "flow_owner" role will be returned.

filter_scope_string
Array of strings
Example: filter_scope_string=0abc,100

Performs a case insensitive substring based search on the Flows' scope string fields. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the strings in its scope strings.

filter_title
Array of strings
Example: filter_title=hello,science

Performs a case insensitive substring based search on the Flows' title field. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the strings in its title.

filter_subtitle
Array of strings
Example: filter_subtitle=hello,science

Performs a case insensitive substring based search on the Flows' subtitle field. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the strings in its subtitle.

filter_description
Array of strings
Example: filter_description=hello,science

Performs a case insensitive substring based search on the Flows' description field. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the strings in its description.

filter_keywords
Array of strings
Example: filter_keywords=hello,science

Performs a case insensitive substring based search on the Flows' keywords field. If multiple values are specified, each Flow returned is guaranteed to contain at least one of the substrings as a keyword.

filter_fulltext
Array of strings
Example: filter_fulltext=globus

Given a one or more patterns, this filter searches against a pre-defined subset of fields for a match. If any of the fields match any of the patterns, the Flow is considered a match.

The fields that are automatically searched in are:

  • title
  • subtitle
  • flow_owner
  • description
  • id
  • flow_administrators
orderby
Array of strings
Example: orderby=title ASC,id DESC

An ordering criteria to apply to the resulting Flows listing. The first value indicates the field to order on, and the second value indicates the sorting order. The first ordering criteria will be used to sort the data, subsequent ordering criteria will be applied for ties.

Fields that support ordering are:

  • id
  • scope_string
  • flow_owner
  • flow_administrators
  • title
  • created_at
  • updated_at

Supported orderings are:

  • ASC
  • DESC

Responses

Response samples

Content type
application/json
{
  • "flows": [
    ],
  • "limit": 0,
  • "marker": "string",
  • "has_next_page": true
}

Retrieve a Flow

Get a previously deployed Flow.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow whose definition is being looked up.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "definition": {
    },
  • "input_schema": { },
  • "globus_auth_scope": "http://example.com",
  • "globus_auth_scopes_by_RunAs": [],
  • "user_role": "flow_viewer",
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "flow_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "synchronous": true,
  • "log_supported": true,
  • "types": [
    ],
  • "api_version": "1.0",
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "principal_urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "globus_auth_username": "string",
  • "flow_url": "http://example.com",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Update a Flow

Update a previously deployed Flow.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow whose definition is being looked up.

Request Body schema: application/json
object (FlowDefinition)
input_schema
object

A JSON schema document.

When starting the flow, input keys and values must conform to the schema. The Globus Web App uses the input schema to created a guided input page when starting the flow.

title
string [ 1 .. 128 ] characters

A non-unique, human-friendly name used for displaying the flow to end users.

subtitle
string <= 128 characters

A short summary of the flow's purpose or functionality.

description
string <= 4096 characters

Arbitrary text to describe the Flow.

flow_owner
string

If provided, the value must be the calling user's Globus Auth identity URN, and the user must be a flow administrator.

It is not possible for non-administrators to take ownership of a flow. Also, it is currently not possible to assign ownership to another user.

flow_administrators
Array of str[ items ]

A list of Globus Auth identity and group URNs that may administer the flow.

Flow administrators are able to see the full flow definition, including any parameters listed in a "__Private_Parameters" value.

flow_starters
Array of str[ items ]

A list of Globus Auth identity and group URNs that may start the flow.

It is possible to make a flow available for use to all authenticated users -- including those outside your organization or domain -- by using the special value "all_authenticated_users".

Parameters listed in "__Private_Parameters" values in the definition will be removed from the definition when it is viewed by a flow starter.

flow_viewers
Array of str[ items ]

A list of Globus Auth identity and group URNs that may see the flow, including its definition and input schema.

It is possible to make a flow available for viewing to all users -- including those outside your organization or domain -- by using the special value "public".

Parameters listed in "__Private_Parameters" values in the definition will be removed from the definition when it is viewed by a flow starter.

keywords
Array of str[ items ]

A list of keywords that can be used for grouping or identifying flows.

Responses

Request samples

Content type
application/json
{
  • "definition": {
    },
  • "input_schema": { },
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "flow_owner": "string",
  • "flow_administrators": [
    ],
  • "flow_starters": [
    ],
  • "flow_viewers": [
    ],
  • "keywords": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "definition": {
    },
  • "input_schema": { },
  • "globus_auth_scope": "http://example.com",
  • "globus_auth_scopes_by_RunAs": [],
  • "user_role": "flow_viewer",
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "flow_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "synchronous": true,
  • "log_supported": true,
  • "types": [
    ],
  • "api_version": "1.0",
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "principal_urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "globus_auth_username": "string",
  • "flow_url": "http://example.com",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Remove a Flow

Remove a Flow from the Flow service.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the Flow whose definition is being looked up.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "definition": {
    },
  • "input_schema": { },
  • "globus_auth_scope": "http://example.com",
  • "globus_auth_scopes_by_RunAs": [],
  • "user_role": "flow_viewer",
  • "flow_viewers": [
    ],
  • "flow_starters": [
    ],
  • "flow_administrators": [
    ],
  • "flow_owner": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "synchronous": true,
  • "log_supported": true,
  • "types": [
    ],
  • "api_version": "1.0",
  • "title": "string",
  • "subtitle": "string",
  • "description": "string",
  • "keywords": [
    ],
  • "principal_urn": "urn:globus:auth:identity:46bd0f56-e24f-11e5-a510-131bef46955c",
  • "globus_auth_username": "string",
  • "flow_url": "http://example.com",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627"
}

Retrieve all Flows Deprecated

Query the Flows service for a listing of Flows available to a user according to the permissions (role) they have on the Flow.

Authorizations:
None
query Parameters
roles
Array of strings
Default: "flow_owner"
Items Enum: "flow_owner" "flow_viewers" "flow_starters" "flow_administrators"
Example: roles=flow_owner,flow_viewers

Return Flow's for which the user has the supplied role. The role the user has on the Flow dictates the operations they can perform.

Responses

Response samples

Content type
application/json
{
  • "flows": [
    ],
  • "limit": 0,
  • "marker": "string",
  • "has_next_page": true
}

Runs

Invoke a Flow

Run an instance of a particular Flow.

Authorizations:
None
path Parameters
flow_id
required
string

The ID for the F