diff --git a/content/docs/study-configurator/configurator-overview.mdx b/content/docs/study-configurator/configurator-overview.mdx new file mode 100644 index 0000000..76d9423 --- /dev/null +++ b/content/docs/study-configurator/configurator-overview.mdx @@ -0,0 +1,50 @@ +--- +title: Study Configurator Overview +description: Overview of the study configurator interface +--- + +## Study Configurator Dashboard + +The Study Configurator lets you manage study-wide configuration: surveys, rules, variables, and settings. The dashboard provides a quick summary and entry points to all relevant actions. + +![Study configurator dashboard overview](./images/study-conf-overview.png) + +### Top Navigation Bar +- **[Dashboard]**: Returns to the main overview of the study. +- **[Surveys](/docs/study-configurator/surveys)**: Manage surveys for the current study. +- **[Rules](/docs/study-configurator/rules)**: View published rules versions and upload a new version. +- **[Variables](/docs/study-configurator/study-variables)**: Define and manage key–value pairs used across rules and surveys. +- **[Settings](/docs/study-configurator/settings)**: Configure settings like status, code lists, notifications, and access. + +![Top navigation bar](./images/top-navigation-bar.png) + +### Study Header +- **Study Key**: Displays the unique study key (e.g., `tekenradar`). +- **Status Toggle**: Shows current status (e.g., `active`). Use the dropdown to update the study status when needed. + +![Study header](./images/study-header.png) + +### Overview Cards +- **Participants**: Shows the number of registered participants. Use “View Participants” to open participant management. +- **Temporary Participants**: Shows the number of temporary participants (e.g., pre-registration). +- **Total Responses**: Shows the total number of submitted survey responses. Use “View Responses” to open the responses explorer. + +![Overview cards](./images/overview-cards.png) + +### Surveys +- Displays all surveys in the study, including last updated date and number of versions. +- Click a survey card to open survey management for that survey. +- The link **Open survey management** takes you directly to the central surveys management page. + +![Surveys overview](./images/surveys-overview.png) + +### Study Card Preview +- Shows how the study card is presented in management views. +- Includes the name, description and tags of the study and a link to go to study settings. + +![Study cards preview](./images/study-card-preview.png) + +### Language Toggle +- Switch interface labels between supported languages (e.g., `nl`, `en`). + +![Language toggle](./images/language-toggle.png) diff --git a/content/docs/study-configurator/images/access.png b/content/docs/study-configurator/images/access.png new file mode 100644 index 0000000..8ebe2b8 Binary files /dev/null and b/content/docs/study-configurator/images/access.png differ diff --git a/content/docs/study-configurator/images/advanced.png b/content/docs/study-configurator/images/advanced.png new file mode 100644 index 0000000..0e4cda2 Binary files /dev/null and b/content/docs/study-configurator/images/advanced.png differ diff --git a/content/docs/study-configurator/images/code-lists1.png b/content/docs/study-configurator/images/code-lists1.png new file mode 100644 index 0000000..94a1a34 Binary files /dev/null and b/content/docs/study-configurator/images/code-lists1.png differ diff --git a/content/docs/study-configurator/images/code-lists2.png b/content/docs/study-configurator/images/code-lists2.png new file mode 100644 index 0000000..666e9fc Binary files /dev/null and b/content/docs/study-configurator/images/code-lists2.png differ diff --git a/content/docs/study-configurator/images/create-study.png b/content/docs/study-configurator/images/create-study.png new file mode 100644 index 0000000..4f634ca Binary files /dev/null and b/content/docs/study-configurator/images/create-study.png differ diff --git a/content/docs/study-configurator/images/display-texts.png b/content/docs/study-configurator/images/display-texts.png new file mode 100644 index 0000000..5157d29 Binary files /dev/null and b/content/docs/study-configurator/images/display-texts.png differ diff --git a/content/docs/study-configurator/images/import-export.png b/content/docs/study-configurator/images/import-export.png new file mode 100644 index 0000000..276a7a0 Binary files /dev/null and b/content/docs/study-configurator/images/import-export.png differ diff --git a/content/docs/study-configurator/images/importer-study-config2.png b/content/docs/study-configurator/images/importer-study-config2.png new file mode 100644 index 0000000..269409f Binary files /dev/null and b/content/docs/study-configurator/images/importer-study-config2.png differ diff --git a/content/docs/study-configurator/images/language-toggle.png b/content/docs/study-configurator/images/language-toggle.png new file mode 100644 index 0000000..8caa399 Binary files /dev/null and b/content/docs/study-configurator/images/language-toggle.png differ diff --git a/content/docs/study-configurator/images/notifications.png b/content/docs/study-configurator/images/notifications.png new file mode 100644 index 0000000..c5c7e45 Binary files /dev/null and b/content/docs/study-configurator/images/notifications.png differ diff --git a/content/docs/study-configurator/images/notifications2.png b/content/docs/study-configurator/images/notifications2.png new file mode 100644 index 0000000..a074da7 Binary files /dev/null and b/content/docs/study-configurator/images/notifications2.png differ diff --git a/content/docs/study-configurator/images/overview-cards.png b/content/docs/study-configurator/images/overview-cards.png new file mode 100644 index 0000000..e5fb7d8 Binary files /dev/null and b/content/docs/study-configurator/images/overview-cards.png differ diff --git a/content/docs/study-configurator/images/rules-workspace.png b/content/docs/study-configurator/images/rules-workspace.png new file mode 100644 index 0000000..b8fdc66 Binary files /dev/null and b/content/docs/study-configurator/images/rules-workspace.png differ diff --git a/content/docs/study-configurator/images/settings-general.png b/content/docs/study-configurator/images/settings-general.png new file mode 100644 index 0000000..f33bf2d Binary files /dev/null and b/content/docs/study-configurator/images/settings-general.png differ diff --git a/content/docs/study-configurator/images/starting-page.png b/content/docs/study-configurator/images/starting-page.png new file mode 100644 index 0000000..d030d34 Binary files /dev/null and b/content/docs/study-configurator/images/starting-page.png differ diff --git a/content/docs/study-configurator/images/study-card-preview.png b/content/docs/study-configurator/images/study-card-preview.png new file mode 100644 index 0000000..d50c454 Binary files /dev/null and b/content/docs/study-configurator/images/study-card-preview.png differ diff --git a/content/docs/study-configurator/images/study-conf-overview.png b/content/docs/study-configurator/images/study-conf-overview.png new file mode 100644 index 0000000..0eadea6 Binary files /dev/null and b/content/docs/study-configurator/images/study-conf-overview.png differ diff --git a/content/docs/study-configurator/images/study-header.png b/content/docs/study-configurator/images/study-header.png new file mode 100644 index 0000000..66c52ec Binary files /dev/null and b/content/docs/study-configurator/images/study-header.png differ diff --git a/content/docs/study-configurator/images/study-status.png b/content/docs/study-configurator/images/study-status.png new file mode 100644 index 0000000..7dad9e7 Binary files /dev/null and b/content/docs/study-configurator/images/study-status.png differ diff --git a/content/docs/study-configurator/images/survey-version-options.png b/content/docs/study-configurator/images/survey-version-options.png new file mode 100644 index 0000000..b0fcba8 Binary files /dev/null and b/content/docs/study-configurator/images/survey-version-options.png differ diff --git a/content/docs/study-configurator/images/surveys-overview.png b/content/docs/study-configurator/images/surveys-overview.png new file mode 100644 index 0000000..542d48c Binary files /dev/null and b/content/docs/study-configurator/images/surveys-overview.png differ diff --git a/content/docs/study-configurator/images/surveys-workspace1.png b/content/docs/study-configurator/images/surveys-workspace1.png new file mode 100644 index 0000000..d07ae8f Binary files /dev/null and b/content/docs/study-configurator/images/surveys-workspace1.png differ diff --git a/content/docs/study-configurator/images/surveys-workspace2.png b/content/docs/study-configurator/images/surveys-workspace2.png new file mode 100644 index 0000000..3fc80b5 Binary files /dev/null and b/content/docs/study-configurator/images/surveys-workspace2.png differ diff --git a/content/docs/study-configurator/images/top-navigation-bar.png b/content/docs/study-configurator/images/top-navigation-bar.png new file mode 100644 index 0000000..2f7f174 Binary files /dev/null and b/content/docs/study-configurator/images/top-navigation-bar.png differ diff --git a/content/docs/study-configurator/meta.json b/content/docs/study-configurator/meta.json index 76acfa5..aea830a 100644 --- a/content/docs/study-configurator/meta.json +++ b/content/docs/study-configurator/meta.json @@ -2,5 +2,13 @@ "title": "Study Configurator", "description": "Create and configure study settings", "root": true, - "icon": "FolderCog" + "icon": "FolderCog", + "pages": [ + "starting-page", + "configurator-overview", + "surveys", + "rules", + "study-variables", + "settings" + ] } \ No newline at end of file diff --git a/content/docs/study-configurator/rules.mdx b/content/docs/study-configurator/rules.mdx new file mode 100644 index 0000000..c009b58 --- /dev/null +++ b/content/docs/study-configurator/rules.mdx @@ -0,0 +1,41 @@ +--- +title: Study Rules Workspace +description: Manage study rules - view published versions and upload new versions for your study. +--- + +[← Back to Study Configurator Overview](/docs/study-configurator/configurator-overview) + +## Overview + +The Rules workspace provides an interface for managing study rules that govern the flows and behaviors in your study. Study rules define scheduling, triggers, and event handlers that control when and how participants interact with surveys and other study elements. + +To create and edit study rules, use the [Study Rules Editor](/docs/study-rules-editor/basics/editor-overview). + +![Rules Workspace](./images/rules-workspace.png) + +## Key Features + +### Upload Study Rules + +Use the **"Upload a new version"** button to import a study rules definition file (JSON format). This allows you to: +- Deploy new rule configurations to your study +- Update existing rules with modified logic +- Import rules created with the [Study Rules Editor](/docs/study-rules-editor/basics/editor-overview) + +### Version Management + +The Versions section displays a chronological history of all published rule versions, with each entry showing: + +- **Publication Status**: The currently active version appears with a star icon +- **Timestamp**: The exact date and time when the rules were published (e.g., 7/3/2023, 11:20:50 AM) + +#### Version Actions + +Each version has an options menu (three-dot icon) with the following actions: + +- **Download JSON**: Export the rules version as a JSON file for backup, review, or editing +- **Delete version**: Permanently remove this version from the history (cannot be undone) + + +Only one rules version can be active at a time. Uploading a new version automatically makes it the active version and unpublishes the previous one. + diff --git a/content/docs/study-configurator/settings.mdx b/content/docs/study-configurator/settings.mdx new file mode 100644 index 0000000..8239882 --- /dev/null +++ b/content/docs/study-configurator/settings.mdx @@ -0,0 +1,230 @@ +--- +title: Settings +description: Configure study-wide settings such as status, visibility, labels, and access controls. +--- + +import { ImageZoom } from 'fumadocs-ui/components/image-zoom'; +import { Step, Steps } from 'fumadocs-ui/components/steps'; +import codeListsAddEntriesImg from './images/code-lists2.png'; +import notificationsNewTopicImg from './images/notifications2.png'; + + +[← Back to Study Configurator Overview](/docs/study-configurator/configurator-overview) + +## Overview + +The Settings workspace provides access to various configuration options for your study. Settings are organized into different categories accessible through the left sidebar. + +## General + +The General tab contains the core configuration settings for your study. + +![Settings General](./images/settings-general.png) + +### Study Status + +Study status defines whether the study is visible to participants and whether data collection is active. + +- **Current status**: Select from the dropdown to set the study status: + - `active`: Study is visible and collecting data + - `inactive`: Study is not visible to participants + +![Settings General](./images/study-status.png) + +### Default Study + +Configure whether this study should be the default study for your instance. + +- **Default Study**: When enabled, all participants will be automatically assigned to this study by default once they log in. If the study is not the default study, participants need to join the study manually. + +### Display Texts + +If the instance supports study selection, the display texts define how the study appears to participants when they choose which study to join. + +Click **"Edit Display Texts"** to open the editor where you can configure: + +![Display Texts Editor](./images/display-texts.png) + +- **Study Name**: A short title for the study card (e.g., "Infectieradar") +- **Study Description**: A brief description of the study shown on the study card +- **Tags**: Optional tags to categorize the study (e.g., "tekenradar") +- **Language Support**: Edit texts for each supported language using the language selector in the top right + +Changes are applied by clicking the **"Apply"** button. + +### File Upload + +Toggle this option to configure whether participants are allowed to upload files as part of their study participation. + +## Code Lists + +The Code lists tab allows you to manage available codes for the study. These can be used to validate participant data, for example when participants need to enter specific codes to join the study or access certain features. + +![Code Lists](./images/code-lists1.png) + +### Managing Code Lists + +Each code list displays: +- **List name**: The identifier for the code list (e.g., "list1") +- **Code entries**: Shows the codes with their creation date (e.g., "9.1.2026") +- **Entry count**: Indicates how many codes are shown (e.g., "Showing 2 of 2") +- **Delete option**: Each code has an X button to remove it from the list + +### Adding Codes + +Click the **+** button in the top right to add new codes to a list. + + +In the "Add Code List Entries" dialog: + + + +**Select code list**: Choose an existing list from the dropdown or create a new one by entering a new name. + + + + +**Enter codes**: Add codes in the text area, one per line + +**Upload**: Click "Upload codes" to add the codes to the selected list + + + +## Notifications + +The Notifications tab allows you to configure email notification subscriptions for study events. This controls which email addresses will receive notifications when specific study events occur. + +![Notifications](./images/notifications.png) + + +To trigger a message topic, you need to use the ["Notify researchers (Email)"](/docs/study-rules-editor/basics/study-rules#notify-researchers) action in the Study Rules Editor when defining event handlers. + + +### Managing Notification Subscriptions + +Each notification topic shows: +- **Topic name**: The identifier for the notification topic (e.g., "topic1"). This is identical to the **message type** attribute used in email templates. +- **Subscribed emails**: Email addresses that will receive notifications for this topic, displayed as icons +- **Delete option**: Remove email addresses from the subscription + +### Adding a New Topic Subscription + +Click **"+ New topic subscription"** to create a new notification subscription. + + + +In the "New topic subscription" dialog: + +1. **Message type**: Enter the type of notification (e.g., "reminder"). Use `*` to subscribe to all message types. +2. **Email**: Enter the email address that should receive notifications for this topic +3. **Add**: Click the "Add" button to create the subscription + +The email address will then receive notifications whenever this topic is triggered through the study rules. + + +To subscribe multiple email addresses to the same topic, repeat this process for each email address individually. + + +## Access Control + +The Access Control tab allows you to manage user permissions for this study. Here you can grant specific users explicit permissions to perform certain actions on the study. + +![Access Control](./images/access.png) + + +Admins or users with access to all studies are not listed here, as they already have full access. + + +### Managing Permissions + +The permissions list shows all users who have been granted explicit permissions to this study. If no permissions have been configured, you'll see "No permissions found". + +### Adding a New Permission + +Click **"+ Add a new permission"** to grant a user access to the study. + +In the "Add a new permission" form: + +1. **User**: Select the user from the dropdown to whom the permission will be granted +2. **Action**: Select the action that this user is allowed to perform on the study. Use `*` to grant all available actions. +3. **Add permission**: Click the button to grant the permission + +Once added, the user will be able to perform the specified action on this study. + +## Import / Export + +The Import/Export tab allows you to export your study configuration for backup or sharing, and to import configurations from other studies or systems. + +![Import Export](./images/import-export.png) + +### Export Study Configuration + +Prepare your study configuration for export by selecting which components to include: + +- **Include study configuration**: Export general study settings +- **Include surveys**: Export all survey definitions and versions +- **Include rules**: Export study rules and logic + +Click **"Prepare and download study configuration"** to generate and download a JSON file containing the selected components. + +### Import Study Configuration + +Click **"Open Importer"** to import a study configuration from a JSON file. + +![Study Config Importer](./images/importer-study-config2.png) + +The importer guides you through three steps: + + + +**Select study configuration file**: Upload a JSON configuration file by clicking to browse or dragging and dropping the file + + +**What to import**: Select which parts of the configuration to import (available after file selection): + - **Override study configuration**: Replace current study settings with those from the imported file + - **Override surveys**: Replace all current surveys with those from the imported file + - **Override rules**: Replace current study rules with those from the imported file + + +**Confirm import**: Review your selections and click "Import" to override the current study configuration with the selected parts + + + + +Importing a configuration will override the current study configuration with the selected parts of the imported file. Make sure to export your current configuration first if you want to keep a backup. + + +## Advanced + +The Advanced tab contains critical actions that can permanently affect your study data. These operations should be performed with caution. + +![Advanced Settings](./images/advanced.png) + +### Danger Zone + + +Actions in this section can permanently result in data loss. + + +#### Delete Study + +If the study is not needed anymore, you can permanently delete it. + + +This is an irreversible action. You won't be able to access the study anymore. All study data, surveys, rules, and participant information will be permanently deleted. + + +Click the red **"Delete study"** button to permanently remove the study from the system. + diff --git a/content/docs/study-configurator/starting-page.mdx b/content/docs/study-configurator/starting-page.mdx new file mode 100644 index 0000000..8359866 --- /dev/null +++ b/content/docs/study-configurator/starting-page.mdx @@ -0,0 +1,32 @@ +--- +title: Getting Started +description: Select or create a study to open the Study Configurator +--- + +## Overview + +The Study Configurator starting page provides access to all studies in the system. From here, you can select an existing study to configure or create a new study. + +![Study Configurator starting page](./images/starting-page.png) + +## Selecting a Study + +The main view displays a list of all available studies. Each study is shown with: +- **Study Key**: The unique identifier for the study +- **Participants**: The number of registered participants in the study +- **Responses**: The total number of submitted survey responses +- **Status**: The current status (e.g., active, inactive) + +To open the Study Configurator for a specific study, click on the study card or the arrow button on the right. This will take you to the [Study Configurator Dashboard](/docs/study-configurator/configurator-overview) for that study. + +## Creating a New Study + +To create a new study, click the **"Create New Study"** button. This will open a form where you can configure the basic settings for the new study: + +![Create new study form](./images/create-study.png) + +- **Study Key**: Enter a unique identifier for the study. This key is used to identify the study in the system and must be unique. It can only contain letters, numbers, hyphens, and underscores, and cannot be changed later. +- **Secret Key**: Enter a secret key for the study. The study secret is used to calculate the participant IDs in combination with a global secret configured in the study system. +- **System default study (inactive)**: Optionally, enable this toggle to set the study as the default study for the system. This means that all participants will be assigned to this study by default. + +After entering the required information, click **"Create Study"** to create the study. You will be automatically taken to the [Study Configurator Dashboard](/docs/study-configurator/configurator-overview) for the newly created study, where you can start configuring surveys, rules, variables, and settings. diff --git a/content/docs/study-configurator/study-variables.mdx b/content/docs/study-configurator/study-variables.mdx index 3a0b398..58a2960 100644 --- a/content/docs/study-configurator/study-variables.mdx +++ b/content/docs/study-configurator/study-variables.mdx @@ -14,60 +14,39 @@ import studyVariablesConfig2Img from './images/variable-config-2.png'; ![Study variables empty](./images/study-variables-empty.png) - ## Introduction -### Study Variables -Study variables allow study administrators to dynamically steer the behavior of the study system, without needing to change the study rules or questionnaires. -While "participant flags" provide a way for individualized logic, study variables provide a simple way to control dynamic "global" (study-specific) behavior. - -A study variable has a **reference key** (unique within the study), a **value** and a **value type**. -The value type can be one of the following: `string`, `integer`, `float`, `boolean`, `date`. - -Each study can have its own set of study variables. The study administrator can manage them (create, edit value or configuration, delete). -For improved readability, the study administrator can also assign a human-readable label and description to each study variable. - - - -- **Flag:** Set a flag to true or false to control the visibility of a question or section. -- **Category:** Choose from a dropdown to change the study flow (e.g., phase1 -> phase2, with different behavior for each phase) -- **Threshold:** Set a threshold for a numeric value to trigger a specific action (e.g., if study-counter reaches the threshold, send a researcher notification.) - +The Variables tab in the Study Configurator provides tools to manage two important concepts for controlling study behavior: **Study Variables** and **Study Counters**. These can be integrated into study rules and questionnaires to control the survey logic based on their values. -### Counters +## Study Variables -A study counter is always an integer number and can be incremented by study rules or study actions [(see also)](/docs/study-rules-editor/basics/study-rules/#4-increment-and-get-study-counter-value). Each counter has a scope key, which is used to identify the counter within the study. +### What are Study Variables? +Study variables are configurable parameters that can be referenced in study rules and questionnaires to control study behavior. By changing the value of a study variable, administrators can dynamically adjust the logic without modifying the rules or questionnaires themselves. +While "participant flags" control individualized logic at the participant level, study variables provide a way to control "global" (study-wide) behavior. - +A study variable has a **study-unique reference key**, a **value** and a **value type**. +The value type can be one of the following: +- `string` +- `integer` +- `float` +- `boolean` +- `date` -Counters can be used to track different aspects of the study, and their values can be accessed by study expressions in the study engine [(see also)](/docs/study-rules-editor/basics/study-rules/#3-get-current-study-counter-value). +Each study can define its own set of study variables. The study administrator can create new variables, change their values and configuration, and delete them if needed. +For improved readability, the study administrator can also assign a human-readable label and description to each study variable. -- **Event count:** Track the number of events that have occurred in the study. E.g., if a participant sends in a specific combination of answers, increment the counter. -- **Participant counter:** Track the number of participants in the study. Count all or eligible participants. This was used for example to assign a unique study code to each participant. - - -## Managing Study Variables -The management of study variables is available in the **"Study Configurator"** module, under the **"Variables"** tab. +- **Flag:** Set a flag to true or false to control the visibility of a question or section. +- **Category:** Choose from a dropdown to change the study flow (e.g., `phase1` -> `phase2`, with different behavior for each phase). +- **Threshold:** Set a threshold for a numeric value to trigger a specific action (e.g., if study-counter reaches the threshold, send a researcher notification). + +### Managing Study Variables -### Creating a Study Variable +#### Creating a Study Variable To create a new study variable, click the **"Create variable"** button. This will open a modal with the editor interface for the study variable. @@ -89,7 +68,7 @@ Select the value type of the study variable. (`string`, `integer`, `float`, `boo -(Optional) Enter the **"UI priority"** of the study variable. This determines the order of study variables in the list — higher values appear first. +Optionally, enter the **"UI priority"** of the study variable. This determines the order of study variables in the list — higher values appear first. @@ -97,7 +76,7 @@ Click **"Next"** to open the **"Configuration"** tab. -(Optional) Enter a **"Label"** for improved readability in the list, in case the key is not self-explanatory. +Optionally, enter a **"Label"** for improved readability in the list, in case the key is not self-explanatory. -(Optional) Enter a **"Description"** for even more context in the list. This will be shown below the value controller in the list. +Optionally, enter a **"Description"** for even more context in the list. This will be shown below the value controller in the list. @@ -120,39 +99,66 @@ Click **"Create"** or **"Save"** to add or update the study variable. +#### Editing a Study Variable - -### Editing a Study Variable - -- To edit the "value" of a study variable, you can use the value input controller in the variable list directly. Depending on the value type, this might be a simple switch, a datepicker or a text/number input. -- To edit the "configuration" of a study variable, use the three-dot menu on the right of the variable's card, and select **"Edit configs"**. +- To edit the **value** of a study variable, you can use the value input controller in the variable list directly. Depending on the value type, this might be a simple switch, a datepicker or a text/number input. +- To edit the **configuration** of a study variable, use the three-dot menu on the right of the variable's card, and select **"Edit configs"**. - To delete a study variable, use the three-dot menu on the right of the variable's card, and select **"Delete"**.
![Study variables with entries](./images/study-variables-with-entries.png)
-## Using Study Variables +### Using Study Variables + +Study variable values can be used in the following places: +#### Study rules/study actions (server-side): +- expressions: retrieve and use the value of the study variable in a condition or as a parameter of an expression +- available study expressions: [conditional expressions](/docs/study-rules-editor/basics/study-rules#study-bool-study-variables) or [numerical](/docs/study-rules-editor/basics/study-rules#study-int-study-variables) and [text](/docs/study-rules-editor/basics/study-rules#study-string-study-variables) expressions. +- actions: [update](/docs/study-rules-editor/basics/study-rules#study-update-study-variables) the value of the study variable +#### Survey conditions (client-side): +- expressions: retrieve and use the value of the study variable in the condition +- available survey expressions: [conditional expressions](/docs/survey-editor/basics/conditions#survey-bool-study-variables) or [numerical and text expressions](/docs/survey-editor/basics/conditions#survey-num-study-variables). + +Other application-specific usage might be available if the application supports it. + +## Study Counters + +### What are Study Counters? -Values of the study variables can be used in the following places: -#### **Study rules/study actions** (server-side): - - expressions: retrieve and use the value of the study variable in a condition or as a parameter of an expression - - available study expressions: [conditional expressions](/docs/study-rules-editor/basics/study-rules#study-bool-study-variables) or [numerical](/docs/study-rules-editor/basics/study-rules#study-int-study-variables) and [text](/docs/study-rules-editor/basics/study-rules#study-string-study-variables) expressions. - - actions: [update](/docs/study-rules-editor/basics/study-rules#study-update-study-variables) the value of the study variable -#### **Survey conditions** (client-side): - - expressions: retrieve and use the value of the study variable in the condition - - available survey expressions: [conditional expressions](/docs/survey-editor/basics/conditions#survey-bool-study-variables) or [numerical and text expressions](/docs/survey-editor/basics/conditions#survey-num-study-variables). +A study counter is always an integer number and can be incremented by study rules or actions [(see also)](/docs/study-rules-editor/basics/study-rules#4-increment-and-get-study-counter-value). Each counter has a scope key, which is used to identify the counter within the study. + + + +Counters can be used to track different aspects of the study, and their values can be accessed by study expressions in the study engine [(see also)](/docs/study-rules-editor/basics/study-rules#3-get-current-study-counter-value). + + +- **Event count:** Track the number of events that have occurred in the study. E.g., if a participant sends in a specific combination of answers, increment the counter. +- **Participant counter:** Track the number of participants in the study. Count all or eligible participants. This can be used for example to assign a unique study code to each participant. + -Other applications specific usage might be available if the application supports it. +### Managing Study Counters -## Managing Counters +The counter management view is located next to the study variables in the **"Variables"** tab. -The view to manage study counters is available in the **"Study Configurator"** module, under the **"Variables"** tab, next to the study variables. Currently supported are the following features: -- View all counters with their scope key and value -- Initialize a new counter for a scope with a specific starting value -- Change the value of a counter to a specific value: use this action carefully, considering the impact on the study flow and the study rules. (E.g., if you are using a counter to generate a sequential ID for a participant, changing the value of the counter will affect the ID assignment.) -- Delete a counter: this will remove the counter from the study, until it is initialized again. Initialisation might happen through a study rule or study action, so the counter value for the scope might appear again automatically. +- All counters are displayed with their scope key and value. +- Initialize a new counter: Click the **"Initialize new counter"** button, enter a unique identifier in the **"Scope"** field, set a starting value in the **"Value"** field, and click **"Save"**. +- Change the value of a counter to a specific value: Use this action carefully, considering the impact on the study flow and the study rules. (E.g., if you are using a counter to generate a sequential ID for a participant, changing the value of the counter will affect the ID assignment.) +- Delete a counter: This will remove the counter from the study, until it is initialized again. Initialization might happen through a study rule or study action, so the counter value for the scope might appear again automatically.
![Study counters view](./images/study-counters.png) diff --git a/content/docs/study-configurator/surveys.mdx b/content/docs/study-configurator/surveys.mdx new file mode 100644 index 0000000..77af33e --- /dev/null +++ b/content/docs/study-configurator/surveys.mdx @@ -0,0 +1,70 @@ +--- +title: Surveys Workspace +description: Manage creation, organization, and versioning of surveys within a study. +--- +[← Back to Study Configurator Overview](/docs/study-configurator/configurator-overview) + +## Interface Layout + +The Surveys workspace provides an interface for creating, editing, and organizing all surveys within your study. +All surveys are displayed in a list, with each survey showing: + +- **Survey Name**: The unique identifier for each survey +- **Last Updated**: The date when the survey was last modified +- **Number of Versions**: How many versions exist for each survey, allowing you to track changes over time + +![Surveys Overview](./images/surveys-workspace1.png) + +### Creating New Surveys + +The **"Create a new survey"** button at the bottom of the list provides two options for adding a new survey to your study: + +1. **Open Editor**: Launch the visual [Survey Editor](/docs/survey-editor/basics/editor-overview) to design a new survey from scratch. + +2. **Upload Survey File**: Import an existing survey definition file (JSON format) from your computer. + +## Survey Detail View + +Click on a survey from the list to see more details of the survey. + +![Survey Detail View](./images/surveys-workspace2.png) + +### Quick Actions + +The detail view offers two primary action buttons: + +- **Upload a new version**: Import a survey definition file (JSON format) to create a new version of the survey. +- **Open Current Version in Editor**: Launch the currently active version in the [Survey Editor](/docs/survey-editor/basics/editor-overview) to modify questions and survey structure. + +Additionally, the three-dot menu next to the survey name provides: + +- **Unpublish**: Make the survey unavailable for participants. + +### Version Management + +The Versions section displays a chronological list of all survey versions, enabling you to: +- Track changes across different versions +- Decide which version should be active in your study + +The version history displays the following information for each version: + +#### Version Information +- **Version Number**: A unique identifier (e.g., 22-10-2, 22-10-1) +- **Publication Status**: The last published version appears with a star icon and is actively used in the study +- **Timestamp**: The exact date and time when the version was created or last modified + + +Only one version can be published at a time. Publishing a new version automatically unpublishes the previously active version. + + + +#### Version Actions +Each version has an options menu (three-dot icon) with the following actions: + +- **Download JSON**: Export the survey version as a JSON file for backup or sharing +- **Open in editor**: Load this version in the [Survey Editor](/docs/survey-editor/basics/editor-overview) to review or create a modified copy +- **Delete version**: Permanently remove this version (cannot be undone) + +![Survey version options](./images/survey-version-options.png) + + diff --git a/content/docs/study-rules-editor/basics/study-rules.mdx b/content/docs/study-rules-editor/basics/study-rules.mdx index 906d5b0..cb46efd 100644 --- a/content/docs/study-rules-editor/basics/study-rules.mdx +++ b/content/docs/study-rules-editor/basics/study-rules.mdx @@ -572,6 +572,7 @@ Some expressions return strings that can be used for various purposes, such as d * **Use Case:** Use to revoke access, remove tags, or clean up data. * **How it works:** Provide the list key and the code to be removed. + #### 6. **Notify researchers (Email)** * **Meaning:** Sends an email notification to designated researchers. * **Use Case:** Use to inform about events like e.g. consent withdrawal or survey completion.