http://caisis.org/wiki/index.php?title=Special:Contributions&feed=atom&target=DelvinkCaisisWiki - User contributions [en]2024-03-29T00:56:36ZFrom CaisisWikiMediaWiki 1.15.1http://caisis.org/wiki/index.php?title=InstallationInstallation2012-05-23T17:01:00Z<p>Delvink: /* Grant Write Access */</p>
<hr />
<div>Translations: [[Installation_41_it|italiano]] - [[Installation_fr|français]]<br />
<br />
Caisis is an ASP.NET web application with a SQL Server backend. Browser support includes Internet Explorer 6,7,8, FireFox 2+, and Safari 3.0+ for the Mac. We are working on Chrome compatibility. <br />
<br />
Caisis was built to scale to from single users to thousands, and the number of users and performance expectations should be considered when selecting hardware. At minimum, the Caisis database and web server can be run on the same server with 5 GB of free hard drive space and 2 GB of RAM. Using SQL Server 2005 Express in place of the Enterprise version allows groups to get up and running at no cost (assuming you have a Windows Server with IIS installed). Note, SQL Server express although free, has limitations on the number of simultaneous connections and no integrated backup tools. <br />
<br />
This page will guide you through the installation of the database and web application.<br />
<br />
<br />
== Installation Prerequisites ==<br />
<br />
===.NET Framework ===<br />
* [http://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=en .NET 3.5 Framework Service Pack 1]<br />
<br />
===Database Server===<br />
* Microsoft SQL Server 2008, 2005 or Express (with limitations: see Microsoft Web Site)<br />
<br />
===Web Server===<br />
* Microsoft Windows 2008, 2003 or XP<br />
* Microsoft Internet Information Services (IIS) 6 or Greater<br />
<br />
'''NOTES'''<br />
* The database and web server can be on the same or different physical machines<br />
* .NET 3.5 (required by Caisis) is not supported under Windows 2000.<br />
* II5 is also not suppored by the .NET 3.5 Framework<br />
<br />
== Downloads ==<br />
Caisis 6.0 can be downloaded as a zip package, which contains the files needed to setup the database and web application.<br />
<br />
There are 3 packages available for download:<br />
==== Caisis 6.0 - New Installation ====<br />
*'''Installer:''' Contains the Windows Installer file for a standard installation.<br />
*'''Database:''' Contains the Database sql script files needed to create and install the Caisis 6.0 database.<br />
<br />
==== Caisis 6.0 - Upgrade from Caisis 5.0.2 ====<br />
*'''WebApp:''' Contains the web application files if you prefer to manually copy (recommended) the Caisis files to a registered IIS web root instead of running the Installer file. See the '''Manual Deployment for Upgrades''' section of this page for step by step instruction. <br />
*'''Installer:''' Contains the Windows Installer file for a standard installation. Before running the install, you may have to uninstall prior versions of Caisis using Control Panel:Add/Remove programs<br />
*'''Database:''' Contains the Database sql script files needed to upgrade your Caisis 5.0.2 Database to the Caisis 6.0 Database.<br />
<br />
* NOTE: The above also applies when upgrading from version 4.5 to 5.0.2 To upgrade the database to 6.0 from an older version of the Caisis database, you '''must''' run the appropriate scripts between versions, as this ensures the data is moved correctly, and metadata is preserved.<br />
<br />
Example: To upgrade from Version 4.1 to 5.0.2<br />
4.1 -> 4.5 -> 5.0.2<br />
Example: To upgrade from Version 4.0 to 6.0<br />
4.0 -> 4.1 -> 4.5 -> 5.0.2 -> 6.0<br />
<br />
==== Caisis 6.0 Source Files ====<br />
Contains the Visual Studio Solution file and source code used to build and modify Caisis.<br />
<br />
== Setup ==<br />
<br />
=== Database Setup ===<br />
You will need to log into your SQL Server in order to run the install or upgrade scripts.<br />
<br />
==== New 6.0 Database ====<br />
<br />
You will find 6 files in the DatabaseFiles folder. These files will be used to create the database structure as well as the necessary meatadata to get starter running Caisis.<br />
This version of Caisis uses SQL files to create the database structure, import metadata (lookup codes, table and field level metadata).<br />
<br />
# _README.txt<br />
# 1_BuildDatabaseObjects.sql<br />
# 2_SecurityData.sql<br />
# 3_Metadata.sql<br />
# 4_CTCAE_TableData.sql<br />
# 5_GrantPermissions.sql<br />
<br />
To setup the database, you will first have to login to the database server as an Administrator and create the base database and login for the application. The follow steps will guide you through creating and setting up the Caisis database using the [http://www.microsoft.com/downloads/details.aspx?FamilyID=08E52AC2-1D62-45F6-9A4A-4B76A8564A2B&displaylang=en Microsoft® SQL Server® 2008 Management Studio Express] tool.<br />
<br />
'''IMPORTANT:''' Make sure when running the creation/upgrade script, to select the Caisis database from the available database drop down menu.<br />
[[Image:db_setup3.jpg|thumb|none|650px|baseline|alt=|Open the DatabaseFiles folder from the Caisis download folder, which includes the README and sql files.]]<br />
[[Image:db_setup1.jpg|thumb|none|650px|baseline|alt=|Log into database server as Server Administrator, i.e., "sa"]]<br />
[[Image:db_setup4.jpg|thumb|none|650px|baseline|alt=|Create a new database]]<br />
[[Image:db_setup5.jpg|thumb|none|650px|baseline|alt=|Give the new database a name]]<br />
[[Image:db_setup7.jpg|thumb|none|650px|baseline|alt=|Ensure the correct '''Collation''' and '''Compatibility Levels''' are set.]]<br />
[[Image:db_setup8.jpg|thumb|none|650px|baseline|alt=|The new database will now show up in the list of available databases.]]<br />
[[Image:db_setup2.jpg|thumb|none|650px|baseline|alt=|Create a new Server Login]]<br />
[[Image:db_setup10.jpg|thumb|none|650px|baseline|alt=|This login will be the account used by the web application to connect to the database.]]<br />
'''Recommended Password Policy'''<br />
<br />
Information regarding what comprises a strong password when the box is checked can be found [http://msdn.microsoft.com/en-us/library/ms161959.aspx here].<br />
<br />
# Enforce password policy - '''checked'''<br />
# Enforce password expiration - '''unchecked'''<br />
# User must change password at next login - '''unchecked'''<br />
<br />
<br />
[[Image:db_setup11.jpg|thumb|none|650px|baseline|alt=|Ensure the login has '''datareader''' and '''datawriter''' role for the Caisis database.]]<br />
[[Image:db_setup12.jpg|thumb|none|650px|baseline|alt=|The new login will now show up in the Security node of the database server.]]<br />
[[Image:db_setup13.jpg|thumb|none|650px|baseline|alt=|The next step is to open the list of SQL files required to create the database tables. NOTE: Select the Caisis database from active database drop down before running scripts.]]<br />
[[Image:db_setup14.jpg|thumb|none|650px|baseline|alt=|Run the list of files sequentially until all are completed.]]<br />
[[Image:db_setup15.jpg|thumb|none|650px|baseline|alt=|The first script will create the database structure.]]<br />
'''NOTE:''' Ensure the correct database which your created is selected when running the database creation scripts.<br />
<br />
<br />
[[Image:db_setup16.jpg|thumb|none|650px|baseline|alt=|The last script will ensure the new login you created can access the Caisis database. NOTE: adjust the username variable to the new login created.]]<br />
[[Image:db_setup17.jpg|thumb|none|650px|baseline|alt=|After the scripts have run, you will now have all the Caisis system tables, metadata and lookup codes.]]<br />
<br />
==== Upgrade from 5.0.2 to 6.0 ====<br />
The upgrade process from 5.0.2 to 6.0 is similar to the new install. The files included will update your 5.0.2 database to a 6.0 database preserving your metadata and lookupcodes (vocabulary). We will expand on these instructions soon - in the meantime please follow the upgrade instructions included in the readme.txt file. Be sure to BACKUP your existing Caisis before proceeding!<br />
<br />
# _README.txt<br />
# 1 5.0.2_to_6.0_upgrade_script.sql<br />
# 2 GrantPermissions.sql<br />
# 3 ImportMetadata.sql<br />
# ChangeLog.xls<br />
# IndividualScriptFiles(folder of individual upgrade scripts)<br />
<br />
'''NOTE:''' The database must be 5.0.2 before proceeding with the update scripts. Older databases will have to be upgraded incrementally to 5.0 before proceeding.<br />
<br />
'''IMPORTANT:''' Make sure when running the creation/upgrade script, to select the Caisis database from the available database drop down menu.<br />
<br />
==== Database Connection String ====<br />
There are two primary ways for the application to connect to the datbase. You can use standard security or a trusted connection. The parameters used in the web.config "dbConnectionString" key will vary accordingly. <br />
# Standard Security: <br />
<add key="dbConnectionString" value="SERVER=<<yourcaisisservername>>,<<port#>>;DATABASE=Caisis;PWD=<<yourpassword>>;UID=<<yourdb username>>;persist security info=True;packet size=4096;" /><br />
<br />
# Trusted Connection: <br />
<add key="dbConnectionString" value="SERVER=<<ourcaisisservername>>,<<port#>>; Initial Catalog= Caisis; Integrated Security=SSPI;<br />
persist security info=True;packet size=4096;"/><br />
<br />
If using the trusted connection, you will also have to create a windows domain account and in some cases assign that domain account to the Application Pool in IIS. <br />
<br />
More detail on connection string syntax can be found here: http://www.sqlstrings.com/SQL-Server-connection-strings.htm<br />
<br />
=== Web Application Setup ===<br />
==== Using Windows Installer ====<br />
Before beginning the installation, please make sure IIS is running and that you have permissions to the modify settings. Caisis comes packed in a Windows Installer file which will install the application through a series of steps. The installer will setup your virtual directory in IIS for hosting Caisis and then launch the '''[[Caisis Configuration Utility]]''', a desktop application which will allow you to to modify various settings in your application, such as Institution settings, Email settings, Database settings and Error Handling. It will also allow you to test the connection from the web app to the Database. <br />
<br />
Once the settings are saved, the installer will end and launch the application in a new browser.<br />
<br />
<br />
'''IMPORTANT''' (Vista and Windows 7 Users): If the installer fails, please verify the "IIS Metabase and IIS6 Configuration Compatibility" feature is enabled as seen below.<br />
*Start > type "Turn Windows features on or off"<br />
* Then turn on feature, "Internet Information Services" > "Web Management Tools" > "IIS 6 Management Compatibility" > "IIS Metabase and IIS6 Configuration Compatibility"<br />
<br />
[[File:IIS6_Compatibility_WindowsInstaller.PNG]] <br />
<br />
<br />
[[Image:Installer_1.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_2.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_3.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_4.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_5.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_6.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_7.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_8.jpg|thumb|none|650px|baseline|alt=|]]<br />
<br />
Note, it is NOT necessary to add all the variables in the Caisis Configuration Utility during setup. The can be modified anytime by:<br />
<br />
* The '''[[Caisis Configuration Utility]]''' will be located in the user's program files directory and can be launched anytime to mange the settings in your web.config file.<br />
* The same installation parameters can also be modified anytime by opening the web.config file found in the web root directly<br />
<br />
'''NOTE:''' You will need to log in to the server as an administrator to install Caisis using the provided Windows Installer.<br />
<br />
==== Manual Deployment For New Installations ====<br />
If you need to manually configure the application, you can create a virtual directory in IIS and place the files contained in the Upgrade/WebApp Folder in there. You will also need to verify that your application is running under ASP.NET 2.0. You can check this, and other web site properties, by opening IIS, find the Caisis web site, right clicking on it and choose properties. When the dialogue box opens select the "ASP.NET" tab and check that 2.0 appears in the drop down box.<br />
<br />
==== Manual Deployment For Upgrades (or experienced server admins) ====<br />
<br />
<br />
1) Backup your existing web files <br />
<br />
2) Delete all files other than your "web.config" file. <br />
<br />
3) Copy all the “FilesForCopyToWebRoot” that you downloaded to your web root, but do not overwrite your web.config file.<br />
<br />
4) View the "keys" in your web.config file (<appSettings key=””>). If new "keys" exist in the web.config you downloaded, insert them into your web.config file. The most important keys are:<br />
a. dbConnectionString<br />
b. institutionName<br />
c. institutionShortName<br />
d. mailServer<br />
e. adminEmail<br />
f. UseSmtpAuthentication<br />
g. smtpUsername<br />
h. smtpPassword<br />
i. emailErrors<br />
j. errorEmail<br />
<br />
5) If you made custom configurations: The App_Data folder contains configuration files. If you made any local configurations, copy the .xml files you modified over the ones provided in the upgrade. Note, the new EformRegistry.xml, PaperFormRegisry.xml, and CannedReports.xml files may register new forms/reports added in the recent release. If the entire file is overwritten these new items will not be accessible.<br />
<br />
6) If you made custom programmatic changes: Copy any additional programmatic changes you have made into the new release. Typically this is local customizations to eForms, or entirely new eForms. Be sure to copy both the “ascx” and “ascx.cs” files in the directory. <br />
<br />
Please note, if you made extensive programmatic changes to your copy of system and they were not provided back to Caisis team for integration into the next release, you will likely need to reintegrate your changes into the source code of the latest version, compile and publish your application.<br />
<br />
== Confirm Application Running ==<br />
After running the Setup file, a web page will launch to your application. The typical URL of your application will be http://'''machine_name'''/'''virtual_directory'''/Login.aspx<br />
If you application was installed on machine ONYX in the virtual directory Caisis, your application would be located at http://onyx/Caisis/Login.aspx. If you receive any errors, you can consult the [[Troubleshooting]] page for help diagnosing the issues.<br />
<br />
[[Image:post_install_web.jpg|thumb|none|650px|baseline|alt=|After the installation, the application can be browsed at http://localhost/caisis_virtual_directory/Login.aspx]]<br />
<br />
== Grant Write Access ==<br />
In order to upload files and display dynamic charts, you must give read/write access to the IIS user for the specified charting and file upload folders.<br />
<br />
The file upload folder may also contain files/documents edited by the application, or outside sources, that would require the folder to have read/write access.<br />
<br />
The default name (specified in the web.config file) for the file upload folder is '''FileUploads'''.<br />
The default location within the web application files is '''App_Data/FileUploads'''.<br />
To give the FileUploads folder modify/write permissions:<br />
<br />
1. Go to the '''App_Data/FileUploads''' directory in the web application files<br />
2. Right click on the '''FileUploads''' folder<br />
3. Select '''Properties'''<br />
4. Select the '''Security''' tab<br />
5. Ensure the appropriate IIS user or Users group has both '''Modify''' and '''Write''' permissions selected for the folder</div>Delvinkhttp://caisis.org/wiki/index.php?title=InstallationInstallation2012-05-23T17:00:09Z<p>Delvink: /* Grant Write Access */</p>
<hr />
<div>Translations: [[Installation_41_it|italiano]] - [[Installation_fr|français]]<br />
<br />
Caisis is an ASP.NET web application with a SQL Server backend. Browser support includes Internet Explorer 6,7,8, FireFox 2+, and Safari 3.0+ for the Mac. We are working on Chrome compatibility. <br />
<br />
Caisis was built to scale to from single users to thousands, and the number of users and performance expectations should be considered when selecting hardware. At minimum, the Caisis database and web server can be run on the same server with 5 GB of free hard drive space and 2 GB of RAM. Using SQL Server 2005 Express in place of the Enterprise version allows groups to get up and running at no cost (assuming you have a Windows Server with IIS installed). Note, SQL Server express although free, has limitations on the number of simultaneous connections and no integrated backup tools. <br />
<br />
This page will guide you through the installation of the database and web application.<br />
<br />
<br />
== Installation Prerequisites ==<br />
<br />
===.NET Framework ===<br />
* [http://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=en .NET 3.5 Framework Service Pack 1]<br />
<br />
===Database Server===<br />
* Microsoft SQL Server 2008, 2005 or Express (with limitations: see Microsoft Web Site)<br />
<br />
===Web Server===<br />
* Microsoft Windows 2008, 2003 or XP<br />
* Microsoft Internet Information Services (IIS) 6 or Greater<br />
<br />
'''NOTES'''<br />
* The database and web server can be on the same or different physical machines<br />
* .NET 3.5 (required by Caisis) is not supported under Windows 2000.<br />
* II5 is also not suppored by the .NET 3.5 Framework<br />
<br />
== Downloads ==<br />
Caisis 6.0 can be downloaded as a zip package, which contains the files needed to setup the database and web application.<br />
<br />
There are 3 packages available for download:<br />
==== Caisis 6.0 - New Installation ====<br />
*'''Installer:''' Contains the Windows Installer file for a standard installation.<br />
*'''Database:''' Contains the Database sql script files needed to create and install the Caisis 6.0 database.<br />
<br />
==== Caisis 6.0 - Upgrade from Caisis 5.0.2 ====<br />
*'''WebApp:''' Contains the web application files if you prefer to manually copy (recommended) the Caisis files to a registered IIS web root instead of running the Installer file. See the '''Manual Deployment for Upgrades''' section of this page for step by step instruction. <br />
*'''Installer:''' Contains the Windows Installer file for a standard installation. Before running the install, you may have to uninstall prior versions of Caisis using Control Panel:Add/Remove programs<br />
*'''Database:''' Contains the Database sql script files needed to upgrade your Caisis 5.0.2 Database to the Caisis 6.0 Database.<br />
<br />
* NOTE: The above also applies when upgrading from version 4.5 to 5.0.2 To upgrade the database to 6.0 from an older version of the Caisis database, you '''must''' run the appropriate scripts between versions, as this ensures the data is moved correctly, and metadata is preserved.<br />
<br />
Example: To upgrade from Version 4.1 to 5.0.2<br />
4.1 -> 4.5 -> 5.0.2<br />
Example: To upgrade from Version 4.0 to 6.0<br />
4.0 -> 4.1 -> 4.5 -> 5.0.2 -> 6.0<br />
<br />
==== Caisis 6.0 Source Files ====<br />
Contains the Visual Studio Solution file and source code used to build and modify Caisis.<br />
<br />
== Setup ==<br />
<br />
=== Database Setup ===<br />
You will need to log into your SQL Server in order to run the install or upgrade scripts.<br />
<br />
==== New 6.0 Database ====<br />
<br />
You will find 6 files in the DatabaseFiles folder. These files will be used to create the database structure as well as the necessary meatadata to get starter running Caisis.<br />
This version of Caisis uses SQL files to create the database structure, import metadata (lookup codes, table and field level metadata).<br />
<br />
# _README.txt<br />
# 1_BuildDatabaseObjects.sql<br />
# 2_SecurityData.sql<br />
# 3_Metadata.sql<br />
# 4_CTCAE_TableData.sql<br />
# 5_GrantPermissions.sql<br />
<br />
To setup the database, you will first have to login to the database server as an Administrator and create the base database and login for the application. The follow steps will guide you through creating and setting up the Caisis database using the [http://www.microsoft.com/downloads/details.aspx?FamilyID=08E52AC2-1D62-45F6-9A4A-4B76A8564A2B&displaylang=en Microsoft® SQL Server® 2008 Management Studio Express] tool.<br />
<br />
'''IMPORTANT:''' Make sure when running the creation/upgrade script, to select the Caisis database from the available database drop down menu.<br />
[[Image:db_setup3.jpg|thumb|none|650px|baseline|alt=|Open the DatabaseFiles folder from the Caisis download folder, which includes the README and sql files.]]<br />
[[Image:db_setup1.jpg|thumb|none|650px|baseline|alt=|Log into database server as Server Administrator, i.e., "sa"]]<br />
[[Image:db_setup4.jpg|thumb|none|650px|baseline|alt=|Create a new database]]<br />
[[Image:db_setup5.jpg|thumb|none|650px|baseline|alt=|Give the new database a name]]<br />
[[Image:db_setup7.jpg|thumb|none|650px|baseline|alt=|Ensure the correct '''Collation''' and '''Compatibility Levels''' are set.]]<br />
[[Image:db_setup8.jpg|thumb|none|650px|baseline|alt=|The new database will now show up in the list of available databases.]]<br />
[[Image:db_setup2.jpg|thumb|none|650px|baseline|alt=|Create a new Server Login]]<br />
[[Image:db_setup10.jpg|thumb|none|650px|baseline|alt=|This login will be the account used by the web application to connect to the database.]]<br />
'''Recommended Password Policy'''<br />
<br />
Information regarding what comprises a strong password when the box is checked can be found [http://msdn.microsoft.com/en-us/library/ms161959.aspx here].<br />
<br />
# Enforce password policy - '''checked'''<br />
# Enforce password expiration - '''unchecked'''<br />
# User must change password at next login - '''unchecked'''<br />
<br />
<br />
[[Image:db_setup11.jpg|thumb|none|650px|baseline|alt=|Ensure the login has '''datareader''' and '''datawriter''' role for the Caisis database.]]<br />
[[Image:db_setup12.jpg|thumb|none|650px|baseline|alt=|The new login will now show up in the Security node of the database server.]]<br />
[[Image:db_setup13.jpg|thumb|none|650px|baseline|alt=|The next step is to open the list of SQL files required to create the database tables. NOTE: Select the Caisis database from active database drop down before running scripts.]]<br />
[[Image:db_setup14.jpg|thumb|none|650px|baseline|alt=|Run the list of files sequentially until all are completed.]]<br />
[[Image:db_setup15.jpg|thumb|none|650px|baseline|alt=|The first script will create the database structure.]]<br />
'''NOTE:''' Ensure the correct database which your created is selected when running the database creation scripts.<br />
<br />
<br />
[[Image:db_setup16.jpg|thumb|none|650px|baseline|alt=|The last script will ensure the new login you created can access the Caisis database. NOTE: adjust the username variable to the new login created.]]<br />
[[Image:db_setup17.jpg|thumb|none|650px|baseline|alt=|After the scripts have run, you will now have all the Caisis system tables, metadata and lookup codes.]]<br />
<br />
==== Upgrade from 5.0.2 to 6.0 ====<br />
The upgrade process from 5.0.2 to 6.0 is similar to the new install. The files included will update your 5.0.2 database to a 6.0 database preserving your metadata and lookupcodes (vocabulary). We will expand on these instructions soon - in the meantime please follow the upgrade instructions included in the readme.txt file. Be sure to BACKUP your existing Caisis before proceeding!<br />
<br />
# _README.txt<br />
# 1 5.0.2_to_6.0_upgrade_script.sql<br />
# 2 GrantPermissions.sql<br />
# 3 ImportMetadata.sql<br />
# ChangeLog.xls<br />
# IndividualScriptFiles(folder of individual upgrade scripts)<br />
<br />
'''NOTE:''' The database must be 5.0.2 before proceeding with the update scripts. Older databases will have to be upgraded incrementally to 5.0 before proceeding.<br />
<br />
'''IMPORTANT:''' Make sure when running the creation/upgrade script, to select the Caisis database from the available database drop down menu.<br />
<br />
==== Database Connection String ====<br />
There are two primary ways for the application to connect to the datbase. You can use standard security or a trusted connection. The parameters used in the web.config "dbConnectionString" key will vary accordingly. <br />
# Standard Security: <br />
<add key="dbConnectionString" value="SERVER=<<yourcaisisservername>>,<<port#>>;DATABASE=Caisis;PWD=<<yourpassword>>;UID=<<yourdb username>>;persist security info=True;packet size=4096;" /><br />
<br />
# Trusted Connection: <br />
<add key="dbConnectionString" value="SERVER=<<ourcaisisservername>>,<<port#>>; Initial Catalog= Caisis; Integrated Security=SSPI;<br />
persist security info=True;packet size=4096;"/><br />
<br />
If using the trusted connection, you will also have to create a windows domain account and in some cases assign that domain account to the Application Pool in IIS. <br />
<br />
More detail on connection string syntax can be found here: http://www.sqlstrings.com/SQL-Server-connection-strings.htm<br />
<br />
=== Web Application Setup ===<br />
==== Using Windows Installer ====<br />
Before beginning the installation, please make sure IIS is running and that you have permissions to the modify settings. Caisis comes packed in a Windows Installer file which will install the application through a series of steps. The installer will setup your virtual directory in IIS for hosting Caisis and then launch the '''[[Caisis Configuration Utility]]''', a desktop application which will allow you to to modify various settings in your application, such as Institution settings, Email settings, Database settings and Error Handling. It will also allow you to test the connection from the web app to the Database. <br />
<br />
Once the settings are saved, the installer will end and launch the application in a new browser.<br />
<br />
<br />
'''IMPORTANT''' (Vista and Windows 7 Users): If the installer fails, please verify the "IIS Metabase and IIS6 Configuration Compatibility" feature is enabled as seen below.<br />
*Start > type "Turn Windows features on or off"<br />
* Then turn on feature, "Internet Information Services" > "Web Management Tools" > "IIS 6 Management Compatibility" > "IIS Metabase and IIS6 Configuration Compatibility"<br />
<br />
[[File:IIS6_Compatibility_WindowsInstaller.PNG]] <br />
<br />
<br />
[[Image:Installer_1.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_2.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_3.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_4.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_5.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_6.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_7.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_8.jpg|thumb|none|650px|baseline|alt=|]]<br />
<br />
Note, it is NOT necessary to add all the variables in the Caisis Configuration Utility during setup. The can be modified anytime by:<br />
<br />
* The '''[[Caisis Configuration Utility]]''' will be located in the user's program files directory and can be launched anytime to mange the settings in your web.config file.<br />
* The same installation parameters can also be modified anytime by opening the web.config file found in the web root directly<br />
<br />
'''NOTE:''' You will need to log in to the server as an administrator to install Caisis using the provided Windows Installer.<br />
<br />
==== Manual Deployment For New Installations ====<br />
If you need to manually configure the application, you can create a virtual directory in IIS and place the files contained in the Upgrade/WebApp Folder in there. You will also need to verify that your application is running under ASP.NET 2.0. You can check this, and other web site properties, by opening IIS, find the Caisis web site, right clicking on it and choose properties. When the dialogue box opens select the "ASP.NET" tab and check that 2.0 appears in the drop down box.<br />
<br />
==== Manual Deployment For Upgrades (or experienced server admins) ====<br />
<br />
<br />
1) Backup your existing web files <br />
<br />
2) Delete all files other than your "web.config" file. <br />
<br />
3) Copy all the “FilesForCopyToWebRoot” that you downloaded to your web root, but do not overwrite your web.config file.<br />
<br />
4) View the "keys" in your web.config file (<appSettings key=””>). If new "keys" exist in the web.config you downloaded, insert them into your web.config file. The most important keys are:<br />
a. dbConnectionString<br />
b. institutionName<br />
c. institutionShortName<br />
d. mailServer<br />
e. adminEmail<br />
f. UseSmtpAuthentication<br />
g. smtpUsername<br />
h. smtpPassword<br />
i. emailErrors<br />
j. errorEmail<br />
<br />
5) If you made custom configurations: The App_Data folder contains configuration files. If you made any local configurations, copy the .xml files you modified over the ones provided in the upgrade. Note, the new EformRegistry.xml, PaperFormRegisry.xml, and CannedReports.xml files may register new forms/reports added in the recent release. If the entire file is overwritten these new items will not be accessible.<br />
<br />
6) If you made custom programmatic changes: Copy any additional programmatic changes you have made into the new release. Typically this is local customizations to eForms, or entirely new eForms. Be sure to copy both the “ascx” and “ascx.cs” files in the directory. <br />
<br />
Please note, if you made extensive programmatic changes to your copy of system and they were not provided back to Caisis team for integration into the next release, you will likely need to reintegrate your changes into the source code of the latest version, compile and publish your application.<br />
<br />
== Confirm Application Running ==<br />
After running the Setup file, a web page will launch to your application. The typical URL of your application will be http://'''machine_name'''/'''virtual_directory'''/Login.aspx<br />
If you application was installed on machine ONYX in the virtual directory Caisis, your application would be located at http://onyx/Caisis/Login.aspx. If you receive any errors, you can consult the [[Troubleshooting]] page for help diagnosing the issues.<br />
<br />
[[Image:post_install_web.jpg|thumb|none|650px|baseline|alt=|After the installation, the application can be browsed at http://localhost/caisis_virtual_directory/Login.aspx]]<br />
<br />
== Grant Write Access ==<br />
In order to upload files and display dynamic charts, you must give read/write access to the IIS user for the specified charting and file upload folders.<br />
<br />
The file upload folder may also contain files/documents edited by the application, or outside sources, that would require the folder to have read/write access.<br />
<br />
The default name (specified in the web.config file) for the file upload folder is '''FileUploads'''.<br />
The default location within the web application files is '''App_Data/FileUploads'''.<br />
To give the FileUploads folder modify/write permissions:<br />
<br />
1. Go to the '''App_Data/FileUploads''' directory in the web application files<br />
2. Right click on the '''FileUploads''' folder<br />
3. Select '''Properties'''<br />
4. Select the '''Security''' tab<br />
5. Ensure the appropriate IIS user or Users group has both Modify and Write permissions selected for the folder</div>Delvinkhttp://caisis.org/wiki/index.php?title=InstallationInstallation2012-05-23T16:58:46Z<p>Delvink: /* Grant Write Access */</p>
<hr />
<div>Translations: [[Installation_41_it|italiano]] - [[Installation_fr|français]]<br />
<br />
Caisis is an ASP.NET web application with a SQL Server backend. Browser support includes Internet Explorer 6,7,8, FireFox 2+, and Safari 3.0+ for the Mac. We are working on Chrome compatibility. <br />
<br />
Caisis was built to scale to from single users to thousands, and the number of users and performance expectations should be considered when selecting hardware. At minimum, the Caisis database and web server can be run on the same server with 5 GB of free hard drive space and 2 GB of RAM. Using SQL Server 2005 Express in place of the Enterprise version allows groups to get up and running at no cost (assuming you have a Windows Server with IIS installed). Note, SQL Server express although free, has limitations on the number of simultaneous connections and no integrated backup tools. <br />
<br />
This page will guide you through the installation of the database and web application.<br />
<br />
<br />
== Installation Prerequisites ==<br />
<br />
===.NET Framework ===<br />
* [http://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=en .NET 3.5 Framework Service Pack 1]<br />
<br />
===Database Server===<br />
* Microsoft SQL Server 2008, 2005 or Express (with limitations: see Microsoft Web Site)<br />
<br />
===Web Server===<br />
* Microsoft Windows 2008, 2003 or XP<br />
* Microsoft Internet Information Services (IIS) 6 or Greater<br />
<br />
'''NOTES'''<br />
* The database and web server can be on the same or different physical machines<br />
* .NET 3.5 (required by Caisis) is not supported under Windows 2000.<br />
* II5 is also not suppored by the .NET 3.5 Framework<br />
<br />
== Downloads ==<br />
Caisis 6.0 can be downloaded as a zip package, which contains the files needed to setup the database and web application.<br />
<br />
There are 3 packages available for download:<br />
==== Caisis 6.0 - New Installation ====<br />
*'''Installer:''' Contains the Windows Installer file for a standard installation.<br />
*'''Database:''' Contains the Database sql script files needed to create and install the Caisis 6.0 database.<br />
<br />
==== Caisis 6.0 - Upgrade from Caisis 5.0.2 ====<br />
*'''WebApp:''' Contains the web application files if you prefer to manually copy (recommended) the Caisis files to a registered IIS web root instead of running the Installer file. See the '''Manual Deployment for Upgrades''' section of this page for step by step instruction. <br />
*'''Installer:''' Contains the Windows Installer file for a standard installation. Before running the install, you may have to uninstall prior versions of Caisis using Control Panel:Add/Remove programs<br />
*'''Database:''' Contains the Database sql script files needed to upgrade your Caisis 5.0.2 Database to the Caisis 6.0 Database.<br />
<br />
* NOTE: The above also applies when upgrading from version 4.5 to 5.0.2 To upgrade the database to 6.0 from an older version of the Caisis database, you '''must''' run the appropriate scripts between versions, as this ensures the data is moved correctly, and metadata is preserved.<br />
<br />
Example: To upgrade from Version 4.1 to 5.0.2<br />
4.1 -> 4.5 -> 5.0.2<br />
Example: To upgrade from Version 4.0 to 6.0<br />
4.0 -> 4.1 -> 4.5 -> 5.0.2 -> 6.0<br />
<br />
==== Caisis 6.0 Source Files ====<br />
Contains the Visual Studio Solution file and source code used to build and modify Caisis.<br />
<br />
== Setup ==<br />
<br />
=== Database Setup ===<br />
You will need to log into your SQL Server in order to run the install or upgrade scripts.<br />
<br />
==== New 6.0 Database ====<br />
<br />
You will find 6 files in the DatabaseFiles folder. These files will be used to create the database structure as well as the necessary meatadata to get starter running Caisis.<br />
This version of Caisis uses SQL files to create the database structure, import metadata (lookup codes, table and field level metadata).<br />
<br />
# _README.txt<br />
# 1_BuildDatabaseObjects.sql<br />
# 2_SecurityData.sql<br />
# 3_Metadata.sql<br />
# 4_CTCAE_TableData.sql<br />
# 5_GrantPermissions.sql<br />
<br />
To setup the database, you will first have to login to the database server as an Administrator and create the base database and login for the application. The follow steps will guide you through creating and setting up the Caisis database using the [http://www.microsoft.com/downloads/details.aspx?FamilyID=08E52AC2-1D62-45F6-9A4A-4B76A8564A2B&displaylang=en Microsoft® SQL Server® 2008 Management Studio Express] tool.<br />
<br />
'''IMPORTANT:''' Make sure when running the creation/upgrade script, to select the Caisis database from the available database drop down menu.<br />
[[Image:db_setup3.jpg|thumb|none|650px|baseline|alt=|Open the DatabaseFiles folder from the Caisis download folder, which includes the README and sql files.]]<br />
[[Image:db_setup1.jpg|thumb|none|650px|baseline|alt=|Log into database server as Server Administrator, i.e., "sa"]]<br />
[[Image:db_setup4.jpg|thumb|none|650px|baseline|alt=|Create a new database]]<br />
[[Image:db_setup5.jpg|thumb|none|650px|baseline|alt=|Give the new database a name]]<br />
[[Image:db_setup7.jpg|thumb|none|650px|baseline|alt=|Ensure the correct '''Collation''' and '''Compatibility Levels''' are set.]]<br />
[[Image:db_setup8.jpg|thumb|none|650px|baseline|alt=|The new database will now show up in the list of available databases.]]<br />
[[Image:db_setup2.jpg|thumb|none|650px|baseline|alt=|Create a new Server Login]]<br />
[[Image:db_setup10.jpg|thumb|none|650px|baseline|alt=|This login will be the account used by the web application to connect to the database.]]<br />
'''Recommended Password Policy'''<br />
<br />
Information regarding what comprises a strong password when the box is checked can be found [http://msdn.microsoft.com/en-us/library/ms161959.aspx here].<br />
<br />
# Enforce password policy - '''checked'''<br />
# Enforce password expiration - '''unchecked'''<br />
# User must change password at next login - '''unchecked'''<br />
<br />
<br />
[[Image:db_setup11.jpg|thumb|none|650px|baseline|alt=|Ensure the login has '''datareader''' and '''datawriter''' role for the Caisis database.]]<br />
[[Image:db_setup12.jpg|thumb|none|650px|baseline|alt=|The new login will now show up in the Security node of the database server.]]<br />
[[Image:db_setup13.jpg|thumb|none|650px|baseline|alt=|The next step is to open the list of SQL files required to create the database tables. NOTE: Select the Caisis database from active database drop down before running scripts.]]<br />
[[Image:db_setup14.jpg|thumb|none|650px|baseline|alt=|Run the list of files sequentially until all are completed.]]<br />
[[Image:db_setup15.jpg|thumb|none|650px|baseline|alt=|The first script will create the database structure.]]<br />
'''NOTE:''' Ensure the correct database which your created is selected when running the database creation scripts.<br />
<br />
<br />
[[Image:db_setup16.jpg|thumb|none|650px|baseline|alt=|The last script will ensure the new login you created can access the Caisis database. NOTE: adjust the username variable to the new login created.]]<br />
[[Image:db_setup17.jpg|thumb|none|650px|baseline|alt=|After the scripts have run, you will now have all the Caisis system tables, metadata and lookup codes.]]<br />
<br />
==== Upgrade from 5.0.2 to 6.0 ====<br />
The upgrade process from 5.0.2 to 6.0 is similar to the new install. The files included will update your 5.0.2 database to a 6.0 database preserving your metadata and lookupcodes (vocabulary). We will expand on these instructions soon - in the meantime please follow the upgrade instructions included in the readme.txt file. Be sure to BACKUP your existing Caisis before proceeding!<br />
<br />
# _README.txt<br />
# 1 5.0.2_to_6.0_upgrade_script.sql<br />
# 2 GrantPermissions.sql<br />
# 3 ImportMetadata.sql<br />
# ChangeLog.xls<br />
# IndividualScriptFiles(folder of individual upgrade scripts)<br />
<br />
'''NOTE:''' The database must be 5.0.2 before proceeding with the update scripts. Older databases will have to be upgraded incrementally to 5.0 before proceeding.<br />
<br />
'''IMPORTANT:''' Make sure when running the creation/upgrade script, to select the Caisis database from the available database drop down menu.<br />
<br />
==== Database Connection String ====<br />
There are two primary ways for the application to connect to the datbase. You can use standard security or a trusted connection. The parameters used in the web.config "dbConnectionString" key will vary accordingly. <br />
# Standard Security: <br />
<add key="dbConnectionString" value="SERVER=<<yourcaisisservername>>,<<port#>>;DATABASE=Caisis;PWD=<<yourpassword>>;UID=<<yourdb username>>;persist security info=True;packet size=4096;" /><br />
<br />
# Trusted Connection: <br />
<add key="dbConnectionString" value="SERVER=<<ourcaisisservername>>,<<port#>>; Initial Catalog= Caisis; Integrated Security=SSPI;<br />
persist security info=True;packet size=4096;"/><br />
<br />
If using the trusted connection, you will also have to create a windows domain account and in some cases assign that domain account to the Application Pool in IIS. <br />
<br />
More detail on connection string syntax can be found here: http://www.sqlstrings.com/SQL-Server-connection-strings.htm<br />
<br />
=== Web Application Setup ===<br />
==== Using Windows Installer ====<br />
Before beginning the installation, please make sure IIS is running and that you have permissions to the modify settings. Caisis comes packed in a Windows Installer file which will install the application through a series of steps. The installer will setup your virtual directory in IIS for hosting Caisis and then launch the '''[[Caisis Configuration Utility]]''', a desktop application which will allow you to to modify various settings in your application, such as Institution settings, Email settings, Database settings and Error Handling. It will also allow you to test the connection from the web app to the Database. <br />
<br />
Once the settings are saved, the installer will end and launch the application in a new browser.<br />
<br />
<br />
'''IMPORTANT''' (Vista and Windows 7 Users): If the installer fails, please verify the "IIS Metabase and IIS6 Configuration Compatibility" feature is enabled as seen below.<br />
*Start > type "Turn Windows features on or off"<br />
* Then turn on feature, "Internet Information Services" > "Web Management Tools" > "IIS 6 Management Compatibility" > "IIS Metabase and IIS6 Configuration Compatibility"<br />
<br />
[[File:IIS6_Compatibility_WindowsInstaller.PNG]] <br />
<br />
<br />
[[Image:Installer_1.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_2.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_3.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_4.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_5.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_6.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_7.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_8.jpg|thumb|none|650px|baseline|alt=|]]<br />
<br />
Note, it is NOT necessary to add all the variables in the Caisis Configuration Utility during setup. The can be modified anytime by:<br />
<br />
* The '''[[Caisis Configuration Utility]]''' will be located in the user's program files directory and can be launched anytime to mange the settings in your web.config file.<br />
* The same installation parameters can also be modified anytime by opening the web.config file found in the web root directly<br />
<br />
'''NOTE:''' You will need to log in to the server as an administrator to install Caisis using the provided Windows Installer.<br />
<br />
==== Manual Deployment For New Installations ====<br />
If you need to manually configure the application, you can create a virtual directory in IIS and place the files contained in the Upgrade/WebApp Folder in there. You will also need to verify that your application is running under ASP.NET 2.0. You can check this, and other web site properties, by opening IIS, find the Caisis web site, right clicking on it and choose properties. When the dialogue box opens select the "ASP.NET" tab and check that 2.0 appears in the drop down box.<br />
<br />
==== Manual Deployment For Upgrades (or experienced server admins) ====<br />
<br />
<br />
1) Backup your existing web files <br />
<br />
2) Delete all files other than your "web.config" file. <br />
<br />
3) Copy all the “FilesForCopyToWebRoot” that you downloaded to your web root, but do not overwrite your web.config file.<br />
<br />
4) View the "keys" in your web.config file (<appSettings key=””>). If new "keys" exist in the web.config you downloaded, insert them into your web.config file. The most important keys are:<br />
a. dbConnectionString<br />
b. institutionName<br />
c. institutionShortName<br />
d. mailServer<br />
e. adminEmail<br />
f. UseSmtpAuthentication<br />
g. smtpUsername<br />
h. smtpPassword<br />
i. emailErrors<br />
j. errorEmail<br />
<br />
5) If you made custom configurations: The App_Data folder contains configuration files. If you made any local configurations, copy the .xml files you modified over the ones provided in the upgrade. Note, the new EformRegistry.xml, PaperFormRegisry.xml, and CannedReports.xml files may register new forms/reports added in the recent release. If the entire file is overwritten these new items will not be accessible.<br />
<br />
6) If you made custom programmatic changes: Copy any additional programmatic changes you have made into the new release. Typically this is local customizations to eForms, or entirely new eForms. Be sure to copy both the “ascx” and “ascx.cs” files in the directory. <br />
<br />
Please note, if you made extensive programmatic changes to your copy of system and they were not provided back to Caisis team for integration into the next release, you will likely need to reintegrate your changes into the source code of the latest version, compile and publish your application.<br />
<br />
== Confirm Application Running ==<br />
After running the Setup file, a web page will launch to your application. The typical URL of your application will be http://'''machine_name'''/'''virtual_directory'''/Login.aspx<br />
If you application was installed on machine ONYX in the virtual directory Caisis, your application would be located at http://onyx/Caisis/Login.aspx. If you receive any errors, you can consult the [[Troubleshooting]] page for help diagnosing the issues.<br />
<br />
[[Image:post_install_web.jpg|thumb|none|650px|baseline|alt=|After the installation, the application can be browsed at http://localhost/caisis_virtual_directory/Login.aspx]]<br />
<br />
== Grant Write Access ==<br />
In order to upload files and display dynamic charts, you must give read/write access to the IIS user for the specified charting and file upload folders.<br />
<br />
The file upload folder may also contain files/documents edited by the application, or outside sources, that would require the folder to have read/write access.<br />
<br />
The default name (specified in the web.config file) for the file upload folder is '''FileUploads'''.<br />
The default location within the web application files is '''App_Data/FileUploads'''.<br />
To give the FileUploads folder modify/write permissions:<br />
<br />
1. Go to the '''App_Data/FileUploads''' directory in the web application files<br />
2. Right click on the '''FileUploads''' folder<br />
3. Select '''Properties'''<br />
4. Select the '''Security''' tab<br />
5. Ensure the appropriate IIS user or Users group has both Modify and Write permissions selected for the folder</div>Delvinkhttp://caisis.org/wiki/index.php?title=InstallationInstallation2012-05-23T16:57:59Z<p>Delvink: /* Grant Write Access */</p>
<hr />
<div>Translations: [[Installation_41_it|italiano]] - [[Installation_fr|français]]<br />
<br />
Caisis is an ASP.NET web application with a SQL Server backend. Browser support includes Internet Explorer 6,7,8, FireFox 2+, and Safari 3.0+ for the Mac. We are working on Chrome compatibility. <br />
<br />
Caisis was built to scale to from single users to thousands, and the number of users and performance expectations should be considered when selecting hardware. At minimum, the Caisis database and web server can be run on the same server with 5 GB of free hard drive space and 2 GB of RAM. Using SQL Server 2005 Express in place of the Enterprise version allows groups to get up and running at no cost (assuming you have a Windows Server with IIS installed). Note, SQL Server express although free, has limitations on the number of simultaneous connections and no integrated backup tools. <br />
<br />
This page will guide you through the installation of the database and web application.<br />
<br />
<br />
== Installation Prerequisites ==<br />
<br />
===.NET Framework ===<br />
* [http://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=en .NET 3.5 Framework Service Pack 1]<br />
<br />
===Database Server===<br />
* Microsoft SQL Server 2008, 2005 or Express (with limitations: see Microsoft Web Site)<br />
<br />
===Web Server===<br />
* Microsoft Windows 2008, 2003 or XP<br />
* Microsoft Internet Information Services (IIS) 6 or Greater<br />
<br />
'''NOTES'''<br />
* The database and web server can be on the same or different physical machines<br />
* .NET 3.5 (required by Caisis) is not supported under Windows 2000.<br />
* II5 is also not suppored by the .NET 3.5 Framework<br />
<br />
== Downloads ==<br />
Caisis 6.0 can be downloaded as a zip package, which contains the files needed to setup the database and web application.<br />
<br />
There are 3 packages available for download:<br />
==== Caisis 6.0 - New Installation ====<br />
*'''Installer:''' Contains the Windows Installer file for a standard installation.<br />
*'''Database:''' Contains the Database sql script files needed to create and install the Caisis 6.0 database.<br />
<br />
==== Caisis 6.0 - Upgrade from Caisis 5.0.2 ====<br />
*'''WebApp:''' Contains the web application files if you prefer to manually copy (recommended) the Caisis files to a registered IIS web root instead of running the Installer file. See the '''Manual Deployment for Upgrades''' section of this page for step by step instruction. <br />
*'''Installer:''' Contains the Windows Installer file for a standard installation. Before running the install, you may have to uninstall prior versions of Caisis using Control Panel:Add/Remove programs<br />
*'''Database:''' Contains the Database sql script files needed to upgrade your Caisis 5.0.2 Database to the Caisis 6.0 Database.<br />
<br />
* NOTE: The above also applies when upgrading from version 4.5 to 5.0.2 To upgrade the database to 6.0 from an older version of the Caisis database, you '''must''' run the appropriate scripts between versions, as this ensures the data is moved correctly, and metadata is preserved.<br />
<br />
Example: To upgrade from Version 4.1 to 5.0.2<br />
4.1 -> 4.5 -> 5.0.2<br />
Example: To upgrade from Version 4.0 to 6.0<br />
4.0 -> 4.1 -> 4.5 -> 5.0.2 -> 6.0<br />
<br />
==== Caisis 6.0 Source Files ====<br />
Contains the Visual Studio Solution file and source code used to build and modify Caisis.<br />
<br />
== Setup ==<br />
<br />
=== Database Setup ===<br />
You will need to log into your SQL Server in order to run the install or upgrade scripts.<br />
<br />
==== New 6.0 Database ====<br />
<br />
You will find 6 files in the DatabaseFiles folder. These files will be used to create the database structure as well as the necessary meatadata to get starter running Caisis.<br />
This version of Caisis uses SQL files to create the database structure, import metadata (lookup codes, table and field level metadata).<br />
<br />
# _README.txt<br />
# 1_BuildDatabaseObjects.sql<br />
# 2_SecurityData.sql<br />
# 3_Metadata.sql<br />
# 4_CTCAE_TableData.sql<br />
# 5_GrantPermissions.sql<br />
<br />
To setup the database, you will first have to login to the database server as an Administrator and create the base database and login for the application. The follow steps will guide you through creating and setting up the Caisis database using the [http://www.microsoft.com/downloads/details.aspx?FamilyID=08E52AC2-1D62-45F6-9A4A-4B76A8564A2B&displaylang=en Microsoft® SQL Server® 2008 Management Studio Express] tool.<br />
<br />
'''IMPORTANT:''' Make sure when running the creation/upgrade script, to select the Caisis database from the available database drop down menu.<br />
[[Image:db_setup3.jpg|thumb|none|650px|baseline|alt=|Open the DatabaseFiles folder from the Caisis download folder, which includes the README and sql files.]]<br />
[[Image:db_setup1.jpg|thumb|none|650px|baseline|alt=|Log into database server as Server Administrator, i.e., "sa"]]<br />
[[Image:db_setup4.jpg|thumb|none|650px|baseline|alt=|Create a new database]]<br />
[[Image:db_setup5.jpg|thumb|none|650px|baseline|alt=|Give the new database a name]]<br />
[[Image:db_setup7.jpg|thumb|none|650px|baseline|alt=|Ensure the correct '''Collation''' and '''Compatibility Levels''' are set.]]<br />
[[Image:db_setup8.jpg|thumb|none|650px|baseline|alt=|The new database will now show up in the list of available databases.]]<br />
[[Image:db_setup2.jpg|thumb|none|650px|baseline|alt=|Create a new Server Login]]<br />
[[Image:db_setup10.jpg|thumb|none|650px|baseline|alt=|This login will be the account used by the web application to connect to the database.]]<br />
'''Recommended Password Policy'''<br />
<br />
Information regarding what comprises a strong password when the box is checked can be found [http://msdn.microsoft.com/en-us/library/ms161959.aspx here].<br />
<br />
# Enforce password policy - '''checked'''<br />
# Enforce password expiration - '''unchecked'''<br />
# User must change password at next login - '''unchecked'''<br />
<br />
<br />
[[Image:db_setup11.jpg|thumb|none|650px|baseline|alt=|Ensure the login has '''datareader''' and '''datawriter''' role for the Caisis database.]]<br />
[[Image:db_setup12.jpg|thumb|none|650px|baseline|alt=|The new login will now show up in the Security node of the database server.]]<br />
[[Image:db_setup13.jpg|thumb|none|650px|baseline|alt=|The next step is to open the list of SQL files required to create the database tables. NOTE: Select the Caisis database from active database drop down before running scripts.]]<br />
[[Image:db_setup14.jpg|thumb|none|650px|baseline|alt=|Run the list of files sequentially until all are completed.]]<br />
[[Image:db_setup15.jpg|thumb|none|650px|baseline|alt=|The first script will create the database structure.]]<br />
'''NOTE:''' Ensure the correct database which your created is selected when running the database creation scripts.<br />
<br />
<br />
[[Image:db_setup16.jpg|thumb|none|650px|baseline|alt=|The last script will ensure the new login you created can access the Caisis database. NOTE: adjust the username variable to the new login created.]]<br />
[[Image:db_setup17.jpg|thumb|none|650px|baseline|alt=|After the scripts have run, you will now have all the Caisis system tables, metadata and lookup codes.]]<br />
<br />
==== Upgrade from 5.0.2 to 6.0 ====<br />
The upgrade process from 5.0.2 to 6.0 is similar to the new install. The files included will update your 5.0.2 database to a 6.0 database preserving your metadata and lookupcodes (vocabulary). We will expand on these instructions soon - in the meantime please follow the upgrade instructions included in the readme.txt file. Be sure to BACKUP your existing Caisis before proceeding!<br />
<br />
# _README.txt<br />
# 1 5.0.2_to_6.0_upgrade_script.sql<br />
# 2 GrantPermissions.sql<br />
# 3 ImportMetadata.sql<br />
# ChangeLog.xls<br />
# IndividualScriptFiles(folder of individual upgrade scripts)<br />
<br />
'''NOTE:''' The database must be 5.0.2 before proceeding with the update scripts. Older databases will have to be upgraded incrementally to 5.0 before proceeding.<br />
<br />
'''IMPORTANT:''' Make sure when running the creation/upgrade script, to select the Caisis database from the available database drop down menu.<br />
<br />
==== Database Connection String ====<br />
There are two primary ways for the application to connect to the datbase. You can use standard security or a trusted connection. The parameters used in the web.config "dbConnectionString" key will vary accordingly. <br />
# Standard Security: <br />
<add key="dbConnectionString" value="SERVER=<<yourcaisisservername>>,<<port#>>;DATABASE=Caisis;PWD=<<yourpassword>>;UID=<<yourdb username>>;persist security info=True;packet size=4096;" /><br />
<br />
# Trusted Connection: <br />
<add key="dbConnectionString" value="SERVER=<<ourcaisisservername>>,<<port#>>; Initial Catalog= Caisis; Integrated Security=SSPI;<br />
persist security info=True;packet size=4096;"/><br />
<br />
If using the trusted connection, you will also have to create a windows domain account and in some cases assign that domain account to the Application Pool in IIS. <br />
<br />
More detail on connection string syntax can be found here: http://www.sqlstrings.com/SQL-Server-connection-strings.htm<br />
<br />
=== Web Application Setup ===<br />
==== Using Windows Installer ====<br />
Before beginning the installation, please make sure IIS is running and that you have permissions to the modify settings. Caisis comes packed in a Windows Installer file which will install the application through a series of steps. The installer will setup your virtual directory in IIS for hosting Caisis and then launch the '''[[Caisis Configuration Utility]]''', a desktop application which will allow you to to modify various settings in your application, such as Institution settings, Email settings, Database settings and Error Handling. It will also allow you to test the connection from the web app to the Database. <br />
<br />
Once the settings are saved, the installer will end and launch the application in a new browser.<br />
<br />
<br />
'''IMPORTANT''' (Vista and Windows 7 Users): If the installer fails, please verify the "IIS Metabase and IIS6 Configuration Compatibility" feature is enabled as seen below.<br />
*Start > type "Turn Windows features on or off"<br />
* Then turn on feature, "Internet Information Services" > "Web Management Tools" > "IIS 6 Management Compatibility" > "IIS Metabase and IIS6 Configuration Compatibility"<br />
<br />
[[File:IIS6_Compatibility_WindowsInstaller.PNG]] <br />
<br />
<br />
[[Image:Installer_1.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_2.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_3.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_4.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_5.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_6.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_7.jpg|thumb|none|650px|baseline|alt=|]]<br />
[[Image:Installer_8.jpg|thumb|none|650px|baseline|alt=|]]<br />
<br />
Note, it is NOT necessary to add all the variables in the Caisis Configuration Utility during setup. The can be modified anytime by:<br />
<br />
* The '''[[Caisis Configuration Utility]]''' will be located in the user's program files directory and can be launched anytime to mange the settings in your web.config file.<br />
* The same installation parameters can also be modified anytime by opening the web.config file found in the web root directly<br />
<br />
'''NOTE:''' You will need to log in to the server as an administrator to install Caisis using the provided Windows Installer.<br />
<br />
==== Manual Deployment For New Installations ====<br />
If you need to manually configure the application, you can create a virtual directory in IIS and place the files contained in the Upgrade/WebApp Folder in there. You will also need to verify that your application is running under ASP.NET 2.0. You can check this, and other web site properties, by opening IIS, find the Caisis web site, right clicking on it and choose properties. When the dialogue box opens select the "ASP.NET" tab and check that 2.0 appears in the drop down box.<br />
<br />
==== Manual Deployment For Upgrades (or experienced server admins) ====<br />
<br />
<br />
1) Backup your existing web files <br />
<br />
2) Delete all files other than your "web.config" file. <br />
<br />
3) Copy all the “FilesForCopyToWebRoot” that you downloaded to your web root, but do not overwrite your web.config file.<br />
<br />
4) View the "keys" in your web.config file (<appSettings key=””>). If new "keys" exist in the web.config you downloaded, insert them into your web.config file. The most important keys are:<br />
a. dbConnectionString<br />
b. institutionName<br />
c. institutionShortName<br />
d. mailServer<br />
e. adminEmail<br />
f. UseSmtpAuthentication<br />
g. smtpUsername<br />
h. smtpPassword<br />
i. emailErrors<br />
j. errorEmail<br />
<br />
5) If you made custom configurations: The App_Data folder contains configuration files. If you made any local configurations, copy the .xml files you modified over the ones provided in the upgrade. Note, the new EformRegistry.xml, PaperFormRegisry.xml, and CannedReports.xml files may register new forms/reports added in the recent release. If the entire file is overwritten these new items will not be accessible.<br />
<br />
6) If you made custom programmatic changes: Copy any additional programmatic changes you have made into the new release. Typically this is local customizations to eForms, or entirely new eForms. Be sure to copy both the “ascx” and “ascx.cs” files in the directory. <br />
<br />
Please note, if you made extensive programmatic changes to your copy of system and they were not provided back to Caisis team for integration into the next release, you will likely need to reintegrate your changes into the source code of the latest version, compile and publish your application.<br />
<br />
== Confirm Application Running ==<br />
After running the Setup file, a web page will launch to your application. The typical URL of your application will be http://'''machine_name'''/'''virtual_directory'''/Login.aspx<br />
If you application was installed on machine ONYX in the virtual directory Caisis, your application would be located at http://onyx/Caisis/Login.aspx. If you receive any errors, you can consult the [[Troubleshooting]] page for help diagnosing the issues.<br />
<br />
[[Image:post_install_web.jpg|thumb|none|650px|baseline|alt=|After the installation, the application can be browsed at http://localhost/caisis_virtual_directory/Login.aspx]]<br />
<br />
== Grant Write Access ==<br />
In order to upload files and display dynamic charts, you must give read/write access to the IIS user for the specified charting and file upload folders.<br />
<br />
The file upload folder may also contain files/documents edited by the application, or outside sources, that would require the folder to have read/write access.<br />
<br />
The default name (specified in the web.config file) for the file upload folder is '''FileUploads'''.<br />
The default location within the web application files is '''App_Data/FileUploads'''.<br />
To give the FileUploads folder modify/write permissions:<br />
<br />
1. Go to the '''App_Data/FileUploads''' directory in the web application files<br />
2. Right click on the '''FileUploads''' folder<br />
3. Select '''Properties'''<br />
4. Select the '''Security''' tab<br />
5. Ensure the appropriate IIS user or Users group has both Modify and Write permissions selected for the folder</div>Delvinkhttp://caisis.org/wiki/index.php?title=Data_Entry_Guide_Part4Data Entry Guide Part42011-06-30T15:16:47Z<p>Delvink: </p>
<hr />
<div>{{TabsTop}}<br />
{{Tab2|[[Data Entry Guide|Part1]]}}<br />
{{Tab2|[[Data Entry Guide Part2|Part2]]}}<br />
{{Tab2|[[Data Entry Guide Part3|Part3]]}}<br />
{{Tab1|[[Data Entry Guide Part4|Part4]]}}<br />
{{TabsBottom}}<br />
<br />
Please note, this documentation is based on Caisis version 4.0 and some admin interfaces may have changed. <br />
<br />
==Administer This System==<br />
<div class="tcenter"><br />
[[image:CaisisManual_Image308.png|none|Figure X The Caisis Splash Screen – on the Home tab'']]<br />
</div><br />
Management of user accounts, permissions, look-up codes, and help information occurs in the <b>Admin</b> section of the application. Users with admin privileges can access this section via the splash screen, please see image above.<br />
<br />
{|class=wikitable<br />
|rowspan=6|[[image:CaisisManual_Image310.png]]||<b> Admin Sections</b><br><br />
|-<br />
|<b>Users:</b><br><br />
In the <b>Users</b> section, user accounts are created, modified, and deactivated. Username, password (hashed), name, and email address are recorded, so users can be emailed and permission assigned. <br />
|-<br />
|<b>Groups and Roles:</b><br><br />
In the <b>Groups and Roles</b> section, permissions and roles are combined to create groups based on job responsibilities. Once groups are created, they can be reused and modified.<br />
|-<br />
|<b>Lookup Codes:</b><br><br />
In the <b>Lookup Codes</b> section, new lookup codes can be added and old ones can be modified. Additionally, the cache can be refreshed, so new look up codes are visible to users.<br />
|-<br />
|<b>Manage Help: </b><br><br />
In the <b>Manage Help</b> Section, the help tables can be modified to update “Help Bubbles” and the content of the user Help.<br />
|-<br />
|<b>System Reports:</b><br><br />
In the System Reports, a report of user statistics can be viewed to determine the number of times a user logged into the application. The user’s last login is also recorded in this report. <br />
|}<br />
<br />
===Users===<br />
[[image:CaisisManual_Image312.png|621px|none|thumb|''The Manage Users Screen'']] <br />
====Add User====<br />
In the <b>Users</b> section, a user can be added by clicking <b>Add User</b>. Once the entry screen loads, complete all of the fields with the information available for the new user: <b>username, password, email, first name</b>, and <b>last name</b>. The policies for the username format should be consistent and mirror the policies in place at your institution. The random check box automatically generates a <b>random</b> password for the user, but a password can be typed as well. After you <b>submit</b> the form, a prompt provides links to email the user their account information. <br />
<br />
[[image:CaisisManual_Image314.png|250px|none|thumb]]<br />
If you click <b>Yes</b>, the <b>Email User</b> screen will load and populate the user’s name, email, and account information in the body of the email. If you click <b>No</b>, the system prompts you to add the user to a group.<br />
=====Email the New User=====<br />
<br />
[[image:CaisisManual_Image316.png|300px|none|thumb|''The Email User Screen'']]<br />
NOTE: The <b>from</b> email populates based on the admin email listed in the <b>Web Config</b> file. <br />
<br />
[[image:CaisisManual_Image318.png|250px|none|thumb]]<br />
During the installation process, this email should be set to a designated email at your institution. Once the email is sent with the user’s new account information, a prompt provides a link to add the user to a group.<br />
<br />
====Add the New User to a Group====<br />
If the admin selects <b>Yes</b>, then the <b>Assign User to Group</b> screen loads with the new user selected and a select box containing a list of pre-defined groups. ''(Please see Creating Groups to learn how these groups are created.)''<br />
[[image:CaisisManual_Image320.png|380px|none|thumb|''Assign User to Group'']]<br />
Groups are created with roles and permissions. The management of user groups is less difficult when the group names correspond to the job titles and responsibilities of the users. For instance, if you have data managers, nurses, and physicians; then user groups should be named “Institution_DataManagers”, “Institution_Nurses”, and “Institution_Physicians” respectively. The institution name represents the name of the dataset that the user can access. In Caisis, datasets represent discrete sets of patients with their own security and access privileges. The use of datasets allows institutions to divide access to many groups of patients within the same installation of Caisis and database.<br />
''(Datasets and groups will be described in more detail later in this document).''<br />
====Edit / Delete User====<br />
[[image:CaisisManual_Image324.png|380px|none|thumb|''Deactivate a User'']]<br />
Once user accounts are created, they can be modified and updated within the <b>Users</b> section of <b>Admin</b>. Current accounts can be edited by clicking on <b>Edit / Delete User</b>. Select the user to be edited and make the changes. Once complete, you must click the <b>update</b> button to save your changes. User accounts can also be deactivated or deleted from this screen. Clicking the <b>deactivate - yes</b> checkbox and clicking <b>update</b> will deactivate the user’s account immediately. To <b>delete</b> the user’s account, you must click the delete button then click <b>OK</b> when the alert box appears.<br />
====Update User Password====<br />
[[image:CaisisManual_Image327.png|380px|none|thumb|''Update User Password'']]<br />
Users can request to have their password updated from the login screen, but the <b>Update User Password</b> section performs the same function. Using this screen, the admin can type in a new password for the user or allow the computer to generate a random password. As with adding a new user, the system will prompt the admin about emailing the new password information. The screens below display the familiar options for accessing the <b>Email User</b> screen and the <b>Email User</b> screen populated with the new password information in the body of the email.<br />
[[image:CaisisManual_Image329.png|300px|none|thumb|]]<br />
[[image:CaisisManual_Image331.png|290px|none|thumb|''Email the Updated Password'']]<br />
====Email User====<br />
[[image:CaisisManual_Image333.png|350px|none|thumb|''Email User – the General-Purpose Email'']]<br />
The <b>Email User</b> screen is a general-purpose email option to contact users from within the application. In this situation, the <b>to</b> and <b>from</b> email addresses and email content must be typed in manually. It is recommended that the <b>from</b> email be the admin email for the account, but your personal email can be entered as well.<br />
<br />
====Add User Group====<br />
[[image:CaisisManual_Image335.png|375px|none|thumb|''Add User to Group'']]<br />
<b>Add User to Group</b> loads the same screen used to add a new user to a group. In the <b>select user</b> field, the admin should select the user to modify and then assign a new group from the <b>Add New Group</b> field. The <b>submit</b> button will save the changes. If a group no longer applies to a user, then the user can be removed from the group. To remove the user, you must click the <b>delete</b> button next to the selected group name, which will remove the group name from the user’s current list of groups.<br />
<br />
===Groups, Roles, and Datasets===<br />
[[image:CaisisManual_Image337.png|350px|none|thumb|''Manage Roles'']]<br />
Clicking on the <b>Groups & Roles</b> section of <b>Admin</b> loads the screen for creating, modifying, and deleting roles, user groups, and datasets, which are the key features of the security in Caisis. Roles directly correspond to the positions at your institution and include physicians, nurses, data managers, and administrative staff as part of the default settings. From this screen, an admin can create a role by clicking on the <b>Add New Role</b> link or modify a role by clicking the <b>edit</b> button next to a particular role. <br />
[[image:CaisisManual_Image339.png|350px|none|thumb|]]<br />
====Create or Modify Roles====<br />
Whether you are creating or modifying roles, the entry screen is the same. You must add or edit the <b>role name, description</b>, and the available <b>permissions</b>. The list of permissions checked should mirror the responsibilities of a user with this title. Once complete, you must click <b>submit</b> to have the changes committed to the database. It is important to keep in mind that the <b>View Data</b> permission should be clicked for all roles.<br />
====Manage User Groups====<br />
[[image:CaisisManual_Image341.png|350px|none|thumb|''Manage User Groups - Options'']]<br />
After clicking on the <b>Manage User Groups</b> link, you will notice a series of subsequent links associated to user groups. From top to bottom, the links are <b>Create New Groups, Edit Groups or Associate with Roles, Associate Groups with Datasets</b>, <b>and Give Groups Access to Tabs and Menus.</b><br />
=====Create New Groups=====<br />
[[image:CaisisManual_Image343.png|375px|none|thumb|''Manage User Groups – Create a New Group'']]<br />
Groups are a combination of roles and datasets. Roles set the permissions for the group and the dataset specifies the population of patients that the group can access. When naming a new group, it is best to include the name of the dataset and the role, “DatasetName_RoleName”. For instance, if you have an institution as a dataset called Warren and you are creating a new group for physicians; then you may want to call the group “Warren_Physicians”, so you can easily identify the users who need to be in this group. The group description should clearly describe the group for future reference, but standard nomenclature is very important. In the <b>select role</b> field, you must click on the applicable role to associate to the dataset, in this example the <b>Physicians</b> role. Submitting this record will load a list of all available groups with the option to edit, delete, or create new groups.<br />
=====Edit Groups or Associate with Roles=====<br />
[[image:CaisisManual_Image345.png|380px|none|thumb|''Manage User Groups – Edit Groups or Associate with Roles'']]<br />
The <b>Edit Groups and Associate to Roles</b> link loads the familiar list of groups. From this screen you can edit and delete groups or add a new group using the <b>Add New Group</b> link. Editing a record loads the same screen as the <b>add a new group</b> screen and allows all fields to be edited and updated. <br />
[[image:CaisisManual_Image347.png|370px|none|thumb]]<br />
=====Associate Groups with Datasets=====<br />
[[image:CaisisManual_Image349.png|385px|none|thumb|''Manage User Groups – Associate User Groups with Datasets'']]<br />
Datasets are discrete populations of patients with a common attribute. This attribute may be an institution, disease, protocol, or any other discerning characteristic. Datasets allow administrators to store multiple sets of patients under one login, while having the ability to apply different permissions to each dataset. Most institutions will have one dataset for every patient, but datasets can be created for a variety of purposes. <br />
<br/><br />
''(The creation of datasets will be discussed later in this section.)''<br />
To associate a group with a dataset, select the dataset from the <b>select dataset</b> drop down list and select the name of a group from the <b>add new group</b> field. Keep in mind that the group name should clearly denote the group and the dataset as in the “Warren_Physicians” example above. Once complete, you must click <b>submit</b> to have the information committed to the database.<br />
=====Give Groups Access to Tabs and Menus=====<br />
[[image:CaisisManual_Image353.png|390px|none|thumb|''Manage User Groups – Give Groups Access to Tabs and Menus'']]<br />
Caisis has numerous tabs and menus that do not always apply to every user. The ability to display and hide menus and tabs has been added to prevent users from being overwhelmed with the complexity of Caisis. Customization of the menus and tabs can be applied at the group level. For example, administrative staff will never enter data, so the <b>Patient Data</b> section can be hidden for all members of that group. To assign tabs and menus, you must select the applicable group from the <b>select group</b> list. When the group is selected, the application will display any access assigned in the past. A check next to any of the items above means that the tab or menu will be visible to users in that group. To apply your changes, the <b>submit</b> button must be clicked.<br />
=====Creating Datasets – Step 1 Update the Dimension (usually the Institutions table )=====<br />
Caisis comes pre-configured with one dataset for all patients. This dataset should be used only by system administrators. Creating Datasets is a three-step process. To date most groups create datasets based on departments or services within their institutioin. In this case, the first step requires adding institution information into the <b>Institutions</b> table. There is an interface for doing this in the Admin under "Manage Datasets" named "Update Insitutions Table". In general, the abbreviated title of the institution or department is entered into the <b>Institutions</b> table. Other datasets can be created using a similar process based on Disease, Physician, Protocol, or Category. Caisis also supports datasets created from any combination of the above 5 criteria, but this logic has not been fully validated. <br />
[[image:CaisisManual_Image355.png|390px|none|thumb|''The Institutions Table'']]<br />
<br />
=====Creating Datasets – Step 2 Update Datasets.xml=====<br />
The second step requires a programmer or an administrator to access the application source files on the web server. In the web root, find the following XML file <b>Datasets.xml</b>. That file has additional instructions for modifying datasets, but in short, the new dataset must be registered in this XML file. The excerpt below depicts what would be entered for the Warren dataset example. In this example, the dataset “id” is set to <b>4</b>, which is important to note because it will have to match the id entered into the admin. The example below represents a dataset with one dimension where the “type” equals the table name and the “value” equals the record in the table. In effect, the XML below is simply denoting the conditions of the query similar to the one below.<br />
[[image:CaisisManual_Image357.png|390px|none|thumb|''Excerpt from “Datasets.xml”'']]<br />
If you were to add another dimension for prostate cancer to the example above, one additional “dimension” element would need to be added to the “dataset” element: <br />
<<font color="993300">dimension</font><font color="red"> type</font><font color="blue">=”Disease”</font><font color="red"> value</font><font color="blue">=”Prostate”></font>. Prostate would also have to be added to the Disease table in the database. The combination of dimensions for datasets are numerous and can group patients using SQL conditions, “and” and “or”, to modify the query above.<br />
*<b>Dataset Query</b><br />
SELECT Institutions.*, Diseases.*<br />
FROM Institutions INNER JOIN Diseases ON Institutions.InstitutionsId = Diseases.DiseaseId; <br />
WHERE InstitutionName = “Warren” AND Disease = “Prostate”;<br />
=====Creating Datasets – Step 3 Update the Datasets Table=====<br />
The final step in dataset creation involves entering the information from the example above into the <b>Datasets</b> table. This step is accomplished using the <b>Manage Datasets</b> section of the <b>Admin</b>. In the entry form displayed below, the dataset id and name must be added to the <b>Datasets</b> table. As noted above, the id of the dataset ''must match'' the id entered into the XML file, which in the case of the Warren Hospital dataset is <b>4</b>. The information in the <b>dataset name</b> field will be displayed to the users, so it is best to keep it as short and as descriptive as possible. The active checkbox allows you to enable or disable datasets easily, but in general should remain checked. Once the id and the dataset name are entered, you must click submit to commit the information to the database.<br />
[[image:CaisisManual_Image359.png|385px|none|thumb|''Manage Patient Datasets – Naming and Committing'']]<br />
Once the dataset is committed, the dataset details will be displayed on the screen below. From this screen, the dataset information can be modified or deleted. In the lower left hand corner, there is also a link to <b>add a new dataset</b>. <br />
[[image:CaisisManual_Image361.png|385px|none|thumb|''Manage Patient Datasets – Add a New Dataset'']]<br />
===Manage Lookup Codes===<br />
[[image:CaisisManual_Image363.png|385px|none|thumb|''Manage Lookup Codes'']]<br />
Caisis installs with a full complement of lookup codes. All of the lookup codes can be modified, replaced, or suppressed. The screen above displays the lookup codes for “BxType”. When a <b>field name</b> is selected from the list of lookup codes, the codes associated with that field name are displayed below. From this screen, you can click the <b>edit</b> buttons to modify each individual item or click the <b>add</b> button to add a new code to “BxType”. When you click <b>add</b> or <b>edit</b>, the entry screen below loads and displays the results for the codes being edited or a blank form for adding a new record. The <b>field name</b> is populated automatically and cannot be edited. To modify the lookup code, you must enter or edit the information in the <b>value</b> field. The optional fields, <b>description, order</b>, and <b>suppress</b> allow you to describe the lookup code in more detail, apply a sort order, or suppress values from the user interface. The default sort order for all lookup codes is alphabetical, but they can be numbered to sort numerically. The <b>suppress</b> check box can be checked to hide a lookup code options from the user while not having to delete values that may prove useful in the future.<br />
[[image:CaisisManual_Image365.png|380px|none|thumb|''Lookup Code Entry Screen'']]<br />
====Add New Field and Lookup Codes====<br />
Caisis also allows the admin to enter new lookup field names and lookup codes. To do so, you need to click the <b>add new field</b> button in the upper right hand corner of the entry screen. The same form used to edit lookup codes will load, but this time it will not have any information in the <b>field name</b> text box. The field name should loosely correspond to the name of the field where the codes will be used. Once information is entered into all of the appropriate fields, you should click the <b>add</b> button to add the new field name and the first lookup code. Since it is the first code, the screen will refresh, but not display the details as it did in the edit/add section. To add the next lookup code, you must select the name of the field name from the drop down list and add additional codes, following the process described above. <br />
''(NOTE: New field names will need to be mapped to their target field through the code behind page of the respective entry form. An experienced developer must handle this process. Please see the technical manual for assistance.)''<br />
[[image:CaisisManual_Image367.png|385px|none|thumb|''The Add New Field Lookup Entry Screen'']]<br />
<br />
====Refresh Lookup Code Cache====<br />
All lookup codes are cached to improve the performance of the application. If lookup codes are changed or modified, the cache must be refreshed before the codes can be visible to the users. To refresh the cache, you must click on the <b>Refresh Lookup Code Cache</b> button.<br />
[[image:CaisisManual_Image369.png|450px|none|thumb|''Refresh the Lookup Code Cache'']]<br />
<br />
====Special Case: Staging Lookup Codes====<br />
The lookup code names for staging drop down lists have to be constructed a specific way for the cascading feature to work. Below are the basic steps:<br />
<br />
'''1.''' Add the disease name value to existing lookup code '''ClinStageDisease''', if not already in list. <br />
''(NOTE: this lookup code is used for both clinical and pathology staging)''<br />
<br />
'''2.''' Add staging system value to existing lookup code '''StagingSystem''', if not already in list. <br />
Value must be entered in format SYSTEM_YY, where YY is the last 2 digits of year ''(i.e. AJCC_10 for 2010 or AJCC_02 for 2002)''<br />
<br />
'''3.''' Add staging values to new lookupcodes. Lookup code names should follow following format:<br />
<br />
For clinical:<br />
StageClin_'''DISEASE_YY'''_T<br />
StageClin_'''DISEASE_YY'''_N<br />
StageClin_'''DISEASE_YY'''_M<br />
StageClin_'''DISEASE_YY'''_S<br />
<br />
For pathology:<br />
StagePath_'''DISEASE_YY'''_T<br />
StagePath_'''DISEASE_YY'''_N<br />
StagePath_'''DISEASE_YY'''_M<br />
StagePath_'''DISEASE_YY'''_R<br />
<br />
where '''DISEASE''' is value from step #1 and '''YY''' is 2-digit year from step #2.<br />
<br />
===Manage Help===<br />
The <b>Manage Help</b> section of the <b>Admin</b> is currently unavailable, but once complete; it will allow all help documentation and field descriptions to be updated from one interface.<br />
[[image:CaisisManual_Image371.png|450px|none|thumb|''Manage Help'']]<br />
===System Reports===<br />
The last section of the admin is the <b>System Reports</b> section. Currently there is only one report, the <b>User Statistics</b> report. This report lists user account information with the number of logins, patients viewed, password changes, and the last login date. Detailed information about patients viewed by users can be found in the table <b>UserPatientViews</b>. The report can be sorted by any column with the title underlined.<br />
[[image:CaisisManual_Image373.png|410px|none|thumb|''The User Statistics Report'']]<br />
<br />
==Data Analysis==<br />
[[image:CaisisManual_Image204.png|500px|none|thumb]]<br />
===Reports===<br />
[[image:CaisisManual_Image206.png|500px|none|thumb|''Select a Report'']]<br />
The <b>Reports</b> section contains “canned” reports that can be generated and printed. Currently there are reports summarizing a patient’s history and the number of surgical cases performed during a given year. The <b>Reports</b> section has the same navigation as the <b>Forms</b> tab with menus that are consistent with the rest of the application. The <b>Summary Report</b> is the most commonly used report in Caisis and it includes, narratives, summary information, and a patient’s entire chronological list. Many physicians use this report as a reference tool when examining patients in clinic.<br />
[[image:CaisisManual_Image208.png|550px|none|thumb|''The Summary Report'']]<br />
Other reports display the statistics for the number of surgeries performed in a given year or list patients with no catheter removal record entered. Reports are printed the same way clinic forms are printed. New reports are added on a regular basis, so please refer to the application to see the most current list of reports.<br />
[[image:CaisisManual_Image210.png|300px|none|thumb|''Reporting the Surgeries Performed in a Year'']]<br />
===Data Export===<br />
The data export tool is used to export large datasets for analysis. The export allows a user to define the tables, privacy level, purpose, and IRB details. The final output of the export is a XML file for Microsoft Access or a XML file without a schema. The XML file for Access can be used to create a new database in Access.<br />
====Parameters====<br />
[[image:CaisisManual_Image212.png|600px|none|thumb|''The Parameters screen'']]<br />
The <b>Parameters</b> screen is used to narrow the list of tables being exported and record the purpose for the export. The <b>Disease Type</b> selection filters the tables to be exported. If you select Prostate, then the list of tables to export is filtered to exclude disease specific tables that are non-prostate. The <b>Privacy Level</b> determines how much patient information will be included. Datasets can be exported with no identifiers, limited identifiers, or de-identified. The <b>Purpose</b> and <b>Review Board</b> sections are related because the purpose for the export should have a corresponding IRB approval type. If you select Data Review Preparatory to Research, then you should have the corresponding approval and checked the Data Review Preparatory to Research approval type. The date of the approval should also be entered in the Approval Date field. The purpose and the approval type/date are saved along with a unique identifier in order to track which user exported the data and for what reason. This information is also added to the XML for tracking purposes.<br />
====Select Tables for Export====<br />
[[image:CaisisManual_Image216.png|600px|none|thumb|''The Select Tables for Export screen'']]<br />
Although, the disease filters can limit the number of tables exported, the user has the additional option of selecting individual tables for export. The <b>Select Tables for export</b> button loads a screen with a list of tables and checkboxes. Clicking on a table name will include that table in the export.<br />
<br />
Please Note: The “LabTests” table can be one of the largest tables in Caisis, so if that table is not required, then it is recommended to exclude it from the export.<br />
[[image:CaisisManual_Image220.png|400px|none|thumb]]<br />
Once all parameters are set and the export format is selected in the lower right hand corner, then the export can be performed by clicking the “Run Export” button in the lower right hand corner. While the export is running, the screen above will be displayed with instructions on how to save the export and import it into Microsoft Access.<br />
[[image:CaisisManual_Image222.png|250px|none|thumb]] <br />
====Save the Export File====<br />
1) When the dialogue box pops up, click the Save button. Do Not click the Open button: the export will fail.<br />
2) Save the .xml file to your local drive.<br />
3) When download is complete, if another dialogue box appears, either click "Close" or "Open Folder"; Do Not click "Open".<br />
====Creating the Access Database====<br />
1) Open Access <br />
2) Create a new blank database <br />
3) From the file menu, click <b>File -- Get External Data -- Import</b> <br />
4) Find the .xml file you just downloaded and click "Import" <br />
5) Click "Okay" to accept the defaults<br />
{|align="left"<br />
|[[image:CaisisManual_Image224.png|left|none|150px|thumb|''Step 2- Create a blank Access database'']]<br />
|}<br />
{|align="left"<br />
[[image:CaisisManual_Image226.png|right|200px|none|thumb|''Step 3 – Import the .xml file to your Access database'']]<br />
|}<br />
<br><br><br />
<br />
===Query Tool===<br />
The Query tool is designed for retrieving data stored in Caisis. Using a series of qualifying statements, a query can be built to return patient data fitting one or more criteria specified by the user. Queries can be saved or modified, and results can be printed. Upon clicking the Query tab, the following screen view will appear.<br />
[[image:CaisisManual_Image228.png|right|400px|none|thumb|''The Query tab'']]<br />
====Create a Query====<br />
Linking together one or more criteria creates a query. To create the first criterion, select a database field from the drop down list on the left. Next, select the desired qualifier that defines the condition of interest. Possibilities include “Starts with,” “ends with,” “contains,” “does not contain,” “equals,” “does not equal,” “less than,” “greater than,” etc. The list of possible qualifiers varies depending on the database field characteristic chosen (e.g. number vs. text). In the value or criterion field, enter the desired search value, either text or a number. If you want to add additional criteria, the linking term can be used to select the relationship between them. <br />
[[image:CaisisManual_Image230.png|right|400px|none|thumb|'Create a Query'']]<br />
Upon selecting a linking term from the drop down list, a new query search term will appear beneath the first. If the option “And” in the linking term drop down list is chosen, the query results will return records meeting all the criteria specified. If “Or” is selected, the records returned will meet at least one of the selected criteria.<br />
====Submit a Query====<br />
Once you have completed the desired search criteria, clicking the <b>Run Query</b> button on the upper right of the command bar will return the results. If no patient records meet the specified query criteria, an error message “No search results available” will appear.<br />
====Save a Query====<br />
If you want to periodically repeat a query, the search criteria can be saved by clicking the <b>Save Query</b> button on the left of the command bar. You will be prompted to enter a name. <br />
<br />
To run a previously saved query, click the <b>View Saved Queries</b> button on the command bar. From the drop down menu, choose the save query to run and click <b>Run Query</b>.<br />
<br />
====Modify a Query====<br />
If you need to change an existing query, or modify a current one, each field in the query search term can be modified. If one or more query criteria need be removed, click the <b>Delete</b> button to the left of each query criteria. To start over with empty fields, click the <b>New Query</b> button on the command bar.<br />
====Advanced Queries - Grouping====<br />
Grouping allows the user to apply multiple query criteria to a subset of query search terms. <br />
<br />
This immediate section of the query documentation is under construction…<br />
<br />
==Protocol Manager==<br />
[[image:CaisisManual_Image233.png|right|450px|none|thumb|''Create a Query'']]<br />
<br />
The Protocol Manager was designed to track the tests and procedures associated with a clinical study. The backbone of the protocol manager is the “Schema” which consists of tests, procedures, and treatments mapped to visits. The idea of a schema came from the Protocol or Treatment schema found in protocol documents that outline the plan for a clinical study. <br />
===Getting Started===<br />
<br />
[[image:CaisisManual_Image239.png|right|450px|none|thumb|]]<br />
The first step in using the protocol manager is to create a Schema. There are two parts to a schema: the first Schema Items and the second intervals. Schema Items are tests, procedures, or other tasks that need to occur for the protocol. Intervals are time points at which tests and Schema Items need to occur. Together they form the Schema and allow the computer to estimate the dates of all test and procedures required for a protocol. The main protocol screen allows users to navigate to the create schema process or the manage schema interface. The select box at the top of the screen allows a user to select a protocol. Once selected, “Step 2” will list any previously created schemas that can be Managed, Edited, or Copied. <br />
===Creating a Schema===<br />
[[image:CaisisManual_Image242.png|right|450px|none|thumb|]]<br />
To create a new schema, enter the name of the schema into the “New Schema Name” and a “Version Number” in the fields at the bottom of the screen. Once entered, click the Create New Schema button to initiate the Schema creation process.<br />
====Schema Items====<br />
[[image:CaisisManual_Image245.png|right|450px|none|thumb|]]<br />
Schema items are mapped to data entry forms in the patient data section. For instance, a schema item may be a lab test, so to create that item a user must enter a “Short Name” which can be “Lab Test” or a specific test name and select “Lab Tests” from the field labeled “What type of item is this?”. Selecting “Lab Tests” will load all of the entry fields for the Lab Tests entry form found in the Patient Data section.<br />
=====Creating Schema Items=====<br />
[[image:CaisisManual_Image249.png|right|350px|none|thumb|]]<br />
The example above displays the Lab Test form which loads when “Lab Tests” is selected. From this screen, a user can flag required fields and pre-populated fields with information known from the protocol, in this case the Lab Test, PSA. <br />
<br />
Required fields are marked using the checkboxes running along the right hand side of the screen. Checking one of these items will make the corresponding field required during data entry. Required fields will also be separated from fields not required on data entry screens to help focus users towards important fields. Populated fields are fields where a value can be added based on the guidelines in the protocol. For instance in the Lab Test example above, the user will know the test being performed, PSA, so instead of checking the field as required, the user can simply select the lab test, PSA. Populating fields with data reduces the amount of information manually entered by data management staff. Ideally, the user creating schema items should try to populate as many fields as possible. Once all of the required items are checked and all possible fields populated, click the “Add This Item” button to create a Schema Item. The details for the item will be displayed on the right with a listing of the item details, see image below.<br />
=====Editing Schema Items=====<br />
{|align="left"<br />
[[image:CaisisManual_Image253.png|right|400px|none|thumb|]]<br />
{|align="left"<br />
[[image:CaisisManual_Image251.png|right|200px|none|thumb|]]<br />
|}<br />
<br><br><br />
To edit an existing schema item, a user must click the item name, Chemo in the example above. Clicking the schema item name will open the “Edit Schema Item” window and allow a user to edit the item or delete the item. The interface mirrors the interface for creating items including check boxes for required fields and all of the fields normally available for data entry. After the changes are made, the save button can be clicked to apply all changes. If all of the schema items have been created then the next step is to schedule on the items based on the visits for the protocol. If a user clicks “Begin Scheduling” then the scheduling process will be initiated.<br />
<br />
=====Setting the Number of Intervals=====<br />
[[image:CaisisManual_Image255.png|right|350px|none|thumb|]]<br />
The first step in the scheduling process is to set the number of events / visits, generally outlined in the protocol. Once the number of intervals or visits is determined, you should enter the number into the Intervals text box, please see above. In this example, we have set that number to 4. If you have entered the number of intervals, you can click continue to begin the process of scheduling each interval.<br />
<br />
Please Note: At anytime, you can add more intervals as long as patients have not been assigned to the schema. If patients have been assigned, then the schema will have to be copied in order to make changes in the number of intervals.<br />
=====Scheduling Intervals=====<br />
[[image:CaisisManual_Image260.png|right|450px|none|thumb|]]<br />
Scheduling is the final step</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T20:11:36Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the most recent version (not included in Caisis 5.02) of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). <br />
See section '''Displaying Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
'''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
'''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above. Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.<br />
<br />
Call the chief complaint “sub” template in the base template as follows:<br />
[[image:BaseEformTemplateExample2.jpg|661px|none|thumb]]<br />
<br />
Below is what the resulting transform looks like to the user:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
[[image:TransformOutputExample2.jpg|1147px|none|thumb]]</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T20:01:10Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the next version (greater than Caisis 5.02) of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). <br />
See section '''Displaying Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
'''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
'''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above. Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.<br />
<br />
Call the chief complaint “sub” template in the base template as follows:<br />
[[image:BaseEformTemplateExample2.jpg|661px|none|thumb]]<br />
<br />
Below is what the resulting transform looks like to the user:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
[[image:TransformOutputExample2.jpg|1147px|none|thumb]]</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:36:45Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). <br />
See section '''Displaying Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
'''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
'''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above. Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.<br />
<br />
Call the chief complaint “sub” template in the base template as follows:<br />
[[image:BaseEformTemplateExample2.jpg|661px|none|thumb]]<br />
<br />
Below is what the resulting transform looks like to the user:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
[[image:TransformOutputExample2.jpg|1147px|none|thumb]]</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:35:54Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). <br />
See section '''Displaying Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
'''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
'''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above. Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.<br />
<br />
Call the chief complaint “sub” template in the base template as follows:<br />
[[image:BaseEformTemplateExample2.jpg|661px|none|thumb]]<br />
<br />
Below is what the resulting transform looks like to the user:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
[[image:TransformOutputExample2.jpg|1147px|none|thumb]]</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:34:40Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). <br />
See section '''Displaying Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
'''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
'''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above.<br />
<br />
Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.<br />
<br />
Call the chief complaint “sub” template in the base template as follows:<br />
[[image:BaseEformTemplateExample2.jpg|661px|none|thumb]]<br />
<br />
Below is what the resulting transform looks like to the user:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
[[image:TransformOutputExample2.jpg|1147px|none|thumb]]</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:30:31Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). <br />
See section '''Displaying Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
- The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
- '''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
- '''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
- As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above.<br />
<br />
- Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
- The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
- the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
- the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.<br />
<br />
Call the chief complaint “sub” template in the base template as follows:<br />
[[image:BaseEformTemplateExample2.jpg|661px|none|thumb]]<br />
<br />
Below is what the resulting transform looks like to the user:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
[[image:TransformOutputExample2.jpg|1147px|none|thumb]]</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:25:31Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
- The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
- '''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
- '''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
- As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above.<br />
<br />
- Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
- The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
- the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
- the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.<br />
<br />
Call the chief complaint “sub” template in the base template as follows:<br />
[[image:BaseEformTemplateExample2.jpg|661px|none|thumb]]<br />
<br />
Below is what the resulting transform looks like to the user:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
[[image:TransformOutputExample2.jpg|1147px|none|thumb]]</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:25:00Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
- The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
- '''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
- '''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
- As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above.<br />
<br />
- Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
- The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
- the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
- the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.<br />
<br />
Call the chief complaint “sub” template in the base template as follows:<br />
[[image:BaseEformTemplateExample2.jpg|661px|none|thumb]]<br />
<br />
Below is what the resulting transform looks like to the user:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
[[image:TransformOutputExample.jpg|1147px|none|thumb]]</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:21:47Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
- The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
- '''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
- '''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
- As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above.<br />
<br />
- Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
- The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
<br />
COMING SOON<br />
<br />
<br />
== Editing Eform Data From Transform ==<br />
<br />
The '''ReviewEform.aspx page''' contains javascript functions that can be called from within the .xslt file that will allow a user to click a transform section (table row) and open a pop up window that will display the corresponding Data Entry component and allow the user to make edits and save, without actually returning to the Data Entry section of the eform.<br />
<br />
Below is an example the Chief Complaint component of the Liver Surgery Eform and its corresponding xml nodes.<br />
[[image:SubTemplateExample2.jpg|648px|none|thumb]]<br />
[[image:SubTemplateExample2b.jpg|527px|none|thumb]]<br />
<br />
Below is the “sub” template created in the .xslt file this will display the complaints:<br />
[[image:SubTemplateExample3.jpg|753px|none|thumb]]<br />
<br />
- the attributes '''onmouseover="this.className='chronListHilighted';"''' and '''onmouseout="this.className='EFormTableRow'"''' handle the mouse over and out affects<br />
<br />
- the attribute '''onclick="LoadComponentByField('EncChiefComplaint', 'Encounters')"''' handles displaying the popup window, specifying Table “Encounters” and table field “EncChiefComplaint“<br />
<br />
'''NOTE''': the pop window can also be invoked using javascript function '''LoadComponentByTable([TABLENAME], [RECORDID])'''. <br />
See other “sub” templates in the LiverSurgery.xslt file, or any those existing eform transforms, for examples.</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:SubTemplateExample2b.jpgFile:SubTemplateExample2b.jpg2011-05-02T19:19:02Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:15:19Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
- The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
- '''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
- '''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
- As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above.<br />
<br />
- Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
- The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample3.jpg|628px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:TransformOutputExample3.jpgFile:TransformOutputExample3.jpg2011-05-02T19:15:02Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:13:15Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
- The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
- '''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
- '''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
- As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above.<br />
<br />
- Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
- The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
Below is a screen shot of the resulting transform seen by the user in the “Review of Approval” section of the eform:<br />
[[image:TransformOutputExample.jpg|1000px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:11:29Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
Below is a snippet of the base template that includes the new Diagnosis Date sub template for the LiverSurgery.xslt file:<br />
[[image:BaseEformTemplateExample1.jpg|656px|none|thumb]]<br />
<br />
- The base transform template '''MUST''' have the attribute '''match="eform"''' and is usually located as the very bottom of the .xslt file, with the “sub” templates definitions located within it. <br />
<br />
- '''pageMaxHeight''' overrides the global javascript variable of the same name that controls the dynamic page breaking. 1050 is the typical value, but it can be adjusted to use less or more of a page when the transform is created.<br />
<br />
- '''McGillEformsStyles''' is an example of referencing a template from the EformTemplateLibrary.xslt file (see section '''Requirements/Files Needed''' above).<br />
<br />
- As you saw with the '''EformHeaderLiver''' template example in section '''Transform Stylesheet Basics''' above, the “sub” templates are normally styled as table rows. Then each “sub” templates (or table row) is combined in the base/primary template table as indicated above.<br />
<br />
- Notice the calls to “sub” templeates '''HPIHeader''' and '''DiagnosisDate'''.<br />
<br />
- The last table row in the above example represents the “footer” of the transform.<br />
<br />
'''NOTE''': There is global page breaking javascript (located in ClientScripts/FormsJS.js) that assumes the first sub template <br />
(or table row) of the base eform template is the transform “Header”, and assumes the last template (or table row) is the transform <br />
“Footer”. It takes the Header and Footer and repeats them on every page. Ensure that in your custom transform the first template <br />
or table row is the Header and the last is the Footer.<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:04:51Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
'''NOTE''': See how the Status Node from the xml is referenced in the XSLT for loop: '''<xsl:for-each select="Status[@RecordId=21]">'''<br />
<br />
'''NOTE''': See how the fields from the Status Node are referenced to retrieve the data stored:<br />
<xsl:value-of select="StatusDateText"/><br />
<xsl:value-of select="StatusDisease"/><br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T19:02:05Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
Below is the corresponding xml node (located in LiverSurgery.xml) that gets populated once the user enters data and saves the eform:<br />
[[image:DataEntryComponentsExample1b.jpg|448px|none|thumb]]<br />
<br />
Below are the “sub” templates created in the .xslt file that will display the diagnosis information and its corresponding header:<br />
[[image:SubTemplateExample1.jpg|916px|none|thumb]]<br />
[[image:SubTemplateExample1b.jpg|628px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:SubTemplateExample1b.jpgFile:SubTemplateExample1b.jpg2011-05-02T19:01:52Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:DataEntryComponentsExample1b.jpgFile:DataEntryComponentsExample1b.jpg2011-05-02T18:58:15Z<p>Delvink: uploaded a new version of "File:DataEntryComponentsExample1b.jpg"</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:DataEntryComponentsExample1b.jpgFile:DataEntryComponentsExample1b.jpg2011-05-02T18:57:26Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T18:54:55Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
Every transform consists of a primary or base template that builds the page by combining “sub” templates. The “sub” templates can represent the data entered in the various components of the eform “Data Entry” section. <br />
<br />
Below is a screen shot of 1 component of the Liver Surgery eform Data Entry section, with sample data (note that the name of the section the component is in is “History of Present illness”):<br />
[[image:DataEntryComponentsExample.jpg|999px|none|thumb]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T18:52:16Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and '''<xsl:otherwise>''' to express multiple <br />
conditional tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
<br />
4. '''XSLT Templates''' - used to build templates.<br />
<br />
Initializing templates:<br />
[[image:TemplateExample1.jpg|791px|none|thumb]]<br />
<br />
'''NOTE''': In this example, “InstitutionName” is a param already initialized in the EformTemplateLibrary.xslt, which is being <br />
referenced in the LiverSurgery.xslt file. (see section '''Requirements/Files Needed''' above) <br />
<br />
Referencing or “calling” a template:<br />
[[image:TemplateExample1b.jpg|363px|none|thumb]]<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T18:48:27Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the '''select''' attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, the '''select''' attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The '''<xsl:choose>''' element is used in conjunction with '''<xsl:when>''' and <xsl:otherwise> to express multiple conditional <br />
tests. If no '''<xsl:when>''' is true, the content of '''<xsl:otherwise>''' is processed. If no <xsl:when> is true, and no <br />
'''<xsl:otherwise>''' element is present, nothing is created. For this example, processing is done ONLY when either xml node fields <br />
ComorbDateText, Comorbidity, OR ComorNotes have values.<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T18:47:01Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
[[image:ForLoopExample1b.jpg|389px|none|thumb]]<br />
<br />
Below is the corresponding xslt for-loop in the LiverSurgery.xslt file that loops through the above node set in the .xml file, and retrieves the stored data:<br />
[[image:ForLoopExample.jpg|761px|none|thumb]]<br />
<br />
'''NOTE''': The value of the select attribute is an XPath expression. An XPath expression works like navigating a file system; <br />
where a forward slash (/) selects subdirectories. For this example, “select” attribute loops through Comorbidity nodes that <br />
have a RecordId >= 1 and RecordId <= 15. <br />
<br />
'''NOTE''': The <xsl:choose> element is used in conjunction with <xsl:when> and <xsl:otherwise> to express multiple conditional <br />
tests. If no <xsl:when> is true, the content of <xsl:otherwise> is processed. If no <xsl:when> is true, and no <xsl:otherwise> <br />
element is present, nothing is created. For this example, processing is done ONLY when either xml node fields ComorbDateText, <br />
Comorbidity, OR ComorNotes have values<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T18:44:50Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
3. '''XSLT For-Each''' - allows you to do looping in XSLT; used to select every XML element of a specified node-set.<br />
<br />
Below is a sample Node set from the LiverSurgery.xml file for the Comorbidities database table:<br />
<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T18:34:15Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
2. '''XSLT Params''' - used to declare a local or global parameter.<br />
<br />
Initializing params:<br />
[[image:ParamExample1.jpg|245px|none|thumb]]<br />
<br />
Referencing or “calling” a params:<br />
[[image:ParamExample1b.jpg|293px|none|thumb]]<br />
<br />
'''NOTE''': The parameter is global if it's declared as a top-level element, and local if it's declared within a template.<br />
<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T18:30:54Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables: <br />
[[image:VariableExample1.jpg|538px|none|thumb]]<br />
[[image:VariableExample2.jpg|769px|none|thumb]]<br />
<br />
'''NOTE''': In the LiverSurgery.xml file, “NoTable” is the parent node/table name, ProcApproachGlobal_40” is the <br />
child node/field name. See section 3. XSLT For-Each below for more information.<br />
<br />
<br />
Referencing or “calling” a variable:<br />
[[image:VariableExample1b.jpg|300px|none|thumb]]<br />
[[image:VariableExample2b.jpg|373px|none|thumb]]<br />
<br />
'''NOTE''': The variable is global if it's declared as a top-level element, and local if it's declared within a template. <br />
See section 4. XSLT Templates below.<br />
<br />
'''NOTE''': Once you have set a variable's value, you cannot change or modify that value.<br />
<br />
'''TIP''': You can add a value to a variable by the content of the <xsl:variable> element OR by the select attribute.<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:VariableExample2b.jpgFile:VariableExample2b.jpg2011-05-02T18:30:04Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:TransformOutputExample2.jpgFile:TransformOutputExample2.jpg2011-05-02T18:18:02Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:TransformOutputExample.jpgFile:TransformOutputExample.jpg2011-05-02T18:17:52Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:DataEntryComponentsExample.jpgFile:DataEntryComponentsExample.jpg2011-05-02T18:17:42Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:SubTemplateExample3.jpgFile:SubTemplateExample3.jpg2011-05-02T18:17:31Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:SubTemplateExample2.jpgFile:SubTemplateExample2.jpg2011-05-02T18:17:19Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:SubTemplateExample1.jpgFile:SubTemplateExample1.jpg2011-05-02T18:17:06Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:BaseEformTemplateExample2.jpgFile:BaseEformTemplateExample2.jpg2011-05-02T18:16:48Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:BaseEformTemplateExample1.jpgFile:BaseEformTemplateExample1.jpg2011-05-02T18:16:34Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:TemplateExample1b.jpgFile:TemplateExample1b.jpg2011-05-02T18:14:55Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:TemplateExample1.jpgFile:TemplateExample1.jpg2011-05-02T18:14:41Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:ForLoopExample1b.jpgFile:ForLoopExample1b.jpg2011-05-02T18:13:45Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:ForLoopExample.jpgFile:ForLoopExample.jpg2011-05-02T18:13:03Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:ParamExample1b.jpgFile:ParamExample1b.jpg2011-05-02T18:12:33Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:ParamExample1.jpgFile:ParamExample1.jpg2011-05-02T18:12:23Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:VariableExample2.jpgFile:VariableExample2.jpg2011-05-02T18:11:52Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=File:VariableExample1b.jpgFile:VariableExample1b.jpg2011-05-02T18:11:34Z<p>Delvink: </p>
<hr />
<div></div>Delvinkhttp://caisis.org/wiki/index.php?title=File:VariableExample1.jpgFile:VariableExample1.jpg2011-05-02T18:11:18Z<p>Delvink: image for Eform transform creation page for developers</p>
<hr />
<div>image for Eform transform creation page for developers</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T18:10:42Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
4. The .aspx.cs page '''ReviewEForm.aspx.cs''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The ReviewEForm.aspx.cs page, when the user enters the “Review for Approval” section, is what <br />
actually loads the .xslt file and generates (“transforms”) the xml data. It can also be used to generate <br />
and load data from outside the eform xml (i.e. existing patient data in database). See section '''Displaying <br />
Existing Database Data in Transform''' for more information.<br />
<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
'''XSLT (Extensible Stylesheet Language Transformations)''' is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. ''(for more information and examples, visit [http://en.wikipedia.org/wiki/XSLT] or simply search for XSLT examples using any search engine)''<br />
<br />
Eform transforms utilize basic XSLT functions for displaying eform data and performing calculations. The following are some examples of functions used existing eform transforms.<br />
<br />
<br />
1. '''XSLT Variables''' - used to declare a local or global variable.<br />
<br />
Initializing Variables:<br />
<br />
<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvinkhttp://caisis.org/wiki/index.php?title=EformsEforms2011-05-02T17:47:47Z<p>Delvink: </p>
<hr />
<div>Translations: [[Eforms_it|italiano]]<br />
<br />
= '''Creating Eforms''' =<br />
<br />
1. Add the Xml file that defines your eform components to the “Eforms” folder of the appropriate disease module. <br />
<br />
The following example would create an eform with one section, and two forms within that section: medications and lab tests. The interface would allow the entry of three medication records and one lab tests record. The letter notations (i.e. (A) ) are not part of the eform, but references to explain each section in more detail below.<br />
<br />
<br />
<?xml version="1.0" encoding="utf-8" ?> <br />
<eform name="GU Pros FU" displayName="GU Prostate Follow Up">(A)<br />
<eformSection name="Presenting Details">(B)<br />
<eformItem displayName="Meds" controlName="Medications"></eformItem>(C)<br />
<eformItem displayName="PSA Lab Test"controlName="LabTestPSA"></eformItem><br />
</eformSection><br />
<br />
<Medications RecordId='1'>(D)<br />
<Medication NotNull="True"></Medication>(E)<br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='2'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<Medications RecordId='3'><br />
<Medication NotNull="True"></Medication><br />
<MedDose></MedDose><br />
<MedUnits></MedUnits><br />
<MedSchedule></MedSchedule><br />
</Medications><br />
<br />
<LabTests>(F)<br />
<LabDate></LabDate><br />
<LabDateText></LabDateText><br />
<LabTest NotNull="True"></LabTest><br />
<LabResult></LabResult><br />
<LabUnits></LabUnits><br />
<LabQuality></LabQuality><br />
</LabTests> <br />
</eform><br />
<br />
<br />
'''(A)''' The eform name=”” attribute must be the same as the physical file name, but can contain spaces. For example, if the file name is GUProsFU.xml then the attribute must be in the format name=”GU Pros FU”.<br />
The value of the displayName=”” attribute will reflect the visible title of the eform on the interface. <br />
<br />
'''(B)''' eformSection is the group of forms that will appear on the interface together. The value of name=”” attribute will reflect the title of the group that appears in the left hand navigation of the eform. <br />
<br />
'''(C)''' The child nodes of eformSection, eformItems are the forms that will be embedded in that section. The value of the displayName=”” attribute will display under the section in the left hand navigation. The value of the controlName=”” attribute is important. It is the name of the physical .ascx file to appear in this section of the eform. It must match exactly the name of an .ascx control that is in any of the Modules/SomeDisease/Eforms folders. For example, in the above example controlName=”LabTestPSA” will embed the LabTestPSA.ascx form in the eform.<br />
<br />
'''(D)''' These are the nodes that hold the data as the eform is submitted. The node structure must match the database tables exactly. It is not necessary to include all the columns of a table, but the parent node must match the table name and any child node used must match a column name. As in this example with Medication, if multiple records for a table are being stored, a RecordId=”” attribute must be used which matches an attribute in the respective .ascx control. In this case, if you open the Medications.ascx file found in the Modules/All/Eforms folder you will find a series of eform input controls with RecordId=”” properties. <br />
<br />
'''(E)''' As mentioned in (D), although not all table columns need to be listed, if a child node is present it must match the name of the table column exactly. Allowable attributes for child nodes are:<br />
• Required=”True” : A Required attribute will prevent a user from going past the data entry step without providing a value.<br />
• NotNull=”True” : A NotNull attribute requires that a value is present only when other fields of this record have a value. Typically used with a field that is non nullable in your database.<br />
<br />
In the example provided, the Medication has a NotNull attribute which will prevent users from going past the data entry step without providing a Medication value only when other values for this record are present. <br />
<br />
The system was structured so that all eform data is stored in a temporary state prior to eform approval. This temporary state is an XML string which in is stored in the EFormXml field of the Eforms table. When the eform is approved, this XML string is parsed and the data is inserted into the respective Caisis tables. <br />
<br />
You may also find times where you would like to collect information, but there is no table/field in Caisis for this data. For this scenario, we provided a <NoTable> node. Under the NoTable node you can create child nodes that have no matching Caisis database fields. On approval, this data will be inserted in the field of the table specified in the PutDataInTable="" PutDataInField="" attributes. At MSK, we typically put this data in the “Encounters” table, “Notes” field. <br />
<br />
You may create your eform from existing components(.ascx files), or you may create your own components. Part II of this document will discuss creating your own eform components. <br />
<br />
In version 4.0, to register your new eform add a reference to it in the App_Config/EformRegistry.xml file.<br />
<br />
<br />
<br />
= '''Eforms Controls''' =<br />
[[Allergies]]<br />
<br />
<br />
= '''Eform Transforms''' =<br />
<br />
<br />
== Overview ==<br />
<br />
After the Eform ”Data Entry” step follows the “Review Data” step where the data just entered into an eform can be presented in a format similar to a paper form. Fields can be edited via a pop up window on click. This “paper like”, or transform, view of the data is generated by creating an .xslt stylesheet to transform the eform xml data. <br />
<br />
A custom .xslt transform is optional. By default the system will generate a bullet point list of the fields you entered that does not resemble paper.<br />
<br />
'''''For our eform custom transform example, we will be using the Caisis 5.02 version of the Liver Surgery eform. The Liver Surgery eform xml (LiverSurgery.xml) and majority of its components is located in the directory Modules/Liver/Eforms. ''''' <br />
<br />
<br />
== Requirements/Files Needed ==<br />
<br />
The following files are used and/or referenced in the creation of a custom eform transform:<br />
<br />
<br />
1. The .xml file of the eform: '''''EformFileName.xml''''' (i.e. the LiverSurgery.xml located in directory Modules/Liver/Eforms)<br />
<br />
2. The corresponding .xslt file: '''''EformFileName.xslt''''' (i.e. the LiverSurgery.xslt located in directory Modules/Liver/Eforms)<br />
<br />
'''TIP''': The eform’s .xslt file MUST have the same base file name as its corresponding .xml file. <br />
It must also be located in the same folder as its corresponding .xml file.<br />
<br />
'''TIP''': If you choose to use a stylesheet for your eform transform, we recommend reusing code from <br />
existing .xslt files to minimize the amount of development time.<br />
<br />
3. The eform template library '''''EFormTemplateLibrary.xslt''''' (located in directory Core/Eforms) <br />
<br />
'''NOTE''': The '''''EFormTemplateLibrary.xslt''''' is used to house the most common styles and patient <br />
data used for eform transforms. However, as eform transforms have become more complex, less and less <br />
styles are used exactly the same across different eforms. Because of this, it is a better practice <br />
for newer eform transforms to put styles in the actual eform .xslt file, as opposed to the library. <br />
Still, the library should still be referenced to have access to some basic patient information commonly <br />
used in transforms such as patient name, address, MRN, date of birth, etc. The following code snippet <br />
should be included in the eform .xslt file in order to reference the eform template library<br />
<br />
[[image:TemplateLibraryReference.jpg|574px|none|thumb]]<br />
<br />
== Transform Stylesheet Basics ==<br />
<br />
<br />
== Displaying Eform Data in Transform ==<br />
<br />
<br />
== Displaying Existing Database Data in Transform ==<br />
<br />
PENDING<br />
<br />
== Editing Eform Data From Transform ==</div>Delvink