Kodjin Configuration

How to enable history functionality

History should be configured in common configuration file for all services - globals.yaml.gotmpl. The configuration file's path is - etc/kodjin/{environment}/globals.yaml.gotmpl

1. Check Zookeeper worker group present, if not add it to the file:

worker_groups = [
# . . .
  {
    name                 = "zookeeper"
    instance_type        = "t3.small"
    additional_userdata  = "t3.small"
    asg_desired_capacity = 3
    asg_max_size         = 3
    asg_min_size         = 3
    ami_id               = "ami-0dd8af8522cf16846"
    kubelet_extra_args   = "--node-labels=db=zookeeper --register-with-taints=key=zookeeper:NoSchedule"
    root_volume_size     = "50"
    root_volume_type     = "gp3"
    enable_monitoring    = false
  },
]

1. Enable clickhouse and zookeeper releases in deps:

zookeeper:
  enabled: true
clickhouse:
  enabled: true

1. Check whether the secrets exist and have the following format:

secret:
    username: ENC[username]
    password: ENC[password]
. . .

1. Enable the fhir-server-clickhouse-migrations release in kodjin:

fhir-server-clickhouse-migrations:
  enabled: true

1. Enable the fhir-server-kafka-config-secrets-sync release in kodjin:

fhir-server-kafka-config-secrets-sync:
  enabled: true

1. Set HISTORY_ENABLED to true in kodjin globals:

envs:
  history:
    HISTORY_ENABLED: true

How to switch on Multi-tenancy on Kodjin cluster

Headers and access token claims should be configured in Kodjin's infrastructure configuration file.

The configuration file indicates whether multi-tenancy is enabled and also provides information about URLs excluded from the multi-tenancy logic. The configuration file's path is - etc/kodjin/<environment>/values/fhir-config/multitenancy.json

{
  "enabled": true,
  "required_metadata": {
    "tenant-id": {
      "rbac_claim": "practice_ids"
    },
    "owned-by": {
      "rbac_claim": "organization_id"
    }
  },
  "exclude_resources": [
    "CapabilityStatement",
    "ImplementationGuide",
    "SearchParameter",
    "ValueSet",
    "CodeSystem",
    "ConceptMap",
    "StructureDefinition"
  ]
}

This configuration file should be delivered to Kodjin FHIR server services that support the multi-tenancy option. Kodjin's infrastructure configuration is pre-configured to deliver this configuration to services using a common configuration for all services - globals.yaml.gotmpl

Configuring bulk-export operation

Duration of Availability for Downloading Exported FHIR Resources

To change the default value for time while exported resources are accessible for downloading (time-to-live or TTL) by bulk-export operation the Kodjin's cluster administrator should override the default value. The configuration file's path is: etc/kodjin/{environment}/values/fhir-server-search-export.yaml.gotmpl. Then add or modify value: OBJECT_TTL: 10

How to configure the export for indirect referenced resources for Patient and Group level export

To define how resources that are not directly referenced by the Patient should be processed for export, navigate to the configuration file at etc/kodjin/<environment>/values/fhir-config/export-additional-included-resources.json.

This configuration section specifies the FHIR resources that should be analyzed during the export process. There are two options for each resource:

• allowedForGroupExport: Determines if the resource is allowed for Group-level export. The default value is true.
• allowedForPatientExport: Determines if the resource is allowed for Patient-level export. The default value is false.

Additionally, it is required to specify a FHIRPath expression for the attribute that contains a reference to the resource without a direct Patient reference and the resource type.

For more information about the Bulk Export operation, see the Bulk Data Export page.

  {
    "MedicationRequest": [
        {
            "allowedForGroupExport": true,
            "allowedForPatientExport": false,
            "path": "$.medicationReference.reference",
            "resourceTypes": [
                "Medication"
            ]
        }
    ],
    "Encounter": [
        {
            "allowedForGroupExport": true,
            "allowedForPatientExport": false,
            "path": "$.location[*].location.reference",
            "resourceTypes": [
                "Location"
            ]
        },
        {
            "allowedForGroupExport": true,
            "allowedForPatientExport": false,
            "path": "$.serviceProvider.reference",
            "resourceTypes": [
                "Organization"
            ]
        }
    ],
    "CareTeam": [
        {
            "allowedForGroupExport": true,
            "allowedForPatientExport": false,
            "path": "$.participant[*].member.reference",
            "resourceTypes": [
                "Practitioner"
            ]
        }
    ]
  }

How to enable/disable opentelemetry tracing

You can enable or disable tracing in your Kodjin environment. If you enable tracing it will use elastic search storage and will affect Kodjin performance.

Enable opentelemetry tracing

1. Enable jaeger releases in deps:

etc/deps/<environment>/releases.yaml:

jaeger:
  enabled: true

1. Remove traefik.yaml config file from etc/deps/<environment>/values directory.

2. Set OTEL_SDK_DISABLED to false in kodjin globals:

etc/kodjin/<environment>/globals.yaml.gotmpl:

envs:
  opentelemetry:
    OTEL_SDK_DISABLED: false

Disable opentelemetry tracing

1. Disable jaeger releases in deps:

etc/deps/<environment>/releases.yaml:

jaeger:
  enabled: false

or remove lines from etc/deps/<environment>/releases.yaml:

jaeger:
  enabled: true

1. Add new traefik.yaml config file to etc/deps/<environment>/values directory with content from corresponded config file from cache - .helmfile/cache/deps.bootstrap.infra-v<version>/etc/deps/<environment>/values/traefik.yaml. You need only additionalArguments key from source file. For example:

additionalArguments:
  - --entryPoints.web.forwardedHeaders.insecure=true
  - --entryPoints.websecure.forwardedHeaders.insecure=true
  - --tracing=true
  - --tracing.serviceName=traefik-edge
  - --tracing.jaeger=true
  - --tracing.jaeger.disableAttemptReconnecting=false
  - --tracing.jaeger.samplingServerURL=http://jaeger-ingress-agent.observability:5778/sampling
  - --tracing.jaeger.collector.endpoint=http://jaeger-collector.observability:14268/api/traces?format=jaeger.thrift

Then change tracing and tracing.jaeger arguments to false. Using the example above you will get content like this:

additionalArguments:
  - --entryPoints.web.forwardedHeaders.insecure=true
  - --entryPoints.websecure.forwardedHeaders.insecure=true
  - --tracing=false
  - --tracing.serviceName=traefik-edge
  - --tracing.jaeger=false
  - --tracing.jaeger.disableAttemptReconnecting=false
  - --tracing.jaeger.samplingServerURL=http://jaeger-ingress-agent.observability:5778/sampling
  - --tracing.jaeger.collector.endpoint=http://jaeger-collector.observability:14268/api/traces?format=jaeger.thrift

Save file.

1. Set OTEL_SDK_DISABLED to true in kodjin globals:

etc/kodjin/<environment>/globals.yaml.gotmpl:

envs:
  opentelemetry:
    OTEL_SDK_DISABLED: true

Note: Keep in mind that disabling tracing does not automatically remove traces from the storage. To delete information about tracks, you need to delete the corresponding indexes in elasticsearch by searching for them using the prefix “observability-jaeger-*”.

Configuring CapabilityStatement template

The Kodjin FHIR server supports configuring common static parameters, such as contacts, description, publisher, etc., for the metadata endpoint (e.g., https://demo.kodjin.com/fhir/metadata).

Follow CapabilityStatement configuration for more details.

To define this configuration, use the configuration file located at etc/kodjin/{environment}/values/fhir-config/capability-statement-template.json

    {
      "resourceType": "CapabilityStatement",
      "publisher": "EdenLab",
      "fhirVersion": "4.0.1",
      "name": "Kodjin FHIR server 4.0.1 CapabilityStatement",
      "contact": [
        {
          "name": "EdenLab",
          "telecom": [
            {
              "system": "email",
              "value": "welcome@edenlab.io",
              "use": "work"
            }
          ]
        }
      ],
      "description": "This is the FHIR capability statement",
      "date": "_",
      "experimental": true,
      "software": {
        "name": "Kodjin FHIR Server"
      },
      "implementation": {
        "description": "Kodjin FHIR Server"
      },
      "format": ["application/fhir+xml", "application/fhir+json"],
      "patchFormat": ["application/fhir+json", "application/fhir+xml"],
      "id": "_",
      "kind": "instance",
      "status": "active",
      "url": "metadata",
      "version": "1.0.0",
      "rest": []
  }

How to enable or disable Audit logging

The auditing process implemented in Kodjin FHIR Server is in accordance with Audit event resource definition and IHE profile for Basic Audit Log Patterns. For further implementation note, please refer to Audit Logging page.

To enable and configure auditing, navigate to the Audit event configuration at etc/kodjin/<environment>/values/fhir-config/audit_log.json

By default auditing is switched off.

The rule to include or exclude specific interactions and resources from audit events is defined by specifying criteria within the audit configuration. This configuration determines which events are recorded and which are omitted, allowing for tailored auditing based on specific interactions (such as read, write, delete) and resources (such as Patient, Observation). By configuring these rules, organizations can ensure that their auditing focuses on significant events, thereby optimizing performance and compliance with regulatory requirements.

Options:

• enabled: true or false - indicates whether auditing is enabled or disabled. If enabled is set to true, every request will be audited based on the filter_mode option.

• filter_mode: exclude or include - defines the rule for including or excluding specific interactions and resources from audit events (see parameters below). When set to exclude, everything will be audited except for the exclusions. Conversely, when set to include, everything will be omitted from auditing except for the inclusions defined in the interaction.

• interaction: is an array of possible actions: read, vread, update, patch, delete, history, create, search from set of action, there is an array of FHIR resources. Wildcards are supported, meaning All actions or All resources

  {
    "enabled": true,
    "buffer_size": 8,
    "filter_mode": "exclude",
    "interactions": {
      "read": ["StructureDefinition"],
      "update": ["*"],
      "*": ["ValueSet", "CodeSystem", "ConceptMap", "SearchParameter"]
    }
  }

  {
    "enabled": true,
    "buffer_size": 8,
    "filter_mode": "include",
    "interactions": {
      "*": ["Patient"],
      "read": ["Observation","MedicationRequest"]
    }
  }

  {
    "enabled": false
  }

RBAC routes configuration file

RBAC routes configuration file allows to manage access to Kodjin endpoints. Current configuration file provides three level of access:

• access is allowed without token or scope
• access is allowed with active and valid token but no scope is required
• access is allowed only with proper scope and valid token

{
    "routes": [
        {
            "method": [
                "POST"
            ],
            "path": "/$apply-fhirpath",
            "mode": "token_only"
        },
        {
            "method": [
                "GET",
                "POST"
            ],
            "path": "/$versions",
            "mode": "public"
        },
        {
            "method": [
                "*"
            ],
            "regex": "/metadata(\\?)*[A-Za-z]*",
            "mode": "public"
        },
        {
            "method": [
                "GET"
            ],
            "path": "/fhir-base-url",
            "mode": "public"
        }
    ]
}

How to read and use file:

• method is an array, where any kinds of interactions should be mentioned, for example POST, GET. If all kinds of interactions should be used, then * (wildcard) could be used instead. Method is required in the file.
• path or regex is a string, where endpoint should be added. Path is an exact match string. Regex allows regex patterns for route path. Path and regex is oneOf element - either path, or regex shall be used.
• mode is a string, where only two variant could be used. Any routes that are not mentioned in this file require proper scope for access. Mode is required in the file. Mode variants are:
  • "public" - access without token or scope
  • "token_only" - access with active and valid token but no scope is required