Migrate from Webservices V2 to the Keep REST API

Webservices v2 (WSv2) is a legacy SOAP-based integration service for Autoform DM. WSv2 is not supported in Keep. Instead, Keep (as well as Autoform DM 9.0 and later) provides a fully documented, JSON-based REST API for integrating external systems and building robust integration solutions.

To migrate existing integrations from WSv2, you can use either of the following approaches:

• Incremental migration: Update the integrations to use Autoform DM’s REST API and then upgrade to the Keep REST API.

  Note

  Before selecting this option, review the differences between the two APIs.

• Direct migration to Keep: Update the integrations to use Keep’s REST API as part of the overall upgrade process.

This guide explains what you need to consider for a direct migration to Keep, but you would follow a similar process for an incremental migration. You need to:

• Identify affected code

• Select replacement endpoints

• Implement your preferred authentication method

Identify Affected Webservices V2 Code

Integrations that call the following WSv2 endpoints, or that retrieve and interrogate the associated WSDL documents (?wsdl), will no longer function after upgrading to Keep:

{baseurl}/pdmwebsvc-v2/document
{baseurl}/pdmwebsvc-v2/search
{baseurl}/pdmwebsvc-v2/import
{baseurl}/pdmwebsvc-v2/email
{baseurl}/pdmwebsvc-v2.1/document
{baseurl}/pdmwebsvc-v2.1/search
{baseurl}/pdmwebsvc-v2.1/import
{baseurl}/pdmwebsvc-v2.1/email

In addition, any SOAP client implementations or custom code that parses returned XML responses from the WSv2 endpoints are no longer applicable or supported.

Select Replacement API Endpoints

To help you identify the correct REST API endpoints when updating your integration code, the following table maps affected WSv2 operations and resources to their REST API equivalents, where available. Any significant functional differences between a WSv2 operation and its mapped resource and endpoint are described in the WSv2 and REST API Differences section.

Tip

Use the Swagger API documentation to review the request URL, parameters, and payload for each endpoint. See the Lasernet Keep REST API section for full details of how to authenticate and use the API documentation.

WSv2 and REST API Differences

In the following cases, WSv2 functionality is not replicated by a single REST API endpoint.

WSv2 /search Operation

To replicate the WSv2 /search operation:

1. Send a request to the following endpoint to execute a named search configuration. The request returns a list of documents along with their metadata.

   GET /searches/{name}/execute

2. To retrieve resources from the returned list of documents, such as files, line items, or notes, send additional requests to the /documents endpoints using metadata from the initial search results. For example:

   • To retrieve a specific revision of a document, use:

     GET /documents/by-id/{id}/{revision}/file

   • To retrieve a specific note from a document, use:

     GET /documents/by-cuk/{cuk}/notes/{noteId}

WSv2 CreateOrUpdate Resource

To replicate the WSv2 CreateOrUpdate resource, you also need to use multiple endpoints.

• To create a document, use:

  POST /documents

• To update an existing document, use either of the following endpoints:

  PUT /documents/by-id/{id}
  PUT /documents/by-id/{id}/{revision}/line-items

Tip

To control whether a document appears in search results, send a request to update the document and set the hidden property as follows:

• Set hidden to true to hide the document.

• Set hidden to false to make the document visible again.

REST API Authentication

The SOAP-based WSv2 integration service supports only stateless authentication, with credentials provided for each request. In contrast, to integrate with the Keep REST API, you can choose from two authentication methods, depending on your implementation requirements, security model, and usage patterns:

• Session-based authentication (cookie-based)

• API key authentication (stateless, token-based)

Both authentication methods require your integration to authenticate as a system user, with access to the document archive constrained by that user’s assigned role and application permissions.

To find out more about each authentication method, use the REST API documentation:

• For session-based authentication, try out the /sessions endpoint and inspect the cookie-based responses.

• For token-based authentication, generate an API key via the user interface or /api-keys endpoint. You can then use the generated key as a bearer token in the authorization request header.