Table of Contents
This guide describes all aspects of DFdiscover system administration and
is written for DFdiscover system
administrators.
Most tasks can be performed through the DFdiscover system application,
DFadmin, but some require typing UNIX commands as either
datafax or root.
Some familiarity with UNIX and computer system administration is assumed.
![[Note]](../../imagedata/note.png) | DFdiscover Installation and Configuration |
|---|---|
|
This guide does not describe DFdiscover installation or configuration procedures. Those topics are covered in Software Installation Guide. In this guide, it is assumed that the installation and initial configuration of DFdiscover has been completed. |
This chapter begins with a system level overview, meant to give an appreciation of how DFdiscover works. Chapter 2, Security presents an overview of security topics related to DFdiscover.
Chapter 3, Getting Started with DFadmin through Chapter 10, DFadmin - Traffic describe how to use the DFdiscover system administration application, DFadmin. This application is used to configure new studies, roles and users, manage your DFdiscover license, start and stop DFdiscover daemons, and several other useful things.
Several administration functions are available when DFdiscover is not running. Chapter 11, DFserveradmin describes DFserveradmin which provides these functions.
Chapter 12, Periodic Maintenance describes recommended periodic maintenance procedures, which are very important to the health of your DFdiscover system.
Chapter 13, Troubleshooting provides troubleshooting and system crash recovery assistance.
Chapter 14, DFdiscover System Files describes the DFdiscover file system and its important directories and files.
The goal in this chapter is to give you a general idea of how DFdiscover works at the server level, a level not typically seen by the end user. We describe the main system components and how they interact. Although we sometimes refer to file and command names, the purpose of this chapter is not to describe how to perform system administration tasks. That will come in the chapters to follow. This introduction will help you to see how the various system administration tasks fit into the bigger DFdiscover system picture.
In DFdiscover, a version number comprises 3 components: a major version number (X), a minor version number (Y) and a patch number (Z). Every client and server application is identified with a version number of the form X.Y.Z.
A major release of the software increments the major version number (X+1) and resets the minor version and patch numbers back to 0. Major releases can include new functionality, protocols and data structures that impact compatibility with previous releases.
Minor releases can include bug fixes and functionality updates/improvements that work on top of the existing protocols and data structures. New functionality may also be introduced so long as it does not require changes to the software infrastructure on the server. Patches may be released for individual applications to fix urgent bugs. Patches do not introduce any new functionality.
Every DFdiscover application has a X.Y.Z version number. Generally speaking, all of the applications have the same number. When a client application connects to a server application they compare version numbers. The major version numbers must always match. If they do not, the connection immediately fails and the client reports an error. If the minor version numbers do not match, the success of the connection is controlled by the Version Strict settings defined for DFdiscover and possibly also at the study level. Those settings are described in Version Strict (Master) and Version Strict (Studies).
DFdiscover is a client/server application which means that the results supplied by the software are not generated by one monolithic application, but rather by multiple, co-operating processes. Some of these co-operating processes are the client applications that users interact with, while other processes are non-interactive, and computationally oriented. The former is called a client and the latter is called a server. In general, a client is any application that a user can invoke from a command-line or from a window system menu. In DFdiscover, typical clients include DFexplore, DFsetup, and DFadmin, as well as command-line clients such as DFexport.
Server applications are more difficult to describe and categorize because there are many different types of servers. In general, a server is an application that a client application can ask to perform an action on its behalf. Your UNIX workstation, as configured by the operating system, may already be a login server (managing login requests from users), a boot server (providing system files to other diskless computers so that they can boot), and a file server (providing disk file access to other computers).
In DFdiscover, there are study database servers (handling all requests to a study database), an EDC server (which handles secure, encrypted requests from DFexplore and DFadmin clients), an incoming document server (routing all incoming documents to their correct location), and an outgoing document server (handling all requests to send out documents).
While most users will only be aware of the individual applications they use, these tools are really just clients which request services from one or more of the main DFdiscover processes. These processes run in the background and do most of the actual work. These processes are: master, slaves, study servers, EDC servers, inbound, and outbound. Four of these processes (master, slave, EDC server and outbound) are referred to as daemons because they run continuously in the background, without human intervention, as long as the DFdiscover system is operational. This distinguishes them from the study database and inbound servers that are automatically started when needed and exit when their task is done.
An operational DFdiscover system will have all of these background processes running concurrently on the same or different computers on your network. There will only be one copy of the master and at most one copy of each database server. In order to send documents there must be an outbound daemon. And finally, if a DFdiscover system has recently received several documents, the inbound server may be running, dealing with one of the newly arrived documents.
The master daemon is started automatically when the host server computer starts. It can also be started by executing the command [1]
# /opt/dfdiscover/bin/DFbootstrapIt runs on the licensed DFdiscover server and has 4 primary functions:
It controls the total number of users (or clients) that are allowed to run concurrently on the system. This is constrained by the DFdiscover software license.
It serves as a connection router for DFdiscover client applications, servicing requests for a connection to a particular server. It determines where the requested server is running and returns this information to the client. If the requested server is not running, the master solicits a slave daemon to start it.
It receives notification of each incoming document and responds by soliciting a helper application to process the incoming document.
It manages outgoing documents (typically Query Reports being that are emailed/sent back to the clinical sites) by assigning the document to the outbound daemon.
When a DFdiscover application needs information about how a study is configured (e.g. where is the default study printer located?), or needs to read from or write to a study database, it requests a connection to the study database server. The master honors this request, if it can, and if not, it solicits a slave to start the study server, making sure that there is one server process executing for each DFdiscover study.
It is the job of the study database server to serialize all database transactions, and to lock data records as needed, ensuring that only one user is able to modify a record at a time.
The EDC server handles the secure, encrypted communication between an DFexplore client and the study server. The EDC server starts another EDC server child process automatically when a new DFexplore connection is established and stops the child process when the DFexplore client exits.
The job of the inbound server is to process the G3 or TIFF fax files received by fax software, as well as PDF and TIFF documents received by email and from DFsend. This includes:
breaking down the incoming files into individual pages,
de-skewing and flipping pages as necessary,
reading the CRF barcodes to identify the study they belong to,
running the ICR software to generate an initial (workflow level 0) data record for each CRF page,
sending the pages and data records to the appropriate study database server, or if none is identified, to the image router,
and finally, archiving the original document.
The inbound server is started, and assigned a document to process, by the master daemon that receives email whenever a new document has arrived. When the inbound server has finished the current document, the master will assign it another document, if there is one. Otherwise, the server exits, and will be subsequently re-started by the master when needed.
The outbound server runs continuously and handles all outgoing document transmissions from DFdiscover. The outbound server receives requests from the master to send a document, queue the document for faxing or emailing, and track the document to its completion or ultimate failure. These documents are typically quality control reports being sent to the clinical sites participating in DFdiscover studies.
The following is a complete listing of DFdiscover database limits and formats used in DFdiscover system administration. The same parameters may appear in other tables with different limits because the limit is different in that context.
Table 1.1. DFdiscover System Limits
| Description | Limit | Comments |
|---|---|---|
| Number of outbound documents that can be queued concurrently | 1-65535 | |
| Username | 16 chars maximum | From the alphabet A-Z, a-z, 0-9, _ (underscore) |
| Study number | 1-255, 1-999 | The suggested range for study numbers that require barcodes is 1-249. Study numbers of 250-255 may be used by DF/Net Research, Inc. in distributing example or test studies such as study 254, Acceptance Test Kit. On an appropriately licensed system, it is further possible to use study numbers in the range 256-999 for EDC studies. |
| Plate number | 0-511 | Plate 0 references the new record queue. |
| Workflow level | 0-7 | Level 0 represents new, not yet validated, or pending records. Once a record has a level greater than 0, it cannot be assigned level 0 again. |
[1] Typically, the daemons are defined at the system level so that the operating system starts them when the computer boots and halts them before the computer is shut-off. Hence, it is rare that a user will have to manually execute this command.