Pre-Seeding Configuration and Data
If you wish to completely automate the provisioning of new environments, you may wish to have various elements of your configuration automatically "pre-seeded" into your system the first time it starts up.
This page describes strategies for achieving various pre-seeded configurations.
Each Smile CDR module type has a set of configuration elements that it supports. These are the properties that are visible in the Node Configuration Properties File.
The Fetch Config: Module Property File operation on the JSON Admin Endpoint can be used to export the complete configuration for an existing node. Note that this export will include all settings except passwords and credentials. These will need to be added manually.
If you wish to create new environments based on an existing environment, this exported file is an easy way to get started. You may wish to also configure the Module Property Source to PROPERTIES, meaning that the values in the file should always take precedence over values in the configuration database.
Variable substitution is available for pre-seeded json files defining OIDC clients, OIDC servers, and users, using the same formatting as required for properties files variable substitution.
eg:
{
"users": [
{
"username": "ADMIN",
"password": "#{systemProperties['SYSTEM_PROPERTY_NAME']}"
}
]
}
See Variable Substitution for more information on how variable substitution works.
If you are using the Local Inbound Security module, it is helpful to have a set of default users added to the user database by default. Typically this would include an admin user that can be used to create other users, as well as an anonymous user whose credentials will be used for anonymous requests.
The Users Seed File property on the Local Inbound Security module should be used for this purpose. The Smile CDR default configuration includes this setting, and will seed two users: admin and anonymous.
In a Node Configuration Properties File there should then be a line similar to the following:
module.local_security.config.seed.users.file =classpath:/config_seeding/users.json
The file contents should be a UserDetailsList object. A sample is shipped in the default Smile CDR configuration in the path: classes/config_seeding/users.json.
The JSON Admin API Search For Users operation uses this same format as its output, so it can be helpful in producing a seed file.
If you are using the SMART Inbound Security or SMART Outbound Security modules, you can have OpenID Connect Server definitions (such as the ones you would create in the Web Admin Console) automatically seed into a newly created environment by using the OpenID Connect Server Pre-Seed File property.
In a Node Configuration Properties File this should appear as a line similar to the following:
module.MODULE_ID.config.seed_servers.file =classpath:/config_seeding/oidc-servers.json
The file contents should be a OAuth2Servers object. A sample is shipped in the default Smile CDR configuration in the path: classes/config_seeding/oidc-servers.json.
The JSON Admin API Fetch All OpenID Connect Server Definitions operation uses this same format as its output, so it can be helpful in producing a seed file.
If you are using the SMART Outbound Security module, you can have OpenID Connect Client definitions (such as the ones you would create in the Web Admin Console) automatically seed into a newly created environment by using the OpenID Connect Client Pre-Seed File property.
In a Node Configuration Properties File this should appear as a line similar to the following:
module.MODULE_ID.config.seed_clients.file =classpath:/config_seeding/oidc-clients.json
The file contents should be a OAuth2Clients object. A sample is shipped in the default Smile CDR configuration in the path: classes/config_seeding/oidc-clients.json.
The JSON Admin API Fetch All OpenID Connect Client Definitions operation uses this same format as its output, so it can be helpful in producing a seed file.
If you are using SMART Outbound Security module, you can have OpenID Connect Keystore definitions (such as the one that is created in Web Admin Console) automatically seed into a newly created environment by using the OpenID Connect Client Pre-Seed File property.
The FHIR Storage (RDBMS) module is able to read and ingest FHIR NPM conformance packages. During this ingestion, conformance resources are stored in a dedicated set of tables where they are made available to the validator during resource validation. These resources can also be stored in the FHIR resource storage tables, allowing them to be accessed through the FHIR API.
When Smile CDR starts, the FHIR Storage module can be configured to automatically import packages into the local registry. This makes the conformance artifacts in these packages available to the validator. It can also optionally import resources from the package directly into FHIR Storage, so that these resources become available for FHIR searches, reads, etc.
To configure pre-seeding of resources, one or more PackageInstallationSpec documents should be created, and linked to from the Package Pre-Seed Installation Spec Files property of the FHIR Storage (RDBMS) module. Multiple spec files may be created (one per package to install) and linked to from the same configuration property.
For example, the following Package Spec file will automatically install the US Core implementation guide.
{
"name" : "hl7.fhir.us.core",
"version" : "3.1.0",
"installMode" : "STORE_ONLY",
"fetchDependencies" : true
}
Note: When multiple FHIR Storage modules are backed by the same database, this pre-seeding only needs to be configured for one of these FHIR Storage modules. Additionally, in such cases one should also enable the Suppress Scheduled Maintenance Jobs property on all but one of the FHIR Storage modules.
Packages can be created using the smileutil tool.
The installMode property of the package spec may have the following values:
STORE_ONLY – In this mode, the conformance resources will be stored in dedicated package tables, but the resources in the package will not be stored as FHIR Resources that can be queried via a FHIR Endpoint. If you are only installing the package for the purpose of validation, or to satisfy a Package Registry Endpoint this option is a good choice since it uses less space and loads faster.
STORE_AND_INSTALL – This mode also accomplishes the same things as the STORE_ONLY mode, but it also installs the FHIR Resources in the package as actual FHIR Resources. This means that if a FHIR Endpoint module is connected to the FHIR Storage module, it can be used to search for, read, and potentially even update these resources.
The fetchDependencies flag indicates whether NPM module dependencies should also be fetched and installed.
For example, the hl7.fhir.us.core package with version 5.0.1 specifies a dependency on the hl7.fhir.r4.core package version 4.0.1. Installing the former with fetchDependencies enabled will cause the latter to also be installed if it isn't already installed.
This element accepts the values true and false.
When enabled, this flag will filter resources during package installation. The filter criteria is the following:
Subscription resources with need to have status set to requestedDocumentReference and Communication resources the status can have a wider variety of values such as: entered-in-error, unknown, preliminaryactiveIf this file is placed into the Smile CDR installation under classes/config_seeding/package-spec.json, the Package Pre-Seed Installation Spec Files property can be set to classpath:/config_seeding/package-spec.json in order to have this package seeded on startup. If you are configuring this in a properties file, the following example shows the equivalent setting in the file (note that you may need to change persistence to the actual ID of your FHIR Storage module):
module.persistence.config.package_registry.startup_installation_specs=classpath:/config_seeding/package-spec.json