TikTok Implementation Manual

INtroductioN

TikTok System Architecture

Dependencies for Files

Build & Test Plan

Diagrams

QuickStart for Extending the TikTok

 

Introduction

Welcome to the TikTok Implementation Manual. This document is meant for those persons who are/will be responsible for maintaining or modifying the pages for the TikTok project.

 

ColdFusion generates all of the web pages for this project, and the project consists of two major components: the User Interface (which is the web pages), and the Database (which was implemented using MS Access 2000).  It is recommended that anyone designated to change the implementation details of this application be experienced in using Cold Fusion and MS Access.

 

The following is a guide to this manual:

 

·        The first section describes the architecture of the system.  This description explains how the system was implemented; what tools, controls, etc. were used; and any other useful information.

·        The second section explains the dependencies for the major files in the project. The dependencies describe the purpose of the file, the functionality of the file, and how the file relates to other files in the project.

·        The third section is a description of the testing of the project. This includes the Build & Test Plan.

·        The next section is a listing of all of the diagrams used in the Implementation Manual.

·        The last section is the QuickStart for Extending TikTok.  It is useful for anyone trying to extend the functionality or compatibility TikTok.


TikTok System Architecture

 

          TikTok is a web application that takes advantage of a number of features that are offered by the Cold Fusion web application environment.  The TikTok application uses both Session level and Application level Cold Fusion variables.  The Session level variables are things like userID, and other pieces of data that are passed between pages, and are specific to a certain session.  Application level variables are application wide constants.  There are defined in Application.cfm, which is implicitly included into every file.  Application wide constants are things like the datasource name, file names, and button labels.

 

          TikTok is a series of forms, and for nearly every form the action file that the form is sent to is redirecter.cfm.  Each form submit button has a unique label, which is sent to redirecter as the form element sender.  Redirecter can then use a series of if statements to determine which form submitted the data.  It can then do processing and send the person to the next appropriate page.

 

          There are three small files that are used sort of like a function in a normal programming language.  These are error.cfm, loggedintest.cfm, and addtolog.cfm.  To use these functions define the necessary session variables as indicated in the code, and then use the Cold Fusion include tag.  This will then include the file, and the file contents will be run.  Error.cfm will simply output an error message and a continue button that will redirect the user to the appropriate form.  Loggedintest.cfm tests to see if the session.userID variable is defined, and if not it will redirect them to the login page.  This is so that people cannot bookmark or otherwise gain entry to our program unless they have logged in.  AddtoLog.cfm will add a text string to the log along with the userID that was logged in at the time and the current system time.  All that needs to be defined is the session.tobelogged variable, then include addtolog.cfm.


Dependencies for Files

 

While TikTok is not an object-oriented system, there are still dependencies in the files.  Notably the logical modules are divided up by GUI screen that the user sees, but have their logic spread across part of a number of files.  Nearly all files include error.cfm and loggedintest.cfm, with some including addtolog.cfm.  The database is used in all modules, whether the actual code lies in redirecter or in the main GUI page for that module or both.  Application.cfm is implicitly included into every page and thus everything is dependent on it.  Lastly every form had redirecter.cfm as the action for the form, so everything is dependent on it.

 

*Lines Indicate Dependencies for Cold Fusion files

** Arrows Indicate Dependencies for the Database of these files


Build & Test Plan

 

In order to thoroughly test the TikTok project, we incorporated the two approaches below into our test plan:

·        Generating schedules and users via the system

·        Boundary and problem case testing on the CF forms

The first approach simply involves inputting users and their schedules via the way prescribed in the user manual. If the package is working correctly, a user and schedule will be generated in which the user will be able to view and modify the information using the system. This is an example of black box testing.

We then did an exhaustive testing phase in which we generated any and every possibility of inputs for a specific functionality.  We then observed the behavior and marked it as right or wrong.


Diagrams

 

 

ER Diagram


QuickStart for Extending the TikTok

 

          This document contains directions on how to make simple changes to the TikTok system from a developer’s standpoint.

 

How Do I:

Change a Button Label?

          Each button label is an application level variable that is contained in Application.cfm.  These labels can be changed, but be aware of the following constraints.  The current architecture requires that button labels be unique to the application.

 

Remove the Login restriction on a page?

          At the top of any page that requires the user to be logged into the system there is the following line “<CFINCLUDE TEMPLATE=#application.loggedintest#>”.  Remove this line and the page will be accessible without logging in.  Please be aware that there are certain session level variables that are defined in the login process that make removing this restriction error-prone.

 

Output error messages to the user?

          To test a condition and output an error message for the user do the following.  Use a <CFIF> to test and see if you are in the condition you want to output an error for.  Then <CFSET> session.errormessage to be the error message, and <CFSET> session.errorfile to be the file that the user is redirected to.  Then

<CFINCLUDE TEMPLATE=#application.loggedintest#>.  This will output an error message with a continue button that will send the user to the page specified.

 

Add a new submit button for more functionality?

          All forms in the TikTok have redirecter.cfm as the form handler.  Also all submit buttons have “sender” as their name.  To add a new submit button first define a new unique label in Application.cfm.  Then put code into Redirecter.cfm to handle that button submission if sender equals the new label.  Then add a new submit button named sender to the form with a value of the label you created.

 

Add a new file to the system?

          First add whatever logic is used to get to this file by using methods from the question above.  Then create the page, using a form with action=”redirecter.cfm” and method=”post”.  Then follow above directions for adding new submit buttons to your page.

Modify the personal information maintained in the database?

          First you will need to download the database and make whatever schema changes are necessary and change the Cold Fusion query.  Then modify the studentchange.cfm page so that it now allows the user to change that new information and does not reference any attributes in the database that have been deleted.

 

Port the TikTok to UNIX?

          The TikTok runs on Cold Fusion server.  During development the only server platform was NT, so no UNIX testing was possible.  Every effort was made to keep the case correct, but as UNIX is case-sensitive and NT is not this will require tedious checking over the code.

 

How to use TikTok on a secure connection?

          First you will need a secure web server with Cold Fusion Server installed.  Then simply install TikTok on that machine.  No source code changes should be necessary.

 

Cause a log entry to be generated?

          To add an event to the log, first find where in the Cold Fusion code that event is processed.  At that point define #session.tobelogged#, and the <CFINCLUDE Template=#application.addtolog#>.  This will include the file that adds whatever string is contained in session.tobelogged to the log file.

 

Change the logic generating email notifications?

          Currently the logic that generates email notifications is located in two locations.  First it is in the absence.cfm module that mails for absence.  Currently this will check if a student is not clocked in when they should be and if so send an email to their supervisor and then mark them as sick and add a special comment to their job comment field.  If your change is in this behavior then this is the code that needs to be changed.  The second place where email notifications can be made is in the clock-in area of redirecter.  This tests to see if a student is marked as sick, and there is the system comment in the clock-status field.  If a student clocks in under these conditions then an email is generated saying that the student reported for work late.  This logic can be changed here.

 

Acquire the source code for TikTok?

       Currently the source code is on the UNC-CH ATN Cold Fusion server interlac.oit.unc.edu.  This is currently where TikTok runs from.  The source code for TikTok is also located on the UNC-CH Department of Computer Science AFS space under ~sarisky/145.

 

Change/Understand the representation of time objects in TikTok?

          TikTok currently deals with times in the following way:  Times are stored in the database not as ODBC time objects but as simple text strings.  Cold Fusion contains an isDate() and ParseDateTime() functions along with other very useful time operations.  Whenever a time object needs to be processed the Cold Fusion code turns it into a time object and processes it on the spot.  This frees up each user from having to specify time in an exact format, anything that Cold Fusion can convert to a time object will do.  Any attempt to modify this system needs to be propogated to everywhere that processes times, ie redirecter for the add schedule block function, and absence.cfm that determines if students are supposed to be at work or not.