Firely Server

https://docs.fire.ly/projects/Firely-Server/en/latest/
Admin
Firely Server is Firely’s FHIR server, providing a stable and certified FHIR API for immediate use...
Tokens:795,512
Snippets:5,720
Trust Score:9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Initiate Real World Testing via GET

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

Example of initiating a Real World Testing operation using an HTTP GET request with query parameters.

```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 HTTP/1.1
```

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

### Start Firely Server from console (dotnet ./Vonk.Server.dll)

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

Command to start Firely Server from the new installation directory after upgrading the binary distribution. Run from the console after stopping the old instance.

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

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

### Start old Firely Server version from console (dotnet .\Vonk.Server.dll)

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

Command to start the previous Firely Server version from the old installation directory when rolling back after a failed upgrade. Use after restoring databases.

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

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

### Start Firely Server container

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

Command to start the firely.server container again.

```bash
docker start firely.server
```

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

### Example operation configuration JSON

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

Example configuration for new operation structure. Shows how to configure core operations like capabilities, create, and $validate with properties like Level, Enabled, RequireAuthorization, RequireTenant, and OperationScope. Also includes administration operations ($reindex, $reset) with NetworkProtected.

```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"
        },
        "$validate": {
          "Name": "$validate",
          "Level": ["System", "Type", "Instance"],
          "Enabled": true,
          "RequireAuthorization": "WhenAuthEnabled",
          "RequireTenant": "WhenTenancyEnabled",
          "OperationScope": "validation"
        }
      },
      "Administration": {
        "AllowedNetworks": ["127.0.0.1/32", "::1/128"],
        "Operations": {
          "$reindex": {
            "Name": "$reindex",
            "Level": ["System"],
            "Enabled": true,
            "NetworkProtected": true
          },
          "$reset": {
            "Name": "$reset",
            "Level": ["System"],
            "Enabled": true,
            "NetworkProtected": true
          }
        }
      }
    }
  }
```

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

### Example request logs for Patient POST

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

Example log output when posting a Patient resource with the Microsoft.AspNetCore.Hosting.Diagnostics override set to Information. Shows request start and finish lines with status code 201 and duration.

```text
2023-08-09 10:25:55.028 +02:00 [UserId: ] [Username: ] [Information] [ReqId: 0HMSOM901IS1A:00000002] Request starting HTTP/1.1 POST http://localhost:4080/Patient application/fhir+json 164
2023-08-09 10:25:57.225 +02:00 [UserId: ] [Username: ] [Information] [ReqId: 0HMSOM901IS1A:00000002] Request finished HTTP/1.1 POST http://localhost:4080/Patient application/fhir+json 164 - 201 340 application/fhir+json;+fhirVersion=4.0;+charset=utf-8 2199.2748ms
```

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

### Administration Repository Configuration

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

Example of the Administration section in appsettings.json for configuring SQL database options.

```json
"Administration": {
        "Repository": "SQLite", //SQL / MongoDb
        "SqlDbOptions": {
            "ConnectionString": "connectionstring to your Firely Server Admin SQL Server database (SQL2012 or newer); Set MultipleActiveResultSets=True",
            "SchemaName": "vonkadmin",
            "AutoUpdateDatabase": true,
            "MigrationTimeout": 1800 // in seconds
            //"AutoUpdateConnectionString" : "set this to the same database as 'ConnectionString' but with credentials that can alter the database. If not set, defaults to the value of 'ConnectionString'"
        },
```

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

### GET /Observation/$lastn

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

Fetches the last N results for all vitals for a patient. The example uses max=3, patient=examplePatient, and category=vital-signs.

```APIDOC
## GET /Observation/$lastn

### Description
Fetches the last N results for all vitals for a patient. The example uses max=3, patient=examplePatient, and category=vital-signs.

### Method
GET

### Endpoint
<base-url>/Observation/$lastn

### Parameters
#### Query Parameters
- **max** (integer) - Required - The maximum number of results to return per code.
- **patient** (string) - Required - The patient ID.
- **category** (string) - Required - The category of observations to filter by.

### Request Example
GET <base-url>/Observation/$lastn?max=3&patient=examplePatient&category=vital-signs
Accept: application/fhir+json

### Response
#### Success Response (200)
- **resourceType** (string) - The resource type, always "Bundle".
- **type** (string) - The bundle type, always "searchset".
- **timestamp** (string) - The timestamp of the response.
- **meta** (object) - Metadata including lastUpdated and versionId.
- **entry** (array) - Array of entries, each containing fullUrl, search mode, and resource.
- **total** (integer) - Total number of entries.
- **link** (array) - Array of links, including self link.
- **id** (string) - The bundle ID.

#### Response Example
{
  "resourceType": "Bundle",
  "type": "searchset",
  "timestamp": "2021-09-14T11:52:58.450+04:00",
  "meta": {
    "lastUpdated": "2021-09-14T11:52:58.450+04:00",
    "versionId": "8f3c6c0a-37d7-4fde-b80b-57e72e655fe7"
  },
  "entry": [
    {
      "fullUrl": "<base-url>/Observation/bac874a3-8d89-bd0c-9157-f2fb153d6642",
      "search": {
        "mode": "match"
      },
      "resource": {
        "resourceType": "Observation",
        "id": "bac874a3-8d89-bd0c-9157-f2fb153d6642",
        "status": "final",
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                "code": "vital-signs",
                "display": "vital-signs"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "2708-6",
              "display": "Oxygen saturation in Arterial blood"
            },
            {
              "system": "http://loinc.org",
              "code": "59408-5",
              "display": "Oxygen saturation in Arterial blood by Pulse oximetry"
            }
          ],
          "text": "Oxygen saturation in Arterial blood"
        },
        "subject": {
          "reference": "<base-url>/Patient/examplePatient"
        },
        "effectiveDateTime": "2020-03-03T01:58:48+04:00"
      }
    }
  ],
  "total": 23,
  "link": [
    {
      "relation": "self",
      "url": "<base-url>/Observation/$lastn?max=3&patient=examplePatient&category=vital-signs&_count=23&_skip=0"
    }
  ],
  "id": "6d6571c3-e6e0-461e-803f-c044c442191c"
}
```

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

### Run FSI migration command (Bash and PowerShell)

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

Initialize the FSI migration process for the main database. Requires a license file with the token http://fire.ly/vonk/plugins/migration and access credentials for both source and target MongoDB instances. Use Continuous mode for zero-downtime migration; AdHoc mode terminates after processing all items. Migration completion is indicated by the message 'No new items found in the database. Waiting for 00:00:05 before retrying...'.

```bash
RECOVERY_JOURNAL_DIRECTORY=./journal # A directory where the progress will be stored in case of a crash. FSI will quickly catch up to the place where an error occurred.
FHIR_VERSION=R4

LICENSE_FILE="<path to your license file>"

RUNNING_MODE=Continuous # Or AdHoc. If AdHoc mode is used, FSI will terminate when all the items from the old DB have been processed.

SOURCE_CONNECTION_STRING="<old db connection string including the database name>"
SOURCE_COLLECTION_NAME=vonkentries

CONNECTION_STRING="<new DB connection string including the database name>"
COLLECTION_NAME=vonkentries

fsi \
   --fhir-version $FHIR_VERSION \
   --provisionTargetDatabase true \
   --useRecoveryJournal $RECOVERY_JOURNAL_DIRECTORY \
   --sourceType MongoDb \
   --srcMongoCollection $SOURCE_COLLECTION_NAME \
   --srcMongoConnectionString $SOURCE_CONNECTION_STRING \
   --srcMongoRunningMode $RUNNING_MODE \
   --update-existing-resources OnlyIfNewer \
   --dbType MongoDb \
   --mongoConnectionstring $CONNECTION_STRING \
   --mongoCollection $COLLECTION_NAME \
   --license $LICENSE_FILE
```

```powershell
$RECOVERY_JOURNAL_DIRECTORY = "./journal" # A directory where the progress will be stored in case of a crash. FSI will quickly catch up to the place where an error occurred.
$FHIR_VERSION = "R4"

$LICENSE_FILE = "<path to your license file>"

$RUNNING_MODE = "Continuous" # Or AdHoc. If AdHoc mode is used, FSI will terminate when all the items from the old DB have been processed.

$SOURCE_CONNECTION_STRING = "<old db connection string including the database name>"
$SOURCE_COLLECTION_NAME = "vonkentries"

$CONNECTION_STRING = "<new DB connection string including the database name>"
$COLLECTION_NAME = "vonkentries"

fsi `
   --fhir-version $FHIR_VERSION `
   --provisionTargetDatabase true `
   --useRecoveryJournal $RECOVERY_JOURNAL_DIRECTORY `
   --sourceType MongoDb `
   --srcMongoCollection $SOURCE_COLLECTION_NAME `
   --srcMongoConnectionString $SOURCE_CONNECTION_STRING `
   --srcMongoRunningMode $RUNNING_MODE `
   --update-existing-resources OnlyIfNewer `
   --dbType MongoDb `
   --mongoConnectionstring $CONNECTION_STRING `
   --mongoCollection $COLLECTION_NAME `
   --license $LICENSE_FILE
```

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

### GET Patient/$export with SMART scope

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/features_data_exchange/bulkdataexport.html

Example request that retrieves only the Patient resource when the access token contains the system/Patient.read scope, as opposed to all resources of the Patient compartment.

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

```

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

### Start Firely Server

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

Command to launch the Firely Server process using the .NET runtime.

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

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

### GET Patient/$export with _type and SMART scope

Source: https://docs.fire.ly/projects/Firely-Server/en/latest/features_data_exchange/bulkdataexport.html

Example request that results in a 403 Forbidden HTTP error code because the system/Patient.read scope does not allow retrieving Observation resources.

```http
GET {{BASE_URL}}/Patient/$export?_type=Patient,Observation

```

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

### Start the dashboard from binaries

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

Executes the dashboard DLL from the extracted binaries folder.

```bash
dotnet .\FirelyServerDashboard.dll
```

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

### GET request for $lastn operation

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

Example HTTP request to invoke the $lastn operation. Requires patient/subject and category parameters; optional max parameter limits results per group.

```http
GET <base-url>/Observation/$lastn
Accept: <any supported FHIR media type>
```

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

### AddInteraction Usage Example

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

Example of adding an interaction to a resource component.

```csharp
resourceComponent.AddInteraction(CapabilityStatementTypeRestfulInteraction.Read);
```

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

### AddOperation Usage Example

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

Example of adding an operation to a resource component.

```csharp
resourceComponent.AddOperation("validate", "http://hl7.org/fhir/OperationDefinition/Resource-validate");
```

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

### Run FSI import targeting MongoDB

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

Same as the previous example but targeting a MongoDB database using --dbType MongoDb and --mongoConnectionstring.

```bash
fsi \
--dbType MongoDb
-s ./path/to/your/input/files \
--license /path/to/your/license/fsi-license.json \
--mongoConnectionstring 'mongodb://username:password@localhost:27017/vonkdata'
```

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

### Import conformance resources with AdministrationImportOptions

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

Imports conformance resources from a local directory and from Simplifier projects. The Uri should be replaced with your actual project URLholidays, and the credentials must be valid. See the documentation on Managing Conformance Resources and Custom Search Parameters for more information.

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

```

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

### AddSearchParameter Usage Example

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

Example of adding a search parameter to a resource component.

```csharp
resourceComponent.AddSearchParameter("name", SearchParamType.String, "http://hl7.org/fhir/SearchParameter/Patient-name", "Search by patient name");
```

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

### Check Docker installation with docker version

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

Run this command in a command line tool to verify Docker is installed and working. The expected output is shown in an image in the source.

```bash
> docker version
```

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

### UseRestComponentEditor example

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

Example of using UseRestComponentEditor to add a system-level interaction (Transaction).

```csharp
builder.UseRestComponentEditor(rc => {
    rc.AddInteraction(CapabilityStatementSystemRestfulInteraction.Transaction);
});
```

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

### Start Firely Server with dotnet

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

Run this command from the working directory to start Firely Server. Requires .NET 10 as of version 6.9.0; older versions need .NET 8 or .NET 6.

```powershell
> dotnet .\Firely.Server.dll
```
Tokens:
Raw