Using Db2 for persistence

Create a Db2 instance

1. Log in to your IBM Cloud account Link.

2. Click Create resource.

3. Choose Db2.

4. Select the Pricing Plan:

   • The IBM FHIR Server recommends the Flex plan for a production workload, development and experiments.

5. Create Create

Scale the instance

1. The scaling of the instance requires a service restart.
2. The instance CPU/Memory are scalable up and down. The storage in only scaled up.

Create the administrator credential

1. Navigate to the Db2 instance you created.

2. Click on the Service credentials panel.

   • If the list of service credentials is empty, create a new one.
     1. Click New credential (+)
     2. Enter the Name. Any name works for example, ibm-fhir-server-db2.
     3. Click Add

3. Access the credential, select View Credentials. The entry you just created looks like the following block of JSON(the secrets are blanked out here):

   {
       "hostname": "dashdb-txn-flex-***********.services.dal.bluemix.net",
       "password": "bluadmin-password-very-secret",
       "https_url": "https://dashdb-txn-flex-************.services.dal.bluemix.net:8443",
       "port": 50000,
       "ssldsn": "DATABASE=BLUDB;HOSTNAME=dashdb-txn-flex-************.services.dal.bluemix.net;PORT=50001;PROTOCOL=TCPIP;UID=bluadmin;PWD=bluadmin-password-very-secret;Security=SSL;",
       "host": "dashdb-txn-flex-************.services.dal.bluemix.net",
       "jdbcurl": "jdbc:db2://dashdb-txn-flex-************.services.dal.bluemix.net:50000/BLUDB",
       "uri": "db2://bluadmin:bluadmin-password-very-secret@dashdb-txn-flex-************.services.dal.bluemix.net:50000/BLUDB",
   Copied!

4. Save these details for later, as these properties are needed to deploy and manage the IBM FHIR Server schema.

Add the FHIRSERVER user and API key

1. Read API Key and the tenant key from the fhir-server-config.json
2. Connect to Db2 to access authenticated data using IAM
3. Confirm tenant-key to access authorized data

1. On the IBM Cloud console, select Manage > Access (IAM).

2. Select the Service IDs panel.

3. Click Create (+)

   1. Enter a meaningful name, such as fhir-service-id.
   2. Enter a description, such as for instance db2-ho.
   3. Click the Create.
   • Note (1): If you have already created the entry, click the entry.
   • Note (2): You may have to wait for the table to populate.

4. Select the API keys tab.

   • Note: This tab is not the same IBM Cloud API keys on the left.

5. To create an API Key, select Create (+).

   1. Enter a name for the api key, for example, fhir-server-api.
   2. Click Create.
   3. Copy or download the key.
   • Note: if you don’t retain a copy, don’t panic - you can simply delete the API key and create a new one. API keys are designed to support additions and deletions, so you add as many as you need and delete others for any reason.

1. Navigate to the Resources page

2. Find and click on your IBM Db2 on Cloud instance.

3. Click on Manage.

4. Click on Open Console.

5. Click SETTINGS > Manage Users.

   • Note: If you do not see Manage Users, you are probably using a non-IAM instance. To confirm:
     1. Click Run Sql
     2. Enter the SQL

        SELECT CASE WHEN VALUE = 'IBMIAMauth' THEN 1 ELSE 0 END AS IAM_ENABLED FROM SYSIBMADM.DBMCFG WHERE NAME = 'srvcon_gssplugin_list'
        Copied!

     3. You see 0 if not IAM enabled.

6. Click Add. A panel opens on the right-hand side.

7. Select Add IBMid User at the top.

   • User ID: FHIRSERVER

   • IBMid: paste the service id fhir-server-id from the Service Id created previously.

   • Note (1): The page forces the value to lower-case, so ServiceId becomes serviceid. Don’t be alarmed, it still works.

   • Note (2): Do NOT select Administrator. One should follow the least-privelege principal for the FHIRSERVER user.

8. Click Create.

Testing the connection

1. Copy the command to your code editor

   java -cp /path/to/db2jcc4.jar com.ibm.db2.jcc.DB2Jcc  -url "jdbc:db2://<DB2-HOSTNAME>:50001/BLUDB:apiKey=<API-KEY>;securityMechanism=15;sslConnection=true;sslTrustStoreLocation=/path/to/truststore.jks;sslTrustStorePassword=<TRUSTSTORE-PASSWORD>;"
   Copied!

   • Note: Don’t forget the trailing ; in the URL. Some of the documented examples don’t include it, but it is required in order for the connection to work, although this may be fixed in a future driver release. This only affects this test URL, not the actual FHIR server configuration.

2. Replace the following values with your service details:

   • /path/to/db2jcc4.jar : replace with the path to your driver jar.

   • <DB-HOSTNAME>: the hostname of your Db2 service from the Service Credentials page

   • <API-KEY>: the API key value created in the previous section

   • <TRUSTSTORE-PASSWORD>: the password for your truststore

   • Note: When using an API Key, no username needs to be provided. This is because the API Key maps to a ServiceId, and that ServiceId is mapped to the Db2 user.

3. Run in your favorite terminal, and you should see no errors in the output. You should see output like:

[jcc][10516][13709]Test Connection Successful.
Copied!

Deploy the IBM FHIR Server schema

1. download the fhir-persistence-schema cli jar from the corresponding project release: https://github.com/IBM/FHIR/releases

2. create a properties file named db2.properties with the db2 connection info from IBM Cloud; for example:

   db.host=dashdb-txn-flex-***********.services.dal.bluemix.net
   db.port=50001
   db.database=BLUDB
   user=bluadmin
   password=bluadmin-password-very-secret
   sslConnection=true
   Copied!

3. execute the following commands:

   java -jar schema/fhir-persistence-schema-*-cli.jar \
     --prop-file db2.properties --schema-name FHIRDATA --create-schemas
   java -jar schema/fhir-persistence-schema-*-cli.jar \
     --prop-file db2.properties --schema-name FHIRDATA --update-schema --pool-size 2
   java -jar schema/fhir-persistence-schema-*-cli.jar \
     --prop-file db2.properties --schema-name FHIRDATA --grant-to FHIRSERVER --pool-size 2
   java -jar schema/fhir-persistence-schema-*-cli.jar \
     --prop-file db2.properties --schema-name FHIRDATA --allocate-tenant default --pool-size 2
   Copied!

4. note the tenantKey from the allocate-tenant step above; this will be needed to configure the IBM FHIR Server datasource in the next step

Configuring an IBM FHIR Server datasource

        "persistence": {
            "datasources": {
                "default": {
                    "tenantKey": "",
                    "type": "db2",
                    "connectionProperties": {
                        "serverName": "dashdb-txn-flex-************.services.dal.bluemix.net",
                        "portNumber": 50001,
                        "databaseName": "BLUDB",
Copied!

Mapping from IBM Db2 on Cloud endpoint credentials

• Reference the section Create the Administrator Credential to see an example.

Configuring a BulkData’s Liberty Datasource with API key

1. Create a Db2 user (e.g. FHIRBATCH)

2. Associate it with a ServiceId (no need to create an Administration user, a simple user has sufficient privileges) using the same procedure you followed for the fhir-server ServiceId user.

3. Using a valid API-KEY for the given ServiceId, configure a new datasource and the Java Batch persistence layer as follows:

    <dataSource id="fhirbatchDS" jndiName="jdbc/fhirbatchDB">
        <jdbcDriver libraryRef="fhirSharedLib"/>
        <properties.db2.jcc
            serverName="dashdb-txn-flex-************.services.dal.bluemix.net"
            portNumber="50001"
            apiKey="<API-KEY>"
            securityMechanism="15"
            pluginName="IBMIAMauth"
            databaseName="BLUDB"
Copied!

• Note: The Java Batch is configured in batchDs.xml and included from the IBM FHIR Server’s server.xml which is installed to {wlp}/usr/server/fhir-server.
• Note: While this feature is not required, it’s best to configure this datasource while configuring the main datasource.

SSL Certificate

Encrypt Secrets

Appendix: Db2 Lite Plan

• The schema size is larger than the available space.
• Concurrent Connections: The Lite plan has a limit of 5 concurrent connections, and the IBM FHIR Server fhirProxyDataSource needs to be updated to avoid failures. One should update the server.xml connectionManager with maxPoolSize - <connectionManager maxPoolSize="5"/>.
• The instance is not enabled with IAM, and you may use the Service Credentials that are created to connect to configure the datasource.

References

• Db2 on Cloud: Database details and connection credentials