The Operations resource contains the currently active operations on Files. It is usually nested under other resources, for example, /workspace_memberships/4/operations and /workspaces/1/operations.

Operations are usually created by Files when a request could take a long time to process. For example, when creating a Workspace (POST to /workspaces), Files talks to the Node to prepare some folders. This communication could take longer than the typical HTTP request/response timeouts, so Files creates an Operation Resource so that the client can monitor the progress. Specifically, Files responds with 202 Accepted and a Location header pointing to /workspaces/{workspace_id}/operations/{id}.

Access rights to the Operation Resources are usually the same as access rights to the associated resource. For example, access to /workpace_memberships/3/operations would be determined by access to /workspace_memberships/3.

Properties

  • created_at
  • data
  • id
  • status - "aborted" | "running" | "stopped" | "success"
  • type
  • updated_at
  • user_id

More properties are added depending on the type of Operation. For example, a workspace-create>workspace.create operation also has a workspace_id property.

group_membership.create

Additional Properties

  • group_membership_id

Possible values for data.type:

  • folder_conflict
  • internal_server_error

workspace.create

Additional Properties

  • workspace_id

Possible values for data.type:

  • folder_conflict
  • internal_server_error

workspace_membership.create

Additional Properties

  • workspace_membership_id

Possible values for data.type:

  • folder_conflict
  • internal_server_error
  • created_at
  • name
  • related_object_id
  • related_object_type
  • status
  • system_group
  • type
  • updated_at

One (and only one) of these query parameters may also be used to filter the result:

  • group_id
  • group_membership_id
  • user_id
  • workspace_id
  • workspace_membership_id

GET only

By default, this lists all Operations that the logged-in user started which is not necessarily all of the Operations that the logged-in user is allowed to list - the others can be accessed through the Nested Operations endpoints. If the logged-in user is an organization_admin, this lists all Operations for the Organization.

GET only

GET /workspaces/3/operations
200 Ok
[
  {
    "id": "1",
    "type": "workspace.create",
    "status": "running",
    "user_id": "1",
    "workspace_id": "3"
  }
]

GET and PUT

Examples

GET /workspaces/3/operations/1
200 Ok
{
  "id": "1",
  "type": "workspace.create",
  "status": "success",
  "user_id": "1",
  "workspace_id": "3"
}

If an error occurs, the status of the operation is set to stopped, and the data property will contain more information. For example, when creating a Workspace Membership Resource, Files will try to create a home folder for that user. If there is a conflict, Files will return:

GET /workspaces/3/operations/1
200 Ok
{
  "id": "1",
  "type": "workspace.create",
  "status": "stopped",
  "user_id": "1",
  "workspace_id": "3",
  "data": {
    "type": "folder_conflict",
    "folder_name": "jay@example.com (3)"
  }
}

In the case of a conflict, the Operation Resource endpoint accepts these properties (in a PUT request):

  • use_existing - (boolean)
  • folder_name
  • retry - (boolean)
  • apply_to_all - (boolean)

In the above example, the Operation can be restarted with:

PUT /workspaces/3/operations/1
{
  "use_existing": true,
  "retry": true,
  "apply_to_all": true
}
200 Ok
{
  "id": "1",
  "type": "workspace.create",
  "status": "running",
  "user_id": "1",
  "workspace_id": "3"
}
Video player

Video

×

Reset your Password Password resets are handled on the Support Site

×