Asynchronous Processing of Keep System Operations

Lasernet Keep can process some administrative actions asynchronously. This capability enables an administrator to start a large and potentially long-running administrative task, which Keep will process while administrators and other users complete other tasks in Keep. For example, deleting a key definition when the Keep database is very large can take a long time.

In earlier versions of the application (known as Autoform DM), if the administrator started a large administrative task through the Autoform DM user interface, they had to wait for the user interface to indicate that processing had completed. Also, the practical maximum size of administrative tasks was constrained by web page timeouts in the administrative user interface.

Lasernet Keep supports an async flag, which can be set as part of requests to particular REST API endpoints. If Keep accepts the request to process an action in asynchronous mode, the REST API endpoint that was called returns an id and a reference to the long-running operation. To monitor the long-running operation, you can follow the supplied reference or use the ID in a request to the GET /system-operations/{id} endpoint.

Note

Asynchronous system operations is currently a feature preview. The scope and capability of this feature could change in later versions of Keep.

This feature is intended for Keep system administrators, and for those who are integrating third-party software with Keep and require Keep to process large administrative tasks.

Use Cases

The main use cases for asynchronous system operations are deleting and unbinding key definitions.

However, Keep supports asynchronous mode for the following operations:

• Create a key definition.

• Unbind a key definition from a document definition.

• Delete a key definition.

• Unbind a document definition from a key definition.

• Delete a document definition.

Note

For information on how to use asynchronous mode for these operations, see Get Started with Asynchronous System Operations.  

Deleting a Key Definition

When a key definition is deleted, the database schema is updated to remove the column that is associated with the key. On large databases, this change can take a significant amount of time.

If this operation is started as an asynchronous operation, administrators can work on other tasks in Keep while the key definition deletion is processed.

Unbinding a Key Definition

Unbinding a key definition from a document definition can trigger updates to a large number of database rows, because obsolete data must be removed. This database update can take a long time.

When performed as an asynchronous system operation, the key binding is disabled immediately and considered complete by other areas of Keep. However, the physical removal of data from the database continues as a long-running operation.

Get Started with Asynchronous System Operations

You can start asynchronous system operations through the Keep REST API.

Start Asynchronous System Operations

The REST API endpoints for actions that support asynchronous processing have a Boolean async parameter.

If you set async to true as part of an API request and Keep determines that the requested operation can run asynchronously:

• The endpoint returns a 202 Accepted response.

• The response contains a Location header.

  • Refer to this location for information about the operation.

  • REST API clients can create a system operation and then get status updates about it from the URL provided in the Location header.

• The response body contains an id and other information about the system operation.

  • You can use this ID in a request to the GET /system-operations/{id} endpoint. The Location header provides a URL that makes a request to this endpoint.

Requests to create system operations are thoroughly validated according to the current business logic. This validation occurs before the operation is created. If a system operation is accepted, it is effectively guaranteed to complete successfully (unless failures outside Keep prevent it from doing so).

In some cases, Keep determines that asynchronous execution is unnecessary. In these situations, Keep completes the action and then returns a standard (non-async) response. The response depends on the endpoint; for example, some endpoints return 200 (OK) whereas others return 201 (Created).

Monitor Running Asynchronous System Operations

The system-operations endpoint provides a consolidated view of all historical and ongoing system operations.

You can retrieve system operations individually by ID (GET /system-operations/{id}) or collectively as a paginated list (GET /system-operations).

Cancel a System Operation

The POST /system-operations/{id}/cancel endpoint enables you to cancel a system operation (identified by its ID). You can cancel operations that are queued and have not started yet.

How Does Asynchronous Processing Affect Keep Users?

In Lasernet Keep, an object that is subject to a current asynchronous system operation enters a relevant state. For example:

• When a document definition is deleted, it enters a PENDING_DELETION state. During this period, it does not appear in search results and cannot be applied to new documents.

• When a key definition is created, it enters a PENDING_CREATION state. While in this state, it cannot store data for new documents, but it can be bound to document definitions in preparation for activation.

However, the Keep user interface does not currently support these states. As a result, the Keep web application displays only objects that are in the ACTIVE state.