Admin User Manual

The first Login/registration

Once the SORMAS has been installed on the server and is functional, then IT administrators within your organization will receive the administrator credential. These administrator credentials allow you to create further users in SORMAS.

Login and Logout

As soon as you have received your username and initial password from your IT team, you can log in to SORMAS for the first time with your account data (username, password). Your IT team must provide you with the URL(Link) to the SORMAS as well. If you don’t receive the URL(link), Please contact your IT Team. Once you have clicked on the link, You will land on the login page of SORMAS which will look like the image below:

Open

Here you have to write your username and password sent by your IT team. Please keep in mind that the username and password both are case-sensitive. Once you have entered your password correctly you will land on the dashboard of SORMAS.

If you are receiving an error message in the login process which looks like the image below. It shows that you have entered the wrong username and password. If the error message exists despite of multiple attempts, please contact with your IT team.

Open

Once you have successfully logged into SORMAS, you will land on the dashboard view.

Once you have logged in and finished your job in the SORMAS system, you can logout from the system safely. To log out safely, the blue ribbon is located on the left-hand side. In the left blue ribbon, there is a button “Logout” at the end, you will see the user name with which you are logged in Clicking this button immediately logs you out of the program.

User Management (Roles and Rights)

The following standard user roles are available in SORMAS. Various combinations can be used. Standard user roles can be combined in such a way that they complement each other. Roles must have the same hierarchy level and therefore correspond to the same area of responsibility restriction. For this reason, management and authorized representative roles, for example, cannot be combined.

A detailed description of the available standard user roles and the associated rights is listed below. These descriptions are intended to provide SORMAS users with a better overview and reflect the workflows applied in the office.

Admin

You create and manage other users and configurations of the system. Administrators can also view and edit all cases and contacts. However, their authorization to view personal data is limited without further user roles. They can also make deletions and perform imports.

Admin Surveillance Supervisor

This combined role combines some user rights of both roles, but other rights are excluded accordingly. The combined role may view and edit cases and contacts that are located in the assigned federal state. The combined role may save filter configurations for the user-defined export and use the mass processing mode for samples for cases. The combined role is NOT allowed to edit lab messages, create users, or perform imports and follow-ups.

National User

The user who sees all surveillance data (cases, contacts, samples, events, etc.) in the system and can make changes to it. This means that this role has no regional restrictions to their own health authority and that surveillance data from all districts/cities that have been created in their own health authority are also visible to people with this role. However, this user role has no adminis-trative or medical authorizations.

Surveillance Supervisor

The surveillance manager has the right to manage and edit all surveillance data for cases in a region. The surveillance manager only has limited rights to manage contacts.

Surveillance Officer

The Surveillance officer has the right to manage and process all monitoring data of cases in a district or a region. Monitoring officers have limited rights to manage contacts. If the monitoring officer is assigned a facility, his/her rights are further limited to this facility.

Hospital Informant/ Community

Informants can create and process cases and samples as well as view and process tasks. They are bound to their institution or municipality in terms of their authorization. These user roles can use both the SORMAS app and the web version

Community Officer

The Community Officer has extended rights to the hospital/community informant. Community officers may additionally change the location of cases, change the case investigation status, per-form case classification, create and edit pathogen tests, create, view, assign, edit, delete, classi-fy contacts, convert to a case, assign index case, access the external symptom diary, create and edit follow-up calls, create and assign tasks, create and edit actions, create and edit events, cre-ate, edit and import event participants and issue quarantine notices. In addition, municipal rep-resentatives can view all tasks in the respective municipality and assign tasks to employees at the next higher level of responsibility and have access to the statistics section.

Clinician

Clinician can document data on treatments, clinical course, therapy and previous illnesses for cases. With this role, additional tabs (therapy and clinical course) are available in the case file. This role can, for example, be assigned to medical This role can be assigned to specialist staff in a treatment center if SORMAS is used for the clinical management of cases. Otherwise, this role can be linked to other roles to extend user roles/rights. It is limited to one region at a time.

Case Officer

Case officers can create and process cases, samples, test results, treatments and therapies. They are not authorized to handle contacts. Their authorizations are linked to districts/cities.

Contact Supervisor (CS)

Contact supervisors have the right to manage and process all contact details of cases in a dis-trict/city. The contact officer only has limited rights to handle cases. If an institution is assigned to the contact officer, his/her rights are further limited to this institution.

Contact Officer (CO)

The contact line has the right to manage and edit all contact details of cases in an assigned re-gion. The contact line only has limited rights for handling cases.

Event Officer

Event officers can create and edit events and their actions. They can also create and edit event participants, cases, and samples. They can only view contacts, but not edit them. Their rights are limited to an assigned region.

Lab Officer

Laboratory officers manage samples, test results and additional tests in the system. They can also create and process cases. They have no location-specific restrictions, but are tied to specific laboratories. They are not authorized to view sensitive personal data.

External Lab Officer

External laboratory officers can only view and process samples, test results, additional tests and tasks. External laboratories are usually laboratories abroad and therefore the external labora-tory representatives are bound to external laboratories with their rights.

National Observer

National users can see all entities (cases, contacts, events, samples) in the system at national level, but have no editing rights. In addition, these users cannot see any sensitive personal data.

Region Observer

Region observers can see all entities (cases, contacts, events, samples) in the system at region level, but have no editing rights. In addition, users cannot see any sensitive personal data.

District Observer

The district observer can see all entities (cases, contacts, events, samples) in the system at the district/city level but has no editing rights. In addition, these users cannot see any sensitive per-sonal data.

National Clinician

National clinician have in principle the same rights as the user role doctor, but is not regionally restricted.

POE Informant/ POE Supervisor/ POE national user

Point-of-entry informant, point-of-entry Supervisor, and point-of-entry national user are similar to the informant, surveillance officer, and national user roles, but are restricted to points of entry. This role is mainly used at points of entry (airports, ports, etc.).

Creating a new user

The administrator can create new SORMAS users under the "Users" menu item. To do this, the "New user" button must be clicked. As shown in the image below:

Once you have clicked on the “New User” button a form will be opened. When users are created in SORMAS by the administrator, the corresponding personal data of the user is stored (first and last name, e-mail address, and, if applicable, telephone number). It is recommended to store a language. As shown in the image below:

The address of the facility should also be entered and the contact person of that facility as well if available. GPS coordinates should also be filled out if they were not added during the creation of the facility in the infrastructure data. Below is the image.

You can adjust the user status in the User Data section. "Active" users can be assigned tasks, cases, etc otherwise you will not be able to perform any actions. The username is automatically generated from the first 4 letters of the first and last name (first letter capitalized) and can be changed afterward. You can also change the automatically generated username as well by entering the desired username but remember that manually entered username must be unique and should not exist in the system before. So, we recommend keeping the automatically generated username. On the right side of the form, you will see a list of user roles. You can choose the most suitable user role for your user. User roles have been described in the document already. Depending on your chosen user role, maybe you be asked to choose the region, district, and facility as well. Below is the image.

You can also restrict the user to a specific disease as well. In some cases, you want the user to deal with and manage the specific disease. In that situation, you have to checkmark the “Restrict access to specific diseases” checkbox and then you will see the list of all available diseases in the SORMAS system. You can checkmark all the diseases that you want to be managed by this user. If you don’t Restrict access to specific diseases” then the user will have access to all diseases. Please note that all information marked with red “*” is mandatory to fill otherwise you will get an error message. Once all the necessary data has been entered, please click on "Save". You can have a look on the screenshot below for further reference.

SORMAS automatically generates a password that is displayed ONCE and must be provided to the user by you.

If the data of users is to be subsequently adjusted or changed, the following steps must be observed. Start editing existing users by clicking on the edit icon as shown in the image below.

You can now change the user data and select "Create new password" at the bottom of the window. If an e-mail address has been entered, the user will be prompted by e-mail to create a new password. If no e-mail address is entered, SORMAS will automatically generate a password again. Note: this password is also only displayed ONCE.

Custom User Roles

The custom user role function offers health departments the possibility to create and edit user roles with specific user rights and to export them.

Definition of User Roles

A user role includes a set of individual rights in SORMAS and the jurisdiction level (such as 'Region'). User roles are used to avoid having to define individual rights for each user: Instead of assigning the same individual rights directly to many users, a user role is defined that contains the rights to be assigned. The users are then assigned the appropriate role (or multiple roles). This simplifies the rights management in SORMAS, since only the rights of the user role need to be adjusted, especially when the rights structure changes.

Typically, user roles are defined for specific use cases. For this purpose, there is a set of default user roles provided by SORMAS. These can be used as templates for new user roles or can be customized by each health department itself.

Definition of User Rights

User rights ensure that the recorded data is protected against unauthorized access. User rights regulate which data individual users are allowed to read and edit. Most user rights define an action related to an entity type, e.g. the user right CASE_EDIT allows users to edit case data.

User rights are assigned in SORMAS by assigning a user role to a user.

Creating New User Roles

The creation of new user roles is complex and should therefore always be tested in practice before it is assigned to several employees/users.

Create a new user role and give it to selected employees for testing. If necessary, modify the role in consultation with the employees until the role covers everything that is intended, and then assign the tested user role to additional employees.

Below are some key points that must be considered when handling the user role creation process.

• The adjustment of a user role becomes active immediately after saving, i.e. all users with this role receive the changed rights.

• For all users active at this time, this means that the next time they interact with the system, these user rights will apply (e.g. open a new tab, select a menu item, save the current active view, etc.). For example, while a user is editing a case, the user's right to edit the case is revoked, then this user will receive an error message when saving the case since the necessary user right is checked when saving the case and the corresponding user right is no longer in possession at this time.

• Users whose role has been changed will not receive any notification from the system.

Some user rights are dependent on other user rights. This must be considered when creating new user roles. For example, the user right to "Edit existing cases" requires that the user right to "View existing cases" is also be assigned. Otherwise, the user rights and the associated function would not be usable.

When a user right is selected, all dependent user rights are automatically selected. In the above example, when the "Edit existing cases" user right is selected, the "View existing cases" user right is also automatically selected.

Please note that if a checkmark is removed from a user right, the user rights dependent on this user right cannot automatically be removed, since the dependent user right may still be dependent on another user right whose checkmark you do not want to remove. It is therefore recommended to assign the rights gradually and not to remove individual rights. Below is the table that describes what each user right means.

 To create or configure a new user role, click on the “Users” button from the left menu and then on the “USER ROLES” tab as shown below:

Once you have clicked on “USER ROLES” button you will see a new tab. On the right top corner of the screen, you will see a button “NEW USER ROLS” as highlighted in the image below:

To create or configure a new user role, select the "New user role" button. In this window, you will see the option to create a new user role. New user roles can be configured based on a user role template.

We recommend you choose a “user role template”(A) that is close to your new required role and then modify the rights but this is optional if your new user role is highly customized and is completely different from default or existing user roles, then please don’t choose any “User role template”. This dropdown lists all the user roles active on your SORMAS instance, including user roles that have been created and customized.

In the caption text field(B), The user role can be named or renamed in this free text field. It is recommended to choose the name in such a way that the specifics of the user role can be quickly recognized and assigned to the target group (users).

By assigning a jurisdiction level(C), access to the data records can be limited and extended on the basis of administrative-structural assignments and facility-related limitations. Here, the jurisdiction is broken down into "levels/areas" of different sizes, with which the respective user right is associated to view/edit the data that falls within the respective jurisdiction level. This means that the larger the jurisdiction level, the more data records can generally be viewed and edited. For example, users with a user role associated with the "Nation" level of responsibility can view records with responsibility throughout the nation.

The following levels of jurisdiction can be selected:

·        None

·        Nation

·        Region

·        District

·        Community

·        Point of entry

·        Facility

·        Laboratory

·        External laboratory

If the empty entry is selected for 'Jurisdiction level', then an error will message appear.

In the 'Description' field(D) you can describe the user role.

This description is visible in the 'User roles' tab in the list of user roles as well as part of the user roles export.

Once you have clicked on the “Save” button(E), Your user role will be saved and you will be redirected to a page where you can further modify your created user role and add or remove the user rights.

After clicking on the Save button, you will land on the newly created user role detailed page where you can assign or remove rights to this user role. If a user role template has been selected, the corresponding user rights are already selected in the list of user rights when a new user role is created. Some user rights are dependent on other user rights. When a user right is selected, all dependent user rights are automatically selected. These dependencies must be taken into account when creating new user roles. It is also recommended to test new user roles first. If a user right is selected for which not all dependencies are fulfilled, the user role cannot be saved and an error message appears with the name of the missing user right(s).

When creating or editing a user role, you can select a user role via the 'Apply user role template' button and thus completely adopt the user rights of this user role template, i.e. previously selected user rights are overwritten. In this way, you can completely reset the changes made and set them to the selected user role template. The drop-down menu also lists the default user roles supplied by the system. If the dropdown field 'Linked default user role' was already filled, please manually select the name of the selected user role from the dropdown list afterward; it will not be set automatically. This way, the next SORMAS update will definitely include the link to the default user role. For the further reference, please see the screenshot below:

In SORMAS itself, the list of user rights is sequentially divided into the following groups:

·        General

·        Data Protection

·        Dashboard

·        Tasks

·        Persons

·        Case Surveillance

·        Case Management

·        Port Health

·        Aggregated Reporting

·        Contact Surveillance

·        Follow-Up

·        Events

·        Sample Testing

·        Immunization

·        Travel Entries

·        Campaigns

·        Environments

·        Statistics

·        Users

·        Infrastructure

·        Documents

·        External emails

·        Export

·        Configuration

·       External Systems

Once you have chosen all the rights for the user role correctly, then at the end of the page,  you will see some button. The “Save” button will save all the changes made in the current opened user role and “Discard” button will discard the changes that are not saved. With the “Disable” button, you can disable the user role and with the “Delete” button you can delete the user role as shown in the image below:

When deleting a user role that has already been assigned to users, the following message will appear. Deletion is still possible if the user has multiple user roles assigned and the user rights associated with this role will be deleted from the affected users. And the dialogue box can be seen below:

An exception is users who have only been assigned the user role to be deleted and it has no other user role in combination. In this case, there is a safety mechanism that ensures that all users remain able to work. A corresponding error message will appear, stating that the user role cannot be deleted (see figure below). This error message lists the UUIDs of the affected users. The user role can only be deleted after the user role of the affected users has been changed or an additional user role has been added. The dialogue box is shown below:

A deleted user role will be deleted immediately and the assigned users will be deprived of this role and the associated user rights. This user role will then also no longer appear in the list of user roles or the 'User Role Template' dropdown.

View or edit existing user roles

You can also edit and view the existing user roles as well. For this, click on the “Users” button from the left menu and then on the “USER ROLES” tab as shown below:

Once you have clicked on the “USER ROLES” button, then you will land on a page where you can see all the users roles that exist in the SORMAS System.

On the top of the page, you will see some filters. One filter(A) can filter the user roles according to rights like “creating new cases”, “deleting cases from the system” etc. This filter helps you to see all the user roles with rights as an overview. The other filter(B) can be used to filter all the user roles based on the jurisdictions like region, district, community and etc. To edit or to view a user role in detail you need to click on the UUID(C) of the specific role which is in the first column. By clicking on the UUID you will be redirected to the page, where you can make all the changes in the user role. On the top right side of the screen you will see a button ”Export User Roles”(D). By clicking on this button, an Excel file will be downloaded which contains four sheets. The “User role” sheet contains the information of all user roles in the SORMAS system. The user rights sheet contains all user rights, descriptions and their corresponding dependent rights. The notification sheet will show you the notification list that when SORMAS sends the notifications if the email or SMS system is configured with SORMAS. The About sheet tells the current version of SORMAS. All options are marked in the image below:

SORMAS Configuration/Infrastructure setup

In the configuration menu (image below), you can store infrastructure data for your SORMAS instance, among other things. When you first start up SORMAS, you can carry out the default imports provided for the continents, subcontinents and WHO countries. You also have the option of importing municipalities and facilities for your district or independent city and storing population data for case incidence calculations. You can also use this menu item to store document templates for cases, contacts, event participants and events. Please note that entries that are stored in the infrastructure data continents can be changed and archived.

Outbreaks Configuration

In the outbreaks configuration tab, you can declare outbreaks for districts for each specific disease. It helps out as a tool for the general surveillance of several infectious diseases and associated outbreaks. In this way, it is possible to clearly document where clusters of infectious diseases are occurring in each region.

To declare a outbreak in a district, you have to click on “Configuration” menu on the left, a table will show up. In the table first row, shows the name of the diseases and first column shows the names of the regions which are already configured in SORMAS. Then you click on the cell for which you want to declare the outbreak. For example, in the image below, If you want to declare the outbreak in for covid in a district of “Default Region”, the cell is marked where you have to click.

Once you have clicked on the cell, then there will be window where you will see list of all districts in that region. You can mark the whole region as outbreak(A) or you can choose the specific districts(B) where you want to declare the outbreak. Once you have chosen the districts, then you can click on the “Save”(C) button and those districts will be marked as outbreak in the SORMAS.

Once you have save, you will see the cell has changed it’s color to red and it also shows the number of districts affected from total as shown in the image below:

If any district or region is declared as an outbreak, then you will also see that the disease is labeled as outbreak on the surveillance dashboard as shown below:

Continents Configuration

The Continents tab contains all six continents in SORMAS, on which the stored subcontinents and countries on the following tabs are based. To access the “Continents”(B) tab, you have to click on “Configuration”(A), then “Continents” (B) tab. There is a filter(C) where you can search in the list of existing continents by typing in the name of the continent. You can also filter the continents by active and archived(J). In the gird view(D) you can see all the list of existing continents and can edit the information about each continent by clicking on the pencil icon. You can also edit the multiple continents at the same time by clicking on “Enter Bulk Mode” (I). You can also export this continents list in a csv format by clicking on “Export” (G) button on the top right of the screen. Once you the csv is downloaded, you can add more continents by adding information in each new row in the specific columns. The CSV method can be used to create continents in bulk.  Once you have added the information in CSV about continents, you can import it back by clicking on “Import” (E) button. You can also import the default continents in the SORMAS by clicking on “Import Default Continents” button(F). It will save all the default continents. If you want to add a single new continent, you can add it by clicking on “New Entry” (H). A popup window will appear where you will input the name of the continent and click on the “Save” button. Please remember that once a continent is created, it cannot be deleted, it can only be archived.

Subcontinents Configuration

All subcontinents in SORMAS are stored in the Subcontinents tab. To access the “Subcontinents”(B) tab, you have to click on “Configuration”(A), then “Subcontinents” (B) tab. There is a filter(C) where you can search in the list of existing subcontinents by typing in the name of the subcontinent and can narrow down your search by specifying the continent name. You can also filter the subcontinents by active and archived(D). In the gird view(J) you can see all the list of existing subcontinents and can edit the information about each continent by clicking on the pencil icon. You can also edit the multiple continents at the same time by clicking on “Enter Bulk Mode” (I). You can also export this subcontinents list in a csv format by clicking on “Export” (G) button on the top right of the screen. Once you the csv is downloaded, you can add more subcontinents by adding information in each new row in the specific columns. The CSV method can be used to create subcontinents in bulk.  Once you have added the information in CSV about continents, you can import it back by clicking on “Import” (E) button. You can also import the default subcontinents in the SORMAS by clicking on “Import Default Subcontinents” button(F). It will save all the default subcontinents. If you want to add a single new subcontinent, you can add it by clicking on “New Entry” (H). A popup window will appear where you will input the name of the subcontinent, choose it’s specific continent and click on the “Save” button. Please remember that once a subcontinent is created, it cannot be deleted, it can only be archived and a subcontinent always have a continent.

Countries Configuration

All countries in SORMAS are stored in the countries tab. To access the “Countries”(B) tab, you have to click on “Configuration”(A), then “Countries” (B) tab. As in the two previous tabs, please also check here whether all of the 200 WHO countries are stored in your system. If not, you can import them into SORMAS using the "Import standard countries" button (F), If you notice over time that countries are missing, you can also add them manually using the "New entry" button (H). As with the subcontinents, you also have an additional filter option here, which you can use to display the countries by subcontinent (C). You can also filter the countries by active and archived(D). In the gird view(J) you can see all the list of existing countries and can edit the information about each country by clicking on the pencil icon. You can also edit the multiple countries at the same time by clicking on “Enter Bulk Mode” (I). You can also export this counries list in a csv format by clicking on “Export” (G) button on the top right of the screen. Once you the csv is downloaded, you can add more countries by adding information in each new row in the specific columns. The CSV method can be used to create countries  in bulk.  Once you have added the information in CSV about countries,  you can import it back by clicking on “Import” (E) button.

Regions Configuration

All regions in SORMAS are stored in the Regions tab. To access the “Regions”(B) tab, you have to click on “Configuration”(A), then “Regions” (B) tab. There is a filter(C) where you can search in the list of existing regions by typing in the name of the region and can narrow down your search by specifying the country name. You can also filter the regions by active and archived(D). In the gird view(I) you can see all the list of existing regions and can edit the information about each region by clicking on the pencil icon. You can also edit the multiple regions at the same time by clicking on “Enter Bulk Mode” (H). You can also export this subcontinents list in a csv format by clicking on “Export” (F) button on the top right of the screen. Once you the csv is downloaded, you can add more regions by adding information in each new row in the specific columns. The CSV method can be used to create regions in bulk.  Once you have added the information in CSV about continents, you can import it back by clicking on “Import” (E) button. If you want to add a single new region, you can add it by clicking on “New Entry” (G). A popup window will appear where you will input the name of the region, EPID Code and click on the “Save” button. The "EPID number" is required for generating the IDs of cases, contacts and all other entities.

Districts Configuration

All districts in SORMAS are stored in the districts tab. To access the “Districts”(B) tab, you have to click on “Configuration”(A), then “Districts” (B) tab. There is a filter(C) where you can search in the list of existing districts by typing in the name of the district and can narrow down your search by specifying the country and region name. You can also filter the districts by active and archived(D). In the gird view(I) you can see all the list of existing districts and can edit the information about each district by clicking on the pencil icon. You can also edit the multiple districts at the same time by clicking on “Enter Bulk Mode” (H). You can also export this districts list in a csv format by clicking on “Export” (F) button on the top right of the screen. Once you the csv is downloaded, you can add more districts by adding information in each new row in the specific columns. The CSV method can be used to create districts in bulk.  Once you have added the information in CSV about districts, you can import it back by clicking on “Import” (E) button. If you want to add a single new region, you can add it by clicking on “New Entry” (G). A popup window will appear where you will input the name of the district, EPID Code region name and click on the “Save” button. The Name, "EPID number" and “Region” are required for generating the IDs of cases, contacts and all other entities.

Communities Configuration

All communities in SORMAS are stored in the communities tab. To access the “Communities”(B) tab, you have to click on “Configuration”(A), then “Communities” (B) tab. There is a filter(C) where you can search in the list of existing communities by typing in the name of the communities and can narrow down your search by specifying the country, region and district name. You can also filter the communities by active and archived(D). In the gird view(I) you can see all the list of existing communities and can edit the information about each district by clicking on the pencil icon. You can also edit the multiple communities at the same time by clicking on “Enter Bulk Mode” (H). You can also export this districts list in a csv format by clicking on “Export” (F) button on the top right of the screen. Once you the csv is downloaded, you can add more communities by adding information in each new row in the specific columns. The CSV method can be used to create districts in bulk.  Once you have added the information in CSV about communities, you can import it back by clicking on “Import” (E) button. If you want to add a single new community, you can add it by clicking on “New Entry” (G). A popup window will appear where you will input the name of the community, region, district and click on the “Save” button. The Name, “Region” and district are required.

Facilities Configuration

In this tab, you list all the facilities where you want to use the SORMAS, you can enter facilities such as schools, hospitals or retirement homes from your region in your SORMAS instance. These stored facilities can then be selected in all SORMAS entities using the drop-down menus in the "Facility" field. All facilities in SORMAS are stored in the facilities tab. To access the “Facilities”(B) tab, you have to click on “Configuration”(A), then “Facilities” (B) tab. There are multiple filters(C) like free text search, facility category, facility type, country, region, district and community.You can use all these filters to narrow down your search for facilities. In the gird view(D) you can see all the list of existing facilities  and can edit the information about each facility by clicking on the pencil icon. You can also edit the multiple facilities at the same time by clicking on “Enter Bulk Mode” (H). You can also export this facilities list in a csv format by clicking on “Export” (F) button on the top right of the screen. Once you the csv is downloaded, you can add more facilities by adding information in each new row in the specific columns. The CSV method can be used to create facilities in bulk.  Once you have added the information in CSV about facilities, you can import it back by clicking on “Import” (E) button. If you want to add a single new facility, you can add it by clicking on “New Entry” (G).

A popup window will appear where you have to fill out the form. (J) section is mandatory to fill out as it contains the crucial information like facility name, facility category, facility type and geographic location information like region, district. You can add the information until community level as well. (K) section contains the exact address information of the facility and contact information for the facility. We recommend you to fill out all the information specially like latitude and longitude. It helps to generate the dashboards.

Points of Entry Configuration

You can store entry points (e.g. airports, ports) in point of entry tab. These are then available to you as a drop-down menu when you enter a new case with the case origin "Point of Entry". To access the “Point of Entry”(B) tab, you have to click on “Configuration”(A), then “Point of Entry” (B) tab. There are multiple filters(C) like free text search, point of entry type, country, region, district, active and archived and community. You can use all these filters to narrow down your search for point of entry. In the gird view(D) you can see all the list of existing points of entry type and can edit the information about each facility by clicking on the pencil icon. You can also edit the multiple facilities at the same time by clicking on “Enter Bulk Mode” (H). You can also export these points of entry list in a csv format by clicking on “Export” (F) button on the top right of the screen. Once you the csv is downloaded, you can add more points of entry by adding information in each new row in the specific columns. The CSV method can be used to create points of entry in bulk. Once you have added the information in CSV about points of entry, you can import it back by clicking on “Import” (E) button. If you want to add a single new point of entry, you can add it by clicking on “New Entry” (G).

A popup window will appear where you have to fill out the form. (J) section is mandatory to fill out as it contains the crucial information like point of entry name, point of entry type and geographic location information like region, district. (K) section contains the exact address information of the point of entry. We recommend you fill out all the information specially like latitude and longitude. It helps to generate the dashboards. Once you have filled out all the information, please click on the save button to make sure newly created point of entry is saved.

Population Data

Population data can be stored in the Population tab in order to be able to calculate the case incidences in the Statistics menu item. Population data is stored using the import function. Please note that a value must always be entered in columns E (TOTAL) to BX (OTHER_AGE_80_PLUS) in the import template (mandatory entry). If the value of a field is unknown, a 0 must be entered. The growthRate field in the import file is an annual percentage, but it is not a mandatory field. If an entry is required, it must be entered as a decimal number with a point (i.e. 2.4 instead of 2.4).

Line Listing Configuration

In the Line Listing tab, you can activate (A) and deactivate the Line Listing function in SORMAS for the Android app.

Document Templates Management

This chapter describes the creation and use of document templates in SORMAS. Document templates are used to create documents based on the data available in SORMAS, for example to create a quarantine notice for a COVID-19 contact person.

A document template is any .docx file or, in the case of event templates, an .html file with text modules and placeholders. The placeholders are automatically filled in by SORMAS with the required data, such as first name and surname, when the document is generated. The principle is similar to the mail merge function in Microsoft Word. In SORMAS, the data description directory is used as the basis for the paths of the data retrieval function. In addition to the data from SORMAS, templates can also contain user-defined placeholders for additional information that is filled in by the user when the document is generated (e.g. comments).

Creating placeholders in a .docx template

In the blue ribbon in the Settings menu item (1), you will find the Document templates tab (2). There you can select "Document template cases" under the respective headings, "Contacts document template", "Event participant document template", "Event form template" and Download or delete (3) document templates that have already been uploaded under "Document template entries". You can use the "Upload template" button (4) to download a sample template with frequently used placeholders from the document template menu that then appears (5). Open your existing notifications and create new placeholders (merge fields) in this document for data that is to be filled in when the document is generated.

Explanation for Microsoft Word

To create a placeholder (MergeField), press Ctrl+ F9. This inserts a pair of curly brackets "{}". If the function key Ctrl+F9 does not work, you can use the key combination Ctrl+Fn+F9. Right-click on the curly brackets and select "Edit field..." from the context menu. You can also access this editing menu via the "Insert" > "Quick block" > "Field..." tab.

Then select "Merge field" or "MergeField" under Field name in the list on the left-hand side of the newly opened window. In the new "Field name" input field that appears, enter the name of your placeholder preceded by the dollar sign "$". For example, you can enter "$person.firstName" for the first name of the person in a case. Finally, click on "Ok".

Attention: Placeholders must be entered via the edit menu. If placeholders are written directly between the curly brackets, this is not recognized by SORMAS as a command and no data is output.

Explanation for LibreOffice

To create a placeholder, insert the name of the placeholder into the text surrounded by curly brackets "{}" and preceded by a dollar sign "$". For example, to create a placeholder for the first name of the case person, insert "${person.firstName}" at the position where the name should appear.

Placeholder for data from SORMAS

To generate a document, such as a quarantine/isolation notice, it is necessary to obtain individual pieces of information from the SORMAS database. For this purpose, individual entries in the database must be queried in the document template via cross-references, which is done using the "merge fields". Root entities are required for this. The root entity is the starting point for all placeholders that are to be filled with data when the document is generated. The root entity must precede each path sequence for reading individual information from the database to ensure that the desired placeholder is read correctly.

Root entities

SORMAS can only read placeholders and fill them accordingly if the paths start with a root entity. Possible root entities for the templates are listed.

For templates in the Cases area, the root entities are:

$case.

$person.

$user.

$sample.

$pathogenTest.

For templates in the Contacts area, the root entities are:

$contact.

$person.

$user.

$sample.

$pathogenTest

For templates in the event participant area, the root entities are as follows:

$eventParticipant.

$person.

$user.

$sample.

$pathogenTest

For templates in the Events area, the root entities are:

$event.

$eventActions.

$eventParticipants.

$user.

The root entities are as follows for templates in the entries area:

$travelEntry.

$person.

$user.

Before the document is generated, for paths with the root entities "$sample." and

"$pathogenTest." shows a selection of the person's samples and pathogen tests.

You can then select the appropriate sample with the corresponding pathogen test to be displayed.

For case isolation decisions, the root entity is "$case". The available information for a "$case" is listed in the SORMAS data description directory in the "Case" worksheet (1) in the "Field" column. Examples of possible placeholders can be found in Chapter 15 Appendix.

You can identify the worksheets referenced from there in the "Type" column by the suffix

"...Reference" can be recognized. For example, "PersonReference" (2) in the worksheet

"Case" indicates that you must use a placeholder with the root entity "person" for personal data for a case. You can find the exact path in the "Person" worksheet in the data description directory in the "Field" column.

Creating the path

The structure of a path always follows the same logic: Starting from a root entity (e.g.$case.), the individual path sections follow the SORMAS database structure. The individual path sections are separated from each other by a dot. When creating the placeholders, ensure that they are spelled correctly.

The valid fields can be found in the corresponding table sheets of the data description directory. Valid placeholders are, for example, "$person.address.postalCode" or "$case.hospitalization.admissionDate".

Please refer to the SORMAS data description directory to find out which data is available in the SORMAS database and the correct names of the merge fields. To access the SORMAS data description directory, click in the blue ribbon in SORMAS, click on the "Info" menu item. On the right-hand side under the heading "Documents" you will find the "Data description directory". You can also download the data description directory from the document template menu (A). The document template menu contains a sample template (B) with various placeholders for each area, which you can use as a guide.

Attention: Before using a document template in practice, test thoroughly whether all placeholders are filled in correctly and the documents are generated correctly. You can check this by uploading your generated document template under the menu item Settings and the Document template tab and then the template can be tested in the menu item Case, Contact or Event for each file created in the "Document template" box.

Explanations for .html

For event forms, the templates must be created in .html format. The placeholders for the Data from SORMAS is written in the same way as in a .docx template. Just make sure that the path is not separated by dots but by underscores. A placeholder is created in the .html Format thus written as "$event_uuid". Further formatting is also possible in .html format using the Apache Velocity Template Engine (see Apache Velocity Engine - User Guide).

Import

If you need the option of uploading a large number of data records in SORMAS at the same time (e.g. cases, contacts), you can use the import function. An import is only possible within the administrator role, while manual data entry is permitted for various roles.

You can also export data records (e.g. contact lists) and make them available for further use or processing.

This manual contains a description of the procedure for importing data into SORMAS. The import menu and the import templates are presented and important requirements for a successful import are described. It provides an introduction to the different import variants and explains where to initiate them. Step by step, this manual guides you through the entire process, from creating your own import template, to eliminating the most common sources of error, to interpreting the data dictionary, where you can find further helpful information on data import.

Examples of error reports and their interpretation can also be found in this document, as well as an overview of the mandatory information in each import variant. Finally, the most common error messages are presented and how to deal with them is explained.

Brief overview of the most important criteria for a successful import        

 Import Button

For each of these import options, there is an import menu, in addition to other special features. You can access this by clicking on the Import button. This is shown here using the example of the case import.

With a few exceptions, the import button is always located directly at the top of the screen. Only in the case of contacts is it hidden under the MORE button. If you would like to import entries, you must first create a sample entry manually. Only then will the import button appear in the entry directory.

Import Menu

In each of the situations described, you will land in the import menu:

The import menu (shown here using the example of the municipality import) offers you the option of uploading data in a specific format. In five steps, you will find all the necessary information and templates specific to each import area:

1. Download import guide

1. Download data dictionary

1. Download import template

1. Start data import

1. Download error report (This field is only active if the import was not successful.)

All five areas are explained in detail next.

Download import guide

“Download Import Guide” is a shortened version of the import instructions or this chapter and contains the most important information from it. In terms of content, it mainly deals with the .csv format, UTF-8 conformity, data field names, spelling errors, and mandatory information.

Download data dictionary

The data description directory lists all data fields stored in SORMAS. As SORMAS has been coded in English, the field names are also in English.

The data directory explains the data fields and their variables and clarifies which data is classified as personal or sensitive by the General Data Protection Regulation (GDPR) are to be used. It also describes which facilities are assigned to which facility categories. The data directory is adapted to the structure of the SORMAS interface. Therefore, information on the case can be found in the Case worksheet, information on the contact can be found in the Contact worksheet, etc. Some of the spreadsheets in the data directory provide information on tabs (e.g. within a case) in SORMAS. Other worksheets provide information on submenus in SORMAS.

Each spreadsheet of the data directory contains exactly the number of data fields that are to be assigned to the unit to be described. In other words, the "Sample" worksheet combines all those data fields that contain individual components of the samples and, describe a sample as a whole. Each spreadsheet, together with its data fields, therefore represents a separate unit.

Download import template

All import functions have their own template with their own mandatory information and additional fields for data entry.

As a rule, there are four lines in each import template:

Line 1: Name of the data field to be filled in English. This must not be changed in its spelling.

Line 2: It shows you the name of the data variables.

Line 3: It starts with ## which means it would be ignored in the import process and it contains the captions of data variables.

Line 4: It starts with ## which it would also be ignored during the import process. It tells you the data type of the variable like text, number etc.

Mandatory information/variables

The mandatory information for each entity could be different. The best way to have an idea of all mandatory variables/information is to create the entity from the UI/web where it will show you what is the mandatory information for creating this entity with the “*” sign. The other possible way to figure out, what are the mandatory information by importing the template only with one variable of information like  disease and then you try to import it. You will get an error message and by downloading the error report, you can read the error in the first column of CSV the exact variables that are needed but we always recommend filling out as much as possible information in import variables.

Further information:

• All details (names) of regions, districts and also communities, and facilities must match the spelling in SORMAS 100% as SORMAS is case-sensitive.

• All the pre-required infrastructure and entities must be created in advance.

• In the same way, the case IDs must match the spelling in SORMAS 100% if the contacts are to be assigned to an index case during contact import.

• healthFacility / facility must first be created under 'Settings' in the 'Facilities' tab

• growthRate must be filled with a decimal number with a point

• When importing infrastructures, the imports must be carried out in the following order so that each subsequent category can be correctly linked to the previous one Continents > Subcontinents > Countries > Regions > Districts > communiaties > Facilities  // Population

• Some fields are automatically filled in by SORMAS during import if they are empty. These include:

o   eventStatus during event import: is entered in SORMAS as 'Signal'

o   reportDate for case and case contact import: is filled with the import date in SORMAS

o   reportDateTime for contact, case contact, and event import: is filled with the import date in SORMAS

o   contactClassification during contact import: is displayed in SORMAS as 'unconfirmed contact'.

o   caseClassification for case import: is calculated in SORMAS from the other details

o   investigationStatus for case import: is displayed in SORMAS as 'Investigation pending'

o   outcome during case import: is entered in SORMAS as 'no result known yet'

o   caseOrigin for case import: is entered in SORMAS as 'in country'

• Some fields After the import, SORMAS automatically identifies the importing user as the reporting user.

Secondary mandatory information based on internal logic

In addition to the mandatory information, there are entries that cannot be made without further accompanying information. This applies, for example, to the creation of a test result or a sample for a case. As soon as an entry is made there, all the following information must be entered:

 All information on the test results is grouped under the PathogenTest unit. The corresponding mandatory information is explained in the data description list in the PathogenTest worksheet. The columns belonging to the sample in the import template can be found under Sample. This is also how the corresponding sheet explaining the mandatory information is marked in the list of data descriptions.

If a data field is not filled in correctly (e.g. incorrect variable form - listed in line 3 (for the cases in line 4), SORMAS will not import the template, but will display a partially successful import with a number of errors. In this case, an error report is created in which the error is described in detail (see also chapter 8.2.3.7 The (potential) error report).

Multiple samples and test results

Samples and test results can also be imported for each case. There are corresponding fields in the corresponding import template for this purpose:

Below is the example of importing samples:

Below is the example of importing test results:

There are two ways to import multiple samples and pathogen tests for a case.

·        Enter all the data to be imported, including a sample and a pathogen test, in one line. Fill in the mandatory information for the case in another line and enter another sample. When importing, the overwriting of the data must be selected.

Enter all data to be imported, including a sample and a pathogen test, in one line. Add the data field names for samples and pathogen tests to empty columns in the top two rows on the right. In the same row that contains the data for the case and the other sample, enter the data for the other samples in empty fields under the corresponding data field names that have been added.

Format and conversion of import templates

Once you have created your import template, you must save it in .csv format and UTF-8 compliant (special characters must be encoded in a specific form).

If your file does not meet these criteria, SORMAS will not perform the import but will display a critical error without further explanation.

Export files as import templates

It is possible to use the export files created by SORMAS for import again. You can use this function, for example, to add forgotten fields. The currently recommended procedure is

1. Export of the relevant data (cases, contacts, etc.)

2. Delete exported data

3. Supplementing the data in the import template

4. Importing the data

The check for duplicates can be bypassed, making this process particularly suitable for adding a large amount of data.

Please note that the values of the disease variants may need to be adjusted. To do this, export the user-definable enum values under Settings>Database export>Configuration data. The disease variants are listed in this file. Only the information from the "value" column can be imported. If your file contains information that corresponds to the values in the "caption" column, these must be changed (for example"B.1.1.529 (Omicron)" must be written "B.1.1.529").

Start data import

You can upload your finished import template here. To do this, select the separators used in your import template(1). You can then select the correct template in your files via Select file(2) and upload it via “Start data import” (3).

Download error report

An error report is always created if an import is partially successful. The basic requirements of the .csv format and UTF-8 conformity are met and the error lies in the specific data fields.

Example error report

First a concrete example:

When importing contacts, the district (see: district) was written incorrectly. The error report displays the message below and describes the error as an invalid value: The municipality "LK Oberspreewald-Lausitz" without a hyphen is not stored in the SORMAS infrastructure data. The municipality was therefore incorrectly written without a hyphen in the import template and must be corrected.

The table below shows the most common errors that appear when creating an error report.

 The critical error

This error message is displayed if something is wrong with the conversion or the format of the import file:

The import document can be a semicolon-separated .csv file, i.e. each individual data entry must be separated from the other by a semicolon. If you export your data from other systems, the data may be tab-delimited, in which case you must select "Tab" when selecting the separators during import.

This could look like this, for example:

The import document must not contain any special characters; these must be displayed in a UTF8-compliant manner.

To find the specific error, you must examine your import file step by step. Check whether

1. the names and other entries are spelled correctly,

2. there are interfering characters anywhere,

3. there are lines in the document that have not yet been completed and contain formulas or other entries. If this is the case, delete them completely.

You can open your file with the Notepad++ program, where you can see exactly which separators are used in your file (Figure 54). UTF-8 conversion errors can then also be easily identified there, e.g. the ß is displayed with a black mark.

Export

You have the option of exporting data from the SORMAS database under various menu items. These are read out as a .csv file. For example, In the Cases menu item, you will find the "Export" field on the right-hand side. If you click on this field, a drop-down menu with various export options opens.

The "Simple export" contains all the information stored under Standard view. The "Detailed export" also includes further information on the cases, such as symptoms or vaccination status. With the "Case management export" option, separate tables for the case are exported from the Clinical Course and Therapy and Treatment tabs. The "Sample export" includes all sample data stored in SORMAS. In the "User-defined Case export", you can create your own export profile. To do this, first click on "User-defined case export". The appropriate window opens in which you click on "New export setting" as below:

In the "New export configuration" window, enter your new export profile name in the input field "Configuration name"(A). If you would like to share the export profile with your colleagues at the public health department, you should check the box "Shared to Public" (B). To create your export profile, make a selection from the list of fields to be exported by clicking on the boxes in front of the respective fields (C).

Then save your selection. The export profile you have created can now be found under "My exports"(A). You can use the blue field with the downward-pointing arrow to apply the created export profile and download the export file. You can edit the profile using the writing pad symbol and delete it using the field with the trash can symbol (B).

Different export options are available to you in the various directories. In the Cases menu item, in addition to the export options already described in the case directory, you also have a simple, detailed and user-defined export within a case file under the Contacts tab.

Under the Contacts menu item, there is - as with cases - a simple, detailed and user-defined export. At the same time, a tracking export is possible, in which information on calls made and symptoms queried is read out.

In the Tasks menu item, you can create a simple, detailed and user-defined export.

Under the menu item Persons, you have the option of creating a simple, detailed and to perform a user-defined export.

In the Events menu item, a simple and detailed export is available in the event directory. In addition, the event participants can be exported in the event via a simple, detailed and user-defined export.

Under the Samples menu item, you can choose between a simple and a detailed export.

Under the Settings menu item, you can export continents, subcontinents, countries, federal states, districts, facilities, entry points, and populations.

Similarly, all other modules have their specific export options.

Database export

Under the menu item Statistics, you will find the option to export a database via the Database export tab. Here you can select and export the entire database or just individual database tables.

Various export filters are offered within the database export. Firstly, there is the SORMAS data, which relates to cases, contacts, events, samples, tasks, persons, locations, entries, immunizations, users, and outbreaks, and secondly, there is the infrastructure data, where you can select all countries, regions, districts cities, communities and facilities. The configuration data) then contains the user-definable enum values of the various COVID-19 disease variants export, function and disease configurations.

The database tables can be selected individually and completely as well as specifically for SORMAS data only. You can then export the selected databases using the export button. The selection of database tables is downloaded separately in .csv format in a ZIP-compressed folder with the export.

Linking database tables

The database export in the statistics area is an exact image of the database. Within these database tables, there are various IDs that can be used to create links between the database tables. Accordingly, the assignment takes place via these IDs and not via the so-called UUID, as is known from cases, for example.

The following example explains that if the personal data and the personal contact data are exported, the link between the two database tables can be established via the person ID. Below are the images for reference.

This also applies to all other database export tables and their sub-tables. A connection can also be established across all tables, as can be seen here using the example of case and facility database export. The facility ID can be used to assign and find out the respective facility of the case. Screenshots are below for further explanation.

Changing SORMAS Language

SORMAS software can be used in different languages. This language will be saved for that specific user who is logged in. By default, SORMAS will be in the same language as you configured while installing the SORMAS.

To change the interface language, click on “User Settings” from the left column menu(A). A popup window will appear, you can choose your desired language from the dropdown menu(B) and click the “Save”(C) button.