migrate-from-aidbox-searchparameter-to-fhir-searchparameter.md

Migrate from Aidbox SearchParameter to FHIR SearchParameter

If you want to use the FHIRSchema validation engine, your custom Aidbox SearchParameters defined via Zen or Entities will not be available. Aidbox with FHIRSchema validation enabled is more aligned with the FHIR specification and only supports FHIR SearchParameters. In this case, use this migration guide.

{% hint style="info" %} If you are using Zen project to define your SearchParameter resources, you can also follow this guide, but you will need to remove the SearchParameter definitions from your Zen project. {% endhint %}

To migrate Aidbox SearchParameter you need to redefine it as regular FHIR SearchParameters using REST API:

POST /fhir/SearchParameter
content-type: application/json
accept: application/json

To define FHIR SearchParameter you should know the meaning of some basic FHIR SearchParameter properties, required fields marked as *:

Property	Description	Additional Notes
base *	The resource type(s) this search parameter applies to.	In Aidbox SearchParameter it was reference to Entity in resource property.
url *	Canonical identifier for this search parameter, represented as a URI (globally unique).	Didn't exists in Aidbox SearchParameter.
expression *	FHIRPath expression that extracts the values.	You need to manually convert Adibox SearchParameter.expression to FHIRPath expression.
name *	Computationally friendly name of the search parameter.	The same as in Adibox SearchParameter.name.
status *	draft | active | retired | unknown. Binding to publication-status ValueSet.	Didn't exist in Aidbox SearchParameter. Use active status.
type *	number | date | string | token | reference | composite | quantity | uri | special. Binding to search-param-type ValueSet.	Transfer this value as it was in Adbox SearchParameter.type.

Simple case

Let's migrate custom Aidbox SearchParameter Patient.city:

GET /SearchParameter/Patient.city

​{
  "name": "city",
  "type": "token",
  "resource": {
    "id": "Patient",
    "resourceType": "Entity"
  },
  "expression": [
    [
      "address",
      "city"
    ]
  ]
}

Migration steps

First step is to replace resource property to base property with target resource type:

Aidbox target resource type

"resource": {
    "id": "Patient",
    "resourceType": "Entity"
  }

FHIR target resource type

"base": ["Patient"]

Than you need to rewrite expression property to FHIRPath format. Usually it may be transformed by joining vector elements with each other separated by . symbol and joining resource type in front of this construction like this:

Aidbox expression

"expression": [
    [
      "address",
      "city"
    ]
  ]

FHIR expression

"expression": "Patient.address.city"

The final step is to add the missing status and url fields required by the FHIR SearchParameter specification. For the status property in the aidbox, you usually just set it to active.

FHIR status and url

"status": "active"
"url": "http://example.org/fhir/SearchParameter/patient-city"

Here is the migration request for Patient.city SearchParameter:

PUT /fhir/SearchParameter/patient-city
content-type: application/json
accept: application/json

{
  "resourceType": "SearchParameter",
  "name": "city",
  "url": "http://example.org/fhir/SearchParameter/patient-city",
  "status": "active",
  "description": "Search by city",
  "code": "city",
  "base": ["Patient"],
  "type": "token",
  "expression": "Patient.address.city"
}

Complex expression cases

For more complex cases, there is a need for more complex expression mapping. Here is a few examples:

Aidbox expression with or

If expression contains multiple arrays, it means or statement between multiple expressions:

"expression": [
  ["address", "city"],
  ["address", "line"]
 ] 

FHIR expression with or

This is what it looks like in the FHIRPath format:

"expression": "Patient.address.city or Patient.address.line"

Aidbox expression with where

When expression contains object, it means where statement. In this case it would extract records with element telecom which contains field system with value email:

"expression": [
  ["telecom", {"system": "email"}]
 ] 

FHIR expression with where

This is what it looks like in the FHIRPath format:

"Patient.telecom.where(system = 'email')"