Developer Blog - API Updates in Preservica 8.1 and Manager Role Changes

For a summary of all our APIs, you can use the documentation index page.

Preservica 8.1 is a Long Term Support (LTS) release, for our cloud hosted customers, and will also be made available to on-premise customers.

Deprecation notice reminder

In the last LTS release (7.6) we announced that we're looking to remove the /api/accesstoken/acquire-external endpoint for security reasons. This endpoint is still available in 8.1 but we plan to remove it before the next LTS release.

In 7.7 we also announced that we plan to remove the SOAP web service for managing workflows, in favour of the REST API. We plan to remove this before the next LTS release.

If you are on premise and you are using either of these APIs, please plan to change to use better alternatives before the next release. Get in touch with us if it isn't clear how to do that for your use case.

Change to Manager Role and Functional Permissions

As we explained in the release notes, we have split the existing TenantManager permission into two permissions:

• UserManager permission is required to manage users, security and configure authentication options (e.g. configure SAML).
• ConfigManager permission is required to configure tenant options like preservation policy, schema and document management and so on.

In terms of API endpoints, UserManager functional permission is required for:

• Management endpoints on the Authentication Management API under /api/auth
• Security related endpoints on the Admin API under /api/admin/security
• User related endpoints on the Admin API under /api/admin/temporary-users and /users
• Two factor authentication configuration under /api/admin/two-factor

All other endpoints which previously required TenantManager permission now require ConfigManager instead. The TenantManager functional permission (associated with the Manager role) grants both ConfigManager and UserManager, so your existing user accounts which have Manager permission will still be able to access all management APIs. However, we recommend you give your API accounts only the permission they need (likely ConfigManager).

As before, you can see the functional permission required to use an endpoint via the Swagger documentation.

Admin API

This API allows you to configure your Preservica system.

Changes since 8.0

• You can now get information about the server time from /status/time, including the time zone the server is running in. You can use this to adjust date range filters or times shown in a UI.

Entitlement API

The Entitlement API exposes information about editions and features from the Entitlement Management System.

Changes since 8.0

• Retrieving information about your edition from GET /edition now includes the display name (e.g. "Professional Edition") as well as the edition key. You should use the edition field for UI choices, as we might change the display name, but you can use the display name to show a friendly view of the edition to the user (e.g. in a browser tab title).

Entity API

The Entity API is the main way we expose information about entities stored in your Preservica system.

Changes since 8.0

• You can now trigger an ingest from a source or a web crawl via POST /actions/ingests. This is similar to the /ingests POST added to the SO resource, when used to refer to a source location. The set of file extensions that are assumed to be packages has been expanded (check the Swagger doc for details).
• Some Entity API endpoints that accepted content including XIP would fail if given older versions of XIP. This was a bug and you can now correctly submit to these with XIP objects in any v6+ namespace. We still recommend that you use versions that match the API version you're using, or if you're using the unversioned API endpoints, the version of Preservica you're using.
• Exports, of a single SO or through /actions/exports, will now not generate a PAX for simple assets, i.e. where the requested export options result in a single file for the asset. Instead, the single file will be included in the export package (DIP).

Location API

This API provides information about locations (also known as sources) configured in Preservica.

Changes since 8.0

• A new endpoint at /upload/{id}/files will allow you to see files available for ingest on the given upload location. This is equivalent to the list shown in the SIP selection step of the ingest workflow. You can use this list to populate a UI, and then call /api/entity/actions/ingests mentioned above to start an ingest.

Process API

The Process API is for starting processes, and retrieving and updating configuration for processes.

Changes since 8.0

• You can now activate or deactivate an ingest configuration via PUT /ingests/configs/{id}/active.

Process Monitor API

The Process Monitor API lets you see information about ongoing processes and messages associated with them.

Changes since 8.0

• You can now retry a process through the API (same effect as clicking Resubmit on the UI) via a POST to /monitors/{id}/retry. This will return a new progress token, which you can use to watch the resubmitted background action.

Settings API

This API allows the retrieval of information about settings on your Preservica system.

Changes since 8.0

• There are now endpoints under /external-sync to configure external sync to happen post ingest, if it's enabled on your tenant. An asset that matches your external sync policy will trigger a new webhook (CHANGE_ASSET_VISIBILITY). We'll be saying more about external sync and how to use this webhook in future versions.

Webhooks

There is a new webhook (CHANGE_ASSET_VISIBILITY) which will receive notifications when an asset has its external sync policy (see above) evaluated, and the visibility either changes or Preservica doesn't know whether it might have changed. This webhook will send you entity type and ref. like other webhooks, but also a visible value that says whether the asset matched the policy or not.

You probably want to subscribe to this hook with includeIdentifiers turned on, as the identifiers you provided will be the only way to link existing items to the consuming system's records. Your consumer should be able to accept multiple webhooks over time for the same asset, even if its condition doesn't change, for example by checking whether a visible: true asset is already present in the external system.