Advanced Endpoint Management
- 1. Overview
- 2. Document Types
- 3. Common Query Parameters
- 4. Common Errors
- 5. Path Arguments
-
6. Operations
- 6.1. Get tasks
- 6.2. Get task
- 6.3. Get task events
- 6.4. Get task pause info as admin
- 6.5. Get task successful transfers as admin
- 6.6. Get task skipped errors transfers as admin
- 6.7. Get endpoint as admin
- 6.8. Get hosted endpoint list
- 6.9. Get endpoint access list as admin
- 6.10. Get monitored endpoints
- 6.11. Cancel tasks as admin
- 6.12. Get cancel status by id
- 6.13. Pause tasks as admin
- 6.14. Resume tasks as admin
- 6.15. Get pause rules
- 6.16. Create pause rule
- 6.17. Get pause rule
- 6.18. Update pause rule
- 6.19. Delete pause rule
1. Overview
The advanced endpoint management API is available to Globus subscribers. This API allows site administrators to manage the transfers to and from their endpoints, to aid in proactive debugging of user transfers. All operations listed below require the user to have either the "activity_manager" or "activity_monitor" roles on on an endpoint, and the endpoint must be marked as Managed and associated with a provider subscription. In particular, for TRANSFER tasks the user must have either of the roles on either the source or destination endpoint to view the task and the manager role to cancel or pause the task. Note that the "activity_manager" role includes all privileges of the "activity_monitor" role. See the Endpoint Role API for how to assign "activity_manager" and "activity_monitor" roles to identities or groups.
All resources in this part of the API are prefixed with /endpoint_manager. This prefix is used to denote that the operation will be run with elevated privileges.
If the user does not have any "activity_manager" or "activity_monitor" roles, PermissionDenied will be returned by all resources under /endpoint_manager.
1.1. Shared Endpoints and Manager Privileges
A user can have the "activity_manager" or "activity_monitor" roles on a shared endpoint or a host endpoint. Having one of these two roles on a host endpoint implicitly gives the corresponding role on all hosted shared endpoints.
With few exceptions, a user with the "activity_manager" role on a shared endpoint can not override a configuration change made by user with the "activity_manager" role on the host endpoint. Activity managers on host and shared endpoints have the following rules:
-
A user with the "activity_manager" role on a host endpoint can create a pause rule on the host endpoint, which also affects all its shared endpoints. The pause rule will not be in the pause rule list of a user with the "activity_manager" role on a shared endpoint.
-
A user with the "activity_manager" role on a host endpoint can also create a pause rule on a specific shared endpoint. In that case, the rule will be in the pause rule list of users with the "activity_manager" role on the shared endpoint, but they cannot edit or delete the rule.
-
A user with the "activity_manager" role on a shared endpoint can create a rule on the shared endpoint. A rule that was created by such a user can be updated or deleted by users with the "activity_manager" role on either the shared endpoint or its host.
-
Users with the "activity_manager" role on a shared endpoint or its host endpoint can pause a task (per-task pause). The pause state is tracked separately depending on whether the user who initiated the pause had the "activity_manager" role on the host endpoint or only on the shared endpoint. A user with the "activity_manager" role on the host endpoint can resume a per-task pause set by either type of user. However, a user with the "activity_manager" role only on the shared endpoint cannot resume a per-task pause set by a user with the "activity_manager" role on the host endpoint.
-
A task to or from a shared endpoint can be canceled by a user with the "activity_manager" role on either the shared endpoint or the host endpoint.
For more details, see the individual operation documentation below.
2. Document Types
2.1. Task Document
The task document includes all fields from the user facing task resources (see the Task Documentation), with the following additions:
2.1.1. Extra Fields
Also includes descriptions for fields that behave differently from their counterpart in the single user document returned by /task_list, notably source endpoint and destination endpoint fields which have different visibility rules.
Field Name | JSON Type | Description |
---|---|---|
source_endpoint |
string |
[DEPRECATED] Use source_endpoint_id instead. Canonical name of the source endpoint. Same visibility rules as source_endpoint_id. |
source_endpoint_id |
string |
Id of the source endpoint. Visible if the endpoint is public or if the user has the "administrator" or "activity_monitor" role on the endpoint, otherwise it will be null. |
source_endpoint_display_name |
string |
Display name of the source endpoint, same visibility rules as source_endpoint_id. |
destination_endpoint |
string |
[DEPRECATED] Use destination_endpoint_id instead. Canonical name of the destination endpoint for tasks of type TRANSFER, null for tasks of type DELETE. Same visibility rules as destination_endpoint_id. |
destination_endpoint_id |
string |
Id of the destination endpoint. Visible if the endpoint is public or if the user has the "administrator" or "activity_monitor" role on the endpoint, otherwise it will be null. |
destination_endpoint_display_name |
string |
Display name of the destination endpoint, same visibility rules as destination_endpoint_id. |
source_host_endpoint |
string |
[DEPRECATED] Use source_host_endpoint_id instead. Canonical name of the endpoint hosting the source_endpoint if the source endpoint is a shared endpoint. Same visibility rules as source_host_endpoint_id. |
source_host_endpoint_id |
string |
Id of the endpoint hosting the source endpoint if the source endpoint is a shared endpoint. Visible if the host endpoint is public, or if the user has the "administrator" or "activity_monitor" effective role on the source host endpoint; otherwise it will be null. Will also be null if the source endpoint is not a shared endpoint. |
source_host_endpoint_display_name |
string |
Display name of the endpoint hosting the source endpoint if the source endpoint is a shared endpoint. Same visibility rules as source_host_endpoint_id. |
source_mapped_collection_id |
string |
UUID of the mapped collection hosting the source endpoint if the source endpoint is a guest collection. Visible if the mapped collection is public, or if the user has the "administrator" or "activity_monitor" effective role on the source mapped collection; otherwise it will be null. Will also be null if the source endpoint is not a guest collection. |
source_mapped_collection_display_name |
string |
Display name of source_mapped_collection_id if non null. |
destination_host_endpoint |
string |
[DEPRECATED] Use destination_host_endpoint_id instead. Canonical name of the endpoint hosting the destination endpoint if the destination endpoint is a shared endpoint. Same visibility rules as destination_host_endpoint_id. |
destination_host_endpoint_id |
string |
Id of the endpoint hosting the destination endpoint if the destination endpoint is a shared endpoint. Same visibility rules as for source_host_endpoint_id, but requires an effective role on the destination endpoint and destination host endpoint instead of source endpoints. Will also be null for delete tasks. |
destination_host_endpoint_display_name |
string |
Display name of the endpoint hosting the destination endpoint if the destination endpoint is a shared endpoint. Same visibility rules as destination_host_endpoint_id. |
destination_mapped_collection_id |
string |
UUID of the mapped collection hosting the destination endpoint if the destination endpoint is a guest collection. Visible if the mapped collection is public, or if the user has the "administrator" or "activity_monitor" effective role on the destination mapped collection; otherwise it will be null. Will also be null if the destination endpoint is not a guest collection. |
destination_mapped_collection_display_name |
string |
Display name of destination_mapped_collection_id if non null. |
source_host_path |
string |
If the source endpoint is a shared endpoint, the path the share is located on at the host endpoint. Visible if the user has the "administrator" effective role on the source endpoint, or if the user has the "activity_monitor" effective role on the source host endpoint; otherwise it will be null. Will also be null if the source endpoint is not a shared endpoint. |
destination_host_path |
string |
If the source endpoint is a shared endpoint, the path the share is located on at the host endpoint. Same visibility rules as source_host_path, but based on having an appropriate effective role on the destination endpoint or destination host endpoint instead of the source endpoints. Will also be null for delete tasks. |
is_ok |
boolean |
For active tasks, this will be True if nice_status is either OK or Queued. Always null for completed tasks, which do not have nice_status. |
source_local_user |
string |
The name of the local user that the activation credential mapped to on the source endpoint at the time the task was started. This will be "null" initially for all tasks until the information can be acquired. For Globus Connect Personal endpoint, this will be the local user that the application was run as during setup. For shared endpoints, this will be the local user that was used when creating the shared endpoint. This will also be "null" on older jobs, that were started before this feature was added, and if the GridFTP server of the endpoint does not support the SITE WHOAMI command. For shared endpoints, this field will be "null" unless the user has the "activity_monitor" effective role on the source host endpoint. For all other endpoint types, this will be "null" unless the user has the "activity_monitor" effective role on the endpoint itself. |
source_local_user_status |
string |
A status code indicating if the local user is available for the source endpoint, or the reason it’s not available. It can have any of the following values, and new values may be added in the future:
|
destination_local_user |
string |
Like source_local_user but for the destination endpoint. Always "null" for delete tasks, which don’t have a destination. |
destination_local_user_status |
string |
Like source_local_user_status, but for the destination endpoint. In addition to the status codes described above, it can have the value "NO_ENDPOINT" for delete tasks. |
owner_string |
string |
The Globus Auth identity username corresponding to the primary task owner (with id owner_id). This is provided as a convenience to clients, as something that can be displayed to end users (without having to call the Globus Auth API to get the identity details using owner_id). |
2.2. Admin cancel document
The admin cancel document is used to request and track cancellation of one or more tasks by id.
{
"DATA_TYPE": "admin_cancel",
"id": 985,
"message": "Disk failure on GridFTP server",
"task_id_list": ["041751b8-d6e3-4452-82a7-aa98200f4557",
"b30c7cb0-946e-4397-aaa4-a541a2c3ee77"],
"done": false
}
2.2.1. Admin cancel fields
Field Name | JSON Type | Description |
---|---|---|
DATA_TYPE |
string |
Always has value "admin_cancel" to indicate this document type. |
message |
string |
Message to users as to why the tasks are being canceled. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported. Not included in create response or later GET responses. |
id |
string |
Unique id of this bulk cancel request. This should not be set in create requests, and will be generated by the system and set in the create response. |
done |
boolean |
"true" when all tasks in the list have been canceled or finished on their own, "false" otherwise. Returned in the create response and the status request, not used on in the create request body. |
task_id_list |
string list |
List of task ids, maximum 1000. Not included in the create response or later GET responses to save bandwidth on large cancel requests. Note that the limit of 1000 is larger than the limit on the filter_task_id parameter on task_list. |
2.3. Admin pause document
The admin pause document is used to request pause for one or more tasks by id. This is tracked separately from pause rules.
{
"DATA_TYPE": "admin_pause",
"message": "Scratch is getting full",
"task_id_list": ["041751b8-d6e3-4452-82a7-aa98200f4557",
"b30c7cb0-946e-4397-aaa4-a541a2c3ee77"]
}
2.3.1. Admin pause fields
Field Name | JSON Type | Description |
---|---|---|
DATA_TYPE |
string |
Always has value "admin_pause" to indicate this document type. |
message |
string |
Message to users as to why the tasks are being canceled. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported. |
task_id_list |
string list |
List of task ids, maximum 1000. Not included in the create response or later GET responses to save bandwidth on large pause requests. |
2.4. Admin resume document
The admin resume document is used to request resume of one or more tasks by id.
{
"task_id_list": ["041751b8-d6e3-4452-82a7-aa98200f4557",
"b30c7cb0-946e-4397-aaa4-a541a2c3ee77"]
}
2.5. Pause rule document
The pause rule document represents a rule that causes tasks and certain operation to be paused.
Pause rule uniqueness is enforced on (endpoint_id, identity_id, created_by_host_manager). For shared endpoints, this means that for each pair of (endpoint_id, identity_id), there can be one pause rule created by a user with the "activity_manager" role on the host endpoint, and one created by a user with the "activity_manager" role on the shared endpoint. For other endpoint types, there can only be one such rule. Rules on the entire endpoint, i.e. with a null identity_id, are treated as a special value of identity_id regarding uniqueness, so there can be only one endpoint wide rule (or two on shared endpoints).
{
"DATA_TYPE": "pause_rule",
"id": 985,
"message": "Quota exceeded, please delete data from /scratch",
"endpoint_id": "339abc22-aab3-4b45-bb56-8d40535bfd80",
"endpoint_display_name": "Globus Tutorial Endpoint 1",
"identity_id": "bbe7b12b-d397-41e3-8895-3b56518302ef",
"start_time": null,
"modified_by_id": "4c77dd76-aa99-4490-af19-dc81a312c3a1",
"modified_time": "2015-05-04 16:32:39+00:00",
"created_by_host_manager": true,
"editable": true,
"pause_ls": false,
"pause_mkdir": true,
"pause_symlink": true,
"pause_rename": true,
"pause_task_delete": true,
"pause_task_transfer_write": true,
"pause_task_transfer_read": false
}
2.5.1. Pause rule fields
Field Name | JSON Type | Description |
---|---|---|
DATA_TYPE |
string |
Always has value "pause_rule" to indicate this document type. |
id |
string |
Unique id of this pause rule. This should not be set in create requests, and will be generated by the system and set in the create response. |
message |
string |
Message to users as to why the tasks are being paused. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported. |
start_time |
ISO 8601 datetime string, null, or "now" |
If null (the default value), pause existing tasks and all future tasks. If specified, only pause tasks created at or after the specified time. If the special string "now", exact case, is specified, uses the current time on the server at the time the request is received. |
endpoint_id |
string |
Id of the endpoint to pause new tasks on. Required (for backward compatibility, endpoint can be specified instead, but all code should be updated to use endpoint_id). |
endpoint_display_name |
string |
Display name of the endpoint. This is an output only field, for convenience when displaying pause rules. Note that it may be null if the display name has not been set for the endpoint. In that case, consider using the endpoint’s canonical name in the endpoint field for display. |
endpoint |
string |
[DEPRECATED] Use endpoint_id instead. Canonical name of the endpoint to pause new tasks on. |
user |
string |
[DEPRECATED] Use identity_id instead. Username of a user to pause tasks for on the endpoint. If identity_id is set to an identity that has never been used in the Transfer service, then this will be null. This will also be null for rules that apply to all users on an endpoint, in which case identity_id will also be null. |
identity_id |
string |
Identity id of an identity to pause tasks for on the endpoint, or null to indicate all identities on the endpoint. This will affect tasks with a matching owner_id or with a match in the set of linked identities at the time the task was submitted. |
modified_time |
ISO 8601 datetime string |
Time the rule was created or last updated. This is set by the server on create and update and can’t be modified by clients. |
modified_by |
string |
[DEPRECATED] Username of the user who last updated or created the pause rule. Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations. Use modified_by_id instead. If the modified by identity id is not a globus-id.org identity, this will be the same as the modified_by_id. |
modified_by_id |
string |
Identity id of the identity that last updated or created the pause rule. If the endpoint in the rule is a shared endpoint, the user has the "activity_monitor" effective role on the shared endpoint and not its host, and the rule has created_by_host_manager set to "true" or has been updated by a user with the "activity_manager" effective role on the host endpoint, this field and modified_by will be set to "null". Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations. |
created_by_host_manager |
boolean |
A rule on a shared endpoint, created by a user with the "activity_manager" role on the shared endpoint and not its host endpoint, will have this field set to false; in all other cases it will be true. This field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations. |
editable |
boolean |
True if the current user has permission to update or delete the rule. See the pause rule operation documentation for details about authorization requirements and when this will be set. See pause rule list for details. Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations. |
pause_ls |
boolean |
Prevent API ls (directory listing) operations. Default "true". |
pause_mkdir |
boolean |
Prevent API mkdir (create directory) operations. Default "true". Note that this only affects the API mkdir operation - if pause_transfer_write is "false", then directories can be created as part of the transfer operation. |
pause_symlink |
boolean |
Prevent API symlink creation operations. Default "true". Note that this only affects the API symlink operation - if pause_transfer_write is "false", then symlinks can be created as part of the transfer operation. |
pause_rename |
boolean |
Prevent API file and directory rename operations. Default 'true'. |
pause_task_delete |
boolean |
Whether to pause matching tasks of type "DELETE". Default "true". |
pause_task_transfer_write |
boolean |
Whether to pause matching tasks of type "TRANSFER" with the endpoint as destination. |
pause_task_transfer_read |
boolean |
Whether to pause matching tasks of type "TRANSFER" with the endpoint as source. |
3. Common Query Parameters
Name | Description |
---|---|
fields |
Comma separated list of fields to include in the response. This can be used to save bandwidth on large list responses when not all fields are needed. For list document types (with DATA_TYPE ending in "_list"), this selects the fields of the item documents, not the top level paging and list meta data fields. |
4. Common Errors
The error code can be found in the HTTP response body JSON document. See error overview .
Code | HTTP Status | Description |
---|---|---|
EndpointNotFound |
404 |
If <endpoint_xid> not found |
TaskNotFound |
404 |
If the task specified by <task_id> is not found |
PauseRuleNotFound |
404 |
If the pause rule specified by <pause_rule_id> is not found |
PermissionDenied |
403 |
If user does not have the required role on one or more of the specified tasks, endpoints, or pause rules. |
ServiceUnavailable |
503 |
If the service is down for maintenance. |
5. Path Arguments
The operations below make use of the following arguments in the URL path. In this documentation parameter names are denoted by < and >; these should not be included literally in the request path.
Name | Type | Description |
---|---|---|
endpoint_xid |
string |
The id field of the endpoint, or for backward compatibility the canonical_name of the endpoint. The latter is deprecated, and all clients should be updated to use id. |
task_id |
string |
Unique id string of a task. |
6. Operations
6.1. Get tasks
Get a list of tasks involving the endpoints the user has the "activity_monitor" role on. All requests will implicitly filter based on the privileges of the user. The results can be sorted and filtered in different ways, and paging is required unless a filter to show only active tasks is used.
This resource uses last key paging.
URL |
/endpoint_manager/task_list |
---|---|
Method |
GET |
Response Body |
List of Task documents. { "DATA_TYPE": "task_list", "limit": 10, "last_key": "123abc", "has_next_page": true, "DATA": [<task document> ...] } |
6.1.1. Query Parameters
Query Parameter | Type | Default | Description |
---|---|---|---|
last_key |
string |
null |
Opaque value representing the last element in the previous result set page, used to fetch the following page. This will return all results starting from but not including the last element of the previous page. |
limit |
int |
100 |
Maximum number of results to return. The maximum allowed limit is 1000. If filter_status is a subset of ("ACTIVE", "INACTIVE"), limit=0 is supported as a shortcut for limit=1000. It was originally designed to return all active tasks, but this was a mistake in the original design because the number of active tasks is not bounded. It’s unlikely we will have more than 1000 active tasks any time soon, but it’s not the kind of thing we want to risk. For this reason limit=0 is deprecated, but for now the UX can safely assume that it will return all active tasks (which it will with very high probability, just not 100%). |
filter_* |
string |
null |
See filter documentation below. |
6.1.2. Ordering
Tasks that are still in progress are always sorted by request_time descending (newest first). Completed tasks are sorted by completion_time descending. In progress tasks will be sorted before completed tasks.
6.1.3. Filters
Filter Syntax
Filters are passed as separate query parameters, of the form filter_FILTERNAME=FILTERVALUE. Many of the filters are named after a field they apply to, but a few are custom filters with more complex behavior.
If multiple filters are set in the request, only results matching all filters will be returned - there is an implicit logical AND between filters, unless otherwise specified. Within a single filter that accepts multiple values, there is typically an implicit OR. For example, specifying filter_task_id=123,456,678 will return tasks with id 123 OR 456 OR 678.
Filter values, like any other query parameter value, must be percent encoded. The query parameter names will always be safe to pass without further encoding, because they use a subset of characters that do not require encoding.
Task List Filters
All task list filters are subject to the user’s endpoint privileges. For example, filtering on user will only return tasks submitted by that user if they involve an endpoint the requesting user has the "activity_manager" or "activity_monitor" role on. Some requests will result in an error: specifying a task id filter for a task that does not involve an endpoint the user has an appropriate role on will result in a PermissionDenied error.
For any query that doesn’t specify a filter_status that is a subset of ("ACTIVE", "INACTIVE"), at least one of filter_task_id or filter_endpoint is required. This requirement is present because completed tasks are stored separately in a very large table and it is very expensive to query without making use of an index, which can be done only if an appropriate filter is present.
Query Parameter | Filter Type | Description |
---|---|---|
filter_status |
equality list |
Comma separated list of task statuses. Return only tasks with any of the specified statuses. Note that in-progress tasks will have status "ACTIVE" or "INACTIVE", and completed tasks will have status "SUCCEEDED" or "FAILED". |
filter_task_id |
equality list |
Comma separated list of task_ids, limit 50. Return only tasks with any of the specified ids. If any of the specified tasks do not involve an endpoint the user has an appropriate role for, a PermissionDenied error will be returned. This filter can’t be combined with any other filter. If another filter is passed, a BadRequest will be returned. |
filter_owner_id |
equality |
A Globus Auth identity id. Limit results to tasks submitted by the specified identity, or linked to the specified identity, at submit time. Returns UserNotFound if the identity does not exist or has never used the Globus Transfer service. If no tasks were submitted by this user to an endpoint the current user has an appropriate role on, an empty result set will be returned. Unless filtering for running tasks (i.e. filter_status is a subset of ("ACTIVE", "INACTIVE"), filter_endpoint is required when using filter_owner_id. |
filter_username |
equality |
[DEPRECATED] Use filter_owner_id instead. A Globus username. The username is mapped to the globus identity id, and passed to filter_owner_id. Just like filter_owner_id, filter_endpoint is required unless filtering for running tasks. Returns UserNotFound if the user does not exist. |
filter_endpoint |
equality |
Single endpoint id or canonical name. Using canonical name is deprecated. Return only tasks with a matching source or destination endpoint or matching source or destination host endpoint. |
filter_is_paused |
boolean equality |
Return only tasks with the specified is_paused value. Requires that filter_status is also passed and contains a subset of "ACTIVE" and "INACTIVE". Completed tasks always have is_paused equal to "false" and filtering on their paused state is not useful and not supported. Note that pausing is an async operation, and after a pause rule is inserted it will take time before the is_paused flag is set on all affected tasks. Tasks paused by id will have the is_paused flag set immediately. |
filter_completion_time |
datetime range |
Start and end date-times separated by a comma. Each datetime should be specified as a string in ISO 8601 format: YYYY-MM-DDTHH:MM:SS, where the "T" separating date and time is literal, with optional +/-HH:MM for timezone. If no timezone is specified, UTC is assumed, or a trailing "Z" can be specified to make UTC explicit. A space can be used between the date and time instead of a space. A blank string may be used for either the start or end (but not both) to indicate no limit on that side. Returns only complete tasks with +completion_time+ in the specified range. If the end date is blank, it will also include all active tasks, since they will complete some time in the future. |
filter_min_faults |
int |
Minimum number of cumulative faults, inclusive. Return only tasks with faults >= N, where N is the filter value. Use filter_min_faults=1 to find all tasks with at least one fault. Note that many errors are not fatal and the task may still be successful even if faults >= 1. See the faults field documentation for details. |
filter_local_user |
equality |
A valid username for the target system running the endpoint, as a utf8 encoded string. Requires that filter_endpoint is also set. Return only tasks that have successfully fetched the local user from the endpoint, and match the values of filter_endpoint and filter_local_user on the source or on the destination. |
6.2. Get task
Get details of a single task by id. The result will include the task document and the extra task fields described above.
Requires the "activity_monitor" effective role on a source or destination endpoint of the task. Note that if the user owns the task but does not have an appropriate role on an endpoint this will still return a "PermissionDenied" error.
URL |
/endpoint_manager/task/<task_id> |
---|---|
Method |
GET |
Response Body |
Task document. |
6.3. Get task events
Get a list of events for a single task.
This resource uses offset paging.
See the event document documentation for details.
Requires the "activity_monitor" effective role on a source or destination endpoint of the task. Note that if the user owns the task but does not have an appropriate role on an endpoint this will still return a "PermissionDenied" error.
URL |
/endpoint_manager/task/<task_id>/event_list |
---|---|
Method |
GET |
Response Body |
List of event documents |
6.3.1. Query Parameters
Query Parameter | Type | Default | Description |
---|---|---|---|
offset |
int |
0 |
Return results starting from this offset within the total result set. Note that for active tasks this results set will be changing, and as the result set changes so will the meaning of the offset. For this reason, paging through events on active tasks may return unexpected results. |
limit |
int |
100 |
Maximum number of results to return. The maximum allowed limit is 1000. |
filter_* |
string |
null |
See filter documentation below. |
6.4. Get task pause info as admin
This operation returns the same information as the normal user get task pause info operation, but has different authorization requirements. Note that pause_rule_limited documents are still returned instead of the full pause_rule, since the result can include pause rules for endpoints the current user does not have an "activity_monitor" role on.
Requires the "activity_monitor" effective role on a source or destination endpoint of the task. Note that if the user owns the task but does not have an appropriate role on an endpoint this will still return a "PermissionDenied" error.
URL |
/endpoint_manager/task/<task_id>/pause_info |
---|---|
Method |
GET |
Response Body |
{ "DATA_TYPE": "pause_info_limited", "pause_rules": [... list of pause_rule_limited documents...], "source_pause_message": null, "destination_pause_message": "Disk problems, pausing all tasks until we resolve", "source_pause_message_share": null, "destination_pause_message_share": null } |
6.5. Get task successful transfers as admin
For a "TRANSFER" type task, get a list of files transferred successfully, after a task is complete (with status "FAILED" or "SUCCEEDED"), as an endpoint admin. See Get task successful transfers (as normal user) for details. If the current user has the "activity_monitor" role on only one of the endpoints, the paths corresponding to the other endpoint will be "null".
This resource uses marker paging.
Requires the "activity_monitor" effective role on a source or destination endpoint of the task. Note that if the user owns the task but does not have an appropriate role on an endpoint this will still return a "PermissionDenied" error.
URL |
/endpoint_manager/task/<task_id>/successful_transfers [?marker=MARKER] |
---|---|
Method |
GET |
Response Body |
|
6.6. Get task skipped errors transfers as admin
For "TRANSFER" tasks that are completed (have status "SUCCEEDED" or "FAILED"), get a list of paths that were skipped due to the skip_source_errors flag being set to true. The list will contain information about the error and the item that was skipped. See Get task skipped errors (as normal user) for details. If the current user has the "activity_monitor" role on only one of the endpoints, the paths and error details corresponding to the other endpoint will be redacted.
This resource uses marker paging.
Requires the "activity_monitor" effective role on a source or destination endpoint of the task. Note that if the user owns the task but does not have an appropriate role on an endpoint this will still return a "PermissionDenied" error.
URL |
/endpoint_manager/task/<task_id>/skipped_errors [?marker=MARKER] |
---|---|
Method |
GET |
Response Body |
|
6.7. Get endpoint as admin
Get details of an endpoint. This resource is similar to standard get endpoint, and has the same authorization requirements. The one difference is that the in_use field is always set to "null".
See the endpoint document documentation for details.
Requires that the endpoint be public, or that the user has an "administrator", "restricted_administrator", or "activity_monitor" effective role on the endpoint.
URL |
/endpoint_manager/endpoint/<endpoint_xid> |
---|---|
Method |
GET |
Response Body |
Endpoint document. |
6.8. Get hosted endpoint list
Get a list of shared endpoints hosted on a specified endpoint. The response contains full endpoint documents, with the same differences from the standard endpoint document as Get endpoint as admin.
This resource uses offset paging, and includes a has_next_page boolean in the response body.
Requires the "activity_monitor" effective role on the endpoint.
URL |
/endpoint_manager/endpoint/<endpoint_xid>/hosted_endpoint_list |
---|---|
Method |
GET |
Response Body |
{ "DATA_TYPE": "endpoint_list", "offset": 0, "limit": 1000, "has_next_page": false, "DATA": [ { "DATA_TYPE": "endpoint", "owner_id": "8ea74f97-e9e4-433d-a513-ac9920350258", "owner_string": "bob@globusid.org", "display_name": "Project1 Share", ... } ] } |
6.9. Get endpoint access list as admin
Get a list of ACLs on the specified endpoint. Returns the same access_list document as the standard access list resource, but has different authorization requirements.
Requires the "activity_monitor" effective role on the endpoint.
URL |
/endpoint_manager/endpoint/<endpoint_xid>/access_list |
---|---|
Method |
GET |
Response Body |
"access_list" document |
6.10. Get monitored endpoints
Get a list of the endpoints the current users has explicit monitor or manager role on. Like all endpoint manager resources, a 403 response with a "PermissionDenied" error code body will be returned if the user has no permissions. The standard my_effective_roles field can be used to determine which roles the user has.
The response contains full endpoint documents, with the same differences from the standard endpoint document as Get endpoint as admin.
URL |
/endpoint_manager/monitored_endpoints |
---|---|
Method |
GET |
Response Body |
{ "DATA_TYPE": "monitored_endpoints", "DATA": [ { "DATA_TYPE": "monitored_endpoint", "id": "196b3545-0878-4443-a1e6-57eb833beb06", "my_effective_roles": ["activity_manager"], "display_name": "Great Endpoint", ... }, ... ] } |
6.11. Cancel tasks as admin
Cancel one or more tasks by task id as an endpoint administrator. If a task is already complete or canceled at the time of the submission it will not raise an error, which allows clients to re-submit the request if there was a network error.
Task owners will be notified via email that their task(s) were canceled by an administrator. One email will be sent for each task, and they will be sent even if the user has notifications disabled in their profile.
Requires the "activity_manager" effective role on the source or destination endpoint of each task in the request. If this check fails for any of the tasks, the entire request will fail with a "PermissionDenied" error.
URL |
/endpoint_manager/admin_cancel |
---|---|
Method |
POST |
Request Body |
Admin cancel document with task_id_list and message fields. |
Response Body |
Admin cancel document with id and done fields. |
6.12. Get cancel status by id
Returns an admin_cancel document without the task_id_list; clients can check the done field to determine if the cancel request is complete.
Only the user who submitted the original cancel request is guaranteed to be able to get its status.
URL |
/endpoint_manager/admin_cancel/<admin_cancel_id> |
---|---|
Method |
GET |
Response Body |
Admin cancel document with id and done fields. |
6.13. Pause tasks as admin
Pause one or more tasks by task id as an endpoint administrator. If a task is already complete or paused at the time of the submission it will not raise an error, which allows clients to re-submit the request if there was a network error.
Per-task pause is tracked separately for host endpoint admins and shared endpoint admins. A task is paused if either has been set, and will only resume when both are cleared. A host endpoint admin can clear both when resuming, while a shared endpoint admin can only clear a pause set by other shared endpoint admins.
Task owners will be notified via email that their task(s) were paused by an administrator. One email will be sent for each task, and they will be sent even if the user has notifications disabled in their profile.
Requires the "activity_manager" effective role on the source or destination endpoint of each task in the request. If this check fails for any of the tasks, the entire request will fail with a "PermissionDenied" error.
URL |
/endpoint_manager/admin_pause |
---|---|
Method |
POST |
Request Body |
'admin_pause' document |
Response Body |
'result' document with code "PauseAccepted" |
6.14. Resume tasks as admin
Resuming a task involves removing all per-task pauses on the task, and overriding existing pause rules (host and share, source and destination) that affect the task. This operation removes and overrides pause on whichever endpoints the current user has the "activity_manager" role on.
As an example, suppose a task involving a shared endpoint has been paused by two different users, one with the "activity_manager" role on the host endpoint, and one with the "activity_manager" role on the shared endpoint. A user with the "activity_manager" role on the host endpoint can clear both per-task pause flags and set an override on all pause rules that might affect the task, so the task will resume. A user with the "activity_manager" role on the shared endpoint and not its host endpoint can only clear one of the per-task pause flags; a resume operation submitted by such a user will still be considered successful, but the task won’t actually start running again until a user with the "activity_manager" role on the host endpoint clears the other per-task pause flag.
This applies to source and destination endpoints as well, i.e. if a user has the "activity_manager" role on the source but not the destination, a resume operation will clear per-task pause and override pause rules on the source but not the destination.
To resume all tasks affected by a pause_rule, use Delete pause rule by id.
This API call will not raise an error if the task is already running and no per-task pause exists - it will simply set the pause rule override timestamp for the task to the specified value.
If there are no other pauses on the task, the task will resume. Otherwise it will only resume once an "activity_manager" of the other endpoint removes the remaining pauses. When the task actually begins running again, a resume email will be sent to the user. Just like pause, this is an asynchronous process.
Requires the "activity_manager" effective role on the source or destination endpoint of each task in the request. If this check fails for any of the tasks, the entire request will fail with a "PermissionDenied" error.
URL |
/endpoint_manager/admin_resume |
---|---|
Method |
POST |
Request Body |
'admin_resume' document |
Response Body |
'result' document with code "ResumeAccepted" |
6.15. Get pause rules
Get a list of pause rules on endpoints that the current user has the "activity_monitor" role on.
Pause rules will be editable (the editable field will be "true") if one of the following conditions are met:
-
The endpoint is a normal or host endpoint, and the current user has the "activity_manager" effective role on the endpoint
-
The endpoint is a shared endpoint, the current user has the "activity_manager" effective role on the shared endpoint, and the rule was not created by a user with the "activity_manager" effective role on the host endpoint. Note that rules created by a share manager and later modified by a host manager are NOT protected from further editing by a share manager.
-
The endpoint is a shared endpoint, and the current user has the "activity_manager" effective role on the host endpoint (host endpoint managers have higher privileges, and can edit and delete rules set by both host managers and share managers).
If the result set contains over 1000 rules, a "LimitExceeded" error will be returned and the client must pass the filter_endpoint query parameter (with the endpoint id) to get the rules one endpoint at a time.
Returns rules on endpoints for which the user has the "activity_monitor" effective role. If filter_endpoint or filter_host_endpoint is specified, the user must have the "activity_monitor" effective role on the specified endpoint.
URL |
/endpoint_manager/pause_rule_list [?filter_endpoint=ENDPOINT_ID] |
---|---|
Method |
GET |
Response Body |
Pause rule list document. |
6.15.1. Pause Rule Filtering
Query Parameter | Filter Type | Description |
---|---|---|
filter_endpoint |
string equality |
Single endpoint id. Include only pause rules on the specified endpoint. |
filter_host_endpoint |
string equality |
Single endpoint id. Include only pause rules on shared endpoints hosted by the specified endpoint. |
6.16. Create pause rule
Create a new pause rule. New tasks matching the rule will be paused immediately. If start_time is not set, any existing tasks that match will be paused asynchronously. If set, only tasks submitted after the specified time will be paused.
If the appropriate flags are set, the rule will also prevent foreground operations for ls, mkdir, and rename. Clients requesting these operation on the specified endpoint and matching the user clause will receive an OperationPaused error containing the pause message (or the most specific pause message if multiple pause messages are in effect).
Requires the "activity_manager" effective role on the endpoint in the rule.
URL |
/endpoint_manager/pause_rule |
---|---|
Method |
POST |
Request Body |
Pause rule document without id field. |
Response Body |
Pause rule document with server generated id field added. |
6.17. Get pause rule
Get a pause rule by id.
Requires the "activity_monitor" effective role on the endpoint in the rule.
URL |
/endpoint_manager/pause_rule/<pause_rule_id> |
---|---|
Method |
GET |
Response Body |
Pause rule document |
6.18. Update pause rule
Update a pause rule by id. Only the start_time, message, and pause type fields (with the pause_ prefix) can be updated. It is recommended that clients include only the fields to be updated in the request. If non-updatable fields are included, they will be ignored.
The modified_time and modified_by_id fields will be updated based on the time of the request and the user updating the rule. The response will contain these updated fields. Any manual task resume requests made in the past that overrode this pause rule will no longer be in effect, and such tasks will become paused.
The rule must be marked editable in the pause rule list, see link for details.
URL |
/endpoint_manager/pause_rule/<pause_rule_id> |
---|---|
Method |
PUT |
Request Body |
Partial pause rule document (containing fields to be updated). |
Response Body |
Pause rule document |
6.19. Delete pause rule
Delete an existing pause rule by id. Any tasks that were paused by this rule and are not affected by any other rule or per-task pause will resume.
The rule must be marked editable in the pause rule list, see link for details.
URL |
/endpoint_manager/pause_rule |
---|---|
Method |
DELETE |
Response Body |
Result document. |