Ontoserver Postman

Syndication Configuration

Ontoserver can act as both a syndication client and a syndication server.

Syndication Client

atom.syndication.feedLocation (https://api.healthterminologies.gov.au/syndication/v1/syndication.xml)

Comma-separated list of URI-encoded absolute URLs of the upstream Syndication feeds. By default, this points to the Australian NCTS Syndication Service (note that this service requires credentials). Minimum is that embedded , and % characters in the URLs must be %-encoded.

It is likely that one or more of the upstream syndication servers requires credentials to be provided in order to download the content it provides. Use the authentication.oauth.endpoint.* family of credentials to provide configuration details for each of the hosts that require authorization. See the list of all configuration parameters for details.

Authenticating with a syndication endpoint

For each endpoint that Ontoserver might need to authenticate with when accessing a syndication feed or its content, appropriate credential configuration must be specified. For example, the following configuration (with appropriate values substituted for NCTS_CLIENT_ID and NCTS_CLIENT_SECRET) could be used:

  authentication.oauth.endpoint.0=https://api.healthterminologies.gov.au/syndication/v1
  authentication.oauth.endpoint.scope.0=user_impersonation
  authentication.oauth.endpoint.strategy.0=basic_auth
  authentication.oauth.endpoint.token_endpoint.0=https://api.healthterminologies.gov.au/oauth2/token
  authentication.oauth.endpoint.client_id.0=NCTS_CLIENT_ID
  authentication.oauth.endpoint.client_secret.0=NCTS_CLIENT_SECRET

Syndication Feed filtering

Sometimes it is desirable to be be able to work with a subset of an existing syndication feed. For example, just the entries for SNOMED CT.

To support this, Ontoserver understands the following filtering parameters that may be appended as a query string to a syndication feed URL.

canonical

You may specify zero or more canonical parameters with a value following the syntax of a FHIR's Canonical datatype.

This filter matches entries where the combined ncts:contentItemIdentifier and ncts:contentItemVersion are equal to any of the provided parameter values.

For example, ?canonical=http://snomed.info/sct&canonical=http://loinc.org will result in a feed that contains only SNOMED CT and LOINC code system entries.

category

You may specify zero or more category parameters with a value being a string.

This filter matches entries where any of the category.term values of the Atom entry is equal to any of the provided parameter values.

For example, ?category=FHIR_CodeSystem will result in a feed that contains only FHIR CodeSystem resource entries.

fhirVersion

You may specify zero or more fhirVersion parameters with a value being a string.

This filter matches entries where the ncts:fhirVersion values is equal to any of the provided parameter values. Note that feeds generated by Ontoserver only specify the major and minor numbers of the FHIR version e.g., 4.0 rather than 4.0.1 or 4.0.2

For example, ?fhirVersion=4.0 will result in a feed that contains only FHIR R4 (4.0.x) resource entries.

Syndication Server

atom.syndication.cache.size (5000)

The maximum number of entries, per Resource type, to cache when building the syndication feed.

atom.syndication.publish.enabled (false)

if true, enables the downstream feed endpoint (/synd/syndication.xml) which allows publication of syndication feed entries referring to pre-indexed CodeSystems and to FHIR Resources

atom.syndication.publish.fhir.enabled (false)

If downstream syndication is also enabled, then true will ensure that all FHIR Terminology Resources are included in the downstream feed, or selected will mean that all resources will be included that have been marked for syndication using /synd/setSyndicationStatus

atom.syndication.publish.fhir.secureSyndicated (false)

Setting this config to true will require SYND_WRITE (in addition to FHIR_WRITE) in order to update or delete a FHIR resource that has been selected for syndication using setSyndicationStatus.

atom.syndication.publish.index.enabled (selected)

If downstream syndication is also enabled, then true will ensure that all CodeSystem binary indexes are included in the downstream feed, or selected will mean that all indexes will be included that have been marked for syndication using /synd/setSyndicationStatus

atom.syndication.republishUpstreamEntries (false)

If true and downstream syndication is enabled, then all upstream syndication entries are included in the downstream feed.

atom.syndication.republishUpstreamFeeds
If specified, entries from these feeds will be republished instead of entries from atom.syndication.feedLocation. This option is only considered if atom.syndication.publish.enabled and atom.syndication.republishUpstreamEntries are both enabled.
ontoserver.synd.base

Base URL for the downstream Syndication API. 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 syndication.xml as well as full URLs in for downloading binary indexes (URLs for downloading syndicated FHIR resources are affected by ontoserver.fhir.base.

atom.syndication.publish.feedTitle (Ontoserver® Syndication Feed)

Title to use for the downstream Syndication feed.

atom.syndication.excludeLength (false)

If true then omit the `length` attribute from the link elements (for locally generated entries) of the Syndication Feed. If your feed includes large Resources, then this can speed up feed generation time.

atom.syndication.excludeXml (false)

If true then omit XML versions of locally syndicated FHIR Resources from the downstream feed. If your feed includes large Resources, then this can significantly speed up feed generation time.

Advanced

atom.syndication.timeout.ms (16000)

time in milliseconds that Ontoserver will wait for when fetching the upstream feed. This is used as part of detecting and preventing indirect cyclic requests

atom.syndication.disableChecksums (false)

set to true to disable signature checking of the contents of a requested feed entry

Australian NCTS Syndication

The Australian National Clinical Terminology Service (NCTS) offers a syndication service for retrieving sources and binary indexes for terminology content such as SNOMED CT and LOINC.

Ontoserver is capable of connecting to this service, and most of the configuration for authentication to this service is pre-configured. However, it is necessary to provide your credentials using the variables:

authentication.oauth.endpoint.client_id.0=NCTS_CLIENT_ID (see below)

authentication.oauth.endpoint.client_secret.0=NCTS_CLIENT_SECRET (see below)

The NCTS_CLIENT_ID and NCTS_CLIENT_SECRET values can be retrieved from the NCTS Portal as follows:

  1. Log in to your account (organisation or individual) on the NCTS Portal.
  2. Click on the Clients link in the top-right of the portal. Note: only "responsible users" for organisational accounts will see this link, if you do not see this link you will need to request that a responsible user from your organisation create the client credentials and give you the resulting Client ID and Client Secret.
  3. Create a credential for Ontoserver (the name and purpose are for information only).
  4. After doing this, the table should include a Client ID and Client Secret that can be used for the configuration NCTS_CLIENT_ID and NCTS_CLIENT_SECRET respectively) above.