Globus Action Providers

Globus provides and operates a number of action providers which may be invoked directly or used within flows. Below is a brief summary of the action providers being operated including specific information on their URLs, scopes, and a summary of their functionality. Specific input specifications are not provided as they may be retrieved from the action provider directly via introspection:

globus-automate action introspect --action-url <action_url>

Or simply click on the URL to view the introspection results in a browser.

Note

When running Globus operated action providers the action subcommands do not require the use of the --action-scope option as these Action Providers are publicly visible. If interacting with a non-publicly visible Provider, all action subcommands will require the --action-scope option followed with the action provider’s corresponding scope value.

List of Globus Operated Action Providers

HelloWorld

URL: https://actions.globus.org/hello_world

Scope: https://auth.globus.org/scopes/actions.globus.org/hello_world

Synchronous / Asynchronous: Either

The HelloWorld action provider is very simple and is primarily intended for testing and bootstrapping purposes. It can operate in either synchronous or asynchronous modes. In the synchronous mode, only a single string is sent in the body and the response will return containing a constant value ("Hello": "World") and a reply to the input ("hello": "<input string>"). To get asynchronous operation, the value sleep_time should be included in the input with a value of a number of seconds the Action should take to complete. Subsequent invocations of /status will return the state ACTIVE until the number of seconds indicated in sleep_time have elapsed at which point the status will become SUCCEEDED.

Example Input

{
    "echo_string": "Hello Globus Automate!",
    "sleep_time": 5
}

Try It

globus-automate action run --watch \
    --action-url https://actions.globus.org/hello_world \
    --body '{"echo_string": "Hello Globus Automate!","sleep_time": 5}'

Globus Transfer - Transfer Data

URL: https://actions.globus.org/transfer/transfer

Scope: https://auth.globus.org/scopes/actions.globus.org/transfer/transfer

Synchronous / Asynchronous: Either

The Globus Transfer - Transfer Data action provider uses the Globus Transfer Task API to perform a transfer of data from one Globus Collection to another. The input includes both the source and destination collection ids and file paths within the collection where the source file or folder is located and the destination folder where the transfer should be placed. It also supports indicating that transfers should be performed recursively to traverse the entire source file system tree and allows labeling the transfer should it be viewed directly in the Globus WebApp or via the Globus API or CLI. The body of the action status directly reflects the information returned when monitoring the transfer task using the Globus Transfer API.

Example Input

{
    "source_endpoint_id": "go#ep1",
    "destination_endpoint_id": "go#ep2",
    "transfer_items": [
        {
            "source_path": "/~/campus_source/dataset1/",
            "destination_path": "/~/dmz_temp/",
            "recursive": true
        }
    ],
    "notify_on_succeeded": false,
    "notify_on_failed": true,
    "notify_on_inactive": true
}

Globus Transfer - Delete Data

URL: https://actions.globus.org/transfer/delete

Scope: https://auth.globus.org/scopes/actions.globus.org/transfer/delete

Synchronous / Asynchronous: Asynchronous

Globus Transfer / delete data works much like the “Transfer / transfer” provider. It takes a source collection and path as inputs and uses the Globus Transfer Task API to initiate an asynchronous delete operation. Also like the transfer operation, labels and recursive options may be set. The status body comes directly from the Task status in the Globus Transfer API.

Globus Transfer - Set/Manage Permissions

URL: https://actions.globus.org/transfer/set_permission

Scope: https://auth.globus.org/scopes/actions.globus.org/transfer/set_permission

Synchronous / Asynchronous: Synchronous

The Globus Transfer - Set Permission action provider uses the Globus Transfer ACL API to set or manage permissions on a folder or file. The body of the request indicates whether the permission rule is to be created, updated or deleted using the operation property. For update or delete, the rule_id of a previously created permission rule must also be provided.

As the Globus Transfer API returns a status directly (rather than a task identifier), the action provider behaves in a synchronous manner, returning the Transfer API result.

Example Input to Set Permissions

{
  "operation": "CREATE",
  "endpoint_id": "ddb59aef-6d04-11e5-ba46-22000b92c6ec",
  "path": "/~/shared/",
  "principal_type": "all_authenticated_users",
  "principal": "",
  "permissions": "r"
}

Example Input to Delete Permissions

{
  "operation": "DELETE",
  "endpoint_id": "ddb59aef-6d04-11e5-ba46-22000b92c6ec",
  "rule_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}

Example Input to Update Permissions

{
  "operation": "UPDATE",
  "endpoint_id": "ddb59aef-6d04-11e5-ba46-22000b92c6ec",
  "rule_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "permissions": "rw"
}

Globus Transfer - List Directory Contents

URL: https://actions.globus.org/transfer/ls

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/transfer_ls

Synchronous / Asynchronous: Synchronous

The Globus Transfer - List Directory action provider uses the Globus Transfer Directory API to retrieve a listing of contents from an (endpoint, path) pair. Although providing a path is optional, the default path used depends on endpoint type and it is best to explicitly set a path. This Action Provider supports all options as defined in the List Directory Contents Transfer API documentation.

Additionally, it adds two features not found in the base Globus Transfer List Directory operation.

1. An input Boolean parameter path_only may be specified which indicates that regardless of the file type of the path, we only will return information about the path itself. This changes the behavior when the path references a folder. Rather than returning the contents of the folder, this will return information about the folder itself. Thus, when this option is present, the output will contain only one file entry.

2. For each file entry returned, an additional property, is_folder, is included. This is set to true if the file type is folder. This can be helpful, particularly within Flows, to perform branching or other logic dependent on whether a path points to a folder or a regular file.

Globus Transfer - Make Directory

URL: https://actions.globus.org/transfer/mkdir

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/transfer_mkdir

Synchronous / Asynchronous: Synchronous

The Globus Transfer - Make Directory action provider uses the Globus Transfer Make Directory API to create a new directory on an endpoint. The input is simply the id for endpoint where the directory will be created and the path on the endpoint to the directory to be created.

Example Input to Make Directory

{
  "endpoint_id": "ddb59aef-6d04-11e5-ba46-22000b92c6ec",
  "path": "/~/new_folder"
}

Globus Transfer - Get Collection Information

URL: https://actions.globus.org/transfer/collection_info

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/transfer_collection_info

Synchronous / Asynchronous: Synchronous

The Globus Transfer - Get Collection action provider uses the Globus Transfer Get Collection API to get information about a Globus Collection. The information returned is the same as defined by the Globus Transfer API with one addition: a property is_managed. When true, the is_managed property indicates that a collection (or its host) is managed under a Globus subscription.

Globus Search - Ingest

URL: https://actions.globus.org/search/ingest

Scope: https://auth.globus.org/scopes/actions.globus.org/search/ingest

Synchronous / Asynchronous: Asynchronous

Records may be added to an existing Globus Search index using the Globus Search - Ingest action provider. The input to the action provider includes the id of the Search index to be added to and the data, in the Search-defined GMetaEntry format. The user calling the Action Provider must have permission to write to the index referenced. Globus Search will process the ingest operation asynchronously, so this action provider also behaves in an asynchronous fashion: requests to update the state of an Action will reflect the result from updating the state of the ingest task in Globus Search. Since Globus Search does not support cancellation of tasks, this action provider also does not support cancellation of its Actions.

Example Input

{
    "search_index": "6077d057-989d-41e2-b60b-91fe001f0687",
    "subject": "http://example.com/foo",
    "visible_to": [
        "public"
    ],
    "content": {
        "testing": {
            "hello": "world"
        }
    }
}

Globus Search - Delete

URL: https://actions.globus.org/search/delete

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/search_delete

Synchronous / Asynchronous: Asynchronous

Subjects or entries may be removed from an existing Globus Search index using the Globus Search - Delete action provider. The input to the action provider includes the Search index id to delete the data from. The body also specifies the type of delete operation to execute via the delete_by parameter. It’s value may be entry to delete a single entry, subject to delete a subject, or query to remove data matching a Search query.

The user calling the action provider must have permission to write to the index referenced. Globus Search will process the delete operation asynchronously, so this action provider also behaves in an asynchronous fashion. Requests for the state of an Action will lookup the state of the task_id in Globus Search, ensuring the status remains up-to-date. Since Globus Search does not support cancellation of tasks, this action provider also does not support cancellation of its Actions.

Example Input to Delete by Subject

{
    "delete_by": "subject",
    "search_index": "00000000-0000-0000-0000-000000000000",
    "subject": "http://example.com/foo"
}

Example Input to Delete by Query

{
    "delete_by": "query",
    "search_index": "00000000-0000-0000-0000-000000000000",
    "q": "a search with filtering and faceting",
    "filters": [
        {
            "type": "range",
            "field_name": "path.to.date",
            "values": [
                {
                    "from": "*",
                    "to": "2014-11-07"
                }
            ]
        }
    ],
    "query_template": "some_query_template"
}

Send Notification - Email

URL: https://actions.globus.org/notification/notify

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/notification_notify

Synchronous / Asynchronous: Synchronous

The Send Notification / Email action provider presently supports sending of email messages to a set of email addresses. The request to send the email contains the standard components of an email: sender, receiver(s), subject and body. The mimetype of the body may be specified so that either HTML or text formatted messages may be sent. The body also supports the notion of variable substitution or “templating.” Values in the body may be specified with a dollar sign prefix ($), and when values are provided in the body_variables property of the request, the template value will be substituted with the corresponding value from the body_variables.

The other important component of the request to this action provider is the email sending credentials. Credentials are provided to allow the provider to communicate with the service used for sending the email. Presently, two modes of sending email are supported: SMTP and AWS SES. When SMTP is provided, the username, password and server hostname are required. When AWS SES is provided, the AWS access key, AWS access key secret and the AWS region must be provided. As this service is synchronous and stateless, the requester can be assured that these credentials will not be stored. The action provider will return success as long as the email service accepts the message. It cannot guarantee successful delivery of the message including an inability to deliver the message due to an improper recipient address.

Example Input with Complex Templating

{
    "notification_method": "email",
    "notification_priority": "high",
    "body_template": "<html><body><h1>Hello $Name</h1></body></html>",
    "body_mimetype": "text/html",
    "body_variables": {
        "Name": "Dude"
    },
    "destination": "user@globus.org",
    "sender": "user@globus.org",
    "subject": "Testing From Automate CLI",
    "send_credentials": [
        {
            "credential_method": "email",
            "credential_type": "ses",
            "credential_value": {
                "aws_access_key_id": "SECRET",
                "aws_secret_access_key": "SECRET",
                "region_name": "us-east-1"
            }
        }
    ]
}

Example Input with Simple Formatting

{
    "body_mimetype": "text/html",
    "body_template": "Hello there",
    "destination": "DESTINATION@example.org",
    "notification_method": "any",
    "notification_priority": "high",
    "sender": "SENDER@example.org",
    "subject": "Testing Notification",
    "send_credentials": [
        {
            "credential_type": "ses",
            "credential_value": {
                "aws_access_key_id": "AWS_ACCESS_KEY_ID",
                "aws_secret_access_key": "AWS_SECRET_ACCESS_KEY",
                "region_name": "us-east-1"
            }
        }
    ]
}

Wait for User Option Selection

URL: https://actions.globus.org/weboption/wait_for_option

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/weboption_wait_for_option

Synchronous / Asynchronous: Asynchronous

Flows or other clients which desire to provide users a method of selecting an option from a fixed set may use the Wait for User Option Selection Action Provider. The action provider can operate in one of two modes.

In the first mode, a list of options are created which are automatically selected by any access to a corresponding URLs. For each option, a name, a URL suffix, and a message or text which is returned in the HTTP response of the selection operation is provided. The URL suffix is registered with the Action Provider and is monitored at the URL https://actions.globus.org/weboption/option/<url_suffix>. Any HTTP access to the URL is considered a selection of that option among all the options defined by the input to the Action and the Action will transition to a SUCCEEDED status. Each of the options may be protected for access only via specific Globus identities by setting values on the selectable_by list. A direct HTTP access may present a Bearer token for authorization using the same scope as used for accessing the other operations on the action provider. If no access token is presented, the user will be re-directed to start an OAuth Flow using Globus Auth to authenticate access to the option URL.

In the second mode, in addition to monitoring the provided URL suffixes, a landing page may be hosted which will present the options to a user on a simple web page. The web page may be “skinned” with options for banner text, color scheme and icon as well as introductory text presented above the options. The options are specified in the same manner as in the first mode, but the page presents links which ease selection of those options for end-users. The landing page is also given a URL suffix, and the selection page will be present at https://actions.globus.org/weboption/landing_page/<url_suffix>. Selection of an option within the landing page behaves the same as direct selection of an option via its URL as described above. Similar to individual options, the landing page can be protected by setting a selectable_by list. As the landing page is intended for use via a browser, it will always start a OAuth Flow to authenticate the user. If selectable_by is set on the landing page but not on any of the individual options, the options inherit the same selectable_by value defined on the landing page for that Action.

In either mode, once an option has been selected, none of the url suffixes, nor the landing page if configured, in the initial request, will be responded to by the action provider: they will return the HTTP not found (error) status 404. Upon completion, the body of the status will include the name and the url suffix for the selected option. The body may also include input on the HTTP data passed when the option’s URL was accessed including the query parameters and the body. To include those in the status, flags are set on the definition of the option.

Example Input for Creating Options

{
    "options": [
        {
            "name": "b",
            "url_suffix": "option_b",
            "completed_message": "Thank you for selecting 'b'"
        },
        {
            "name": "default",
            "url_suffix": "option_a",
            "completed_message": "Thank you for selecting the default option"
        }
    ]
}

Example Input for Creating Options on a Landing Page

{
    "landing_page": {
        "url_suffix": "landing_page",
        "header_background": "darkred",
        "header_icon_link": "http://example.com",
        "header_text": "Hey, Make a choice",
        "page_title": "Look at my title",
        "preamble_text": "Please make a very careful decision"
    },
    "options": [
        {
            "name": "b",
            "description": "This is option b",
            "url_suffix": "option_b_new",
            "completed_message": "Thank you for selecting 'b'"
        },
        {
            "name": "default",
            "description": "This is the default option",
            "url_suffix": "option_a_new",
            "completed_message": "Thank you for selecting the default option"
        }
    ]
}

Example Input for Creating Options on a Landing Page Limiting Selection

{
    "landing_page": {
        "url_suffix": "landing_page",
        "header_background": "darkred",
        "header_icon_link": "http://example.com",
        "header_text": "Hey, Make a choice",
        "page_title": "Look at my title",
        "preamble_text": "A summary of the user's input...",
        "include_text_input_form": true,
        "text_input_form_prompt": "Please provide your reason",
        "display_options_as": "link",
        "selectable_by": [
            "urn:globus:auth:identity:c5ab1c3d-b812-4ef9-acb6-4d84c58db4de"
        ]
    },
    "options": [
        {
            "name": "Yes",
            "description": "Allow the submission",
            "url_suffix": "yes",
            "completed_message": "The submission will be allowed"
        },
        {
            "name": "No",
            "description": "Reject the submission",
            "url_suffix": "no",
            "completed_message": "The submission will be rejected"
        },
        {
            "name": "Maybe",
            "description": "Request the user to re-submit",
            "url_suffix": "maybe",
            "completed_message": "The user will be required to update their submission"
        }
    ]
}

Simple Expression Evaluation

Note

Expression evaluation has been integrated with action definitions directly (see section Expressions in Parameters). Thus, for most use cases, the Simple Expression Evaluation action provider described here is not needed and expressions defined on Action definitions within a Flow are preferred.

URL: https://actions.globus.org/expression_eval

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/expression

Synchronous / Asynchronous: Synchronous

Evaluation of simple expressions is supported using the simpleeval library and therefore syntax. A single invocation of the action provider may evaluate a single expression or multiple expressions. An Expression request consists of up to three parts:

• An expression (required) which is a basic “arithmetic” type expression. This does include string type operations so an expression like “foo” + “bar” is permitted and performs string concatenation as is common in many programming and scripting languages.
• A set of arguments (optional) in a JSON object format. These arguments may be referenced in an expression. So, if there’s an expression such as “x + 1” and the arguments contain {"x": 2} the result will be 3.
• A result_path (optional) which is a path where the result will be stored. It may be in “Reference Path” format as defined in the AWS Step Functions State Machine Language specification or it may simply be a dot separated string of the path elements. In either case, the path indicates where in the details of the returned action status the value for the evaluated expression should be placed. If result_path is not present, the result will be stored in the details under the key result.

A single request may specify multiple expressions to be evaluated by providing an array named expressions as in {"expressions": [{ expression1 }, {expression2}, ...]} where each of the expressions expression1 and expression2 contains the three fields defined for an expression. These will be evaluated in order, and expressions using the same result_path will result in previous results being over-written.

Datacite DOI Minting

URL: https://actions.globus.org/datacite/mint/basic_auth

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/datacite_mint_basic_auth_action_all

Synchronous / Asynchronous: Synchronous

The Datacite DOI Minting action provider uses the Datacite JSON API to mint DOIs. The main part of the body input is as specified in that API. The additional fields provide the username and password (the “Basic Auth” credentials which is part of the name of the URL and scope string) as well as a flag indicating whether it should be used in the Datacite test service or the production service.

Example Input

{
    "as_test": true,
    "username": "DATACITE_USERNAME",
    "password": "DATACITE_PASSWORD",
    "Doi": {
        "id": "10.80206/ap_test",
        "type": "dois",
        "attributes": {
            "doi": "10.80206/ap_test",
            "creators": [
                {
                    "name": "Globus Dev Team"
                }
            ],
            "titles": [
                {
                    "title": "Test Title"
                }
            ],
            "publisher": "Globus",
            "publicationYear": "2020"
        }
    }
}

funcX

URL: https://automate.funcx.org

Scope: https://auth.globus.org/scopes/b3db7e59-a6f1-4947-95c2-59d6b7a70f8c/action_all

Synchronous / Asynchronous: Asynchronous

FuncX supports an asynchronous action provider to provide access via the Globus automation platform. More details can be found in the funcX documentation.