====== decimal Bolus Designer User Guide ====== ===== Overview ===== decimal Bolus Designer is used for designing and editing DICOM structure files to .decimal for manufacturing as a bolus treatment device. The decimal Bolus Designer app allows users to import DICOM files, edit or design the treatment bolus, and place the order to [[https://direct.dotdecimal.com|decimal Direct]]. ===== Purpose ===== The purpose of this document is to provide guidance on the setup, access, and usage of decimal Bolus Designer. ===== Getting Started ===== Review each of the sections below for how to get started with the decimal Bolus Designer. ==== Initial Setup ==== The decimal Bolus Designer application must be licensed and added to your account by .decimal staff. Please contact .decimal customer support (1-800-255-1613) for access to this application. ==== Access Control ==== decimal Bolus Designer uses [[https://auth0.com/security|Auth0]] as an Identity-as-a-Service provider for user account management. All user accounts and credentials are managed by the Auth0 service including user creation, password policies, password resets, and secure authentication. Users will never directly use Auth0 to manage their accounts, but will use [[https://direct.dotdecimal.com|decimal Direct]] to [[direct:userguide#managing_users_on_your_site|invite and manage their user accounts]]. As decimal Bolus Designer is deployed on customer workstations the site administrator will be responsible for the installation of the software on the appropriate workstations and the account management of all users at the facility. Each employee should have an individual login and password to access the application that prevents unauthorized access, and account sharing should be strictly prohibited. === User Authentication === Users authenticate and launch the decimal Bolus Designer application using the [[decimalauncher:decimallauncher#authentication | decimal Launcher]]. === Account Management === decimal Bolus Designer site managers have the ability to [[direct:userguide#managing_users_on_your_site|add and remove users]] to their site. When adding a new user an .decimal account will be created for the new user and automatically linked to the site. The user will then be notified to set their password following the .decimal password reset process. Removing a user from a site does not delete the user's .decimal account, but removes the account from the site, effectively removing all access to the site's apps, data, and device order history. Refer to the [[direct:userguide|decimal Direct User Guide]] for more information. === User Sessions === When decimal Bolus Designer is launched from the decimal Launcher, the application is given an JWT authentication token for the logged in user. This token is used to authenticate and perform [[https://direct.dotdecimal.com|decimal Direct API]] requests. This JWT token is issued by decimal Direct and Auth0 and has a built in expiration. When this token expires the user will be logged out of the application and be forced to re-authenticate and relaunch the application using the decimal Launcher. Refer to [[decimalauncher:decimallauncher#inactivity_and_session_timeout|decimal Launcher's User Guide]] for details on this authentication token and its expiration. Auth0 user credentials are authenticated and validated using the decimal Direct API by decimal Bolus Designer each time a user logs in and on recurring timer events. If user credentials are invalid or expired, users will automatically be logged out of the application and prevented from using or accessing any data within the application/system. === Inactivity Timeout === decimal Bolus Designer has a built in inactivity timeout that will automatically log the user out if no mouse/keyboard activity has occurred. The timeout setting can be changed in the [[bolusdesigner:userguide:tutorials#application_settings|decimal Bolus Designer application settings]]. Idle workstation locking at the OS level is also recommended for all workstations with access to decimal Bolus Designer. While there are inactivity and session timeouts built into the application, workstation idle locking will further protect the system from unauthorized access in-between session timeouts. ==== Installation ==== The decimal Bolus Designer application is installed via the [[decimalauncher:decimallauncher|decimal Launcher]] client application. Refer to the decimal Launcher [[decimalauncher:decimallauncher|user guide]] for details on using the decimal Launcher. The main high level requirements for using the decimal Launcher and decimal Bolus Designer application are: - .decimal Direct account credentials - This account needs association with a Site ID (.decimal Customer Account number) that has been licensed for use of the decimal Ordering Tool application - This account needs specific .decimal Permission for accessing the application - The decimal Launcher installed Please refer to the decimal Bolus Designer [[bolusdesigner:userguide:systemrequirements|System Requirements]] page for complete details on hardware and network requirements. ==== Release Management (decimal Launcher) ==== The decimal Bolus Designer app is installed and launched from the [[decimalauncher:decimallauncher|decimal Launcher]]. The Launcher program provides the following functionality in regards to decimal Ordering Tool: - Ensures that all users at a site are using the same version of the application - Ensures that the local app client stays in sync with the latest release version (as set via decimal Direct) - Provides user authentication and password management - Provides binary file security to ensure that the application files are not tampered with on .decimal's server or on client workstations (via hashes and checksums). Refer to [[decimalauncher:decimallauncher#application_security|decimal Launcher's Application Security]] page for further details. When an application update is available via the decimal Launcher, the users will be required to install the app in the Launcher. This is accomplished by selecting the //Download// button for the specific app. Within a few minutes, the app should be downloaded and installed locally for the current user account. The user will then be able to launch the released app version from the Launcher. Details regarding the specific requirements for computers on which the decimal Launcher and decimal Bolus Designer client applications will be installed can be found on the [[decimalauncher:decimallauncher#system_requirements|decimal Launcher System Requirements]] and [[bolusdesigner:userguide:systemrequirements|decimal Bolus Designer System Requirements]] page. === Releasing a new App Version === When a new application version of decimal Bolus Designer is released, users will be notified in the [[decimalauncher:decimallauncher#updating_applications|decimal Launcher]]. This notification serves only to notify users of a newer version of the application and does not result in a newer version being installed for use. Once a new app version is available, the application will be deployed to the decimal Launcher following the [[decimalauncher:decimallauncher#updating_applications|Updating Applications]] guide. This will immediately push the app update to all decimal Ordering Tool users (via the decimal Launcher) and all users will be required to update to the released version to continue using the software. === Release Notes === For the release notes for each version of the decimal Bolus Designer application, please refer to the [[bolusdesigner:versions|decimal Bolus Designer Version History]] page. === Release Version Compatibility === The decimal Bolus Designer app is tested for version compatibility by .decimal prior to release to customers. Specifically, .decimal will test the version compatibility by: * Adding manual and automatic data upgrades, as appropriate, for changes in the data model. When applicable, these changes are required to be sensible to the clinical environment and will be documented in the release notes. ===== Application Tutorials ===== The following sections are thorough guides providing complete information about each task within the decimal Bolus Designer application. * [[bolusdesigner:userguide:tutorials#launching_the_decimal_bolus_designer|Launching decimal Bolus Designer]] * [[bolusdesigner:userguide:tutorials#dicom_patient_import|DICOM Patient Import]] * [[bolusdesigner:userguide:tutorials#bolus_designer_settings|Bolus Designer Settings]] * [[bolusdesigner:userguide:tutorials#export_logs|Export Usage Logs]] * [[bolusdesigner:userguide:tutorials#dicom_settings|DICOM Settings]] * [[bolusdesigner:userguide:tutorials#shipping_address_settings|Shipping Address Settings]] * [[bolusdesigner:userguide:tutorials#app_default_settings|Default App Settings]] * [[bolusdesigner:userguide:tutorials#patient_management|Patient Search and Management]] * [[bolusdesigner:userguide:tutorials#treatment_plans|Treatment Plans]] * [[bolusdesigner:userguide:tutorials#right_hand_side_controls_options|Right Hand Side Controls]] * [[bolusdesigner:userguide:tutorials#designing_a_bolus|Designing a Bolus]] * [[bolusdesigner:userguide:tutorials#plan_locking|Plan Locking]] * [[bolusdesigner:userguide:tutorials#dicom_export|DICOM Export]] * [[bolusdesigner:userguide:tutorials#ordering_devices|Ordering Devices]] * [[bolusdesigner:userguide:tutorials#bolus_designer_app_settings|Local App Settings]] ==== Coordinates and Units of Measure ==== The following is a list of several important items that users should understand in regards to the information displays in the decimal Bolus Designer application: * decimal Bolus Designer exclusively uses the DICOM patient coordinate system for position display information (equipment based coordinates are NOT available) * All linear dimensions are shown in centimeters (cm) * All angular dimensions are shown in degrees (deg) * All date/time values are provided in a // yyyy-mm-dd h:m:s // format using local time on a 24 hour clock * All date and time notifications in decimal Bolus Designer should match current Windows OS date and time, including proper use of daylight savings time where appropriate (note: decimal Bolus Designer will display in 24 hour format, while Windows may display in am/pm depending on local settings) ==== Keyboard and Mouse Controls ==== The decimal Bolus Designer app utilizes keyboard shortcuts to help streamline many commonly used functions and display controls. A complete listing of these shortcuts along with a full description of the mouse controls is located at the [[bolusdesigner:userguide:keyboard_controls| Keyboard and Mouse Controls page]]. ===== Application Data Management ===== ==== Data Storage ==== The decimal Bolus Designer app has four main components for its data storage that allow secure and efficient data access while sharing patient data and cached calculation results across an organization for multiple users. The four data storage systems are as follows: |< - 14em 35em>| ^ Storage ^ Description / Purpose ^ | 1. Patient Database | SQLite database for all organization, patients, and treatment records | | 2. Patient File Storage | Folder directory that contains all propitiatory data file formats | | 3. Network Data Cache | Optional folder directory that contains an SQLite database and cached calculation results to share across multiple users | | 4. Local (client) Data Cache | Folder directory that contains an SQLite database and cached calculation results | At a high level, the application interacts with each data storage element during normal application usage as depicted in . {{ :bolusdesigner:userguide:data_management_overview.png?400 |}} === Patient Database & File Storage === The decimal Bolus Designer app allows for centralized patient data that is shared between multiple clients (). The patient storage folder includes an SQLite database for maintaining data records and modification events. By placing this directory on a network location users can share the database across multiple workstations and users. Patient files are stored in a folder structure that represents the organizational hierarchy of the patient data model. All patient identifying information is encrypted, refer to [[bolusdesigner:userguide:userguide#file_security|File Security]] for more details, in the database and patient data files to prevent unauthorized access to patient data. Files also include 32bit checksums that are linked to encrypted database entries to ensure they are not substituted or modified in an unauthorized manner. Refer to [[bolusdesigner:userguide:userguide#data_integrity|Data Integrity]] for further details on how data is prevented from modification and changes. === Network & Local Data Cache === The decimal Bolus Designer app uses calculation data caching to improve the user experience by loading results from disk rather than recomputing on demand. The calculation disk cache files are comprised of proprietary compressed binary files that represent a completed calculation result. Storing and using the cached calculations results in speedier load times of patient/plan data, beam dose, and hardware devices without having to utilize the processing power of the computer each time a plan is opened. If a calculation result is not found in the calculation cache, the calculation will be performed and the results stored in the cache. The calculation cache is comprised of a local disk cache and an optional network cache (refer to ). Using the local cache allows for the caching of calculation results to the individual user’s workstation and the network cache allows users to share calculation results among all users using the centralized patient database (e.g.: user 1 saves a plan and user 2 opens the plan on a different computer; by saving to the network cache, user 2 automatically loads in user 1’s results without having to recompute them). Reading data from the local cache allows for the fastest data load time for the end user. Refer to for the cache saving mechanics between the local and network caches. By default when decimal Bolus Designer is installed the cache locations are set to the following: * **Local cache:** C:\ProgramData\decimal Bolus Designer\cache * **Network cache:** None - This must be setup in the [[bolusdesigner:userguide:tutorials#cache_settings|application cache settings]] for each client workstation that is intended to use the network cache {{ :electronrt:instructions_for_use:data_caching.png?direct&400 |}} When the local and/or network cache fills past the set limit within the decimal Bolus Designer client, the oldest data will be removed so the cache remains under the limit in the app settings. No plan record data is kept within the local or network cache, so loss of this data only impacts user performance of unapproved plans. On plan locking all critical plan data (devices, etc) is captured in the Patient File Storage. == Clearing the Cache == The local or network cache can be cleared by using the decimal Bolus Designer [[bolusdesigner:userguide:tutorials#cache_settings|application cache settings]]. In the case of a cache corporation, a manual cache deletion may be required. If the app is unable to open or crashes immediately on open, the local cache should be cleared: - Navigate to the cache directory (e.g.: C:\ProgramData\decimal Bolus Designer\cache) and manually remove the entire cache folder - Reopen the application and the cache will be rebuilt as the decimal Bolus Designer application is used ==== Data Duplication or Backup ==== decimal Bolus Designer patient data can be duplicated or backed up by manually copying the file system stored on disk. This will create an exact replicate of the original data used by decimal Bolus Designer. This process allows for data backup, release testing, or data manipulation without adversely impacting the original data store. === Copying Data === The current data storage locations are set in the decimal Bolus Designer [[bolusdesigner:userguide:tutorials#application_settings|application settings]] page. By copying the folders linked from these settings, the application data is fully captured and backed up. The [[bolusdesigner:userguide:userguide#data_backup_recommendations|Data Backup Recommendations]] section outlines the recommended frequency for backup of each data storage element used by decimal Bolus Designer. Refer to [[bolusdesigner:userguide:userguide#application_data_management|Data Management ]] for an outline of each data storage location to determine the appropriate scope of the data duplication or backup. === Linking to New Data Storage === To restore or link to a different data store, open the decimal Bolus Designer [[bolusdesigner:userguide:tutorials#application_settings|application settings]] page and update each setting to the new file storage location. ==== Data Integrity ==== === Local Data Storage === As with any software application there is always concern with system and data integrity. decimal Bolus Designer makes use of caching at various system levels to improve performance and mitigate some of these concerns. Refer to [[bolusdesigner:userguide:userguide#application_data_management|Application Data Management]] for details on decimal Bolus Designer data caching. While decimal Bolus Designer has been designed with security in mind, users should understand that it is still their responsibility to ensure the system is accessed and controlled properly. Following international standards for IT risk management, such as IEC 80001-1, is therefore highly recommended. Since data integrity is a critical feature for application such as this, the decimal Bolus Designer app automatically and continuously saves both the state of the application and the working record data on a timer (triggering every minute or less) as well as on exit of any create or edit event in the application. Additionally, each "save" event creates a new entry in the record's history log in the local database, which provides a log file for editing of all records and ensures that patient records are saved securely. Note it is highly recommended that the application database is hosted on a separate server containing independent, redundant storage drives so that data is not lost in the event of a local system failure or crash. === File Security === The following table describes the file security methods used for decimal Bolus Designer data. The subsequent paragraphs provide supplemental details for each item. ^ Item ^ Storage Type ^ Encryption Type ^ | Patient Database | SQLite Database | AES-256 | | ::: | Fields Containing PHI/PII | AES-256 | | Patient/Data Files | Local/Network File System | AES-256 | All PHI/PII data (including data files and database fields) is encrypted using AES-256 with an encryption key that is unique for each organization/patient storage location. * **decimal Bolus Designer data files:** (includes but is not limited to: settings, patients, DICOM data, plans, etc) Files are encrypted using AES-256 when stored to disk and secured with a checksum stored as an encrypted field in the application database. When files are read from disk, the contents are checked against the corresponding encrypted checksum to ensure the file contents have not been changed, manipulated, or substituted. * **decimal Bolus Designer patient database:** Database is encrypted using AES-256. Additionally, the patient identifying fields within the database are further encrypted using separate AES-256 encryption, adding an additional level of security for patient data within the application database. **Note**: The [[bolusdesigner:userguide:userguide#network_local_data_cache|local calculation cache]] files are a non-human readable, proprietary compressed binary format. These files may contain unencrypted patient identifying information. The local cache is purged as the cache fills with data, so exposure to long term data is limited. Workstation level disk encryption (e.g.: bitlocker) is recommended to protect against unauthorized access to calculation caches by providing encryption at rest. === Data Import/Export === Patient data is imported and exported using the DICOM NEMA 2020 standard to ensure the data is transferred error free and securely. Refer to the decimal Bolus Designer {{:bolusdesigner:usr-015_dicom_conformance_statement.pdf|Dicom Conformance Statement}} for the supported DICOM tags. === Data Backup Recommendations === Since the decimal Bolus Designer app stores data on local file storage on each customer's servers we recommend frequent periodic backups of the file-system in which the patient database and file store are kept. There are 4 major components for the decimal Bolus Designer app that should be considered for data backup using the following [[bolusdesigner:userguide:userguide#data_duplication_or_backup|Data Duplication or Backup Process]]. Refer to [[bolusdesigner:userguide:userguide#application_data_management|Application Data Management]] for a full detailed explanation of each item. ^ Data ^ Severity of Data Loss ^ Recommended Frequency ^ | 1. Patient Database | Critical | As frequent as possible \\ (minimum daily) | | 2. Patient File Storage | Critical | ::: | | 3. Network Data Cache | Medium | Daily | | 4. Local (client) Data Cache | Low | N/A | .decimal recommends Patient Database [1] and Patient File Storage [2] backups as frequent as possible, at least nightly, to ensure there is no substantial dataloss or interruption of software use. If the [4] Local Data Cache is lost on each workstation the [3] Network Data Cache will be fallen back to by the decimal Bolus Designer app. So backup of this data is not necessary. Refer to [[electronrt:instructions_for_use:instructions_for_use#network_local_data_cache|Network & Local Caching]] for a overview of the caching mechanic. It's also recommended that prior to deploying a new release version, a full data backup is performed. While this step should be unnecessary, it's recommended as a precaution in case there are problems with the version upgrade. ==== Internet Data Transfer ==== Since radiation therapy using .decimal requires frequent use of patient-specific devices that are fabricated within our facility, there is a necessity to transmit device manufacturing parameters and information to .decimal servers to all for fabrication of the custom devices. In order to protect patient privacy, .decimal's proprietary order file format contains only the minimal data necessary to manufacture each requested device. .decimal values the privacy of patients and security of our customer's sensitive information and we believe the best safeguard to protect critical data is to ensure it doesn’t leave your facility. As such, no PHI, PII, or any sensitive customer billing/payment information is contained in the order files sent to .decimal. {{ :decimal_ordering_tool:userguide:dot_internet_data_transmission.png?400 |}} Data is transferred to and from the decimal Direct servers using secure HTTPS transfer protocols that guarantee error-free transfer using common industry standard techniques. All data passed to and from .decimal's ordering servers is encrypted during transit and does not contain patient identifying data. ==== Simultaneous Plan Access ==== Treatment plans are protected against simultaneous record access and data loss by ensuring an attempted update to plan data is not based on an outdated base file. If the local plan record has been accessed simultaneously by another user and has been modified (committed to the database) by another user, the outdated local plan record will be unable to commit the change until the plan has been updated locally. ===== Improper System Usage ===== When using decimal Bolus Designer, as with any complex program, there is the potential for misuse. The decimal Bolus Designer is a radiotherapy medical device ordering tool that is intended to be used by experienced and knowledgeable professionals working in the field of radiation therapy. ===== Known Application Limitations ===== Below are listed the known application limitations, defects, or inconsistencies. ==== General ==== ^ ID ^ Affected Version(s) ^ Description ^ | 1 | All | Simultaneous record access: * If multiple instances of the application have the same treatment plan record opened, changes will be prevented from being pushed to the patient database if the treatment plan is changed first by another user. This will cause the other simultaneous instances to become outdated. Changes to the local application on outdated instances will be blocked from pushing plan changes to the patient database, but the changes may still appear to have happened in the local application. Users will be warned of their changes being blocked by the error: ''“Plan revision is outdated. Please close and reopen the treatment plan to continue using this plan."'' | | 2 | All | Random Application Crashes: * If the local or network disk cache becomes corrupted the application may crash at seemingly random places while calculations are computing. Clearing the local disk cache within the application settings may help resolve unreproducible application crashes during calculations running. | | 3 | All | Network patient database: * If the application is set to use a [[electronrt:instructions_for_use:instructions_for_use#patient_database_file_storage|network patient directory]] shared with multiple users there may be a risk for 'database is locked' errors. This is due to the application using SQLite as it's database engine, which does not robustly support concurrent database users and reading/writing. While normal usage between one or two users may not pose a problem with this, having a significant number of users simultaneously accessing the network database or the following scenarios can cause the database to lock and throw this error: * The application crashes or a network connection is interrupted during a SQL commit that allows the 'unlock' step to be missed OR * The file is locked due to other network usage (e.g.: the file is in use by an external service such as an Antivirus scan, backup, etc) OR * Multiple simultaneous users are attempting to read/write to the database at the same time * If you receive the error "database is locked" you'll have to wait and try again once the database is unlocked | | 4 | All | Application fails to load computed data: Under the following scenario, the application request and state handling has a known bug that results in computed data not loading within the application until a application close and re-open is performed: * A patient/plan is opened and a user interface or task is opened * Data begins computing (e.g.: a dose, beam, or device) * While the data is computing the user navigates to another user interface within the application * If the data finishes computing for the first user interface while the user is navigated to a new user interface and then the user navigates back to the first user interface, the application may not know the data is computed to display or use the results. | ==== DICOM Import ==== ^ ID ^ Affected Version(s) ^ Description ^ | 1 | All | Closing the application immediately after importing a DICOM patient and before the job 'copy_imported_dicom_files_to_plan' completes will cause an incomplete CT Image Set when exporting DICOM later in the application. | ===== System Requirements ===== Details regarding the specific requirements for computers on which the decimal Launcher and decimal Bolus Designer client applications will be installed can be found on the [[decimalauncher:decimallauncher#system_requirements|decimal Launcher System Requirements]] and [[bolusdesigner:userguide:systemrequirements|decimal Bolus Designer System Requirements]] pages.