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.
Custom roles required by you implementation can be added to the database by default.
The Custom Roles Seed File property on the Cluster Manager module should be used for this purpose. A sample custom roles file is shipped in the default Smile CDR configuration in the path: classes/config_seeding/custom-roles.json.
In order to have the defined roles ingested, in a Node Configuration Properties File there should then be a line similar to the following:
module.clustermgr.config.seed.custom_roles.file = classpath:/config_seeding/custom-roles.json
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.
For example, the following JSON will pre-seed a keystore with inline JSON Web Key Set (JWKS) shown below.
{
"keystoreId": "my-inline-keystore",
"jsonKeys": "{\"keys\": [{\"kty\": \"RSA\",\"d\": \"GweK...[trimmed]]\",\"e\": \"AQAB\",\"use\": \"sig\",\"kid\": \"smilecdr-demo\",\"alg\": \"RS256\",\"n\": \"gCRC...[trimmed]\"}]}",
"filePath": ""
}
Alternatively, the following JSON will use JSON Web Key Set (JWKS) found at the given location.
{
"keystoreId": "my-filepath-keystore",
"jsonKeys": "",
"filePath": "classpath:/smilecdr-demo.jwks"
}
It is not recommended to use the JWKS shown here, as these are for demo purposes only.
For more information on configuring keystores, see OIDC Keystores.
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.
Please note that, when stored to the FHIR resource tables using STORE_AND_INSTALL mode, the handling of conformance resource IDs depends on the versionPolicy setting. See Version Policy for details on how IDs are assigned. Conformance resources pre-seeded from packages via the Package Installer should be referenced by their canonical URL.
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.
The URL each package is fetched from must match a prefix in the Allowed Package URLs (whitelist) on the same FHIR Storage module.
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
}
When using STORE_AND_INSTALL or INSTALL_ONLY mode, only the following resource types are installed from the package by default: NamingSystem, CodeSystem, ValueSet, StructureDefinition, ConceptMap, SearchParameter, Subscription, Questionnaire, OperationDefinition, PlanDefinition, ActivityDefinition, ImplementationGuide.
Any other resource types present in the package (e.g., Organization, Patient, Questionnaire) are ignored unless explicitly specified. To install additional or non-default resource types, use the installResourceTypes property in the PackageInstallationSpec to provide the list of resource types to install. When installResourceTypes is specified, it completely replaces the default list.
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.
The installMode property controls what is persisted during installation. See Install Mode in the HAPI FHIR documentation for the full description of STORE_ONLY, STORE_AND_INSTALL, and INSTALL_ONLY.
The fetchDependencies flag controls whether NPM module dependencies are also fetched and installed. See the HAPI FHIR package documentation for details.
During package installation, the system searches for an existing resource before deciding whether to create or update. See Resource Matching in the HAPI FHIR documentation for the full matching rules by resource type.
Of note: non-conformance resources (e.g. Patient, Organization) are matched by identifier and must include one — resources without an identifier will fail to install with HAPI-1292.
The dependencyExcludes property skips specific transitive dependencies when fetchDependencies is enabled. See the HAPI FHIR package documentation for syntax and examples.
By default, only resources from the standard package folder within an NPM package are installed. Some Implementation Guides include resources in additional folders (e.g. example). To install resources from these folders, use the additionalResourceFolders property:
{
"name" : "com.example.my-ig",
"version" : "1.0.0",
"installMode" : "STORE_AND_INSTALL",
"additionalResourceFolders" : [ "example" ]
}
See Installing Resources from Additional Folders in the HAPI FHIR documentation for details.
References between non-conformance resources: Enable the Auto-Create Placeholder Reference Targets setting on the FHIR Storage module to avoid HAPI-1094 errors when installing non-conformance resources that reference each other. See Installing Resources from Additional Folders in the HAPI FHIR documentation for details.
The versionPolicy property controls how canonical resource versions are handled during package installation when using STORE_AND_INSTALL mode. This setting has no effect in STORE_ONLY mode.
Note: This setting applies only to canonical resources (e.g. StructureDefinition, ValueSet, CodeSystem, ConceptMap). Non-conformance instance resources (e.g. Patient, Organization) are always installed per-resource using their original IDs and are unaffected by this setting.
See Version Policy in the HAPI FHIR documentation for a full explanation of MULTI_VERSION (default) and SINGLE_VERSION behavior.
When this flag is enabled, resources are filtered during installation based on their status value. See Resource Status Validation in the HAPI FHIR documentation for the accepted values per resource type. The corresponding setting in Smile CDR is Validate Resource Status for Package Upload on the FHIR Storage module.
If 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
Each package is only fetched if its URL matches a prefix in the Allowed Package URLs (whitelist) on the same FHIR Storage module. A default whitelist applies when neither whitelist property is set, so no configuration is needed unless your packages are fetched from somewhere the default does not cover.
To supply your own, place the whitelist JSON into the Smile CDR installation under classes/config_seeding/package-url-whitelist.json and point the Package URL Whitelist File property at it. The distribution ships a copy of the default whitelist at that path to use as a starting point:
module.persistence.config.package.url.whitelist.file=classpath:/config_seeding/package-url-whitelist.json
The same JSON may instead be supplied inline through the Package URL Whitelist property. See Allowed Package URLs (whitelist) for the format and for the contents of the default whitelist.
You can also load a collection of resources into the FHIR repository when the server starts up.
Please note that any client-assigned ID provided in resources that are not a SearchParameter will be ignored and replaced by a server-assigned ID. You can pre-seed the collection of resources by following these steps:
smilecdr/classes/config_seeding folder.smilecdr/classes/config_seeding per the PackageInstallationSpec instructions.Let's say you wanted to pre-load a couple of Organization resources org1.json and org2.json into your persistence module when the server first starts up. You could run:
cp org1.json org2.json /path/to/folder
smilecdr/bin/smileutil create-package --fhir-version R4 --name com.example.demo --version 1.0.1 --include-package "/path/to/folder/*.json"
mv smilecdr/com.example.demo-1.0.1.tgz smilecdr/classes/config_seeding
Then you would create a file named smilecdr/classes/config_seeding/demo-package-spec.json with contents like this:
{
"name" : "com.example.demo",
"version" : "1.0.1",
"packageUrl" : "classpath:/config_seeding/com.example.demo-1.0.1.tgz",
"installMode" : "STORE_AND_INSTALL",
"installResourceTypes" : [ "Organization" ],
"reloadExisting" : true,
"fetchDependencies" : false,
"versionPolicy" : "MULTI_VERSION"
}
And lastly, if you are running in node.propertysource=PROPERTIES mode, you would add the following line to your cdr-config-Master.properties file:
module.persistence.config.package_registry.startup_installation_specs=classpath:/config_seeding/demo-package-spec.json
If you're running in node.propertysource=DATABASE mode, you'd need to set this value in the Web Admin Console on the Storage Module Config page in the field called "Package Pre-Seed Installation Spec Files".