### Install Firely Server Packages via NuGet

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/facade/projectsetup

Installs core Firely Server packages and FHIR specification packages using the NuGet Package Manager Console. Supports STU3 and R4 specifications. The `-IncludePrerelease` flag can be used to install beta versions.

```powershell
Install-Package Vonk.Core
```

```powershell
Install-Package Hl7.Fhir.Specification.STU3
```

```powershell
Install-Package Hl7.Fhir.Specification.R4
```

--------------------------------

### Install Firely FHIR Specification Package (STU3)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/facade/projectsetup

Installs the Hl7.Fhir.Specification.STU3 NuGet package to support the FHIR STU3 specification. This is required if your facade needs to interact with FHIR R3 resources. Run this command in the Package Manager Console.

```powershell
Install-Package Hl7.Fhir.Specification.STU3
```

--------------------------------

### Install Firely FHIR Specification Package (R4)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/facade/projectsetup

Installs the Hl7.Fhir.Specification.R4 NuGet package to support the FHIR R4 specification. This is required if your facade needs to interact with FHIR R4 resources. Run this command in the Package Manager Console.

```powershell
Install-Package Hl7.Fhir.Specification.R4
```

--------------------------------

### Install Firely Server Core Package

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/facade/projectsetup

Installs the core Vonk.Core NuGet package, which is essential for building facades with Firely Server. This command is run in the Package Manager Console within Visual Studio.

```powershell
Install-Package Vonk.Core
```

--------------------------------

### Install Latest Beta Firely Server Packages

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/facade/projectsetup

Installs the latest beta release of Firely Server packages. This is achieved by adding the '-IncludePrerelease' flag to the Install-Package command in the Package Manager Console.

```powershell
Install-Package Vonk.Core -IncludePrerelease
```

```powershell
Install-Package Hl7.Fhir.Specification.STU3 -IncludePrerelease
```

```powershell
Install-Package Hl7.Fhir.Specification.R4 -IncludePrerelease
```

--------------------------------

### Plugin Example

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/releasenotes/releasenotes_v3

Examples for pre- and post-handlers in plugins.

```APIDOC
## Plugin Example

### Description
This section highlights examples for pre- and post-handlers within plugins.

### Examples:

- Added examples for pre- and post handlers.
```

--------------------------------

### Verify Docker Installation

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/setting_up_firely_server/deployment/docker_win

Checks if Docker is installed and running by displaying its version information. This is a fundamental step after installation.

```bash
> docker version
```

--------------------------------

### Facade Example

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/releasenotes/releasenotes_v3

Examples and fixes for the Facade API.

```APIDOC
## Facade Example

### Description
This section details examples and fixes implemented for the Vonk Server's Facade API.

### Examples and Fixes:

- **Reference Searching:** Added support for searching directly on a reference from Observation to Patient (e.g., `/Observation?patient=Patient/3`).
- **RevInclude Support:** Fixed support for _revinclude of Observation on Patient (e.g., `/Patient?_revinclude:Observation:subject:Patient`).
- **Version Upgrade:** Upgraded to Vonk 2.0.0 libraries (not yet 3.0.0-beta1).
```

--------------------------------

### Starting Firely Server (.NET CLI)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/releasenotes/upgrade

This command initiates the Firely Server using the .NET CLI. Ensure you are in the correct installation directory before executing. It is used both for starting the upgraded server and for rolling back to a previous version.

```shell
> dotnet ./Vonk.Server.dll
```

```shell
> dotnet .\Vonk.Server.dll
```

--------------------------------

### Verify Docker Installation (CLI)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/setting_up_firely_server/deployment/docker_win

Executes Docker commands to check the installed version and list available images. Requires Docker to be installed and accessible via the command line.

```bash
> docker version

```

```bash
> docker images

```

--------------------------------

### Start Firely Server (Binary)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/releasenotes/upgrade

Command to start the Firely Server application after upgrading the binary distribution. Ensure you are in the new installation directory.

```shell
> dotnet ./Vonk.Server.dll
```

--------------------------------

### List Docker Images

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/setting_up_firely_server/deployment/docker_win

Displays a list of all Docker images currently present on the machine. Useful for checking available images after installation or pulling new ones.

```bash
> docker images
```

--------------------------------

### Plugin Examples Updates (Release 3.0.0-beta2)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/releasenotes/releasenotes_v3

Updates to the provided plugin examples, including `Vonk.Plugin.ExampleOperation` and `Vonk.Plugin.DocumentOperation`, as part of Release 3.0.0-beta2.

```APIDOC
## Plugin Examples Updates (Release 3.0.0-beta2)

### Description
Provides details on updates made to example plugins, demonstrating new functionalities and corrections.

### Method
N/A (Documentation of changes)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

**Example Updates:**
- **Vonk.Plugin.ExampleOperation:**
  - Added an example showcasing middleware interaction with `HttpContext` in `VonkPluginMiddleware.cs`.
  - Resolved an issue where `CapabilityStatementBuilder` was not being called.
- **Vonk.Plugin.DocumentOperation:**
  - Corrected the logic for determining the Composition ID when using POST.
```

--------------------------------

### Document Plugin Examples

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/releasenotes/releasenotes_v3

Examples and issues related to the Document plugin operation.

```APIDOC
## Document Plugin Examples

### Description
This section provides examples and addresses specific issues encountered with the Document plugin operation.

### Examples and Issues:

- **Bundle Identifier:** Document Bundle does not contain an identifier (Issue #27).
- **Custom Resources:** Missing unit test for custom resources (Issue #29).
- **Version Upgrade:** Upgraded to Vonk 2.0.0 libraries (not yet 3.0.0-beta1).
```

--------------------------------

### Install Firely Server Ingest CLI

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/connecting_data_sources/firely-server-ingest

Installs the Firely Server Ingest global tool using the .NET Core SDK. Requires .NET Core SDK v8.x or later.

```bash
dotnet tool install --global Firely.Server.Ingest
```

--------------------------------

### Start Firely Server with Kestrel

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/setting_up_firely_server/deployment/reverseproxy/nginx

Command to start the Firely Server application using the .NET Core runtime. Assumes 'dotnet' is in the PATH and 'Vonk.Server.dll' is in the current directory.

```bash
dotnet Vonk.Server.dll
```

--------------------------------

### Install EF Core Tools Package

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/facade/databasemodel

Installs the EF Core tools package, which is required for scaffolding the DbContext and entity classes from an existing database.

```powershell
Install-Package Microsoft.EntityFrameworkCore.Tools
```

--------------------------------

### ExecuteStorePlanCommand Example (STU3)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/connecting_data_sources/pubsub

An example of the ExecuteStorePlanCommand JSON structure used to send batch operations to Firely Server. It includes destination and response addresses, message type, and a message payload with instructions for creating, updating, or deleting resources.

```json
{
        "destinationAddress": "rabbitmq://rabbitmq-host/Firely.Server.Contracts.Messages.V1:ExecuteStorePlanCommand",
        "responseAddress": "rabbitmq://rabbitmq-host/response?temporary=true",
        "faultAddress": null,
        "messageType": [
          "urn:message:Firely.Server.Contracts.Messages.V1:ExecuteStorePlanCommand"
        ],
        "message": {
          "instructions": [
            {
              "itemId": "Patient/1",
              "resource": "{\"resourceType\":\"Patient\",\"id\":\"1\",\"meta\":{\"versionId\":\"1\"},\"name\":[{\"family\":\"Smith\"}] }",
              "resourceType": null,
              "resourceId": null,
              "currentVersion": null,
              "operation": "create"
            }
          ]
        },
        "headers": {
          "MT-Request-AcceptType": [
            "urn:message:Firely.Server.Contracts.Messages.V1:ExecuteStorePlanResponse"
          ],
          "fhir-release": "STU3"
        }
      }
```

--------------------------------

### Install Vonk.Facade.Relational NuGet Package

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/facade/enablesearch_1

Installs the Vonk.Facade.Relational NuGet package using the Package Manager Console. This package provides a basis for using Entity Framework with Firely Server for relational database interactions.

```csharp
Install-Package Vonk.Facade.Relational
```

--------------------------------

### GET /Patient?example=<value>

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/features_and_tools/customsearchparameters

Verify the functionality of a newly added SearchParameter by performing a search query using the parameter. This example shows a GET request to search for Patients using a custom 'example' SearchParameter.

```APIDOC
## GET /Patient?example=<value>

### Description
Verifies a custom SearchParameter by performing a search query on the Patient resource.

### Method
GET

### Endpoint
http(s)://<firely-server-endpoint>/Patient

### Parameters
#### Query Parameters
- **example** (string) - Required - The value to search for using the custom 'example' SearchParameter.

### Request Example
```bash
GET http(s)://<firely-server-endpoint>/Patient?example=<value>
```

### Response
#### Success Response (200)
- **(FHIR Bundle containing matching Patient resources)**

#### Response Example
(No example provided in source text)
```

--------------------------------

### Patient $everything Operation - Example GET Request

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/features_and_tools/custom_operations/patienteverything

Demonstrates a GET request to the Patient $everything operation, specifying resource types and a since date. This example fetches Patient and Observation resources updated after January 1st, 2021, in FHIR JSON format.

```http
GET <base-url>/Patient/1/$everything?_type=Patient,Observation&_since=2021-01-01
Accept: application/fhir+json
```

--------------------------------

### Patient Query Examples

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/performance/performance_firely_server

Examples of various GET requests to query Patient resources, demonstrating filtering and inclusion of related resources.

```APIDOC
## GET /Patient

### Description
Queries Patient resources by name.

### Method
GET

### Endpoint
/Patient?name=...

### Parameters
#### Query Parameters
- **name** (string) - Required - The name to search for.

### Request Example
```json
{
  "example": "GET {url}/Patient?name=..."
}
```

### Response
#### Success Response (200)
- **Bundle** (object) - A FHIR Bundle resource containing matching Patient resources.

### Response Example
```json
{
  "example": "[FHIR Bundle Response]"
}
```

## GET /Patient

### Description
Queries Patient resources by name and maximum birthdate.

### Method
GET

### Endpoint
/Patient?name={name}&birthdate=ge{year}

### Parameters
#### Query Parameters
- **name** (string) - Required - The name to search for.
- **birthdate** (string) - Required - The minimum birthdate (inclusive), formatted as 'geYYYY'.

### Request Example
```json
{
  "example": "GET {url}/Patient?name={name}&birthdate=ge{year}"
}
```

### Response
#### Success Response (200)
- **Bundle** (object) - A FHIR Bundle resource containing matching Patient resources.

### Response Example
```json
{
  "example": "[FHIR Bundle Response]"
}
```

## GET /Condition

### Description
Retrieves all Condition resources.

### Method
GET

### Endpoint
/Condition

### Response
#### Success Response (200)
- **Bundle** (object) - A FHIR Bundle resource containing all Condition resources.

### Response Example
```json
{
  "example": "[FHIR Bundle Response]"
}
```

## GET /Patient/{id}

### Description
Queries a Patient resource by identifier, including associated Observations.

### Method
GET

### Endpoint
/Patient?identifier={some identifier}&_revinclude=Observation:subject

### Parameters
#### Query Parameters
- **identifier** (string) - Required - The identifier of the Patient to search for.
- **_revinclude** (string) - Optional - Specifies to include related resources, 'Observation:subject' to include Observations linked to the patient.

### Request Example
```json
{
  "example": "GET {url}/Patient?identifier={some identifier}&_revinclude=Observation:subject"
}
```

### Response
#### Success Response (200)
- **Bundle** (object) - A FHIR Bundle resource containing the Patient and their Observations.

### Response Example
```json
{
  "example": "[FHIR Bundle Response with Patient and Observations]"
}
```

## GET /Patient/{id}

### Description
Queries a Patient resource by identifier, including associated Observations and DiagnosticReports.

### Method
GET

### Endpoint
/Patient?identifier={some identifier}&_revinclude=Observation:subject&_revinclude=DiagnosticReport:patient

### Parameters
#### Query Parameters
- **identifier** (string) - Required - The identifier of the Patient to search for.
- **_revinclude** (string) - Optional - Specifies to include related resources, 'Observation:subject' for Observations and 'DiagnosticReport:patient' for Diagnostic Reports linked to the patient.

### Request Example
```json
{
  "example": "GET {url}/Patient?identifier={some identifier}&_revinclude=Observation:subject&_revinclude=DiagnosticReport:patient"
}
```

### Response
#### Success Response (200)
- **Bundle** (object) - A FHIR Bundle resource containing the Patient, their Observations, and Diagnostic Reports.

### Response Example
```json
{
  "example": "[FHIR Bundle Response with Patient, Observations, and Diagnostic Reports]"
}
```
```

--------------------------------

### ExecuteStorePlanCommand Example (R4)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/connecting_data_sources/pubsub

An example JSON payload for the ExecuteStorePlanCommand, demonstrating instructions for resource operations with FHIR R4 specification. It specifies the FHIR release, response address, and details for each instruction like itemId, resource, resourceType, resourceId, currentVersion, and operation.

```json
{
      "messageType": [
        "urn:message:Firely.Server.Contracts.Messages.V1:ExecuteStorePlanCommand"
      ],
      "headers": {
        "fhir-release": "R4"
      },
      "responseAddress": "rabbitmq://rabbitmq-host/response-exchange?temporary=true",
      "message": {
        "instructions": [
            {
              "itemId": "example-operation",
              "resource": "{\"resourceType\":\"Patient\",\"id\":\"testid\",\"meta\":{\"versionId\":\"test\",\"lastUpdated\":\"2023-10-09T12:00:22.8990506+02:00\"},\"name\":[{\"family\":\"id=test\"}]}",
              "resourceType": "Patient",
              "resourceId": "testid",
              "currentVersion": "test",
              "operation": "create"
          }
        ]
      },
      ...
    }
```

--------------------------------

### Example CapabilityStatement Contributor

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/reference/programming_api/capabilities

Demonstrates the usage of ICapabilityStatementBuilder within an ICapabilityStatementContributor. This example showcases how to configure capability statements, rest components, and resource components, including adding operations and search parameters.

```csharp
public class ExampleCapabilityStatementContributor : ICapabilityStatementContributor
{
    public void ContributeToCapabilityStatement(ICapabilityStatementBuilder builder)
    {
        builder.UseCapabilityStatementEditor(cs => {
            cs.Name = "ComprehensiveCapabilityStatement";
            cs.Version = "2.0.0";
            cs.AddFormats("xml", "json");
        });

        builder.UseRestComponentEditor(rc => {
            rc.AddInteraction(CapabilityStatementSystemRestfulInteraction.Transaction);
            rc.AddOperation("batch", "http://hl7.org/fhir/OperationDefinition/Resource-batch");
        });

        builder.UseResourceComponentEditor(rc => {
            if (rc.TypeLiteral == "Observation") {
                rc.AddReadInteraction();
                rc.AddSearchParameter("code", SearchParamType.Token, "http://hl7.org/fhir/SearchParameter/Observation-code", "Search by observation code");
            }
            if (rc.TypeLiteral == "Patient") {
                rce.AddOperation("member-match", "http://hl7.org/fhir/us/davinci-hrex/OperationDefinition/member-match");
            }
        });
    }
}
```

--------------------------------

### Example GET Request with SMART Scope

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/features_and_tools/bulkdataexport

Demonstrates how to use SMART on FHIR scopes to filter export results by resource type. This example requests only Patient resources.

```http
GET {{BASE_URL}}/Patient/$export
```

--------------------------------

### Conformance Resource Loading

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/releasenotes/releasenotes_v2

Details the updated approach to loading conformance resources from zip files and directories at startup.

```APIDOC
## Conformance Resource Loading

### Description
This section explains the changes in how conformance resources are loaded from zip files and/or directories at startup in version 0.6.5.0. They are now added to the Administration API's database instead of being loaded only in memory.

### Impact:
* A delay may be observed on the first startup as Vonk loads these resources into the database.
* Imported files are no longer moved to the `:ref:`AdministrationOptions.ImportedDirectory<conformance_import>`.
```

--------------------------------

### Example $versions Operation Request and Response

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/features_and_tools/custom_operations/versions

This example demonstrates how to make a GET request to the $versions operation and the expected JSON response format, which includes a list of FHIR versions and the default version.

```http
GET <base-url>/$versions
Accept: application/fhir+json
```

```json
{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "version",
            "valueString": "3.0"
        },
        {
            "name": "version",
            "valueString": "4.0"
        },
        {
            "name": "version",
            "valueString": "5.0"
        },
        {
            "name": "default",
            "valueString": "4.0"
        }
    ]
}
```

--------------------------------

### Firely Server $versions Operation Request Example

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/features_and_tools/custom_operations/versions

An example HTTP GET request to the $versions endpoint of Firely Server. It specifies the Accept header to request the response in FHIR JSON format.

```http
GET <base-url>/$versions
Accept: application/fhir+json
```

--------------------------------

### Starting Firely Auth Server (PowerShell)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/security/firely-auth/firely-auth-tutorial

Command to execute the Firely Auth Core application. This command assumes the executable is in the current directory or a defined path.

```powershell
> ./Firely.Auth.Core.exe
```

--------------------------------

### Configure Administration Import Options

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/setting_up_firely_server/appsettings_reference

Sets up the directory for importing conformance resources and defines Simplifier projects for automated resource import and simplification.

```APIDOC
## PUT /config/admin-import

### Description
Configures the administration import process, specifying directories for new and processed conformance resources, and defining external Simplifier projects to import resources from.

### Method
PUT

### Endpoint
/config/admin-import

### Parameters
#### Request Body
- **ImportDirectory** (string) - Required - The path to the directory where new conformance resources are placed for import.
- **ImportedDirectory** (string) - Required - The path to the directory where imported conformance resources are moved.
- **SimplifierProjects** (array of objects) - Optional - A list of projects from Simplifier.net to import resources from.
    - **Uri** (string) - Required - The URI of the Simplifier project.
    - **UserName** (string) - Required - The username for accessing the Simplifier project.
    - **Password** (string) - Required - The password for accessing the Simplifier project.
    - **BatchSize** (integer) - Optional - The batch size for importing resources from this project.

### Request Example
```json
{
  "ImportDirectory": "./vonk-import",
  "ImportedDirectory": "./vonk-imported",
  "SimplifierProjects": [
    {
      "Uri": "https://stu3.simplifier.net/<your-project>",
      "UserName": "Simplifier user name",
      "Password": "Password for the above user name",
      "BatchSize": 20
    }
  ]
}
```

### Response
#### Success Response (200)
Returns the updated administration import configuration.

#### Response Example
```json
{
  "ImportDirectory": "./vonk-import",
  "ImportedDirectory": "./vonk-imported",
  "SimplifierProjects": [
    {
      "Uri": "https://stu3.simplifier.net/<your-project>",
      "UserName": "Simplifier user name",
      "Password": "Password for the above user name",
      "BatchSize": 20
    }
  ]
}
```
```

--------------------------------

### Initiate Real World Testing via HTTP GET

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/features_and_tools/realworldtesting

Example of initiating a Real World Testing operation using an HTTP GET request to the Firely Server administration endpoint. It includes parameters for the Library URL and time range.

```http
GET {{BASE_URL}}/administration/$realworldtesting?url=https://fire.ly/fhir/Library/rwt-all-requests&from=2024-03-18T14:34:16.772Z&to=2024-03-18T14:34:52.453Z
```

--------------------------------

### Endpoint Version Mapping Example

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/maintenance/multiversion

Provides examples of HTTP GET requests to different endpoints and how they map to specific FHIR versions based on the configured 'Path' mode in the InformationModel. It shows equivalent calls with and without explicit versioning in the URL.

```http
GET http://myserver.org/Patient
Accept=application/fhir+json; fhirVersion=3.0

is equivalent to

GET http://myserver.org/R3/Patient
```

```http
GET http://myserver.org/Patient (defaults to R4)

is equivalent to

GET http://myserver.org/R4/Patient
```

```http
GET http://myserver.org/administration/StructureDefinition (defaults to R4)

is equivalent to

GET http://myserver.org/administration/R4/StructureDefinition (/R4 is a postfix to '/administration')
```

--------------------------------

### Feature: Log configuration at startup

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/releasenotes/releasenotes_v2

Vonk now logs its configuration details at startup, providing visibility into the server's setup.

```APIDOC
## Server Startup Logging

### Description
Logs the server's configuration upon startup for easier debugging and verification.

### Details
- At the time of startup, Vonk will log its current configuration settings.
- This log output can be directed to a file or the console, aiding in troubleshooting and understanding the server's operational environment.

### Example (Log Output Snippet)
```
INFO: Configuration loaded:
{
  "ServerOptions": {
    "Port": 8080,
    "BasePath": "/fhir"
  },
  "Database": {
    "Type": "SQLite"
  }
}
```
```

--------------------------------

### Get Recent Laboratory Observations

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/features_and_tools/custom_operations/lastn

Retrieves a list of the most recent laboratory observations for a given patient. This example shows how to fetch a specific count of observations.

```JavaScript
GET <base-url>/Observation/$lastn?patient=examplePatient&category=laboratory&_count=36&_skip=0
Accept: application/fhir+json
```

--------------------------------

### Load Conformance Resources from Simplifier.net Configuration

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/releasenotes/releasenotes_v2

Configuration section for loading conformance resources. The `ArtifactResolutionOptions` has been updated to `ResourceLoaderOptions`, with a new `LoadAtStartup` option to attempt loading resource sets on Vonk startup.

```json
{
  "ResourceLoaderOptions": {
    "LoadAtStartup": true
  }
}
```

--------------------------------

### Implementing the Search Method

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/facade/enablesearch_2

Overrides the abstract Search method from SearchRepository. This method dispatches the search request to specific handlers based on the resourceType, starting with 'Patient'.

```csharp
protected override async Task<SearchResult> Search(string resourceType, IArgumentCollection arguments, SearchOptions options)
{
    switch (resourceType)
    {
        case "Patient":
            return await SearchPatient(arguments, options);
        default:
            throw new NotImplementedException($"ResourceType {resourceType} is not supported.");
    }
}

```

--------------------------------

### FSI Configuration Example (appsettings.instance.json)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/connecting_data_sources/firely-server-ingest

This JSON snippet provides a template for the appsettings.instance.json file, used to configure Firely Server Ingest. It includes settings for licensing, import parameters, data sources (Filesystem, MongoDB), target databases (SQL Server, MongoDB, PubSub), and telemetry. Users should update values and remove unnecessary records.

```JavaScript
{
    // General
    "license": "C:\\data\\deploy\\vonk\\license\\performance-test-license.json",

    // Import settings
    "limit": -1,
    "fhirVersion": "R4",
    "updateExistingResources": true,
    "haltOnError": false,
    "recoveryJournalDirectory": null,

    "absoluteUrlConversion": {
        "baseEndpoints": [
            // "http://localhost:4080/R4"
        ],
        "elements": [
            "DocumentReference.content.attachment.url"
        ]
    },

    "workflow": {
        "readBufferSize": 750,
        "metaParallel": 1,
        "metaBufferSize": 50,
        "typeParallel": 4,
        "typeBufferSize": 50,
        "absoluteToRelativeParallel": 1,
        "absoluteToRelativeBufferSize": 50,
        "indexParallel": -1, 
        "indexBufferSize": 50
    },

    // Source
    "sourceType": "Filesystem", 
    "source": "./fsi-source", 
    "mongoDbSource": {
        "connectionString": "<connectionstring to the Firely Server MongoDb source database>",
        "collectionName": "vonkentries",
        "runningMode": "AdHoc",
        "documentFilterBson": "{ }" 
    },

    // Target
    "provisionTargetDatabase": false,
    "databaseType": "SQL", 

    "sqlserver": {
        "connectionString": "<connectionstring to the Firely Server SQL Server database>",
        "saveParallel": 2,
        "queryExistenceParallel": 4,
        "batchSize": 500,
        "commandTimeOut": 60 
    },

    "mongodb": {
        "entryCollection": "vonkentries",
        "connectionString": "<connectionstring to the Firely Server MongoDb database>",
        "saveParallel": 2,
        "queryExistenceParallel": 4,
        "batchSize": 500
    },

    "PubSub": {
      "batchSize": 1,
      "MessageBroker": {
          "Host": "<connectionstring to the pubsub endpoint>",
          "Username": "guest",
          "Password": "guest",
          "ApplicationQueueName": "FirelyServer",
          "PrefetchCount": 1,
          "ConcurrencyNumber": 1,
          "RabbitMQ": {
              "Port": 5672
          },
          "VirtualHost": "/",
          "BrokerType": "AzureServiceBus" 
      },
      "ClaimCheck": {
          "StorageType": "Disabled", 
          "AzureBlobContainerName": "messages-data",
          "AzureBlobStorageConnectionString": "<connection string>"
      }
    },

    // Telemetry
    "OpenTelemetryOptions": {
        "EnableMetrics": false,
    }
}
```

--------------------------------

### Search with Chaining

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/security/tokens_and_compartments

Example of a GET request using chaining to search for Patients based on their general practitioner's identifier. This demonstrates filtering patients through a chained reference.

```http
GET [base]/Patient?general-practitioner.identifier=123
```

--------------------------------

### Run Firely Server using .NET Core CLI

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/getting_started/basic_installation

This command executes the Firely Server application using the .NET Core CLI. It requires the .NET Core Runtime to be installed and assumes the command is run from the server's working directory.

```bash
> dotnet .\Firely.Server.dll

```

--------------------------------

### Direct Search on Compartment Type

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/security/tokens_and_compartments

Example of a direct GET request to search for Patients by name. It also illustrates how the Patient Compartment filter (e.g., identifier=123) is appended to the search query.

```http
GET [base]/Patient?name=fred
// With active Patient Compartment: GET [base]/Patient?name=fred&identifier=123
```

--------------------------------

### Search on Related Type with Compartment

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/security/tokens_and_compartments

Example of a GET request to search for Observations by code. It shows how links to the Patient resource within the Observation are used to apply the active Patient Compartment filter.

```http
GET [base]/Observation?code=x89
// With active Patient Compartment: GET [base]/Observation?code=x89& (subject:Patient.identifier=123 OR performer:Patient.identifier=123)
```

--------------------------------

### Administration Import Configuration

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/setting_up_firely_server/appsettings_reference

Sets up options for importing conformance resources like SearchParameters. It specifies the directories for import and processing, and can define Simplifier projects for batch import.

```json
{
  "AdministrationImportOptions": {
    "ImportDirectory": "./vonk-import",
    "ImportedDirectory": "./vonk-imported", 
    "SimplifierProjects": [
      {
        "Uri": "https://stu3.simplifier.net/<your-project>",
        "UserName": "Simplifier user name",
        "Password": "Password for the above user name",
        "BatchSize": 20
      }
    ]
  }
}
```

--------------------------------

### OpenTelemetry Collector Configuration for Firely Server

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/features_and_tools/realworldtesting

Example configuration for an OpenTelemetry collector to receive traces from Firely Server, filter health checks, and export to Telegraf. This setup facilitates metrics processing.

```yaml
receivers:
    otlp:
      protocols:
        grpc:
    ...

exporters:
    otlp/telegraf:
      endpoint: http://telegraf.influxdb.svc.cluster.local:4311
      tls:
        insecure: true

processors:
    batch: {}
    filter/health: #https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/filterprocessor
      error_mode: ignore
      traces:
        span:
          - 'attributes["url.path"] == "/$$liveness"'
          - 'attributes["url.path"] == "/$$readiness"'
        filter/health: #https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/filterprocessor
      error_mode: ignore
      traces:
        span:
          - 'attributes["url.path"] == "/$$liveness"'
          - 'attributes["url.path"] == "/$$readiness"'
    filter/requestmeter:
      spans:
        include:
          match_type: strict
          attributes:
            - key: "scope"
              value: "request"

service:
    pipelines:
      traces/requestmeter:
        receivers: [otlp]
        exporters: [otlp/telegraf]
        processors: [filter/health, filter/requestmeter, batch]
      ...

```

--------------------------------

### Run Firely Server using .NET CLI

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/getting_started/basic_installation

This command executes the Firely Server application using the .NET CLI. It assumes you are in the working directory where the Firely.Server.dll is located.

```bash
dotnet .\Firely.Server.dll
```

--------------------------------

### Search with Include Outside Compartment

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/security/tokens_and_compartments

Example of a GET request searching for Patients and including their associated organizations. It highlights that read access to both Patient and Organization is required, and the compartment filter is applied to the Patient part of the query.

```http
GET [base]/Patient?_include=Patient:organization
// With active Patient Compartment: Applied as in case 1.a.
```

--------------------------------

### New Configuration Structure for Operations (JSON)

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/setting_up_firely_server/appsettings_reference

Illustrates the new top-level 'Operations' section for organizing operation configurations by name, including example settings for different operations.

```json
{
  "Operations": {
    "$closure": {
      "Name": "$closure",
      "Level": [
        "System"
      ],
      "Enabled": true,
      "RequireAuthorization": "WhenAuthEnabled",
      "RequireTenant": "Never"
    },
    "capabilities": {
      "Name": "capabilities",
      "Level": [
        "System"
      ],
      "Enabled": true,
      "RequireAuthorization": "Never",
      "RequireTenant": "Never"
    },
    "create": {
      "Name": "create",
      "Level": [
        "Type"
      ],
      "Enabled": true,
      "RequireAuthorization": "WhenAuthEnabled",
      "RequireTenant": "WhenTenancyEnabled"
    }
  }
}
```

--------------------------------

### Repository Options

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/setting_up_firely_server/appsettings_reference

Details on configuring different repository types for Firely Server.

```APIDOC
## Repository Options

### Description
Provides details on configuring the storage repository for Firely Server, including options for Memory, MongoDB, SQL Server, and SQLite.

### Endpoint
Not applicable (Configuration settings)

### Parameters
#### Repository Type
- **Repository** (string) - Required - Specifies the type of repository. Valid values: "Memory", "SQL", "SQLite", "MongoDb".

#### Memory Options
- **SimulateTransactions** (string) - Optional - Controls transaction simulation for in-memory storage.

#### MongoDB Options
- **ConnectionString** (string) - Required - MongoDB connection string.
- **EntryCollection** (string) - Required - Name of the MongoDB collection for entries.
- **MaxLogLine** (integer) - Optional - Maximum number of log lines to store.

#### SQL Server Options
- **ConnectionString** (string) - Required - SQL Server connection string.
- **AutoUpdateDatabase** (boolean) - Optional - Whether to automatically update the database schema.
- **MigrationTimeout** (integer) - Optional - Timeout for database migrations in seconds.
- **LogSqlQueryParameterValues** (boolean) - Optional - Whether to log SQL query parameter values.
- **AutoUpdateConnectionString** (string) - Optional - Connection string for database schema updates.

#### SQLite Options
- **ConnectionString** (string) - Required - SQLite connection string.
- **AutoUpdateDatabase** (boolean) - Optional - Whether to automatically update the database schema.
- **MigrationTimeout** (integer) - Optional - Timeout for database migrations in seconds.
- **LogSqlQueryParameterValues** (boolean) - Optional - Whether to log SQL query parameter values.
- **AutoUpdateConnectionString** (string) - Optional - Connection string for database schema updates.

### Request Example (MongoDB)
```json
{
  "Repository": "MongoDB",
  "MongoDbOptions": {
    "ConnectionString": "mongodb://localhost/vonkdata",
    "EntryCollection": "vonkentries",
    "MaxLogLine": 300
  }
}
```

### Request Example (SQLite)
```json
{
  "Repository": "SQLite",
  "SQLiteDbOptions": {
    "ConnectionString": "Data Source=./data/vonkdata.db;Cache=Shared",
    "AutoUpdateDatabase": true,
    "MigrationTimeout": 1800,
    "LogSqlQueryParameterValues": false
  }
}
```

### Response
This section describes configuration, not an API response.
```

--------------------------------

### Preventing IIS Idle Shutdowns for Firely Server

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/setting_up_firely_server/deployment/reverseproxy/iis

This guide explains how to prevent IIS from shutting down the Firely Server application when it's idle. It involves two key settings: setting the 'Start Mode' to 'AlwaysRunning' and 'Preload Enabled' to 'True' to ensure the server is always available and loads immediately.

```text
Set **Start Mode** to **AlwaysRunning**
```

```text
Set **Preload Enabled** to **True**
```

--------------------------------

### Fix for Warning on LoadAtStartup

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/releasenotes/releasenotes_v2

Resolves a warning message 'WRN No server base configured, skipping resource loading.' that appeared when `LoadAtStartup` was specified in `ResourceLoaderOptions` without a server base configured. This prevents misleading warnings.

```json
{
  "Vonk": {
    "ResourceLoaderOptions": {
      "LoadAtStartup": true
    }
  }
}
```

--------------------------------

### Generate JSON Web Key Set using 'jose' CLI on Ubuntu

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/security/auditing

This example shows how to install the 'jose' package on Ubuntu and then use its command-line interface to generate a JSON Web Key Set (JWKS). The generated key is configured for Elliptic Curve (EC) with P-256 curve, signature usage, and signing/verification operations.

```shell-session
sudo apt install jose -y
```

```shell-session
jose jwk gen -i '{"kty":"EC","crv":"P-256","use":"sig","key_ops":["sign","verify"],"alg":"ES256","kid":"yourkeyid"}' -s -o ec.jwk
```

--------------------------------

### Loading ValueSet and CodeSystem Resources

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/releasenotes/releasenotes_v2

Allows `ValueSet` and `CodeSystem` resources to be loaded into the administration endpoint and imported from Simplifier. This expands the support for FHIR conformance resources.

```text
ValueSet and CodeSystem resources can be loaded into the administration endpoint, and loaded from Simplifier.
```

--------------------------------

### Batch Request for Test Data

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/_sources/security/firely-auth/firely-auth-tutorial

Issue a batch request to add example resources for testing purposes. This should be done before enabling authorization.

```APIDOC
## POST /R4/

### Description
Sends a batch of resources (e.g., Patient, Observation) to the server for testing.

### Method
POST

### Endpoint
/R4/

### Request Body
- **resourceType** (string) - Required - Specifies the resource type within the bundle (e.g., 'Bundle').
- **type** (string) - Required - Specifies the bundle type (e.g., 'batch').
- **entry** (array) - Required - An array of entry objects, each containing a request and a resource.
  - **request** (object) - Required - Contains the HTTP method and URL for the entry.
    - **method** (string) - Required - HTTP method (e.g., 'POST').
    - **url** (string) - Required - FHIR resource URL (e.g., 'Patient').
  - **resource** (object) - Required - The FHIR resource to be included in the batch.

### Request Example
```json
{
  "resourceType": "Bundle",
  "type": "batch",
  "entry": [
    {
      "request": {
        "method": "POST",
        "url": "Patient"
      },
      "resource": {
        "resourceType": "Patient",
        "id": "patient1",
        "name": [
          {
            "family": "Smith",
            "given": ["John"]
          }
        ]
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **resourceType** (string) - The resource type (e.g., 'Bundle').
- **type** (string) - The bundle type (e.g., 'batch').
- **entry** (array) - An array of entry responses, corresponding to the request entries.
  - **response** (object) - Details of the response for each entry.
    - **status** (string) - HTTP status code (e.g., '201 Created').
    - **location** (string) - The URL of the created resource.

#### Response Example
```json
{
  "resourceType": "Bundle",
  "type": "batch",
  "entry": [
    {
      "response": {
        "status": "201 Created",
        "location": "http://localhost:4080/R4/Patient/patient1"
      }
    }
  ]
}
```
```

--------------------------------

### Administration Import Options

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/setting_up_firely_server/appsettings_reference

Configuration for importing SearchParameters and other Conformance Resources, including directories and remote simplifier projects.

```APIDOC
## SearchParameters and other Conformance Resources

### Description
This configuration specifies how Firely Server imports FHIR Conformance Resources, such as SearchParameters and StructureDefinitions. It defines local directories for import and a list of remote Simplifier projects to pull definitions from.

### Method
N/A (Configuration File)

### Endpoint
N/A (Configuration File)

### Parameters
#### Request Body (Configuration Structure)
- **AdministrationImportOptions** (object) - Options for importing conformance resources.
  - **ImportDirectory** (string) - The local directory to scan for conformance resources to import.
  - **ImportedDirectory** (string) - The directory where imported resources are placed. Ensure this is not a subdirectory of `ImportDirectory` to avoid recursive reading.
  - **SimplifierProjects** (array of objects) - A list of remote Simplifier projects to import from.
    - **Uri** (string) - The URI of the Simplifier project.
    - **UserName** (string) - The username for authenticating with the Simplifier project.
    - **Password** (string) - The password for authenticating with the Simplifier project.
    - **BatchSize** (integer) - The number of resources to fetch per batch from the Simplifier project.

### Request Example
```json
{
  "AdministrationImportOptions": {
    "ImportDirectory": "./vonk-import",
    "ImportedDirectory": "./vonk-imported",
    "SimplifierProjects": [
      {
        "Uri": "https://stu3.simplifier.net/<your-project>",
        "UserName": "Simplifier user name",
        "Password": "Password for the above user name",
        "BatchSize": 20
      }
    ]
  }
}
```
```

--------------------------------

### Configure License File in appsettings.json

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/getting_started/basic_installation

This JSON snippet shows how to specify the license file path within the Firely Server's application settings. It's used to configure the server with a valid license for operation.

```json
{
  "License": {
        "LicenseFile": "firelyserver-trial-license.json"
  }
}

```