From fe81a1d52e7a5068d0162881bc566b99c9cec392 Mon Sep 17 00:00:00 2001 From: Lee Surprenant Date: Thu, 19 Nov 2020 05:13:58 -0500 Subject: [PATCH 1/4] Update the search configuration to reflect new config and reindex Update the docs to reflect that `fhirServer/searchParameterFilter` has been replaced with `fhirServer/resources//searchParameters`. We should probably add more documentation to explain `fhirServer/resources//searchIncludes`, `fhirServer/resources//searchRevIncludes`, and `fhirServer/resources//searchParameterCombinations`, but for now I just wanted to make sure the stale content was cleaned up. I also added a section on using the new `$reindex` operation. Note that, rather than update them, I removed some examples and the description of the algorithm to reduce the burden of maintenance. Signed-off-by: Lee Surprenant --- .../pages/guides/FHIRSearchConfiguration.md | 217 +++++++++--------- 1 file changed, 103 insertions(+), 114 deletions(-) diff --git a/docs/src/pages/guides/FHIRSearchConfiguration.md b/docs/src/pages/guides/FHIRSearchConfiguration.md index 4f089c7dfcf..a60b028170e 100644 --- a/docs/src/pages/guides/FHIRSearchConfiguration.md +++ b/docs/src/pages/guides/FHIRSearchConfiguration.md @@ -7,46 +7,43 @@ markdown: kramdown --- # IBM FHIR Server - Search Configuration Overview -The [FHIR Specification](https://www.hl7.org/fhir/r4/search.html) defines a set of searchable fields for each resource type, and corresponding RESTful API. The IBM FHIR Server supports searching using the specification defined search parameters and using tenant-specific search parameters (extensions). +The [FHIR Specification](https://www.hl7.org/fhir/r4/search.html) defines a set of searchable fields for each resource type. The IBM FHIR Server supports searching via both specification-defined search parameters and tenant-specific search parameters. Specifically, the IBM FHIR Server supports searching on additional fields, including: -* fields that are defined in the base specification, which are not configured for search; -* extension elements that a tenant may add to a standard FHIR resource type; and -* attributes that you define as part of a custom resource type +* fields that are defined in the base specification, which are not configured for search; and +* extension elements that a tenant may add to a standard FHIR resource type -The IBM FHIR Server allows deployers to define search parameters on a tenant-specific basis. This allows each tenant to share an instance of the FHIR server while maintaining the ability to have their own set of search parameters. +The IBM FHIR Server allows deployers to define search parameters on a tenant-specific basis. This allows each tenant to share an instance of the FHIR server while maintaining the ability to have their own set of search parameters. Additionally, specificatin-defined search parameters can be filtered out in order to avoid the cost of extracting and storing the corresponding indices. -A tenant must provide a [Bundle](https://www.hl7.org/fhir/r4/bundle.html) of [SearchParameter](https://www.hl7.org/fhir/r4/searchparameter.html) resources that define the additional search parameters which describe the searchable field and define the FHIRPath expression for extraction. For example, a tenant that extends the `Patient` resource type with the `favorite-color` extension, enables search on `favorite-color` by defining a SearchParameter as part of this bundle. - -Note, the [composite](https://www.hl7.org/fhir/r4/codesystem-search-param-type.html#search-param-type-composite) and [special](https://www.hl7.org/fhir/r4/codesystem-search-param-type.html#search-param-type-special) SearchParameter types are not supported. +Tenant search parameters are defined via a [Bundle](https://www.hl7.org/fhir/r4/bundle.html) of [SearchParameter](https://www.hl7.org/fhir/r4/searchparameter.html) resources that define the additional search parameters which describe the searchable field and define the FHIRPath expression for extraction. \For example, a tenant that extends the `Patient` resource type with the `favorite-color` extension, enables search on `favorite-color` by defining a SearchParameter as part of this bundle. ## 1 Configuration There are three layers of search parameter configuration. -- specification defined -- default -- tenant-specific - -The specification defined SearchParameters are embedded as [a JSON file](https://github.com/IBM/FHIR/blob/master/fhir-search/src/main/resources/search-parameters.json) in the `fhir-search` module. +- built-in parameters from the core specification and packaged implementation guides +- default tenant parameters +- tenant-specific parameters -Note, the search-parameters.json and search-parameters.xml in the `fhir-search` module match the latest definition resource from the [FHIR download site](http://hl7.org/fhir/r4/downloads.html). +The built-in SearchParameters are loaded from the `fhir-registry` in the `fhir-search` module during server startup. The default and tenant level configurations are put in the `default` and tenant-specific (e.g. `tenant1`) config folders respectively. These folders are populated with `extension-search-parameters.json`. The IBM FHIR Server configuration prefers the JSON formatted configuration documents, and implements caching via [TenantSpecificSearchParameterCache.java](https://github.com/IBM/FHIR/blob/master/fhir-search/src/main/java/com/ibm/fhir/search/parameters/cache/TenantSpecificSearchParameterCache.java). -The IBM FHIR Server supports compartment searches based on the CompartmentDefinition resources found at [fhir-search/src/main/resources/compartments.json](https://github.com/IBM/FHIR/blob/master/fhir-search/src/main/resources/compartments.json). These definitions come directly from the specification and the server provides no corresponding default or tenant-level configuration. +The IBM FHIR Server supports compartment searches based on the CompartmentDefinition resources found at [fhir-search/src/main/resources/compartments.json](https://github.com/IBM/FHIR/blob/master/fhir-search/src/main/resources/compartments.json). These definitions come directly from the specification and the server provides no corresponding default or tenant-level configuration. -### 1.1 Configuration per Tenant +### 1.1 Tenant-specific parameters To configure tenant-specific search parameters, create a file called `extension-search-parameters.json`, placing it in the `${server.config.dir}/config/` directory. For example, the `${server.config.dir}/config/acme/extension-search-parameters.json` file would contain the search parameters for the `acme` tenant, while `${server.config.dir}/config/qpharma/extension-search-parameters.json` would contain search parameters used by the `qpharma` tenant. -When the FHIR server processes a request associated with the `acme` tenant, the server is only aware of the set of built-in search parameters (defined by the HL7 FHIR specification) plus the user-defined search parameters defined in the `acme` tenant's extension-search-parameters.json file. Likewise, when processing a request associated with the `qpharma` tenant, the server is only aware of the built-in search parameters plus the user-defined search parameters defined in the `qpharma` tenant's `extension-search-parameters.json` file. +When the FHIR server processes a request associated with the `acme` tenant, the server is uses the built-in search parameters and the user-defined search parameters defined in the `acme` tenant's extension-search-parameters.json file. Likewise, when processing a request associated with the `qpharma` tenant, the server uses the built-in search parameters and the user-defined search parameters defined in the `qpharma` tenant's `extension-search-parameters.json` file. If a tenant-specific extension-search-parameters.json file does not exist, the server falls back to the global `extension-search-parameters.json` file found at `${server.config.dir}/config/default/extension-search-parameters.json`. The FHIR server caches search parameters in memory (organized first by tenant id, then by resource type and search parameter). Any updates to a tenant's `extension-search-parameters.json` file causes the FHIR server to re-load the tenant's search parameters and refresh the information stored in the cache, without requiring a server re-start. This allows the deployer to deploy a new tenant's `extension-search-parameters.json` or update an existing file without re-starting the FHIR server and any subsequent requests processed by the FHIR server after the updates have been made use the updated search parameters. However, it is important to note that this process **does not** re-index already-created resources that are stored on the FHIR Server. One technique for updating the indices for a given resource type is to `read` and `update` each resource instance with itself, triggering search parameter extraction (and creating a new version of each resource). -#### 1.1.1 Search Parameters Configuration: extension-search-parameters.json -To configure the FHIR server with one or more custom search parameters, one must create a file called `extension-search-parameters.json` and populate the contents with a Bundle of `SearchParameter` resources. +Starting in version 4.5.0, the IBM FHIR Server supports [re-indexing resources](#2-re-index) with an updated set of search parameters. This is very similar to creating a new version of the resources, except in this case the version number doesn't change and the data for the resource never leaves the server. + +#### 1.1.1 Search parameters configuration: extension-search-parameters.json +To configure the FHIR server with one or more custom search parameters, create a file called `extension-search-parameters.json` and populate the contents with a Bundle of `SearchParameter` resources. The `fhir-search` module requires that the [expression](https://www.hl7.org/fhir/r4/searchparameter-definitions.html#SearchParameter.expression), [type](https://www.hl7.org/fhir/r4/searchparameter-definitions.html#SearchParameter.type) and [code](https://www.hl7.org/fhir/r4/searchparameter-definitions.html#SearchParameter.code) be set, as in the following example: ``` @@ -103,52 +100,81 @@ A few things to note are: In the preceding example, extension elements (on a Patient resource) with a url of `http://ibm.com/fhir/extension/Patient/favorite-color` are indexed by the `favorite-color` search parameter. To search for Patients with a favorite color of "pink", users could send an HTTP GET request to a URL like `[base]/api/v1/Patient?favorite-color:exact=pink`. -For more information on search parameters, see the HL7 FHIR specification. +For more information on search parameters, see the [HL7 FHIR specification](https://www.hl7.org/fhir/R4/searchparameter.html). #### 1.1.2 Recommendations -When creating the SearchParameter FHIRPath expression, one should test the FHIRPath expression and test the search parameter. +When creating the SearchParameter FHIRPath expression, be sure to test both the FHIRPath expression and the search parameter. If a search parameter expression extracts an element with a data type that is incompatible with the declared search parameter type, the server skips the value and logs a message. For choice elements, like Extension.value, its recommended to restrict the expression to values of the desired type by using the `as` function. For example, to select only Decimal values from the http://example.org/demical extension, use an expressions like Basic.extension.where(url='http://example.org/decimal').value.as(Decimal). -### 1.2 Configuration: Filtering of search parameters -The FHIR server supports the filtering of built-in search parameters (that is, search parameters defined by the HL7 FHIR specification for each resource type). The default behavior of the FHIR server is to consider all built-in search parameters when storing resources or processing search requests, but you can configure inclusion filters to restrict the FHIR server's view to specific search parameters on a given resource type. This filtering feature does not apply to user-defined search parameters in the extension-search-parameters.json file. User-defined search parameters are always included in the FHIR server's view regardless of the configured inclusion filters. +### 1.2 Filtering +The FHIR server supports the filtering of built-in search parameters. The default behavior of the FHIR server is to consider all built-in search parameters when storing resources or processing search requests, but you can configure inclusion filters to restrict the FHIR server's view to specific search parameters on a given resource type. This filtering feature does not apply to user-defined search parameters in the extension-search-parameters.json file. User-defined search parameters are always included in the FHIR server's view regardless of the configured inclusion filters. Why would you want to filter built-in search parameters? The answer lies in how search parameters are used by the FHIR server. When the FHIR server processes a _create_ or _update_ operation, it stores the resource contents in the datastore, along with search index information that is used by the FHIR server when performing search operations. The search index information stored for a particular resource instance is driven by the search parameters defined for that resource type. Therefore if you are storing a resource whose type has a lot of built-in search parameters defined for it (e.g. `Patient`), then you could potentially be storing a lot of search index information for each resource. -For performance and scalability reasons, it might be desirable to limit the number of search parameters considered during a _create_ or _update_ operation for particular resource types, if those search parameters will never be used in search operations. After all, if there will be no need to use the search index information, there's no need to store it. For example, if you know that due to the way in which a particular tenant's applications use the FHIR REST API that those applications will never need to search Patients by birthdate, then there would be no need to store search index information for the `birthdate` attribute in `Patient` resources. And consequently, you could filter out the `birthdate` search parameter for the `Patient` resource type and not lose any needed functionality, but yet save a little bit of storage capacity in your datastore. +For performance and scalability reasons, it might be desirable to limit the number of search parameters considered during a _create_ or _update_ operation for particular resource types, if those search parameters will never be used in search operations. After all, if there will be no need to use the search index information, there's no need to store it. For example, if you know that due to the way in which a particular tenant's applications use the FHIR REST API that those applications will never need to search Patients by birthdate, then there would be no need to store search index information for the `birthdate` attribute in `Patient` resources. Consequently, you could filter out the `birthdate` search parameter for the `Patient` resource type and not lose any needed functionality, but yet save a little bit of storage capacity in your datastore. -The search parameter filtering feature is supported through a set of inclusion rules specified via the `fhirServer/searchParameterFilter` configuration property. The search parameter inclusion rules allow you to define a set of search parameters per resource type that should be included in the FHIR server's view of search parameters when storing resources and performing search operations. The rules also allow you to specify a wildcard for resource types and also for search parameter. The following example shows the general form for specifying inclusion rules: +The search parameter filtering feature is supported through a set of inclusion rules specified via the `fhirServer/resources` property group in `fhir-server-config.json`. The search parameter inclusion rules allow you to define a set of search parameters per resource type that should be included in the FHIR server's view of search parameters when storing resources and performing search operations. The following snippet shows the general form for specifying inclusion rules: ``` -{ - "fhirServer": { - "searchParameterFilter": { - "<resource type1>": [ - "sp-name1", - "sp-name2", - ..., - "sp-namen" - ], - "<resource type2>": [ - "sp-name1", - "sp-name2", - ..., - "sp-namen" - ], - "<resource type3>": [ "*" ], - "*": [ "*" ] +"resources": { + "open": false, + "CarePlan": { + "searchParameters": {} + }, + "ExplanationOfBenefit": { + "searchParameters": { + "_id": "http://hl7.org/fhir/SearchParameter/Resource-id", + "_lastUpdated": "http://hl7.org/fhir/SearchParameter/Resource-lastUpdated", + "patient": "http://hl7.org/fhir/us/carin-bb/SearchParameter/explanationofbenefit-patient", + "type": "http://hl7.org/fhir/us/carin-bb/SearchParameter/explanationofbenefit-type", + "identifier": "http://hl7.org/fhir/us/carin-bb/SearchParameter/explanationofbenefit-identifier", + "service-date": "http://hl7.org/fhir/us/carin-bb/SearchParameter/explanationofbenefit-service-date" } + }, + "Patient": { + "searchParameters": {} + }, + "RelatedPerson": { + "searchParameters": {} } } ``` -The `fhirServer/searchParameterFilter` property is a JSON map where the key represents the resource type, and the value is an array of strings representing search parameter codes. The wildcard (`"*"`) can be used either as a resource type or as a search parameter code. +The `fhirServer/resources//searchParameters` property group is a JSON map where the key is the search parameter code that will be used to search on this parameter and the value is a canonical URL which resolves to a SearchParameter definition from the `fhir-registry` at run-time. +Omitting this property is equivalent to supporting all search parameters in the server's registry that apply to the given resource type. +An empty object, `{}`, can be used to indicate that no global search parameters are supported. +It may be desirable to re-define a single search parameter code. In this case, if you do not wish to filter any other parameters for this type, a value of `"*": "*"` can be used to prevent further filtering. -Filtering can only be controlled at the Resource level on which it is defined. For example, for SearchParameters defined on the resource type `Resource` (i.e. applicable to all Resources), the filter must be applied with a key of `Resource`: +Additionally, for SearchParameters defined across all resource types (i.e. SearchParameters with a base of type `Resource`), the filter can be applied at this level as well: ``` -"searchParameterFilter": { - "Resource": [ "_id" ], +"resources": { + "open": false, + "CarePlan": { + "searchParameters": {} + }, + "ExplanationOfBenefit": { + "searchParameters": { + "patient": "http://hl7.org/fhir/us/carin-bb/SearchParameter/explanationofbenefit-patient", + "type": "http://hl7.org/fhir/us/carin-bb/SearchParameter/explanationofbenefit-type", + "identifier": "http://hl7.org/fhir/us/carin-bb/SearchParameter/explanationofbenefit-identifier", + "service-date": "http://hl7.org/fhir/us/carin-bb/SearchParameter/explanationofbenefit-service-date" + } + }, + "Patient": { + "searchParameters": {} + }, + "RelatedPerson": { + "searchParameters": {} + }, + "Resource": { + "searchParameters": { + "_id": "http://hl7.org/fhir/SearchParameter/Resource-id", + "_lastUpdated": "http://hl7.org/fhir/SearchParameter/Resource-lastUpdated" + } + } +} ``` For reference, the following is the list of codes in this category: @@ -166,81 +192,44 @@ For reference, the following is the list of codes in this category: Note: `_content` and `_query` are not yet supported by the IBM FHIR Server. -The filter `"*": ["*"]` is not necessary to include these Resource-level parameters. -The following sections presents several examples. - -#### 1.2.1 Example 1 -In the following example, a single inclusion rule uses wildcards to instruct the FHIR server to include any search parameter for any resource type. This is also the default behavior of the server when the `fhirServer/searchParameterFilter` configuration property is not set: - -``` -{ - "fhirServer": { - "__comment": "include all search parameters for all resource types (default)", - "searchParameterFilter": { - "*": [ "*" ] - } - } -} -``` - -#### 1.2.2 Example 2 -In the following example, inclusion rules are specified for a few specific resource types, and then wildcards are used to include search parameters for the remaining resource types: +The filter `"*": "*"` is not necessary to include these Resource-level parameters. -``` -{ - "__comment": "FHIR server configuration", - "fhirServer": { - "searchParameterFilter": { - "Device": [ patient", "organization" ], - "Observation": [ "code" ], - "Patient": [ - "active", - "address", - "birthdate", - "name" - ], - "Resource": ["_id", "_lastUpdated"], - "*": [ "*" ] - } - } -} -``` - -For Device resources, only the `patient` and `organization` search parameters are included, while for `Observation` resources, only the `code` search parameter is included. For `Patient` resources, you can see that the `active`, `address`, `birthdate` and `name` search parameters are included. Finally, for any other resource types, all of their built-in search parameters are included in the server's view when storing resources or performing search operations. - -Note that if this example did not include the last inclusion rule, then no other resource type's built-in search parameters would be included. - -##### 1.2.3 Summary of the inclusion rules and filtering algorithm -Here are some rules about the rules: -1. Each rule specifies a resource type name and a JSON array of search parameter codes. -2. A resource type should appear in at most one rule. In other words, you cannot specify two or more inclusion rules with the same resource types. -3. At most one rule can specify the wildcard (`*`) for the resource type, and it should appear as the last rule in the map. - -This is how the filtering algorithm works: -1. When retrieving the built-in search parameters for a particular resource type, the FHIR server will retrieve the rule associated with that resource type, if one exists. If one doesn't exist, then the rule for the wildcard resource type (`"*"`) is retrieved if it exists. -2. If no inclusion rule was found in Step 1 (that is, the resource type in question has no rule and there's no rule containing a wildcard for the resource type), then no built-in search parameters for this resource type will be included in the FHIR server's view of search parameters while storing a resource of performing a search operation. -3. Using the search parameter codes associated with the rule retrieved in Step 1, the FHIR server will apply the rule to each built-in search parameter defined for that resource type.If the search parameter's code is found within the inclusion rule's list of search parameter codes or the inclusion rule's list of codes includes the wildcard (`"*"`), then the search parameter will be included in the FHIR server's view of search parameters for that resource type. - -#### 1.2.4 Handling unexpected search parameters +#### 1.2.1 Handling unexpected search parameters The IBM FHIR Server supports configurable handling of unknown or unsupported search parameters as defined at https://ibm.github.io/FHIR/Conformance#http-headers. Filtered search parameters are handled exactly the same as undefined search parameters, meaning that searches which include these parameters will fail in `strict` mode. -#### 1.2.5 fhir-server-config.json properties -The following properties are available to configure searchParameterFilter: +## 2 Re-index +Reindexing is implemented as a custom operation that tells the server to read a set of resources and replace the existing search parameters with those newly extracted from the resource body. + +The `$reindex` operation can be invoked via an HTTP(s) POST to `[base]/$reindex`. By default, the operation will select 10 resources and re-extract their search parameters values based on the current configuration of the server. The operation supports the following parameters to control the behavior: +|name|type|description| +|----|----|-----------| +|`_tstamp`|string|Reindex any resource not previously reindexed before this timestamp. Format as a date YYYY-MM-DD or time YYYY-MM-DDTHH:MM:DDZ.| +|`_resourceCount`|integer|The maximum number of resources to reindex in this call. If this number is too large, the processing time might exceed the transaction timeout and fail.| -##### 1.2.5.1 Default property values -| Property Name | Default value | -|-------------------------------| ----------------| -|`fhirServer/searchParameterFilter`|`"*": ["*"]`| +To aid the re-indexing process, the IBM FHIR Server team has introduced some new features into the fhir-bucket resource-loading tool for driving the reindex. The fhir-bucket tool uses a thread-pool to make concurrent POST requests to the IBM FHIR Server `$reindex` custom operation. -##### 1.2.5.2 Property attributes -| Property Name | Tenant-specific? | Dynamic? | -|-------------------------------|------------------|----------| -|`fhirServer/searchParameterFilter`|Y|Y| +To run the reindex step, see this example (using PostgreSQL): -In general, the configuration properties for a particular tenant are stored in the `/wlp/usr/servers/fhir-server/config//fhir-server-config.json` file, where `` refers to the tenant's "short name" or tenant id. The global configuration is considered to be associated with a tenant named `default`, so those properties are stored in the `/wlp/usr/servers/fhir-server/config/default/fhir-server-config.json` file. Similarly, tenant-specific search parameters are found at `/wlp/usr/servers/fhir-server/config//extension-search-parameters.json` whereas the global/default extension search parameters are at `/wlp/usr/servers/fhir-server/config/default/extension-search-parameters.json`. Search parameters are handled like a single configuration property; providing a tenant-specific file will override the global/default extension search parameters. +``` +JAR="/path/to/fhir-bucket-4.5.0-cli.jar" + +java \ + -Djava.util.logging.config.file=logging.properties \ + -jar "${JAR}" \ + --db-type postgresql \ + --fhir-properties fhir.properties \ + --tenant-name "YOUR-TENANT-NAME" \ + --max-concurrent-fhir-requests 200 \ + --no-scan \ + --reindex-tstamp YYYY-MM-DD \ + --reindex-resource-count 10 \ + --reindex-concurrent-requests 200 +``` -If you have any issues, open an issue with the IBM FHIR Server team. +The value of YYYY-MM-DD is a date-stamp used to indicate the date on which the resources have been reindexed. The IBM FHIR Server tracks when a resource was last reindexed and only resources with a reindex_tstamp value less than the given YYYY-MM-DD parameter will be processed. When a resource is reindexed, its reindex_tstamp is set to the given YYYY-MM-DD value indicating it has been processed. In most cases, using the current date (for example "2020-10-27") is the best option for this value. -
+Reindexing is resource-intensive and can take several hours or even days to complete depending on the number of resources currently in the system and the capability of the hosting platform. + +--- FHIR® is the registered trademark of HL7 and is used with the permission of HL7. From 357cdcfc00f6614b1addc3ab32146b71e0202dbd Mon Sep 17 00:00:00 2001 From: Lee Surprenant Date: Thu, 19 Nov 2020 05:15:36 -0500 Subject: [PATCH 2/4] fix typo Signed-off-by: Lee Surprenant --- docs/src/pages/guides/FHIRSearchConfiguration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/pages/guides/FHIRSearchConfiguration.md b/docs/src/pages/guides/FHIRSearchConfiguration.md index a60b028170e..f7574e46bed 100644 --- a/docs/src/pages/guides/FHIRSearchConfiguration.md +++ b/docs/src/pages/guides/FHIRSearchConfiguration.md @@ -13,7 +13,7 @@ Specifically, the IBM FHIR Server supports searching on additional fields, inclu * fields that are defined in the base specification, which are not configured for search; and * extension elements that a tenant may add to a standard FHIR resource type -The IBM FHIR Server allows deployers to define search parameters on a tenant-specific basis. This allows each tenant to share an instance of the FHIR server while maintaining the ability to have their own set of search parameters. Additionally, specificatin-defined search parameters can be filtered out in order to avoid the cost of extracting and storing the corresponding indices. +The IBM FHIR Server allows deployers to define search parameters on a tenant-specific basis. This allows each tenant to share an instance of the FHIR server while maintaining the ability to have their own set of search parameters. Additionally, specification-defined search parameters can be filtered out in order to avoid the cost of extracting and storing the corresponding indices. Tenant search parameters are defined via a [Bundle](https://www.hl7.org/fhir/r4/bundle.html) of [SearchParameter](https://www.hl7.org/fhir/r4/searchparameter.html) resources that define the additional search parameters which describe the searchable field and define the FHIRPath expression for extraction. \For example, a tenant that extends the `Patient` resource type with the `favorite-color` extension, enables search on `favorite-color` by defining a SearchParameter as part of this bundle. From 98aca21a55c5a1a0b716655f631b0696f53f20e7 Mon Sep 17 00:00:00 2001 From: Lee Surprenant Date: Thu, 19 Nov 2020 09:08:21 -0500 Subject: [PATCH 3/4] fix typo Signed-off-by: Lee Surprenant Co-authored-by: Paul Bastide --- docs/src/pages/guides/FHIRSearchConfiguration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/pages/guides/FHIRSearchConfiguration.md b/docs/src/pages/guides/FHIRSearchConfiguration.md index f7574e46bed..01096a8fb37 100644 --- a/docs/src/pages/guides/FHIRSearchConfiguration.md +++ b/docs/src/pages/guides/FHIRSearchConfiguration.md @@ -15,7 +15,7 @@ Specifically, the IBM FHIR Server supports searching on additional fields, inclu The IBM FHIR Server allows deployers to define search parameters on a tenant-specific basis. This allows each tenant to share an instance of the FHIR server while maintaining the ability to have their own set of search parameters. Additionally, specification-defined search parameters can be filtered out in order to avoid the cost of extracting and storing the corresponding indices. -Tenant search parameters are defined via a [Bundle](https://www.hl7.org/fhir/r4/bundle.html) of [SearchParameter](https://www.hl7.org/fhir/r4/searchparameter.html) resources that define the additional search parameters which describe the searchable field and define the FHIRPath expression for extraction. \For example, a tenant that extends the `Patient` resource type with the `favorite-color` extension, enables search on `favorite-color` by defining a SearchParameter as part of this bundle. +Tenant search parameters are defined via a [Bundle](https://www.hl7.org/fhir/r4/bundle.html) of [SearchParameter](https://www.hl7.org/fhir/r4/searchparameter.html) resources that define the additional search parameters which describe the searchable field and define the FHIRPath expression for extraction. For example, a tenant that extends the `Patient` resource type with the `favorite-color` extension, enables search on `favorite-color` by defining a SearchParameter as part of this bundle. ## 1 Configuration There are three layers of search parameter configuration. From 228a0862cf399045a705df07268f83e84d57a12a Mon Sep 17 00:00:00 2001 From: Lee Surprenant Date: Sun, 22 Nov 2020 15:19:32 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Signed-off-by: Lee Surprenant --- docs/src/pages/guides/FHIRSearchConfiguration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/pages/guides/FHIRSearchConfiguration.md b/docs/src/pages/guides/FHIRSearchConfiguration.md index 01096a8fb37..8ccef5a6077 100644 --- a/docs/src/pages/guides/FHIRSearchConfiguration.md +++ b/docs/src/pages/guides/FHIRSearchConfiguration.md @@ -34,7 +34,7 @@ The IBM FHIR Server supports compartment searches based on the CompartmentDefini ### 1.1 Tenant-specific parameters To configure tenant-specific search parameters, create a file called `extension-search-parameters.json`, placing it in the `${server.config.dir}/config/` directory. For example, the `${server.config.dir}/config/acme/extension-search-parameters.json` file would contain the search parameters for the `acme` tenant, while `${server.config.dir}/config/qpharma/extension-search-parameters.json` would contain search parameters used by the `qpharma` tenant. -When the FHIR server processes a request associated with the `acme` tenant, the server is uses the built-in search parameters and the user-defined search parameters defined in the `acme` tenant's extension-search-parameters.json file. Likewise, when processing a request associated with the `qpharma` tenant, the server uses the built-in search parameters and the user-defined search parameters defined in the `qpharma` tenant's `extension-search-parameters.json` file. +When the FHIR server processes a request associated with the `acme` tenant, the server is uses the built-in search parameters and the user-defined search parameters defined in the `acme` tenant's `extension-search-parameters.json` file. Likewise, when processing a request associated with the `qpharma` tenant, the server uses the built-in search parameters and the user-defined search parameters defined in the `qpharma` tenant's `extension-search-parameters.json` file. If a tenant-specific extension-search-parameters.json file does not exist, the server falls back to the global `extension-search-parameters.json` file found at `${server.config.dir}/config/default/extension-search-parameters.json`. @@ -105,7 +105,7 @@ For more information on search parameters, see the [HL7 FHIR specification](http #### 1.1.2 Recommendations When creating the SearchParameter FHIRPath expression, be sure to test both the FHIRPath expression and the search parameter. -If a search parameter expression extracts an element with a data type that is incompatible with the declared search parameter type, the server skips the value and logs a message. For choice elements, like Extension.value, its recommended to restrict the expression to values of the desired type by using the `as` function. For example, to select only Decimal values from the http://example.org/demical extension, use an expressions like Basic.extension.where(url='http://example.org/decimal').value.as(Decimal). +If a search parameter expression extracts an element with a data type that is incompatible with the declared search parameter type, the server skips the value and logs a message. For choice elements, like Extension.value, its recommended to restrict the expression to values of the desired type by using the `as` function. For example, to select only Decimal values from the http://example.org/demical extension, use an expressions like `Basic.extension.where(url='http://example.org/decimal').value.as(Decimal)`. ### 1.2 Filtering The FHIR server supports the filtering of built-in search parameters. The default behavior of the FHIR server is to consider all built-in search parameters when storing resources or processing search requests, but you can configure inclusion filters to restrict the FHIR server's view to specific search parameters on a given resource type. This filtering feature does not apply to user-defined search parameters in the extension-search-parameters.json file. User-defined search parameters are always included in the FHIR server's view regardless of the configured inclusion filters.