* Configuration Folder Structure

[This is preliminary documentation and is subject to change.]

Important
Configuration folders are created inside the Configuration folder inside the framework folder structure.

All configurations have the same basic structure.

An initial configuration folder may be almost empty. The only requirement is, that the files Application.config and Server.config (see .config files) must exist in the configuration folder.

When the configuration is completed, the folder structure may look like this:

Copy

<configuration folder>
    bin
    binTopica
    Forms
    Help
    IncludeHTML
    Login
    Modules
    News
        LogIn
        Start
    Organization
    PerformanceLog
    PreProcess
    PostProcess
    RadControls
    Skins
    SQL
        Run
    Structure
    StyleSheets
    Temp
    Test
    Views

Folder

Description

bin

TOPICA plugins (compiled .NET assemblies = .dll files) must be placed in this folder. - see Extensibility / Plug-ins.

Note

Such plugins are almost obsolete (a few old plugins are still in use, but new ones should not be developed). Everything that these plugins were used for earlier, may be more easlily implemented by simpler means, for example custom webforms.

As a consequence, the "bin" folder inside the configuration folder is not used much any more.

binTopica

You may implement custom code components (custom webforms, custom webservices, etc.), that rely on separate assemblies (.dll files).

Such "extra" assemblies could be placed in the same folder as the custom code using the extra assembly.

But in some situations the custom code may not be able to load the .dll files when they are placed in the same folder as the custom code, e.g. the configuration's bin folder. Also, there are situations, where you use an assembly from several pieces of custom code, placed in different folders.

Is this situation, placing the .dll files in framework's bin folder will always work.

The .dll files are configuration specific (not part of the framework), so should they are stored (in version control etc.) and distributed/deployed with the configuration.

This is the reason for this folder (the configuration's binTopica folder). Place any configuration specific .dll files in this folder. But remember, that the .dll files must reside in the framework's bin folder:

Important

After deploying a configuration, remember to copy files in this folder (binTopica) to the framework's bin folder. There is no automatic copying!

In TOPICA framework versions 4.25 and newer, the webform BinFolderSynch.aspx (found in main menu: "Tools / Framework Tools") should be used to copy any newer files in binTopica to the framework's bin folder.
In TOPICA framework versions 4.24 and older, the deployer must do this manually (requires access to the web server's file system).

Forms

This folder stores form definitions a.k.a. form templates (XML files) for configured ("dynamic") forms.

See Working with Forms.

Help

Configuration-specific help files.

The folder containing custom login modules - see Configuring LogIn.

News

The two subfolders Login and Start holds text files (in HTML-format) containing the messages displayed on the login and start forms, respectively.

Each time a user edits these messages, the previous version is stored. So these folders contain the full history of messages.

This folder is automatically created when needed (in release 4.12 and later).

Organization

Contains a subfolder Images, that holds icons (images) to be displayed in the organization tree.

There must be one image for each type of organizational unit used in the organization. Name must match the organizational unit type. Files should be in gif-format. Size should not be greater than 20 pixels by 20 pixels.

See Organization Administration.

PerformanceLog

If performance logging to text files performance logging (to text files) has been enabled, log files are written to this folder.

Note

Performance logging to text files is only implemented in TOPICA version 4.20 and earlier.

In releases 4.21 and newer, this is replaced by performance loggin to database table, son the PerformanceLog is not used any more.

PreProcess

Pre-process files referenced from configured forms must be stored in this folder.

A pre-process file is an .aspx-file, that executes BEFORE a configured form loads. The .aspx must generate an XML document with data. This data may be used to set default values for fields.

PostProcess

Post-process files referenced from configured forms must be stored in this folder.

A post-process is an .aspx file, that runs AFTER the form instance (record) is saved (optionally: after a record is copied and deleted).

SQL

This folder is used to store SQL scripts useful in the current configuration.

A subfolder Run may exist. This subfolder is used to store SQL scripts, that may be run from the standard web application (provided the user is a system administrator!). In this way the system administrator may run scripts that alters the database without having direct access to the database server. This may be used to define configuration specific database objects: tables, views, stored procedures etc. These database objects may be used in reports, test modules, batch processing, etc.

To access the script in the SQL/Run folder from the user interface, select "SQL / Run" from the main menu.

Note

In TOPICA framework versions 4.21 and newer, it is possible to execute all SQL-scripts in this folder in "batch" mode, and it is possible to control the sequence in which the scripts are run (by choosing suitable file names - scripts are run in alphabetical order).
In TOPICA framework versions 4.20 and older, the configurator / deployer must run the scripts one by one - in proper sequence.

Note
Scripts that are NOT placed in the SQL/Run folder or a sub-folder (for example: scripts placed directly in the SQL folder) are not (directly) accessible from the "SQL / Run" command in the main menu. This might be used for SQL scripts that should only be used internally during development (i.e. that should never be run in e.g. production environments). Use this feature with sparingly!

Structure

This folder holds The Structure File, that is used to define the relations between configured forms (and hence relations between tables in the database).

Skins

This folder contains the configuration specific skins (that supplement the standard skins delivered with the framework).

A skin defines "look and feel" of the application. End users may select their preferred skin.

Note
Skins were introduced in TOPICA release 4.21, so this folder only exist in release 4.21 and newer.

StyleSheets

This folder may contain any number of subfolders, images and other resources used from CSS-files.

The configuration key StyleSheetFolder refers to one of these folders. The value of this key determines which stylesheets are used in the configuration.

Note
Skins were introduced in TOPICA release 4.21. Skins have replaced the older system of configuration specific stylesheets. So this folder is NOT used by the TOPICA framework release 4.21 and newer - but it may be used in some applications, e.g. when custom webforms refers application specific stylesheets.

Temp

Folder for temporary files. Will be created automatically as needed.

Test

This folder may contain configuration specific test tools, typically custom webforms (.aspx files), reports, or SQL scripts.

Typical uses for test tools: Create test data, reports that sould only be accessible for testers, etc.

This folder may have any internal folder structure. Regarding context, this folder works alomst like the Views folder (see below).

This folder is visible only for employee users having the Test permission. The folder is invisible for "normal" users (not having the Test permission).

Note
The test system was introduced in TOPICA release 4.22. So this folder is only used in release 4.22 and newer.

Views

Holds definitions of reports. May contain the following subfolders - each corresponding to a particular context type - see Report Context.

Employee	Reports to be run with an employee user in context.
OrgUnit	Reports to be run with an organizational unit in context.
Patient	Reports to be run with a patient in context.
System	Reports to be run without any of the above objects in context - i.e. system reports. A subfolder named Table is used to hold reports, that relate to a particular configured form (= table in the database). The Table subfolder may contain a subfolder for each table in the Data Dictionary, that has the OrgUnitConfigure flag set (i.e. that may be configurable in the "Data owner" tab in the property page for organizational unit). The "data ownership" defined on each organizational unit controls which forms may be "owned" by the actual organizational unit. See Organization Administration. When placing reports appropriately in the System/Table folder, the system makes sure, that the user may only start reports that are meaningful for the actual organizational unit. I.e. it is not possible for the user to start a report that returns some data, that cannot be "owned" by the organizational unit. Placing reports in System/Table also has the effect, that reports may be run WITH an organizational unit in context or WITHOUT an organizational unit in context (e.g. as a system report). See Understanding Context. Example: The Data Dictionary contains tables TableA and TableB. Report Report1 may be run with any organizatioanl Report Report1 may be run with any organizational unit in context. The Data Dictionary contains tables TableA and TableB. Report ReportA shows data from table TableA, Report ReportB shows data from table TableB, The reports should be organized in the following folder structure: Copy Views OrgUnit Report1.xml System Table TableA ReportA.xml TableB ReportB.xml If the organizational unit in context is set up to be "data owner" for TableA but not for TableB, the user may run reports Report1.xml and ReportA.xml, - ReportB.xml is not accessible.