Lasernet Keep Configuration Management

The Lasernet Keep configuration management capability consists of configuration import and export features.

You can use the configuration export feature to export Keep’s system configuration as a JSON file. You can export specific parts of the system configuration, or the entire system configuration.

You can then import and apply that system configuration to another Keep system.

This feature enables you to run a change and configuration management process for Keep configurations, to support an environment segregation model for Keep within your organization. Configuration management is a general term used to define the process of making ongoing changes to a product while limiting the possibility of introducing problems or breakages.

Note

This feature exports and imports Keep system configuration. This can include the document definitions, key definitions, key bindings, groups, and other entities that are defined within Keep’s system configuration. It does not export the data held within Keep, such as the archived documents themselves.

Note

In the context of this feature, the term configuration refers specifically to the Keep system configuration.

In other parts of Keep, the term configuration refers to uploads and searches instead.

Environment Segregation

To adopt a robust change management process, it is important to understand the lifecycle of a product and the changes being applied. The minimum requirement to achieve some level of change control is to have a distinct test environment, separate from the live environment. This enables whoever manages the test environment to manually make changes there and test them in that environment, before utilising the configuration management process to apply the now quality-assured configuration in the test environment to other environments.

To achieve a more robust process, a common set of environments that we recommend are:

• DEV: Allows changes to be applied freely and in isolation in order to investigate and solve problems or meet requirements.

• UAT: Allows changes to be rolled out in a controlled manner in order to be tested as part of the solution.

• LIVE: Allows only approved changes from UAT to be applied in order to ensure minimal risk of disruption to production.

If you did not use a configuration management process (to export the configuration from one environment and apply it to another), you would need to manually make the same configuration changes in each environment. This manual process would introduce the risk of human error, and it would require Keep to have more top-level administration users. Keep’s configuration import and export feature, which enables you to take a system configuration from one environment and apply it to another, solves this problem.

Version Control

Version control is critical to ensuring the configuration management process is robust. In essence, this means storing a copy of the configuration outside the application in some form of source control technology, such as Git.

Taking this approach ensures a full audit history of any changes, and where necessary, the ability to roll back specific revisions.

Keep exports system configurations as JSON data, which can be easily stored in a version control system.

Export and Import the Keep System Configuration

You can export and import the system configuration through the Keep user interface. You can also use the Keep REST API. Both of these methods provide the same basic import and export functionality. However, through the user interface, you can select which search, uploads, definitions, users, groups, and settings to include in the export.

The import feature includes a configuration validation capability, which enables you to perform a test import of the system configuration. This test import enables you to see if any errors are raised when Keep simulates importing the configuration. Crucially, the configuration is not applied to Keep after the test import completes.

Validation enables you to identify any problems that importing a configuration will cause, with no risk of applying a problematic configuration that will break the destination Keep environment. You can use the validation results to fix any problems, and then you can validate and import an updated Keep configuration.

Note

Before you use this feature, ensure that you have a good understanding of the content of a Keep system configuration.

Note

In this section, the Keep system that you import a configuration into is referred to as the destination.

Export Through the User Interface

The following sections describe how to start the configuration export process in the Keep user interface, and then complete each stage of the export process.

Start the Configuration Export Process

To access the Configuration Export page, click Archive Structure in the admin menu, then select Configuration Export.

The Configuration Export process is a straightforward page-by-page experience. A progress indicator shows you how far through the process you currently are.

Click Next and Back (in the upper-right corner) to navigate between pages of the process.

The Configuration Export Process

To set up and complete an export of a Keep system configuration, follow this process:

1. Choose the export type. You can export every element of the system configuration, or only selected parts.

2. Select other export options.

3. Select which uploads and searches to export.

4. Select which document definitions, key definitions, archive path definitions, users, and groups to export.

5. Select which system settings to export.

6. Complete the export process. At this final stage, you can view the configuration export JSON and download it as a file.

For step-by-step instructions for each part of this process, see the following sections.

1. Choose the Export Type

In the Export Type area of the Export Options page, click Entire System or Selective:

• Entire System: All uploads, searches, document definitions, key definitions, archive path definitions, users, and groups are exported.

• Selective: You use subsequent pages of the process to choose which of these items are exported.

2. Select Export Options

On the Export Options page, appropriately set the following options.

• Existing Item Strategy: This option determines whether items (such as document definitions) that already exist in the destination Keep system are retained or deleted. For more information, see Existing Item Strategy.

  Note

  Existing item strategy applies only to the types of items that are included in the configuration export.

  For example, if you choose to include document definitions in the export, this setting determines whether other document definitions that already exist in the destination system are retained or deleted when the configuration is imported. Whereas if you choose, for example, to omit user and groups from the configuration export, the users and groups in the destination system will be unaffected after you import the configuration, regardless of whether you select Keep or Delete for Existing Item Strategy.

• Existing Relationship Strategy: This option determines whether relationships (such as bindings of key definitions to document definitions) that already exist in the destination Keep system are retained or deleted when the configuration is imported. For more information, see Existing Relationship Strategy.

• Include User References: This option determines whether the export contains the relationships that exist between searches and users, uploads and users, and groups and users. This option should be selected only if your Keep system contains these relationships. Some Keep systems do not contain them, because user access to searches and uploads is assigned via group access (rather than direct access), and group membership data for users is provided through LDAP or other means (rather than by adding users to groups in Keep).      

• Include Protected Settings: Some server settings (such as Lock Server) can have a significant impact on Keep. These settings are known as protected settings. When an administrator modifies them through the Keep user interface, they have to explicitly confirm the change to avoid accidentally altering significant aspects of how Keep operates. To include protected settings in the configuration export, select Include Protected Settings.

The Export Items summary pane summarizes the current configuration export setup.

To move to the next stage, click Next:

• If you selected Selective for Export Type, Keep moves to the page that enables you to select which uploads and searches to export.

• If you selected Entire System for Export Type, Keep moves to the Export Result page.

3. Select Which Uploads and Searches to Export

On the Configurations page, select which uploads and searches to export.

• To select all uploads, select Document Uploads (see 1 in the image below).

• To select all searches, select Document Searches (2).

• To select particular uploads or searches, click the arrow in the corresponding row to expand that area (3), and then select individual uploads or searches (4).

The area headers indicate how many items are selected (5). For example, if the uploads header contains Document Uploads (0/1), one upload is currently set up in Keep, and none are selected for export.

If no items in an area are selected, the checkbox in the area header is empty. If all items are selected, the checkbox is selected. If some items are selected (but not all), the checkbox contains a horizontal line.

The Export Items summary pane (6) summarizes the current configuration export setup. It lists the searches and uploads that you selected. It also includes other items (such as document definitions and key definitions) that Keep has automatically selected for export because those searches and uploads depend on them.

To move to the next stage, click Next (7).

4. Select Which Document Definitions, Key Definitions, Archive Path Definitions, Users, and Groups to Export

On the Definitions page, select which document definitions, key definitions, archive path definitions, users, and groups to export.

• To select all items of a particular type, select the checkbox in the relevant row (see 1 in the image below).

• To select particular items only, click the arrow in the corresponding row (2), and then select individual items (3). The area that Keep displays also enables you to select other items that are related to those in the list, such as extended properties for users.

  Note

  The Users list contains deleted users. When you delete a user, the user account is removed from the All Users page, but Keep does not actually delete the user account, because it is linked to data about the past actions that the user performed in Keep. Because the user is still defined in Keep, it is present in the Users list on this Definitions page.

The area headers indicate how many items are selected (4). For example, if the document definitions header contains Groups (1/2), two groups are currently set up in Keep, and one is selected for the configuration export.

Some items (such as document definitions) might already be selected and grayed (5). These items must be exported, because an item that you have already selected depends on them. For example, if you select a particular search, the document definitions that are bound to it must also be exported.

If no items in an area are selected, the checkbox in the area header is empty (6). If all items are selected, the checkbox is selected (1). If some items are selected (but not all), the checkbox contains a horizontal line (7).

The Export Items summary pane (8) summarizes the current configuration export setup. It lists the items that will be exported.

To move to the next stage, click Next (9).

5. Select Which System Settings to Export

On the Settings page, select which Keep system settings to export.

To select a category of Keep settings (such as Password Settings), select the checkbox in the relevant row (see 1 in the image below). All settings of that type are selected. To see which settings that category includes, click the arrow (2) in the corresponding row (to expand that area). However, some settings are exported only if Include Protected Settings is enabled on the Select Export Options page.

The Export Items summary pane (3) summarizes the current configuration export setup. It lists the items that will be exported.

To move to the next stage, click Next (4).

6. View and Download the Configuration Export JSON

The Export Result page displays the configuration export JSON in the Export Result area (see 1 in the image below). You can copy the JSON from there.

Alternatively, click Download (2) to download the result as a JSON file.

Missing References

The current setup of the configuration export might omit some items that other items included in the export contain references to. For example, suppose that a group is granted access to a search, but that group is not included in the configuration export. In this scenario, the Export Result page contains a Missing References area. This area lists the missing items and identifies the items in the export that refer to them.

To add these items to the export, select the Add checkbox in their rows. After you do this, Keep updates the JSON in the Export Result area.

Import Through the User Interface

To import a configuration into Keep, follow the instructions in the following sections.

1. Start the Configuration Import Process

To access the Import Configuration page, click Archive Structure in the admin menu, then select Configuration Import.

2. Choose a Keep Configuration File to Import

Click the file selection box (see 1 in the image below) and then select a Keep configuration file to import. Keep opens the file.

The Properties box (2) summarizes the main import properties and settings (including Keep Version, the Existing Item Strategy, and the Existing Item Relationship Strategy).

Keep indicates the import file’s current Validation Status (3).

The next part of the page (4) displays the items that the configuration file contains. You can click the arrow beside a category to expand it and see what items it contains, or click Expand All to expand all categories.

3. Recommended: Validate the Import File

To validate the content of the import file (to ensure that importing its content won’t cause errors), click Validate.

If the validation identifies no errors, Keep displays a File successfully validated message. The Validation Status changes to Successfully Validated.

If the validation identifies errors in the file, Keep displays a Validation failed message (see 1 in the image below). The Validation Status changes to Validation Error (2), Keep displays an x beside the affected import items (3), and an Error Details area (4) describes the errors that Keep found. If validation fails, Keep grays out the Import button to prevent you importing the file.

4. Fix Any Validation Errors

If Keep identified any errors when you validated the import file, fix these errors in the source system (by checking the Keep system configuration and checking the configuration export settings), then export the configuration file again.

Select the updated file on this destination Keep system’s Configuration Import page, then validate the updated file. If validation fails again, repeat this “fix and then validate” process until the validation succeeds.

5. Import the Configuration File

After you import a configuration file and successfully validate it (or if you decide not to validate it), you can click Import.

Keep will import the configuration and then display a message after it completes the import.

Use the Keep REST API

Export and import are exposed via the Keep REST API because most automated interactions are likely to be performed using this method.

An example process that uses the REST API would be that an administrator logs into Keep, selects items to export, produces a configuration.json file, and then runs that JSON file through an automated script that automatically deploys it to the relevant destination Keep system via its REST API.

Full automation using the /export endpoint is currently not recommended due to the complexity of building the export definition, however, it is possible by traversing other resources.

Data Format

The data format used by the configuration management feature is JSON (Java Script Object Notation). This is a simple text-based format that is human-readable and supports version control. It also matches the format used by the Keep REST API.

The following example JSON configuration file contains:

• A properties section detailing the source of the export.

• The existingItemStrategy setting (see Existing Item Strategy).

• The existingItemRelationshipStrategy setting (see Existing Relationship Strategy).

• An example document definition.

• Two example key definitions.

{
  "properties": {
    "dmVersion": "11.0.0",
    "applicationServer": "keepserver",
    "databaseServer": "keepserver/AFPDM",
    "exportTimestamp": "2025-10-08T08:14:52.655Z"
  },
  "existingItemStrategy": "KEEP",
  "existingItemRelationshipStrategy": "REPLACE",
  "documentDefV3s": [
    {
      "name": "letter",
      "label": "Letter",
      "customFilename": "",
      "properties": {},
      "keyDefBindings": [
        {
          "reference": "customerid",
          "lifecycle": "ACTIVE"
        },
        {
          "reference": "document-date",
          "lifecycle": "ACTIVE"
        }
      ]
    }
  ],
  "keyDefV2s": [
    {
      "name": "customerid",
      "label": "CustomerID",
      "lifecycleStatus": "ACTIVE",
      "dataType": "STRING",
      "cardinality": "SINGLE",
      "docDefBindings": [
        {
          "reference": "letter",
          "lifecycle": "ACTIVE"
        }
      ]
    },
    {
      "name": "document-date",
      "label": "Document Date",
      "lifecycleStatus": "ACTIVE",
      "dataType": "DATE",
      "cardinality": "SINGLE",
      "docDefBindings": [
        {
          "reference": "letter",
          "lifecycle": "ACTIVE"
        }
      ]
    }
  ]
}

Item Hierarchy and Relationships

Most configurable items in Keep conform to a hierarchy that dictates the dependencies between configurable items. This diagram shows the relationships:

The export process is ordered in a way that reflects this. It is important to note that selecting an item will cause Keep to automatically select any items that it has a Depend on relationship with.

For example, selecting an Account Statement document definition will force the selection of the Account Number key definition on which it depends. However, the inverse is not true – selecting the Account Number key definition would not force selection of the Account Statement document definition because this is only a References link. As a result, it is possible to export the Account Number without the Account Statement. Importing that into a target system would be successful if Account Statement already exists, otherwise it would fail stating that a referenced item did not exist.

In summary, Depends On links are forced on export. References links are not forced on export, but will still fail on import if the link cannot be established in the destination system due to a missing item.

This flexibility allows items with References links to be exported and updated without the items they reference necessarily needing to be updated as well, enabling partial rollout of changes as required.

Existing State Interaction

Importing data into a blank instance of Keep is simple and conflict-free. Whereas importing into a Keep system that is not blank and has an existing configuration raises the question of conflict resolution, both in terms of existing items and the relationships between them. This is where two strategies come in.

Existing Item Strategy

This strategy defines how the import process treats items that exist in the destination system but not in the export.

The options for this are:

• Keep: Items that exist in the destination system but are not referenced in the export will not be affected. This is the default option.

• Delete: Item groups that exist in the destination system but are not included in the export will be deleted.

In most cases, Keep is likely to be the desired action.

However, when keeping systems aligned, it is usual to remove old, unused configuration elements, and this is when the Delete option would be suitable.

The following example scenario involves an application, a document definition, and two key definitions, in a scenario where Existing Item Strategy is set to Delete. In the diagram, green means created, blue means updated, and red means deleted.

Existing Relationship Strategy

This strategy defines how the import process treats existing item relationships that are not referenced in the export when updating items.

The options for this are:

• Replace: Replaces the relationships on the existing items in the destination system with those provided in the export. This is the default option.

• Merge: Combines the relationships provided on an exported item with those on the matching item in the destination system.

In most cases, Replace will help keep two systems aligned.

However, when deploying smaller configuration packs, which might share configuration, Merge allows some flexibility because it does not overwrite existing relationships. In the following example of the Merge option, green means created, blue means updated, and grey means unchanged:

The following diagram shows what happens if Replace is selected. In this diagram, green means created, and blue means updated. After the import, period is no longer bound to account-statement.

Users

Users are an outlier in the world of configuration management as they are often environment-specific or handled by LDAP. As a result, they come with some usage complications as detailed below.

We recommend managing user access via group membership and LDAP.

Strict deletion of users is still unsupported, and therefore, configuration management still handles user deletion as a hide and disable operation.

To provide flexibility in this area, the Include User References export setting is available. In most cases, this can be left as false, ignoring any direct assignments of user access to applications or groups. However, if direct user access is managed in Keep and needs to be mirrored on the target system, selecting true will make sure it is respected.

To ensure security, Keep does not export user passwords; however, the creation of users via import does require that a password is specified. Currently, users will be exported with a blank password field, which must be populated manually with a temporary password prior to import. This applies if being used to create the user in the new system. That password will then expire on next login and the user will be able to specify a new one.

For example:

{
  ...
  "users": [{
    "user" : {
      "username": "JohnSmith",
      "status": STANDARD,
      "accountExpiry": "2019-01-01T00:00:00.000Z",
      "emailAddress": "string",
      "noPasswordExpiry": true,
      "bypassLockout": false,
      "changePasswordNextLogin": true,
      "fullName": "John Smith",
      "roles": [
        "pdm", 
        "pdmAdmin"
      ],
      "groups": [
        "testGroup"
      ]
    },
   "password": "a$6hyYtq*&Av" // required by the import
  }]
  ...
}

Documents

Documents are not classed as part of the configuration, so it is important that the configuration management feature in no way manipulates or destroys document data. As a result, any import operation that would require the deletion of dependent documents (for example, the removal of a key definition) will fail.

Configuration that relates directly to document data is:

• Key definitions

• Document definitions

• Document definition properties

• Users