{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "CodeSystem",
"url": "http://sample.com/CodeSystem/1",
"status": "draft",
"content": "complete",
"concept": [
{
"code": "A",
"display": "First concept"
},
{
"code": "B",
"display": "Second concept"
}
]
}
}
]
}
Part of Content release process
Appendix G - Configure Ontoserver
Ontoserver has a wide range of configuration options that can be used to control the way the server behaves, including functionality related to FHIR operations, indexing, syndication, security and the appearance of the capability statement.
Configuring Ontoserver is done by specifying values for configuration parameters. These can be passed to the Ontoserver Docker image using environment variables. See the full set of configuration parameters.
We have provided a selection that cover areas of the configuration that are frequently customised.
1. Configuring the CapabilityStatement
The following parameters can be used to customise the CapabilityStatement resource that is provided by Ontoserver at the /metadata endpoint .
These should be set appropriately for each server (authoring, staging and each production server) in the deployment.
conformance.contact[n]
Contact details to assist a user in finding and communicating with the publisher.
This controls the content within the contact element:
| Element Id | CapabilityStatement.contact |
|---|---|
| Definition | Contact details to assist a user in finding and communicating with the publisher. |
| Cardinality | 0..* |
|
Type. |
ContactDetail |
| true | |
| Comments | May be a web site, an email address, a telephone number, etc. |
Example
conformance.contact[0].name=Jo Smith
conformance.contact[0].telecom[0].system=email
conformance.contact[0].telecom[0][email protected]
conformance.contact[1].name=Maria Martinez
conformance.contact[1].telecom[0].system=email
conformance.contact[1].telecom[0][email protected]
conformance.contact[1].telecom[1].system=phone
conformance.contact[1].telecom[1].value=+987 6543 2100
conformance.experimental
Default value:true
A Boolean value to indicate that this capability statement is authored for testing purposes (or education/evaluation/marketing) and is not intended to be used for genuine usage.
Controls the content of the experimentalelement:
| Element ID | CapabilityStatement.experimental |
|---|---|
| Definition | A Boolean value to indicate that this capability statement is authored for testing purposes (or education/evaluation/marketing) and is not intended to be used for genuine usage |
| Cardinality | 0..1 |
| Type | boolean |
| Requirements | Enables experimental content to be developed following the same lifecycle that would be used for a production-level capability statement. |
| Summary | true |
| Comments | Allows filtering of capability statements that are appropriate for use versus not. |
conformance.implementation.description
Default value: Ontoserver, The Australian e-Health Research Centre, CSIRO
Information about the specific installation that this capability statement relates to.
Controls the content of the implementation.description element:
| Element ID | CapabilityStatement..implementation.description |
|---|---|
| Definition | Information about the specific installation that this capability statement relates to. |
| Cardinality | 1..1 |
| Type | string |
| Summary | true |
conformance.publisher
Controls the content of the publisher element:
| Element ID | CapabilityStatement.publisher |
|---|---|
| Definition | The name of the organization or individual that published the capability statement. |
| Cardinality | 0..1 |
| Type | string |
| Requirements | Helps establish the "authority/credibility" of the capability statement. May also allow for contact. |
| Summary | true |
| Comments | Usually an organisation but may be an individual. The publisher (or steward) of the capability statement is the organization or individual primarily responsible for the maintenance and upkeep of the capability statement. This is not necessarily the same individual or organization that developed and initially authored the content. The publisher is the primary point of contact for questions or issues with the capability statement. This item SHOULD be populated unless the information is available from context. |
2. Customising how the FHIR API works
The following configuration parameters affect the behaviour of the FHIR API.
ontoserver.fhir.base
Base URL for the FHIR API endpoint – public. Set this explicitly if the auto-detected value is wrong (e.g. when your server is sitting behind an API gateway/load balancer/proxy server). This affects CapabilityStatement.url – as well as full URLs in FHIR responses such as Bundle. It also affects the URLs pointing at this server in the downstream syndication feed (if enabled).
snomed.default.edition
Default value: 32506021000036107
Default SNOMED CT Edition to use when a SNOMED CT version is not supplied.
32506021000036107 corresponds to the Australian Edition of SNOMED CT.
Possible values for this parameter might include 83821000000107 (UK Combined edition, which includes both clinical and drug extension modules as well as their reference sets), or 999000031000000106 (the UK Clinical edition, including clinical reference sets).
5. Preload
atom.preload.feedLocation
Default value: file:///data/preload.xml
Comma-separated list of URI-encoded absolute URLs for Atom feeds whose entries will be fetched into Ontoserver on startup. For more information, see Preload Configuration:
Preload a bundle of resources
The Ontoserver docker image includes a preload feed that points to a FHIR Bundle at file:///data/preload.json.
This can be overwritten with a new Bundle to make Ontoserver load other resources.
For example, the following Bundle includes a very simple CodeSystem resource:
Having created this in a file called preload.json we can make a new docker image using a dockerfile like:
FROMaehrc/ontoserver:ctsa-6.1
COPY preload.json data/preload.json
We can then put the Dockerfile and our preload.json file in a directory for example myOntoserver) and tweak our docker-compose.yml file to use our new image instead of the base Ontoserver image, by replacing the line:
image:aehrc/ontoserver:ctsa-6.1
with
build:myOntoserver
and running it with a build step such as:
docker-compose - f docker - compose.yml build
docker -compose - f docker 0 compose.ylm up - d
Preload with a feed of resource
If you prefer to load resource separately rather than bundling them up, another option is to create is to create a syndication feed and preload content from that.
For example, the following includes a CodeSystem and a ValueSet.
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:ncts="http://ns.electronichealth.net.au/ncts/syndication/asf/extensions/0.1.0">
<title type="text">My preload feed</title>
<link rel="alternate" type="application/atom+xml" href="file:///data/preload.xml"/>
<updated>2019-06-30</updated>
<id>urn:uuid:b617906a-e0f8-45f7-a0f3-0742a2bb3135</id>
<ncts:atomSyndicationFormatProfile version="http://ns.electronichealth.net.au/ncts/syndication/asf/profile/0.1.0"/>
<entry>
<title>My CodeSystem</title>
<category term="FHIR_CodeSystem" label="FHIR Code System" scheme="http://ns.electronichealth.net.au/ncts/syndication/asf/scheme/1.0.0" />
<id>7f6af166-cf09-4741-83d3-ac2be4880e00</id>
<published>2019-06-30</published>
<summary type="text">This is my CodeSystem</summary>
<link rel="alternate" href="file:///data/myCodeSystem.json" type="application/fhir+json" />
<ncts:contentItemIdentifier>http://example.com/CodeSystem/1</ncts:contentItemIdentifier>
<ncts:contentItemVersion>1.0.0</ncts:contentItemVersion>
</entry>
<entry>
<title>My ValueSet</title>
<category term="FHIR_ValueSet" label="FHIR Value Set" scheme="http://ns.electronichealth.net.au/ncts/syndication/asf/scheme/1.0.0" />
<id>539a689f-cd46-4756-94be-29aed8544cb2</id>
<published>2019-06-30</published>
<summary type="text">This is my ValueSet</summary>
<link rel="alternate" href="file:///data/myValueSet.json" type="application/fhir+json" />
<ncts:contentItemIdentifier>http://example.com/ValueSet/1</ncts:contentItemIdentifier>
<ncts:contentItemVersion>1.0.0</ncts:contentItemVersion>
</entry>
</feed>
We can then out our files in a directory structure such as:
+ myOntoserver/
- Dockerfile
+ data/
- preload.xml
- myCodeSystem.json
- myValueSet.json
With a Dockerfile such as:
FROM quay.io/aehrc/ontoserver:ctsa-6.1
COPY data/* data/
and like option 1, change our docker.compose.yml file to use our new Docker image by replacing:
image: quay.io/aehrc/ontoserver:ctsa-6.1
with:
build: myOntoserver
and running it with a build step, such as:
docker-compose -f docker-compose.yml build
docker-compose -f docker-compose.yml up -d
Preload using a remote feed or multiple feed
It is necessary to use either remote syndication feeds or multiple feeds, this can be done using the atom.preload.feedLocation configuration parameter.
This setting can be included in the docker.compose.yml file.
For example, we could add the following line to the environment section of our ontoserver container.
- atom.preload.feedLocation=https://acme.com/acme-terminology.xml,https://some.department.gov.au/fhir-resources.xml
atom.preload.schedule.cron
If set to a valid cron expression, the server will re-execute preload at the schedule specified by the cron expression. If this property is not present the schedule is disabled, which is the default.
A Crontab expression is a list of six single space-separated fields: representing second, minute, hour, day, month, weekday. Month and weekday names can be given as the first three letters of the English names.
| 0 0 * * * * | The top of every hour of every day |
| */10 * * * * * | Every ten seconds |
| 0 0 8-10 * * * | 8, 9 and 10 o'clock of every day |
| 0 0 6,19 * * * | 6:00 AM and 7:00 PM every day |
| 0 0/30 8-10 * * * | 8:00, 8:30, 9:00, 9:30, 10:00 and 10:30 every day |
| 0 0 9-17 * * MON-FRI | On the hour, nine-to-five, weekdays |
| 0 0 0 25 12 ? | Every Christmas Day at midnight |
Security and anonymous read mode
ontoserver.security.enabled
Default value: false
If "true", enables role-based security on the various Ontoserver API families. Each of the "api", "fhir", and "synd" endpoints has separate READ and WRITE roles.
ontoserver.security.token.secret
The secret signing key for the JWT tokens that allows Ontoserver to trust the tokens produced by your authorisation server. See the Configure identity providers page for more information on how to configure the authorisation server:
Configure identity providers
Ontocloak can be configured to use external services for identity, and also user feedback.
External identity provider
Ontcloak can be confgured to delegate to the following types of identity provides:
SAML: See SAML v2.0 identity providers
OpenID Connect: See OpenID Connect v1.0 Identity providers
Well known social OpenID Connect providers: Includes Bitbucket, Github, Google, LinkedIn, Microsofy , OpenShift,Paypal. Stack, Overflow, Twitter and Instagram . See social identity providers.
User federation
Ontocloak can be configured to federate identities from an external LDAP/Activite Directiory Soruce , SDAP and Active Directory.
Kerberos bridge
Ontocloak can be configured to integrate with a Kerberos server for login see Kerbos.
ontoserver.security.readOnly.api
Default value: false
If true, and role-based security is enabled, then all users (including unauthenticated users) get minimum of READ access to the "api" endpoint. This effectively enables read only access to anonymous unauthenticated users to the "api" endpoint.
ontoserver.security.readOnly.fhir
Default value: false
If "true", and role-based security is enabled, then all users (including unauthenticated users) get minimum of "READ" access to the "fhir" endpoint. This effectively enables read only access to anonymous unauthenticated users to the "fhir" endpoint.
This does not override the need for resource-level authorisation when the resource in question has a security label, unless that label is a "*.read" label.
ontoserver.security.readOnly.synd
Default value: false
If "true", and role-based security is enabled, then all users (including unauthenticated users) get minimum of "READ" access to the "synd" endpoint. This effectively enables read only access to anonymous unauthenticated users to the "synd" endpoint.
This does not override the need for resource-level authorisation when the resource in question has a security label, unless that label is a "*.read" label.
Last edited: 17 August 2021 5:51 pm