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 cannot override a configuration change made by a 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 |
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
|
destination_endpoint |
string |
[DEPRECATED] Use |
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
|
source_host_endpoint |
string |
[DEPRECATED] Use |
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_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 |
destination_host_endpoint |
string |
[DEPRECATED] Use |
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 |
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_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 |
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 |
is_ok |
boolean |
For active tasks, this will be True if |
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 |
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 |
destination_local_user_status |
string |
Like |
owner_string |
string |
The Globus Auth identity username corresponding to the primary task
owner (with 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 |
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_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 |
string |
[DEPRECATED] Use |
user |
string |
[DEPRECATED] Use |
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 |
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 |
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 |
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_symlink |
boolean |
Prevent API symlink creation operations.
Default "true". Note that this only affects
the API symlink operation - if |
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 |
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 |
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.
source_endpoint
and destination_endpoint
) will be visible if the endpoint
is public or if it’s owned by the current user, just like standard visibility
in /endpoint_search
. As a special case, if the endpoint is private and not
owned by the current user (and would normally be hidden), but the current user
has the "activity_monitor" role on the host, then the
name will be visible. This is the same as the visibility rules for
/endpoint_manager/endpoint/<endpoint_xid>
. See the extra field descriptions
above for visibility of the host endpoint name and path.
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_* |
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 |
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 |
filter_username |
equality |
[DEPRECATED] Use |
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 |
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 |
filter_min_faults |
int |
Minimum number of cumulative faults, inclusive.
Return only tasks with |
filter_local_user |
equality |
A valid username for the target system running the endpoint, as a utf8
encoded string. Requires that |
filter_endpoint_use |
equality |
Can be set to either |
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.
done
field indicates when all tasks in the request
have status "FAILED" or "SUCCEEDED" and are no longer running.
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 |
Response Body |
Admin cancel document with |
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 |
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 |
Response Body |
Pause rule document with server generated |
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/<pause_rule_id> |
---|---|
Method |
DELETE |
Response Body |
Result document. |