Publication
Release processes for publication is dependent on your deployment model.
Provided are some example publication processes and considerations for common deployment models
Single read/write terminology server
Without a separate read-only instance of Ontoserver to separate the authoring and use of content, there is no “release” process per se. Rather content is authored in the Ontoserver instance, and through the security model and syndication status if resources, availability of that content to various cohorts of users can be controlled.
As there is single server, controlling the approved/published state visible to users of the content is purely based on the resource level security model.
The general approach is to ensure that content under development is secured for read access to communities that only authors can see until it is ready for others to use. To release content either
- a security label or labels are added to grant read access to a cohort or cohorts of users (see Securing a FHIR resource for a community), or
- a security label is added to grant Anonymous global read access to a resource.
This requires that authors understand the ramifications of the security labels for read access to users and have the discipline to not add these before the content is approved. It also requires that an appropriate approver knows to add the appropriate set of security labels to publish a resource, which may vary for resources depending upon the number and access levels of the various user cohorts.
Ontoserver can be configured to automatically syndicate all resources it contains automatically. This removes the need for an approver to set the syndication status as specified in the Approval processes section. The security labels described to control read access vis the FHIR API will still apply to syndication API access, thereby controlling read-only access via both FHIR and syndication APIs with the same security labels with no further action required.
For an extra level of control, Ontoserver can be configured to not automatically include resources in its syndication endpoint. This will require that an approver sets the syndication status to “true” on a resource to have it appear in Ontoserver’s syndication API for download, which applies on top of the security labels described in the previous section.
Separate authoring and production servers
To publish the Authoring server’s system syndication feed state to the Production server, the process varies depending upon whether
- the release is additive, or needs to remove content from the existing content deployed on the Production server
- persistent or transient storage is being used – see Shared resources and persistent storage for more details
If performing a publication that is purely additive, i.e. the Production instance does not contain any resources that should be removed by the deployment (these are signalled by being omitted in the syndication feed to be deployed) this process can be used.
As this deployment model has a fixed preload syndication URL configured for the Production Ontoserver instance (the syndication feed URL of the Authoring server) no reconfiguration or restart of the Production Ontoserver instance is required. This process can be used regardless of whether the Production Ontoserver instance is a single instance or a scaled instance – for more details refer to Horizontally scaled read-only endpoint.
The process requires that the Production Ontoserver instance is triggered to “redo” the preload operation, which will import any resources in its configured preload feed it does not already have loaded. For resources it does have loaded, any updated versions of resources will replace existing versions (existing versions will become historical “record” version of the resource).
Manual trigger
Triggering this process manually requires an API call to Ontoserver’s syndication API, with appropriate credentials.
A bearer token with syndication API write access is required to trigger this process. Below is a sample request assuming that AAA is such a token.
curl --location --request POST 'https://ontoserver-prod-nhs.australiaeast.cloudapp.azure.com/synd/redoPreload' \ --header 'Authorization: Bearer AAA' |
WARNING: If using a read-only scaled instance (see Horizontally scaled read-only endpoint) using separate disk and database for each Ontoserver instance, this request must be sent to each Ontoserver instance serving the endpoint. If this request is passed through a load balancer to only one Ontoserver instance of many supporting the endpoint, only that Ontoserver instance’s content will be updated. The other instances will remain out of date, and requests to the endpoint will be inconsistent depending upon the instance they are routed to.
If a resource is removed from the Authoring server’s syndication feed, there are a series of options to propagate this change to the Production read-only endpoint. The resources can be removed and the new content loaded by
- manually by deleting the resources with administrative access and performing the “redo” preload process described above, OR
- restarting the Production server with a blank disk and database, which will reload the server’s state from the configured preload feed (Authoring server’s syndication URL).
Manually deleting resources
This process is described in How to delete a FHIR resource and Removing indexes for FHIR resources and indexes respectively. The current syndication feed content and Production server content need to be compared to determine which resources need to be removed.
WARNING: If using a read-only scaled instance (see Horizontally scaled read-only endpoint) using separate disk and database for each Ontoserver instance, this request must be sent to each Ontoserver instance serving the endpoint. If this request is passed through a load balancer to only one Ontoserver instance of many supporting the endpoint, only that Ontoserver instance’s content will be updated. The other instances will remain out of date, and requests to the endpoint will be inconsistent depending upon the instance they are routed to.
Clearing production storage and restarting the server
If using transient storage for the Production Ontoserver instance, then simply stopping and deleting the Ontoserver container and its PostgreSQL container is sufficient. The transient storage with the Ontoserver and PostgreSQL containers will be removed when the containers are removed, and new blank storage will be created when a new Ontoserver and PostgreSQL container are created. Upon boot, Ontoserver will populate its blank disk and database from the configured preload syndicaiton feed, which in this case is the Authoring Ontoserver instance.
If using persistent storage
- The Ontoserver container must be stopped
- Its persistent disk content must be cleared to blank, or the persistent disk replaced with a new blank persistent disk
- Ontoserver’s PostgreSQL database schema must be emptied, this can simply be achieved by dropping and recreating the schema
- The Ontoserver container is restarted, at which point it will repopulate its disk and database content from the configured preload syndication feed – the Authoring server’s syndication feed.
A zero down time deployment approach can be applied on top of this process, refer to Zero down time deployments for more details.
Staging and syndication server
When the syndication feed of the Authoring server achieves a milestone publishable state, an Administrator creates a release candidate snapshot (1) of the Authoring server’s syndication feed in the syndication server. This is a static snapshot of the Authoring syndication feed which can then be deployed to the Staging server (2) for testing and verification.
If testing passes, the release candidate snapshot feed in the syndication server can be deployed to the Production terminology server (3) by an Administrator making the content available for downstream consumers on the FHIR and Syndication APIs. If testing fails, corrections need to be made on the Authoring server and the process re-executed.
As multiple release candidates are created over time, a process is also described in the following sections to list the available release candidate snapshots on the syndication server to aid Administrators.
Creating a release candidate
The syndication server, Atomio, can clone a syndication feed and keep a static copy.
Timing of this snapshot must be coordinated with all the affected content owners/approvers for the Authoring server to ensure they are not part way through setting syndication status on resources – i.e. their current syndicated resources on the Authoring server represent a stable state. You can find the procedure to create a release candidate here
Listing release candidates
It is possible to view a list of available feeds on the syndication server, which will list all available release candidate snapshots. This is useful when confirming configuration to deploy a release candidate to Staging or Production. You can find the procedure to create a release candidate here
Deploy a release candidate
The release candidate will need to be deployed to the Staging or Production server. You can find the procedure to deploy a release candidate here.
An optimisation of the processes described above to release content changes to Staging/Production can be applied in the case where a release candidate only contains additions to the previously loaded content. I.e. the release candidate doesn’t need to “remove” any currently deployed content which is now omitted from the syndication feed to be deployed.
Ontoserver supports a syndication API REST request that causes the server to redo the “preload” it performs on start up. This will cause Ontoserver to fetch any content it doesn’t already have from its configured atom.preload.feedLocation feed URL.
This can be useful when persistent storage is being used with an Ontoserver instance and can even be used to do “hot” updates to the content of a running Ontoserver instance if the preload feed has been updated at the same URL. This process is typically quick as only the delta between the currently deployed release and the new release is downloaded and installed. However this method is limited to cases where the release being deployed is additive to the existing deployed content, any deployed content that is not in the new release feed will not be removed from the server.
With a new preload URL for a new release candidate feed, the Staging and Production servers would need to be restarted to configure in the new atom.preload.feedLocation value, and on restart would add the new content in the preload feed to the existing content in the persistent storage.
If the existing preload URL has been updated with added content (this can be achieved by deleting and recreating a release candidate feed with the same “feed name”) the following syndication API method can be called.
A bearer token with syndication API write access is required to trigger this process. Below is a sample request assuming that AAA is such a token.
curl --location --request POST 'https://ontoserver-prod-nhs.australiaeast.cloudapp.azure.com/synd/redoPreload' \ --header 'Authorization: Bearer AAA' |
The request will return immediately reporting 200 OK if the process has been triggered and is running asynchronously, or an error code if it cannot be.
WARNING: If using a read-only scaled instance (see Horizontally scaled read-only endpoint) using separate disk and database for each Ontoserver instance, this request must be sent to each Ontoserver instance serving the endpoint. If this request is passed through a load balancer to only one Ontoserver instance of many supporting the endpoint, only that Ontoserver instance’s content will be updated, the other instances will remain out of date, and requests to the endpoint will be inconsistent depending upon the instance they are routed to.