Skip to main content
Version: 3.1.0

Configuration

Pathling is distributed in two forms: as a JAR file, and a Docker image. The easiest way to configure Pathling is through environment variables.

If environment variables are problematic for your deployment, Pathling can be also configured in a variety of other ways as supported by the Spring Boot framework (see Spring Boot Reference Documentation: Externalized Configuration).

Configuration variables​

General​

  • server.port - (default: 8080) The port which the server should bind to and listen for HTTP connections.
  • server.servlet.context-path - A prefix to add to the API endpoint, e.g. a value of /foo would cause the FHIR endpoint to be changed to /foo/fhir.
  • pathling.implementationDescription - (default: Yet Another Pathling Server) Controls the content of the implementation.description element within the server's CapabilityStatement.
  • JAVA_TOOL_OPTIONS - (default in Docker image: -Xmx2g) Allows for the configuration of arbitrary options on the Java VM that Pathling runs within.

Additionally, you can set any variable supported by Spring Boot, see Spring Boot Reference Documentation: Common Application properties.

Outgoing connections​

  • pathling.allowInsecureUrls - (default: false) Whether plain-http URLs may be used for outgoing connections from the server (the $import, $import-pnp and $bulk-submit operations). Setting this to true is intended for local testing against http:// endpoints; production deployments should leave it at the default.

Import​

  • pathling.import.allowableSources - (default: file:///usr/share/staging) A set of URL prefixes which are allowable for use within the import operation. HTTP(S) prefixes are matched with proper URI semantics: scheme, host (case-insensitive), effective port (default 80 or 443) and a path-segment boundary must all match, and any candidate that contains a userinfo component is rejected. So https://example.com admits https://example.com/foo but not https://example.com.evil.com/foo or https://example.com@evil.com/foo. Non-HTTP prefixes (e.g. s3://, file://) are matched by case-sensitive string prefix; for these, a trailing slash should be used in cases where an attacker could create an alternative URL with the same prefix, e.g. s3://some-bucket would also match s3://some-bucket-alternative.

Ping and pull​

These settings configure the ping and pull import operation, which retrieves data from external FHIR bulk export endpoints.

  • pathling.import.pnp.allowableExportUrls - (default: []) A list of URL prefixes which are allowable for use as export URLs within the $import-pnp operation. This list is mandatory: when it is empty every $import-pnp request is rejected. Any exportUrl that does not match one of the configured prefixes is also rejected. HTTP(S) prefixes are matched with proper URI semantics (see pathling.import.allowableSources above for the full rules).
  • pathling.import.pnp.clientId - The client identifier for SMART Backend Services authentication.
  • pathling.import.pnp.tokenEndpoint - The token endpoint URL for obtaining access tokens. If not specified, the client will attempt to discover it via the SMART configuration endpoint.
  • pathling.import.pnp.privateKeyJwk - The private key in JWK format for asymmetric authentication (RS384).
  • pathling.import.pnp.clientSecret - The client secret for symmetric authentication.
  • pathling.import.pnp.scope - The requested scope for authentication (e.g., system/*.read).
  • pathling.import.pnp.tokenExpiryTolerance - (default: 120) The minimum number of seconds that a token should have before expiry when deciding whether to use it. If a cached token has less than this many seconds until expiry, a new token will be requested.
  • pathling.import.pnp.downloadLocation - (default: /usr/share/staging/pnp) The directory where files will be downloaded during ping and pull import operations. This location should have sufficient space for large FHIR exports.
  • pathling.import.pnp.fileExtension - (default: .ndjson) The file extension to filter for when processing downloaded files.
  • pathling.import.pnp.allowInternalUrls - (default: false) When set to false, the $import-pnp operation will reject exportUrl values that resolve to internal or private IP addresses (loopback, link-local, site-local, and unique-local). Set to true only if your deployment legitimately uses internal FHIR bulk export endpoints.
  • pathling.import.pnp.maxConcurrentDownloads - (default: 4) The number of files to download concurrently. Each download is written to storage as it is received, so a value higher than the storage can keep up with leaves connections idle while they wait their turn to write.
  • pathling.import.pnp.downloadSocketTimeout - (default: 600000) The number of milliseconds a download may wait for more data before the connection is treated as failed. A download that is blocked writing what it has already received is not reading from its connection, so this needs to accommodate the slowest write the storage will perform, not just network latency.

If imports of large resource types fail with a download error while smaller ones succeed, lower maxConcurrentDownloads or raise downloadSocketTimeout: the symptom of exceeding what the storage can sustain is a connection closed part-way through a file.

Security note: When PNP credentials are configured, pathling.auth.enabled must also be set to true. If authentication is disabled but PNP credentials are present, the server logs a warning at startup and rejects all $import-pnp requests.

Export​

  • pathling.export.resultExpiry - (default: 86400) The duration in seconds that export results will be available before expiry. Defaults to 24 hours.

Bulk submit​

  • pathling.bulkSubmit.allowedSubmitters - (default: []) The list of allowed submitters (by system and value) that can use the $bulk-submit operation.
  • pathling.bulkSubmit.allowableSources - (default: []) URL prefixes that are allowed as sources for manifest and file URLs. This list is mandatory: when it is empty every URL is rejected and the operation cannot be used. This applies to the manifestUrl parameter, every output[].url discovered within fetched manifests, and the oauthMetadataUrl parameter. HTTP(S) prefixes are matched with proper URI semantics (see pathling.import.allowableSources above for the full rules).

Asynchronous processing​

  • pathling.async.enabled - (default: true) Enables asynchronous processing for those operations that support it, when explicitly requested.
  • pathling.async.varyHeadersExcludedFromCacheKey - (default: Accept, Accept-Encoding) A subset of pathling.httpCaching.vary HTTP headers, which should be excluded from determining that asynchronous requests are equivalent and can be routed to the same asynchronous job.
  • pathling.async.cacheMaxAge - (default: 1) The max-age value (in seconds) for Cache-Control headers on async endpoint responses ($job and $result). This value should be configured to match your strategy for cleaning up job result files, such as an S3 bucket lifecycle policy. For example, if job files are retained for 24 hours, set this to 86400.

Operations​

These settings enable or disable individual server operations. All operations are enabled by default. When an operation is disabled, it returns a client error response and is excluded from the CapabilityStatement.

  • pathling.operations.createEnabled - (default: true) Enables CRUD create operations.
  • pathling.operations.readEnabled - (default: true) Enables CRUD read operations.
  • pathling.operations.updateEnabled - (default: true) Enables CRUD update operations.
  • pathling.operations.deleteEnabled - (default: true) Enables CRUD delete operations.
  • pathling.operations.searchEnabled - (default: true) Enables CRUD search operations.
  • pathling.operations.batchEnabled - (default: true) Enables batch/transaction bundle operations.
  • pathling.operations.exportEnabled - (default: true) Enables the system-level $export operation.
  • pathling.operations.patientExportEnabled - (default: true) Enables the Patient-level $export operation.
  • pathling.operations.groupExportEnabled - (default: true) Enables the Group-level $export operation.
  • pathling.operations.importEnabled - (default: true) Enables the $import operation.
  • pathling.operations.importPnpEnabled - (default: true) Enables the $import-pnp operation.
  • pathling.operations.sqlRunEnabled - (default: true) Enables the $sql-run operation.
  • pathling.operations.sqlExportEnabled - (default: true) Enables the $sql-export operation.
  • pathling.operations.bulkSubmitEnabled - (default: true) Enables the $bulk-submit operation.

SQL query​

These settings govern the resolution of a query's dependency graph, for both $sql-run and $sql-export.

  • pathling.sqlQuery.maxDependencyDepth - (default: 10) The maximum nesting depth of the SQLView dependency graph resolved for a single query. The top-level query's direct dependencies sit at depth one; each further level of nested SQLView dependency increments the depth. A graph nested deeper is rejected with a 400 before any Spark work, guarding against accidental fan-out and runaway resolution.
  • pathling.sqlQuery.externalTables.N.url - The canonical URL by which a SQLQuery or SQLView relatedArtifact names this external table. Each configured table is a read-only Delta or Parquet table, outside the warehouse, that a SQL subject may join to its FHIR views; see external tables.
  • pathling.sqlQuery.externalTables.N.path - The location of the table. Accepts the same URL schemes as pathling.storage.warehouseUrl.
  • pathling.sqlQuery.externalTables.N.format - (default: delta) The storage format of the table, either delta or parquet. The format is passed to Spark as declared, so declare it accurately: a Parquet directory declared delta fails to read, but a Delta table declared parquet is read as its raw data files, including those superseded by later commits.
  • pathling.sqlQuery.valueSetMaxMembers - (default: 100000) The maximum number of members a single value set referenced as a SQLQuery or SQLView dependency may have. Must be at least 1. A value set with exactly this many members is accepted; one with more is rejected with a 422 naming the label, the canonical URL and the maximum, before any SQL runs. In server mode an expansion page whose total exceeds the maximum is rejected at once, without fetching further pages. The total is trusted for this even though abstract entries, which contribute no member, are counted in it. Where no total is reported, no page beyond the one that reveals the excess is fetched.
  • pathling.sqlQuery.conceptMapMaxMappings - (default: 100000) The maximum number of rows a single concept map referenced as a SQLQuery or SQLView dependency may have, counted after duplicate mappings are removed. Must be at least 1. A concept map with exactly this many rows is accepted; one with more is rejected with a 422 naming the label, the canonical URL and the maximum, before any SQL runs. The limit applies equally to a map from the terminology layer and to one supplied as a context ConceptMap.

N is a zero-based index. The list is validated at startup: every entry must have a non-blank url that contains no | and is unique among the configured tables, a non-blank path and an allowed format. A violation prevents the server from starting, with a failure naming the offending property. No path is probed at startup, so an unreachable or not-yet-written table does not stop the server; each table is read at its current state on every request that references it.

A value set dependency takes its membership from the terminology layer configured under terminology service, according to pathling.terminology.mode. In server mode (the default) the value set is expanded through ValueSet/$expand on pathling.terminology.serverUrl, paged in requests of 10,000 entries until the expansion is complete, and the request carries only the canonical URL, the pinned version where the reference has one, and the paging controls. The client and authentication settings below apply to those requests as to any other, but expansions are not held in the terminology result cache, since each is resolved once per request or job in any case. In local mode membership is computed by the local terminology store. With pathling.terminology.enabled set to false, a value set dependency that is not supplied inline as a context ValueSet with an expansion is a 404, since the canonical cannot be resolved, and a context ValueSet carrying only a compose is a 422, since nothing can expand it.

A dependency that no context entry, external table, stored ViewDefinition or stored SQLView matches is resolved through the terminology layer, first as a value set and then, only where no value set is found, as a concept map. Two kinds of URL skip one of these lookups, because their grammar already says what they are: an implicit value set URL - a SNOMED CT base (http://snomed.info/sct, or an edition and version URI) with a fhir_vs query, or a http://fhir.org/VCL?... URL - is never looked up as a concept map, and a SNOMED CT base with a fhir_cm query is never looked up as a value set. A URL held as both a value set and a concept map resolves as the value set, and the collision is not detected, since a canonical URL should be globally unique.

Each lookup either finds the artefact, finds that there is none, or cannot tell. A lookup that cannot tell because the terminology server failed does not end resolution: its failure is kept and the next lookup runs. If the concept map lookup then finds a map, the kept failure is discarded; if nothing is found, the request is a 422 carrying one issue per kept failure, in lookup order, each naming the operation that failed and the server's reason. A terminology server that cannot be reached during the value set lookup ends resolution at once with a 422, since the concept map lookup would fail the same way. Where every lookup finds nothing, the request is a 404.

In server mode the value set lookup is the ValueSet/$expand described above: a 404 means that there is no value set at the URL, and any other failure status on the first page means that the lookup cannot tell. A concept map dependency therefore costs one $expand of its URL before its concept map lookup, and a value set that expands costs no ConceptMap request. The concept map lookup is a search of the terminology server's ConceptMap resources: GET [serverUrl]/ConceptMap?url=[url]&_summary=true, adding &version=[pin] where the reference is pinned and following next links, and then one read, GET [serverUrl]/ConceptMap/[id], of the map chosen. Where several versions match an unpinned reference, the latest is chosen from the summaries, so the content of the versions not used is never retrieved. An empty search, any 4xx status or 501 means that there is no concept map at the URL; any other 5xx status, or a server that cannot be reached, means that the lookup cannot tell. Concept maps are not held in the terminology result cache, since each is resolved once per request or job in any case. A SNOMED CT fhir_cm URL is not expanded but is searched for like any other concept map. Pathling synthesises SNOMED CT implicit concept maps only from the local store, so a fhir_cm URL that the search does not return is a 404 stating that such maps are resolved only in local terminology mode.

In local mode concept maps come from the local terminology store at pathling.terminology.local.storagePath, from two sources:

  • the ConceptMap resources imported into the store (see local terminology mode), matched by canonical URL and version under the same pinned and unpinned rules as in server mode; and
  • the SNOMED CT implicit concept maps that HL7 Terminology (THO) defines over four association reference sets, named by http://snomed.info/sct?fhir_cm=[refsetId]: SAME AS (900000000000527005) and REPLACED BY (900000000000526001), whose rows have the relationship equivalent, and POSSIBLY EQUIVALENT TO (900000000000523009) and ALTERNATIVE (900000000000530003), whose rows have related-to.

An implicit map holds one row for every active association row of its reference set, so a concept with three POSSIBLY EQUIVALENT TO targets has three rows. Both systems are http://snomed.info/sct, both versions are the version URI of the SNOMED CT release the rows come from, and the displays are the store's; a target the store has no display for has a null target_display. An edition and version URI (http://snomed.info/sct/[moduleId]/version/[yyyymmdd]) in place of the bare http://snomed.info/sct base selects that release, and the bare base selects the store's default. An edition URI without a version is not a SNOMED CT base, so a fhir_cm URL on one is not an implicit map and, unless a ConceptMap is held at that exact URL, is a 404. A fhir_cm URL selecting a release the store does not hold is a 404. A fhir_cm URL naming any other reference set, such as a simple map, is a 422 stating that only the four association reference sets can be read as a concept map. A |version pin on a fhir_cm URL is a 422, since such a URL carries its version in its base; a pin on any other URL, whether or not it carries a query, is looked up with its pin.

With pathling.terminology.enabled set to false, a concept map dependency that is not supplied inline as a context ConceptMap is a 404, since the canonical cannot be resolved; a context ConceptMap works as usual, since it is converted without the terminology layer.

Encoding​

  • pathling.encoding.maxNestingLevel - (default: 3) Controls the maximum depth of nested element data that is encoded upon import. This affects certain elements within FHIR resources that contain recursive references, e.g. QuestionnaireResponse.item.

  • pathling.encoding.enableExtensions - (default: true) Enables support for FHIR extensions.

  • pathling.encoding.openTypes - (default: boolean, code, date, dateTime, decimal, integer, string, Coding, CodeableConcept, Address, Identifier, Reference) The list of types that are encoded within open types, such as extensions. This default list was taken from the data types that are common to extensions found in widely-used IGs, such as the US and AU base profiles. In general, you will get the best query performance by encoding your data with the shortest possible list.

    Shortening this list against a warehouse that already holds data, or pointing a server at a warehouse written by a deployment with a longer list, leaves stored columns that the running encoder no longer emits. Those columns are preserved: they are not dropped from the table, and writes to the affected resource types succeed with the columns written as null on the new rows. Reads return what the running encoder can represent, so the values in those columns are not visible until the original list is restored. Each affected table is named in the log at startup, along with the field paths involved.

Storage​

  • pathling.storage.warehouseUrl - (default: file:///usr/share/warehouse) The base URL at which Pathling will look for data files, and where it will save data received within import requests. Can be an Amazon S3 (s3a://), HDFS (hdfs://) or filesystem (file://) URL.

  • pathling.storage.databaseName - (default: default) The subdirectory within the warehouse path used to read and write data.

  • pathling.storage.cacheDatasets - (default: true) This controls whether the built-in caching within Spark is used for resource datasets. It may be useful to turn this off for large datasets in memory-constrained environments.

  • pathling.storage.compactionThreshold - (default: 10) When a table is updated, the number of partitions is checked. If the number exceeds this threshold, the table will be repartitioned back to the default number of partitions. This prevents large numbers of small updates causing poor subsequent query performance.

  • pathling.storage.schemaAutoMerge - (default: false) When enabled, the schema of an existing Delta table is automatically evolved to accommodate new fields produced by the FHIR encoder. This is useful when upgrading to a Pathling version whose encoder emits additional columns or nested struct fields that are not yet present in tables written by an earlier version. Evolution happens in two places: at startup, every table in the warehouse whose schema is missing encoder fields is migrated before it is served; and on update, a table whose schema is behind the incoming data is evolved before the merge, with the in-memory dataset refreshed so subsequent reads see the new schema without a restart. Migration is additive only - no existing field or row is modified, and existing rows present newly added fields as absent values. When no table has drifted, startup adds only the cost of comparing schemas. When the setting is disabled and a drifted table is detected, the server logs a warning naming the table, the missing fields, and the remedy, and requests against that resource type return an error that describes the condition rather than a generic failure. In multi-replica deployments, a runtime schema evolution is only visible to the replica that performed it; other replicas require a restart, although redeploys (which replace all replicas and re-run startup migration) are self-correcting.

    Where a stored table and the running encoders cannot be reconciled at all, the request fails with an error that describes the condition rather than a generic one. The message names the resource type, which direction the two schemas differ in, the field paths involved, and the remedy - enabling this setting where the table is behind the encoders, or restoring the encoding configuration the table was written with where it is ahead of them. It deliberately excludes the underlying schema definitions and warehouse paths, so the full detail remains in the server log alone.

Pathling will automatically detect AWS authentication details within the environment and use them to access S3 buckets. It uses a chain of authentication methods, see DefaultAWSCredentialsProviderChain for details.

In addition to this, any Hadoop S3 configuration variable (fs.s3a.*) can be set within Pathling directly. See the Hadoop AWS documentation for all the possible options.

This is the default S3 configuration, along with some hints on how to add some common configuration parameters:

fs:
    s3a:
        aws:
            # credentials:
            #   provider: org.apache.hadoop.fs.s3a.AnonymousAWSCredentialsProvider
            #   provider: org.apache.hadoop.fs.s3a.auth.AssumedRoleCredentialProvider
            #
            # For use with: SimpleAWSCredentialsProvider
            # access:
            #   key: [access key]
            # secret:
            #   key: [secret key]
            #
            # For use with: AssumedRoleCredentialProvider
            # assumed:
            #   role:
            #     arn: [role ARN]
            #
            connection:
                maximum: 100
            committer:
                name: magic
                magic:
                    enabled: true

When the warehouse is an S3 object store, the S3A magic committer avoids the rename-based commit that is unsafe on some stores by completing writes through S3 multipart uploads instead. Setting fs.s3a.committer.name=magic alone is not enough for Spark's Parquet writes to use it; the commit protocol classes must also be selected:

spark:
    sql:
        sources:
            commitProtocolClass: org.apache.spark.internal.io.cloud.PathOutputCommitProtocol
        parquet:
            output:
                committer:
                    class: org.apache.spark.internal.io.cloud.BindingParquetOutputCommitter

These committer bindings ship with the server image, so no extra dependency is required to enable this configuration.

Query​

  • pathling.query.explainQueries - (default: false) If set to true, Spark query plans will be written to the logs.
  • pathling.query.cacheResults - (default: true) This controls whether the built-in caching within Spark is used for search results. It may be useful to turn this off for large datasets in memory-constrained environments.
  • pathling.query.maxUnboundTraversalDepth - (default: 10) Controls the maximum depth for same-type recursive traversal in repeat() and repeatAll() FHIRPath functions. Cross-type traversals do not consume depth budget. The minimum value is 1.

Apache Spark​

  • pathling.spark.appName - (default: pathling) Controls the application name that Pathling will be identified as within any Spark cluster that it participates in.

Any Spark configuration variable can be set within Pathling directly. See Spark Configuration for the full list.

Here are a few that you might be particularly interested in:

  • spark.master - (default: local[*]) Address of the master node of an Apache Spark cluster to use for processing data, see Master URLs.
  • spark.executor.memory - (default: 1g) The quantity of memory available for each child task to process data within, in the same format as JVM memory strings with a size unit suffix (k, m, g or t) (e.g. 512m, 2g).
  • spark.sql.shuffle.partitions - (default: 2) This option controls the number of data partitions used to distribute data between child tasks. This can be tuned to higher numbers for larger data sets. It also controls the granularity of requests made to the configured terminology service.

This is the default Spark configuration:

spark:
    master: local[*]
    sql:
        adaptive:
            enabled: true
            coalescePartitions:
                enabled: true
        extensions: io.delta.sql.DeltaSparkSessionExtension
        catalog:
            spark_catalog: org.apache.spark.sql.delta.catalog.DeltaCatalog
    databricks:
        delta:
            schema:
                autoMerge:
                    enabled: false
    scheduler:
        mode: FAIR

Terminology service​

See terminology for a guide to setting up a remote terminology server or a local terminology store.

  • pathling.terminology.enabled - (default: true) Enables use of terminology functions within queries.
  • pathling.terminology.mode - (default: server) Selects where terminology functions are evaluated. server sends requests to the FHIR terminology service at pathling.terminology.serverUrl. local evaluates them against a local terminology store, configured as described in local terminology store.
  • pathling.terminology.serverUrl - (default: https://tx.ontoserver.csiro.au/fhir) The endpoint of the FHIR terminology service (R4) that the server can use to resolve terminology queries. Only used in server mode.
  • pathling.terminology.verboseLogging - (default: false) Setting this option to true will enable additional logging of the details of requests between the server and the terminology service.
  • pathling.terminology.acceptLanguage - If this variable is set, it will be used as the value of the Accept-Language HTTP header passed to the terminology server. The value may contain multiple languages, with weighted preferences as defined in RFC 9110. If not provided, the header is not sent. The server can use the header to return the result in the preferred language if it is able. The actual behaviour may depend on the server implementation and the code systems used.

Local terminology store​

In local mode the FHIRPath terminology functions (memberOf, translate, subsumes, subsumedBy, display, property and designation), and the value set dependencies of SQL queries (see SQL query), are evaluated against a store of SNOMED CT and FHIR terminology content, with no requests to a terminology server.

The server reads the store but does not create it. Build it beforehand with the import-snomed and import-fhir-terminology commands of the Pathling CLI, or the equivalent functions of the Python or R libraries, as described in local terminology mode.

  • pathling.terminology.local.storagePath - The location of the store, as a path or URL accessible through the Hadoop FileSystem API (e.g. file:///usr/share/terminology, s3a://my-bucket/terminology). Required in local mode.
  • pathling.terminology.local.defaultSnomedEdition - The module identifier of the SNOMED CT edition to use for an unversioned SNOMED CT reference when the store holds more than one edition (e.g. 32506021000036107 for the Australian edition). If it is not set, such a reference is an error.
  • pathling.terminology.local.expansionCacheSize - (default: 100) The maximum number of value set expansions held in memory by each Spark executor.
  • pathling.terminology.local.dialectAliases - A map of additional language tags to the identifiers of the SNOMED CT language reference sets that serve them, used when a display is requested in a particular language (e.g. en-NZ to 271000210107). Each entry is a separate variable named after the tag, e.g. pathling.terminology.local.dialectAliases.en-NZ=271000210107. See registering additional dialects.

This is a minimal configuration using environment variables:

PATHLING_TERMINOLOGY_MODE=local
PATHLING_TERMINOLOGY_LOCAL_STORAGEPATH=file:///usr/share/terminology

The same configuration in the pathling.config map of the Helm chart, with a dialect alias:

pathling:
    config:
        pathling.terminology.mode: local
        pathling.terminology.local.storagePath: s3a://my-bucket/terminology
        pathling.terminology.local.dialectAliases.en-NZ: "271000210107"

The store is opened when the server starts, so a missing storagePath, or a store that cannot be read, stops the server from starting. In a Spark cluster the executors also open the store, so the path must be reachable from every executor - for example an object store bucket, or a volume mounted into the executor pods (see Kubernetes). The executors use the Hadoop configuration of the server, so object store credentials set through spark.hadoop.* configuration apply to both.

The serverUrl, client, cache and authentication settings have no effect in local mode, and the server logs a warning at startup for each one that has been changed from its default. acceptLanguage and verboseLogging also apply only to requests to a terminology server; in local mode, request a display in a particular language through the language argument of display or property.

Client​

  • pathling.terminology.client.maxConnectionsTotal - (default: 32) The maximum number of total connections allowed from the client.
  • pathling.terminology.client.maxConnectionsPerRoute - (default: 16) The maximum number of connections allowed from the client, per route.
  • pathling.terminology.client.socketTimeout - (default: 60000) The maximum period (in milliseconds) that the server should wait for incoming data from the terminology service.
  • pathling.terminology.client.retryEnabled - (default: true) Enables automatic retry of failed terminology service requests.
  • pathling.terminology.client.retryCount - (default: 2) The maximum number of times that failed terminology service requests should be retried.

Cache​

  • pathling.terminology.cache.enabled - (default: true) Set this to false to disable caching of terminology requests (not recommended).
  • pathling.terminology.cache.storageType - (default: memory) The type of storage to be used by the terminology cache. Valid values are memory and disk.
  • pathling.terminology.cache.maxEntries - (default: 50000) Sets the maximum number of entries that will be held in memory. Only applicable when using the memory storage type.
  • pathling.terminology.cache.storagePath - The path at which to store cache data. Required if pathling.terminology.cache.storageType is set to disk.
  • pathling.terminology.cache.defaultExpiry - (default: 600) The amount of time (in seconds) that a response from the terminology server should be cached if the server does not specify an expiry.
  • pathling.terminology.cache.overrideExpiry - If provided, this value overrides the expiry time provided by the terminology server.

Authentication​

  • pathling.terminology.authentication.enabled - (default: false) Enables authentication for requests to the terminology service.
  • pathling.terminology.authentication.tokenEndpoint, pathling.terminology.authentication.clientId, pathling.terminology.authentication.clientSecret - Authentication details for connecting to a terminology service that requires authentication, using OAuth 2.0 client credentials flow.

Authorization​

  • pathling.auth.enabled - (default: false) Enables authorization. If this option is set to true, pathling.auth.issuer and pathling.auth.audience options must also be set.
  • pathling.auth.issuer - Configures the issuing domain for bearer tokens, e.g. https://pathling.au.auth0.com/. Must match the contents of the issuer claim within bearer tokens.
  • pathling.auth.audience - Configures the audience for bearer tokens, which is the FHIR endpoint that tokens are intended to be authorised for, e.g. https://pathling.csiro.au/fhir. Must match the contents of the audience claim within bearer tokens.
  • pathling.auth.capabilities - (default: launch-standalone) A list of SMART on FHIR capabilities to advertise in the SMART configuration document at /.well-known/smart-configuration.
  • pathling.auth.grantTypesSupported - (default: authorization_code) A list of OAuth 2.0 grant types supported at the token endpoint, e.g. authorization_code, client_credentials, refresh_token. See SMART App Launch Conformance for more details.
  • pathling.auth.codeChallengeMethodsSupported - (default: S256) A list of PKCE code challenge methods supported. Must include S256 and must not include plain as per the SMART specification.
  • pathling.auth.tokenSigningAlgorithms - (default: empty) A list of the JWS signing algorithms accepted within incoming bearer tokens. When empty, the accepted algorithms are derived from the keys published in the issuer's JWKS: a key's alg value is used when present, otherwise the algorithms implied by its key type. This derivation happens at token verification time, so key rotation at the identity provider takes effect without a restart. When one or more values are configured, only tokens whose header algorithm is in that list are accepted, regardless of what the JWKS publishes. Tokens are verified against a public JWKS, so only the asymmetric algorithm names RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES256K, ES384, ES512 and EdDSA are permitted; any other value fails validation at startup.

Admin UI​

  • pathling.adminUi.clientId - The OAuth client ID for the admin UI. When set, this value is included in the SMART configuration response at /.well-known/smart-configuration as admin_ui_client_id. The admin UI uses this value when initiating OAuth flows. If not set, the UI falls back to the VITE_CLIENT_ID environment variable (set at build time), then to the default value pathling-admin-ui. See Admin UI for more details.

HTTP caching​

  • pathling.httpCaching.vary - (default: Accept, Accept-Encoding, Prefer, Authorization) A list of values to return within the Vary header.
  • pathling.httpCaching.cacheableControl - (default: must-revalidate, max-age=1) A list of values to return within the Cache-Control header, for cacheable responses.
  • pathling.httpCaching.uncacheableControl - (default: no-store) A list of values to return within the Cache-Control header, for uncacheable responses.

Cross-Origin Resource Sharing (CORS)​

See the Cross-Origin Resource Sharing specification for more information about the meaning of the different headers that are controlled by this configuration.

  • pathling.cors.allowedOriginPatterns - (default: [empty]) This is a comma-delimited list of domain name patterns that controls which domains are permitted to access the server per the Access-Control-Allow-Origin header. Supports wildcard patterns, e.g. https://*.somedomain.com.
  • pathling.cors.allowedMethods - (default: OPTIONS,GET,POST) This is a comma-delimited list of HTTP methods permitted via the Access-Control-Allow-Methods header.
  • pathling.cors.allowedHeaders - (default: Content-Type,Authorization,Prefer) This is a comma-delimited list of HTTP headers permitted via the Access-Control-Allow-Headers header.
  • pathling.cors.exposedHeaders - (default: Content-Location,Content-Disposition,X-Progress) This is a comma-delimited list of HTTP headers that are permitted to be exposed via the Access-Control-Expose-Headers header.
  • pathling.cors.maxAge - (default: 600) Controls how long the results of a preflight request can be cached via the Access-Control-Max-Age header.

Monitoring​

  • pathling.sentryDsn - If this variable is set, all errors will be reported to a Sentry service, e.g. https://abc123@sentry.io/123456.
  • pathling.sentryEnvironment - If this variable is set, this will be sent as the environment when reporting errors to Sentry.

Server base​

There are a number of operations within the Pathling FHIR API that pass back URLs referring back to API endpoints. The host and protocol components of these URLs are automatically detected based upon the details of the incoming request.

In some cases it might be desirable to override the hostname and protocol, particularly where Pathling is being hosted behind some sort of proxy. To account for this, Pathling also supports the use of the X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port headers to override the protocol, hostname and port within URLs sent back by the API.