Upgrading a Legacy Repository to JSON Advanced SQL

Mappings

Although it is recommended to use the JSON Advanced SQL strategy when possible, the legacy strategy is still supported. This appendix provides details comparing the legacy strategy to the advanced strategy, and includes upgrade instructions for those currently using the legacy strategy who wish to take advantage of the additional features available with the advanced strategy.

Migrating to JSON Advanced SQL

Follow these instructions to migrate from the legacy strategy to the JSON Advanced SQL strategy with no down time:

1. Before you begin migrating from the legacy strategy to the JSON Advanced SQL strategy, perform these pre-migration steps:

   1. Evaluate your customizations of the existing repository that extends the legacy JSON strategy.

   2. Create a new strategy by extending these classes:

      • HS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategy

      • HS.FHIRServer.Storage.JsonAdvSQL.RepoManager

      • HS.FHIRServer.Storage.JsonAdvSQL.Interactions

   3. Migrate the relevant customizations from your legacy strategy to the new extended classes in your JSON Advanced SQL strategy.

   4. Validate that the new customizations work, and make needed fixes.

2. Begin migration by creating a new repository. To do so, execute the following command in the terminal:

   set status = ##class(HS.FHIRServer.Storage.JsonAdvSQL.ConvertJson).Start(<endpoint_to_be_converted>, <new_strategy_key>)
   

   <new_strategy_key> is the strategy key associated with your extended JSON Advanced SQL classes. For more information about strategy keys, see Subclass Parameters. For information about additional optional parameters such as pNumWorkers and pWait, see HS.FHIRServer.Storage.JsonAdvSQL.ConvertJsonOpens in a new tab in the class reference.

   This command creates a new repository that uses existing Resource and Version tables as well as most other settings from the old repository. It creates new search tables and maps them to the Resource database if needed. It runs indexing of the new search tables in a background job.

3. Wait for the background job indexing the new search tables to finish. Progress and completion of this job are logged in the interoperability event log.

4. When the background job is complete, cut over from the old Json-based repository to the new one based on JsonAdvSQL, by executing the following command:

   set status = ##class(HS.FHIRServer.Storage.JsonAdvSQL.ConvertJson).Cutover(<endpoint_to_be_converted>,<service_id_of_new_endpoint>)
   

   The exact arguments to use in this command are included in the background job completion message in the interoperability event log.

   This command assocates the cspUrl with the new repository and disables the old one. Once this is complete, all new requests to that URL will be handled by the new JsonAdvSQL-based code and data structures. The search tables associated with the old repository will no longer be maintained.

5. Optional. You can clean up unnecessary parts of the old Json-based endpoint by executing the following command:

   set status = ##class(HS.FHIRServer.Storage.JsonAdvSQL.ConvertJson).Cleanup(<old_repo_service_id>)
   

   The old repository service ID is included in the terminal output from the cut-over process.

   The following entities are cleaned up:

   • All HSFHIR search tables associated with the old endpoint

   • All HS_FHIRServer_Storage_JSON.SearchColumn rows associated with the old service key

   • The cached CapabilityStatement for the old endpoint

   • The ComparmentsIdx index from the resource table

   • The HS_FHIRServer.Repo where ID = <old_repo_service_id>