Subscriptions

❗	Warning: This page is going to be retired and this documentation will be maintained at - https://github.com/OpenConceptLab/ocl-docs/blob/main/docs/source/oclapi/technical/subscriptions.md

Table of Contents

Overview

• Overview
• Subscription Process
• Example

Overview

A client system may subscribe to the concepts and mappings in a source by using a combination of the Export API and the sources endpoint. The high-level subscription process is as follows:

1. SUBSCRIPTION CLIENT CONFIGURATION: Configure OCL subscription module to subscribe to a specific source with the correct authentication token and to optionally automatic retrieve future updates on a schedule
2. INITIAL SYNCHRONIZATION: Perform initial synchronization, which consists of (1) downloading and importing the full export file (containing concepts and mappings) of the "latest" released source version; and (2) fetching updates to the dictionary that were made after the export timestamp
3. SUBSEQUENT SYNCHRONIZATIONS: Requests additional updates (includes Creates, Updates and Deletions) to the source manually or automatically based on a schedule (e.g. weekly/monthly) that occurred after the most recent prior synchronization. Import the changes into the OpenMRS concept dictionary.

The recommended approach is to create an OCL user that is only used for subscriptions. All requests must use the API token displayed on the OCL user profile page.

An external_id field is supported in most resources to allow correct matching of resources between OCL and client systems. The following resources include the external_id field: sources, concepts, mappings, concept names, and concept descriptions.

Subscription Process

For the first synchronization, fetch the most recent export of a released source version

• Fetch the latest released version of the source -- record the source version "id" field

GET /orgs/[:org]/sources/[:source]/latest/

• Retrieve the filename of full export for the latest released source version, which is returned in the response header as the exportURL field. Note that if the export file does not already exist, is still being processed, or is invalid, the API returns a specific status or error code and the export can be retrieved later after an appropriate interval. Refer to Export-API for more info on this request.

GET /orgs/[:org]/sources/[:source]/[:sourceVersion]/export/

• Download the export file from the exportURL (returns a compressed tar file of the JSON). Record the lastUpdated timestamp which is part of the filename. Refer to Export-API for more info on this request. Note that the exportURL is designed to be used only once and it expires after a set time limit -- to ensure that the exportURL works correctly, use it immediately and request another exportURL each time you want to download an export file.
• Fetch all updates to the source that are more recent than the export using the lastUpdated timestamp (e.g. ISO 8601 timestamp (e.g. 2011-11-16T14:26:15Z)). There are two methods for doing this:
  • Use a combination of the limit and offset parameters to iteratively retrieve results until fewer than limit results are returned. Note that the standard paging response headers (num_returned, num_found, offset, page, next_url, prev_url) are not supported at the source endpoint, and paging must be managed by the client.

GET /orgs/[:org]/sources/[:source]/?includeConcepts=true&includeMappings=true&includeRetired=true&limit=500&offset=500&updatedSince=[:lastUpdated]

* Use the `Compress: true` request header to retrieve the results as a compressed file -- this will disable paging (the `limit` and `offset` parameters will have no effect) and return all the concept/mapping results. Note that this will result in a server timeout / 404 if there are too many results. In practice, if you expect more than 1,000 results, it is not recommended to use this approach at this time.

GET /orgs/[:org]/sources/[:source]/?includeConcepts=true&includeMappings=true&includeRetired=true&updatedSince=[:lastUpdated]

For subsequent synchronizations, fetch records that have been updated since the lastUpdated timestamp

• Fetch all updates to the source that are more recent than lastUpdated timestamp (e.g. ISO 8601 timestamp (e.g. 2011-11-16T14:26:15Z)) from the previous synchronization. See above for the two methods of retrieving updated records at the source endpoint. Record the current timestamp to be used in subsequent requests.

GET /orgs/[:org]/sources/[:source]/?includeMappings=true&includeConcepts=true&includeRetired=true&limit=0&updatedSince=[lastUpdated]

Example

• A subscription client, such as the OpenMRS OCL Subscription module, should be configured with the source URL (e.g. `/orgs/CIEL/sources/CIEL/), an API token, and a synchronization schedule (e.g. weekly or monthly)
• On the first synchronization:
  • Subscription client will request details on the most recent released source version: GET /orgs/CIEL/sources/CIEL/latest/
  • Subscription client will request the export file URL of the most recent released source version, which will return the exportURL in the response header: GET /orgs/CIEL/sources/CIEL/[:sourceVersion]/export/
    • Note that if the export file is not ready, the subscription client will need to request the export file again after an appropriate interval
  • Subscription client will download the export file from exportURL, which is returned as a compressed tar of the JSON results -- the exportURL can be discarded, as it is re-generated for each request
  • Subscription client will decompress the file and process the results
  • Subscription client may then request any changes to the source that occurred after the lastUpdated timestamp of the export file: GET /orgs/CIEL/sources/CIEL/?includeConcepts=true&includeMappings=true&includeRetired=true&updatedSince=[:lastUpdated] -- these results should be processed in the same manner as above; the lastUpdated date should be stored for subsequent synchronizations
• On subsequent synchronizations:
  • Later, subscription client may request any changes to the source that occurred after the lastUpdated timestamp of the previous synchronization: GET /orgs/CIEL/sources/CIEL/?includeConcepts=true&includeMappings=true&includeRetired=true&updatedSince=[:lastUpdated] -- these results should be processed in the same manner as above; the lastUpdated date should be stored for subsequent synchronizations