Time Tracker 3.1 - User DocumentationWelcome to the Time Tracker user guide. This guide is intended for end-users, explaining how to create, edit, and delete records - as well as a few of the more in-depth tracker features. There is a seperate guide for developers and anyone looking to customize the Time Tracker should refer to that document.While the information presented within this document is not exhaustive, it does explain each of the required fields or attributes for Time and Expense tracker components, while also summarizing the intended uses for each component. Plans for future updates and increased or expandedfunctionality are also mentioned where appropriate. In order to continue, please choose an option from the menu below. |
|||||||||||||||||||||
| General Topics: The procedures required for adding, editing, and deleting records is generally the same for all Time Tracker and Expense Tracker components. Because of this it may be useful to first explain the generic steps required to manipulate records, before going into a more detailed explaination of specific tracker components. [[ back to top ]] |
|||||||||||||||||||||
| Creating a Record Creating a new record is largely the same regardless of which section of the tracker you happen to be in. A user may create a record using either of the following methods: 1 - At the bottom of each page, there is a link that says 'create new record'. By clicking on this link, a user will be prompted for the information needed to complete a new record's creation. 2 - Beside each pre-existing record in the main view mode, there is a blue circle with a '+' inside of it. Clicking this button will also bring up the form to create a new record. In some cases, this button will even default one or more of the new record fields to a pre-determined value (which the user may then choose to change or leave at his or her own discretion). Select Menus: One of the most important jobs of the tracker is to manage the relationship between 2 or more entities or data types. When creating (or editing) a record, a user will often be presented with drop down menus allowing them to select one of many options. In this event, each menu choice presented is likely a record itself in another section of the tracker. The record being created will then be associated with the record chosen from the dropdown. Required Fields: Certain fields will be required in each section in order to create (or edit) a record. The number and type of these fields will vary from section to section, but can be easily determined if not known: required field names will always be underlined. Stay in Add Mode: If a user wishes to add multiple records at once, it is often faster to choose the option to "Stay in Add Mode". If checked, after a new record has been created, this option will then return the user to an empty 'create new record' form. The user may continue to add as many new records as desired, or select "no" from the Add Mode drop-down to be returned to the main view mode. Return to View All Records If a user has chosen to create a new record accidentally, he or she may return to the main view mode simply by selecting the "Return to View All Records" button at the bottom of the page. In the event that this button is clicked, no new record information will be recorded. [[ back to top ]] |
|||||||||||||||||||||
| Editing a Record Editing an existing record is very similar to creating a new record. The main differences is that instead of clicking 'create a new record', the user will need to click the middle, light-grey button to the left of the record he or she wishes to edit. To verify that the right button is being clicked, a user may hover the mouse over the button and view the displayed text that reads 'Edit Record...'. Once the edit button has been clicked, a user may either supply updated information about the record in question, or choose to delete the record. [[ back to top ]] |
|||||||||||||||||||||
| Deleting a Record To delete a record, a user has two options: 1 - While in the main view mode a user may select the dark grey button with an 'x' in the center, to the left of the record. 2 - Whlie in editing a record, the user may choose to 'Delete Record' by clicking the button at the bottom of the screen. In either case, before the record is actually deleted the user will be shown the full record details, and prompted to verify that they wish to proceed with the deletion. If the user declines, he or she will be returned to the main view mode and the record will not be updated. If the user accepts, the record will be permanently deleted. There is no way to recover a deleted record short of a database restore, so be certain that you wish to delete a record before proceeding with this step. The tracker is setup to easily allow older records to be filtered out of the main view mode without being deleted, while allowing for a quick and easy removal of erroneous records. This is the prefered way to interact with the system. [[ back to top ]] |
|||||||||||||||||||||
| Searching and Sorting
Each component of the Time Tracker system offers the ability to search, sort, and filter records or entries. This filtering may be done based soly on attributes of the component in question, but may also incorporate attributes of related components as well. Searching / Filtering: In order to view a restricted record set, a filter must be applied. Filter specifications are stored via session, and as such will stay active as long as a user's browser remains open. In order to apply a new filter, or override an existing filter, a user must simply enter their search criteria into the filtering form presented at the top of each Time Tracker component. Once the desired conditions have been entered, the 'apply new filter' button should be clicked to activate the filter. The most basic type of filtering criteria are dropdown menus. These menus allow a user to view one or more records that match the chosen value for that attribute. For example, if a user viewing the Time component chooses an Employee Name from the dropdown and then applies his or her search filter, that user will be shown all Time records entered for the Emlpoyee whose name was selected in the dropdown. Many of the slightly more complex dropdown menus will show more than one attribute in the same field, in an attempt to clarify the relationship between records for a user. For example, when viewing the Time component a user is presented with a dropdown list labled 'Project Name'. However, this list contains more than simply an alphabetically sorted list of Project Names - as that could potentially confuse the user. Instead, entries are grouped and displayed in a format as follows: 'Company Short Name -> Project Name'. This allows the user to easily filter by company and project, and reduces confusion as well. Another type of filtering is often used for *Date or Time data types. This filtering allows the user to enter text directly into a textbox, and is designated by one of the following signs: <=, <, =, >=, >. Depending on the sign shown, records will be filtered based on whether or not they are greater than, less than, or equal to the value entered. *When entering dates, the tracker requires a standard format of YYYY-MM-DD, or YYYY-MM-DD HH:MM:SS for Times. If a user enters a value in another format, the system will attempt to convert that value but may fail under certain conditions. For example, a value entered in the format of MM/DD/YY would be converted incorrectly, as the system requires that any Date or Time values entered with slashes have the year first, then the month, and lastly the day. Pagination: If more records are present for a component than can be displayed on the screen at any given time, records will be split into seperate pages accessible by hyperlinks at the top of a component's page. These hyperlinks will appear in the format of 'page 1', 'page 2', etc. A user's current page is also stored in a session, allowing the user to leave a section of the Time Tracker, and return later to the same page by default. Sorting: By default, all records are displayed in the order in which they were entered into the tracker. To change this behavior, a user must simply click on the lable of the field by which he or she wishes to sort records. Upon being clicked, an arrow will appear by the fieldname in question and records will be re-sorted in either ascending or descending order. (The default direction for sorts is ascending, but descending direction will be applied if a field is clicked twice consecutively.) Each time a new sorting option is applied, the user will be returned to the first page of the newly sorted record set. This may at first confuse a user, but is much more intuitive than leaving the user on a pre-selected page of newly sorted results when the order of results itself is, in most cases, not related to the previous result's order. [[ back to top ]] |
|||||||||||||||||||||
| Logging in and Out
To login to the system, a user must enter his or her username and password when prompted. (The password may be specified in the user's Employee record, or may correspond with his or her LDAP username, depending on how the tracker has been configured.) Upon a successful login, several pieces of information are recorded and stored temporarily in a Cookie on the user's machine. These pieces of information include, but are not limited to: employee id, username, password, email address, employee name, minimal weekly hours requirement, threshold value and lable, and employee type. Also stored are the date and time at which the employee last logged in to the tracker. Throughout a user's session with the Time Tracker, these bits of information are used to personalize the system, perform advanced functions, check restrictions and permissions, etc. Because of this, it is important for a user to remember than any time changes are made to his or her Employee account, those changes will not be applied until the user first logs out of the tracker and then logs back in. To logout of the system, a user must simply select the 'Logout' option at the top left-hand corner of the screen. Before logging a user out, the Time Tracker first destroys all values being stored in the user's session as well as the previously mentioned Cookie information. This assures that users will not be granted unrestricted access to other user's accounts in cases which require that a terminal be used by more than one user or Employee. [[ back to top ]] |
|||||||||||||||||||||
| Time Tracker Components: The Time Tracker system was initially designed with a relatively simple set of goals in mind, but has since expanded to include a broader range of functionality and options. At the heart of the system however, the logic remains the same: to track time entries for a list of employees and record them against a dynamic set of company contracts and projects. What this means in a nutshell is that to use the Time Tracker system as it was intended, an Administrator must first do a certain amount of initial setup work. To begin he or she must create a list of Employees (or users) who are able to login to the system. Next, one or more Companies should be added, underneath which one or more Contracts will be attached. Finally, * Projects will be entered and associated with the previously created Contracts. Although the above paragraph describes how the Time Tracker was intended to be used, many of the steps listed are still optional. At the least, an Administrator must create one or more Employee accounts. These users will then be able to login to the tracker and create Time and Expense entries. It is important to mention however that the Time Tracker is only as useful as the amount of information entered into it. Because of this, the additional setup time required for Administraters to enter the full amount of data expected by the tracker may be well worth it in the long run. * If the Mantis Bug Tracking software is also being used the Projects created may be associated with existing Mantis projects for increased usability in both systems. To learn more about how the Time Tracker interacts with the Mantis Bug Tracker software, click here. [[ back to top ]] |
|||||||||||||||||||||
| Employees Employee records may also be thought of Time Tracker user accounts, as each employee will be allowed to login to the tracker, and view / modify at least some of the records contained therein. Conversely, a user may not login to the tracker unless he or she has been given an employee account. When creating or editing an employee record, a user will be prompted for some or all of the following information: Username: A username is used to easily identify a user in a system which may feasibly have more than one user with the same full name. Because of this purpose, each username should be unique. Furthermore, if LDAP authentication has been enabled the username given to each user should match their LDAP username. Otherwise a user will be allowed to authenticate against LDAP, but will not be able to complete his or her login to the tracker. Password: If LDAP authentication has been disabled, then a password should be assigned to each user for security purposes. Initially the password field may be left blank, allowing the user to provide a personalized password upon loging into the system for the first time. As password are stored encrypted, it is not possible to retrieve a lost password - only to reset it. Threshold: Threshold indicates which level of permissions a user has been granted within the tracker. There are 5 default threshold levels:
Eastern, Central, Mountain, and Pacific timezones have been implemented by default into the time tracker system. Based on the default company timezone specified in the configuration file, a user's time may automatically be adjusted so that their entries match the timezone of the main company office. This feature may be easily disabled by setting each user's timezone to be the same as the default company timezone. Full Name: Employee names are used by several sections of the tracker to easily identify employees, as well as in the automatically generated emails sent when a user submits an Expense Report. Because of this, employee names are required fields for all employee records. Work Department: Employee may be assigned to specific work departments if desired. Although the Time Tracker does not currently make use of the Work Department field beyond standard searching / sorting operations, future releases may include advanced functionality such as automatic task assignment. Employee Status: Employee Status allows for simple filtering of emloyee accounts, but otherwise does not affect account functionality. Minimum Weekly Hours: In order for a user to submit time entered, he or she must meet or exceed the number of hours specified in the Minimal Weekly Hours field. If the required hours have not been met, an error will be displayed and the user will be prompted to enter PTO time entries to account for the difference in time. Employee Manager: Employee manager allows for easy filtering of employee records, as well as restricted access for users with a threshold level of MANAGER. [[ back to top ]] |
|||||||||||||||||||||
| Companies Company records are very important, as they direct the fllow of a significant portion of the Time Tracker software. For example: Time records are generally (though not necessarily) associated with Project records. Project records are in turn required to be associated with Contract records. Finally, Contract records are required to be associated with Company records. (Company Contact records are also required to be associated with Company records, as the name would suggest.) Another way of representing the relationships described above is this:
Company Name is a required field for obvious reasons: a company's name may be used by other sections of the Time Tracker to reference company records. Short Name: A company's Short Name is also required for much the same reason as listed above. Many sections that allow filtering by company, (or any record which is in turn associated with a company), opt to display all possible filtering options proceeded by the appropriate company's Short Name. This is convenient, avoids confusion, and takes up less space than displaying the full Company Name. Parent Company: Although not a required field, each company may be associated with a parent company if desired. The Parent Company is also a company itself, but by specifying a company's Parent Company a user gains the advantage of easily filtering a company to view all of its subsidiary companies. [[ back to top ]] |
|||||||||||||||||||||
| Company Contacts Company contacts are perhaps the most optional component of the entire Time Tracker system. A user may specified one or several contacts for each Company record- doing so can be very helpful- but is not required to specify any at all. Company records will still function at full capacity with or without contact records attached, so use this component only if it enhances your productivity. If you do choose to enter Company Contacts as well, only two pieces of information are required: Company Name: In order for a contact to be valid, it must be attached to a Company record. Choosing a Company Name from the drop-down presented will setup the necessary association. In the event that a user has one or more contacts which do not necessarily correlate with any specific company, it is recommended that he or she create an empty company to attach these contacts to. Full Name: Each contact must be named in order to be useful, and so the Full Name is also a required field for contact creation. [[ back to top ]] |
|||||||||||||||||||||
| Contracts One or more contracts may be signed with any given Company, and so each Contract record is attached to the specific Company record to which it relates. (Furthermore each Contract may encompass one or more Projects as the next section explains.) Company Name: Company Name specifies which Company a contract belongs with. It will be appended before the Contract Name when filtering by contract in most Time Tracker sections. Contract Number: Each Contract record requires a unique Contract Number. Because the format or numbering scheme for contracts likely varies from company to company, up to 15 alphanumeric characters are accepted for this field in order to allow for flexibility. Contract Name: The Contract Name should be a descriptive, but short, name for the specific contract record. Although it is possible for there to be multiple Contracts for a given Company sharing the same name it is recommended that each Contract for a given Company be assigned a unique name in order to reduce confusion. Start Date / Stop Date: Many contracts will only be valid for a specified date range. By providing a Start Date and Stop Date for each contract, a user enhances the userfulness of the Time Tracking system. Not only is more information attached to each record, allowing for an easier coordination of contracts between offices, but contracts may also be filtered and sorted by specified date ranges as well. This allows for a user to view all active contracts for any given time period simply by entering the desired dates. Work Department : At the current time, the Work Department field merely serves as an additional organizational and filtering tool. However, in future releases of the Time Tracking system this field may be used to auto-assign tasks to users or to allow limited user access to Contract and/or Project records. [[ back to top ]] |
|||||||||||||||||||||
| Projects Projects are yet another key component to the Time Tracker system, offering all of the standard component options in addition to ehanced functionality unique to the Projects section. As the Time Tracker system was initially developed to work alongside the Mantis Bug Tracking software, one of the attributes deserving additional explanation is the Mantis ID field. Mantis ID: If the Mantis Bug Tracker has been installed and setup in the Time Tracker configuration file, the Mantis ID attribute will allow each Project records to be associated with a corresponding Mantis Project. Furthermore, if no Mantis Project exists at the time of Project creation in the Time Tracker, one may be created automatically simply by selecting the 'Create Mantis Project' checkbox. If the checkbox is marked, but a Project with the same name already exists within the Mantis database, that record will automatically be associated with the Time Tracker project and no changes will be made to the pre-existing entry. Contract Name: Just as a Project record may be associated with a Mantis ID, it may also be associated with a Time Tracker Contract. To create this association a user must simply select the appropriate Contract Name from the drop down menu presented. Project Name: The Project Name field is used to identify the Project within various sections of the Time Tracker system, and so should be unique within a given Company to reduce confusion. Start Date / Stop Date: As with the Department Assigned attribute of the Contracts component, additional functionality may be added in later releases of the Time Tracker allowing limited user access to Project records based on active records as indicated in the Start Date and Stop Date fields. [[ back to top ]] |
|||||||||||||||||||||
| Times Perhaps the most complex of the Time Tracker components, the Times section deserves extensive covering in the User Documentation. For this reason, every Time attribute will be explained in detail below, followed by a summary of the advanced Time management options available to specific users. Project Name: Project Name may be used to associate a Time entry with a specific Time Tracker Project record, or may be left blank. Projects are listed in alphabetical order, and groupd by the Company to which they in turn are associated with. Employee Name: Employee Name is used to specify the Employee for which time is being entered. Users with Admin permissions may edit and/or view time for any existing Time Tracker Employee, while regular Users are restricted to records they themselves create. Under most cases, the Employee Name employee drop-down defaults to select the user that is currently logged in. However, if an Admin user has selected a search filter for another Employee, then his or her name will be the default value for new Time entries. Mantis Bug ID: Just as Time entries may be associated with Project records, they may also be associated with Mantis Bugs if Mantis has been installed and configured to run with the Time Tracker. Neither the Mantis Bug ID or the Project Name fields are required, but it is advised that either or both be used whenever possible as the tracker's usefulness directly correllates with the amount of data entered by users. Start Datetime / Stop Datetime: The duration of a Time Entry is specified by the Start Datetime and Stop Datetime attributes. (Only the Start Datetime field is actually required for record creation, as the Stop Datetime may not be known until a later time - but both fields are required in order for an entry to be processed and evaluated by some of the more complex Time features explained below.) An additional feature offered for each of these fields is the ability to round the time entered by a given interval. Although this is certain not required, it does allow users an easy mechanism by which to estimate their start and stop times if desired for a cleaner, more unified presentation in the main view mode. Percent Billable: The Percent Billable field accepts input in the form of an integer ranging from 0 to 100. It is used by some of the advanced features, summarized below, to determine the actual billable amount of time for each Time record, as apposed to the total duration of time entered. Invoice Description: The Invoice Description field allows Employees to enter notes which may then be viewed by other users with a threshold of Client. These comments may also be included by one or more of the report-generating functions found in the Administration Panel. Internal Description: The Internal Description field is similar to the Invoice Description field in that it allows Employees to attach notes to each Time record. However, it has the important distinguishing factor of being viewable only by users with a threshold of User or higher. Internal Descriptions are also not included in any of the reports generated in the Administration Panel, and so require a lower level of formality than do Invoice Description comments. Time Submitted / Time Approved: The Time Submitted and Time Approved attributes are not editable directly, only viewable. These fields are used by the more complex functions of the Time component to handle submitting and approving of time between company employees and accountants or managers. Because of this they may only be updated by the previously mentioned functions, which are explained below in greater detail. Time Reviewed: The Time Reviewed attribute is not required in order for a Time record to be created, updated, submitted, approved, or deleted. It simply acts as a helper mechanism which may be selectively used at the discretion of employees with an Manager threshold or higher. If used, this field allows for users with a Threshold of Reviewer or higher to view submitted time for a restricted set of Employee records, and mark that time to indicate that it has been reviewed and approved by the reviewer. A Manager may then see this mark and choose to approve the time or not, based on various company conditions / qualifications. PTO Type: Each user is required to meet a specific number of Minimum Weekly Hours, (as specified in his or her Employee record), before submitting a week's time. If this minimum has not been met, the user must enter in the difference as a PTO (Personal Time Off) entry and account for the type of PTO which best describes the period of time specified. All Time records marked as PTO should also have a specified Percent Billable of 0. Advanced Time Features Advanced Time Statistics: While in the main view mode of the Time component, a user is presented with some additional statistical information. This information pertains only to the range of records currently being filtered / viewed, and may be located at the bottom of the page below all displayed Time records.
In order to submit time, a user must first select his or her name from Submit Time dropdown and click the 'retrieve oldest unsubmitted week' link. (Manager users may select from a list of all Time Tracker Employees, while other users are restricted to submitting their own records only.) Once the appropriate week of Time has been retrieved, it will be displayed for the user to review before submitting. The user will then be given the option of returning to his or her previous selection of records (which will not submit any new time) or submitting the time being displayed. Time may only be submitted if a user meets or exceeds his or her Minimum Weekly Hours. An error will be displayed if this condition is not satisfied. Once time has been submitted it becomes locked and may neither be edited or deleted unless unsubmitted by a Manager. Submitted time may also be logged to increase security and user accountability. For instructions on how to enable time logging, click here. Approving Time: Only users with a threshold of Manager or higher may approve time. In order to approve time, first a username should be selected from the given dropdown menu, then the time being viewed should be designated as either 'Approved' or 'Un-Submitted'. (If the time is marked as Un-Submitted, a user will then be responsible for correcting any errors in the time block before re-submitting.) If an Admin chooses to un-approve, or un-submit, a user's time he or she will be given the opportunity to comment on why the time was not approved. Although this step is not mandatory and may easily be skipped, it is recommended that Administrators make a habbit of commenting when prompted. Comments entered are automatically emailed to the appropriate user, increasing efficiency and reducing an administrator's workload. [[ back to top ]] |
|||||||||||||||||||||
| Employee Types
The Employee Types component is a restricted access area of the Time Tracker system, accessible only by users with a threshold of Admin. Furthermore, operations on Employee Type records are also restricted in that new Employee Types may be entered, but not removed once they are in user. This restriction has been put into place to prevent the possible corruption of Emlpoyee accounts associated with a specific Employee Type that is no longer present within the tracker system. And in order for an Employee Type to be removed once it has been entered, all Employee records which are associated with that specific Employee Type must first be modified or deleted. [[ back to top ]] |
|||||||||||||||||||||
| Work Departments
Work Departments are another organizational tool available to Administrators. By creating a list of company departments, and associating each Contract or Employee record with a particular department, Admins can easily filter and sort records sets to view department tasks, productivity, and history. Although the current release of the Time Tracker does not make additional use of the Work Departments attribute beyond what was previously described, future releases may also add methods to automatically assign Projects to Employees based on their Work Department, or to limit an Employee to viewing only Projects which are assigned to his or her Work Department. [[ back to top ]] |
|||||||||||||||||||||
| PTO Types
PTO Types specify a list of "personal time off" options which a user may pick to account for any potential differences in his or her actual work hours for a given week, and the Minimum Weekly Hours requirement specified in the corresponding Employee record. PTO Types are similar to Employee Types in both aspects of restricted access, and restricted deletion. [[ back to top ]] |
|||||||||||||||||||||
| Timezones
By default, Eastern, Central, Mountain, and Pacific timezones have been included with the Time Tracker system. For each Emlpoyee record, a Timezone may be specified which may then be used to automatically adjust time entries entered by the Employee so that they match the timezone of the main coporate office (as specified in the configuration file). Timezones are also similar to Employee Types in that they offer restricted access and moderated delation privileges. [[ back to top ]] |
|||||||||||||||||||||
| Expense Tracker Components:
The Expense Tracker was created to manage company expense reports, and all of the items that are generally associated with expense reports. The main logic for this system is simple: first a user creates an expense report using the Expense Reports tab, then attaches all receipts and mileage entries that are associated with that report by creating records in their corresponding sections. Once all of the relevant items have been attached to a report the user then returns to the 'Expense Reports' section of the Expense Tracker, selects the record they have just created, and clicks 'submit report' button at the bottom of the page. Following the above steps will create a report, and submit it along with all related items to one or more company accountants (as specified in the configuration file). The accountants, as well as the user who created the report, will receive email notification that the report has been submitted, along with a brief summary of the report and its line items. Upon receiving this email, an accountant may choose to approve or reject the report. [[ back to top ]] |
|||||||||||||||||||||
| Expense Reports
Much like Company Records are a key component in the Time Tracker system, Expense Reports are a key component in the Expense Tracker system. All other expense items are linked to an expense report, creating a hierarchy as shown below:
Employee Name: Each Expense Report is associated with an Employee, or user, account. This means that if several Employees work on a particular project, each Employee must submit his or her own Expense Report. Report Name: Expense reports should be given unique, descriptive, and easily recognizable names. Although no limitations or restrictions are imposed on the Report Name attribute, each name should be unique to avoid confusion. For this purpose it is recommended that either an Employee, or the company as a whole, settle on a report naming scheme which will assist in meeting the previously mentioned conditions. Description: Currently, the Expense Tracker does not make use of the Descriptions field other than to allow Employees to enter personal comments or reminders for Expense Reports. Future versions of the tracker may use these comments in automatically generated Administrative Expense Reports however, so Employees should make note to keep any comments entered brief and professionally written. Advanced Expense Report Features In addition to recording and tracking expense reports, the Expense Tracker also handles submitting and approving those reports by providing users with an additional set of options when viewing a record in Edit mode. Submitting a Report: In order to submit an expense report, a user must first view the report in Edit mode and then click on the 'submit report' button located at the bottom of the screen. Once this button has been clicked, a report summary will be sent to each of the company accountants (listed in the configuration file) as well as the user submitting the report. Expense report submissions may also be logged to increase security and user accountability. For instructions on how to enable report logging, click here. Approving / Declining a Report: When an expense report is submitted, an email is sent to each of the company accountants containing a description of the report, and a summary of all report line-items. Also included in this report are hyperlinks to view any attached receipt scans, as well as buttons for approving or declining the report. Not all email clients support approving / declining reports directly from the notification email. In this event, reports may also be approved by viewing the appropriate report in Edit mode. Admin users will then be presented with buttons to 'approve report' or 'unsubmit report'. If an administrator chooses to unsubmit a report, he or she will then be prompted for comments as to why the report was not approved. As with unsubmitted Time records, this step is not mandatory and may easily be skipped. However it is recommended that Administrators make a habbit of commenting when prompted. Comments entered are automatically emailed to the appropriate user, increasing efficiency and reducing an administrator's workload. Viewing Statistics: When viewing one or more reports in the main View mode, additional statistics will be presented at the bottom of the page. These statistics are calculated for all reports being viewed, so if a user wishes to view statistics for a single report he or she will need to select that report from the 'Report Name' drop down menu, and then click to 'apply new filter'. All currency values displayed have been pre-converted to USD.
|
|||||||||||||||||||||
| Receipts
Receipts entries are individual records of purchases or expenses incurred while on a job-related assignment. Each receipt belongs to a corresponding Report, and contains some or all of the following attributes: Report Name: Since each receipt must belong to a Report, a user must select the desired Report from the Report Name drop down menu when creating a receipt. To reduce confusion, all reports displayed are proceeded by the name of the Employee to whom the Report belongs. Example: 'John Doe -> Sample Report' Project Name: Since it is assumed that any work-related expense will be associated with a task or Project, a user must also specify which Project the expense is most closely related to. If a Project entry does not exist, then the user will be required to contact an Administrator and ask that they create the new Project. Although this may seem like extra work for the user, it helps to ensure that both the Time Tracker and Expense Tracker systems are being used properly and to the fullest capacity. Currency Type: Currency Type designates the currency for which each receipt has been recorded in. When an Expense Report is submitted, all receipt entries are converted to a standard currency type. Amount: The amount incured by each expense must be entered into the Amount field. This is a required field, meaning that no record may be created or modified unless an Amount value has been given. Company Credit Card: If a Company Credit Card was used to make the purchase being entered, that card should be specified by selecting it from the drop-down menu in question. If a personal credit card, check, or cash was used to make the purchase this field should be set to 'N/A'. Receipt Type: To aid in accounting operations, users must specify which type of expense most closely matches that of the Reciept being entered. If no matching type can be found, the user should select 'Other' or contact an Administrator for assistance. Description: Each line item on a submitted report includes comments taken directly from the Description field of a Receipt record. Users should keep in mind this fact while entering receipt descriptions, and make an effort to keep all text entered short, descriptive, and professionally worded. Receipt Scan: If the user wishes to submit a scanned image of the receipt being entered he or she may do so by clicking the 'Browse' tab and selecting the appropriate image file before creating the record. When editing a record, the user may override the receipt scan by browsing to select another. If no new image is selected when an edit is being made, the existing image will be left as-is. Billable Percentage: The Billable Percentage field specifies how much of the total cost of the receipt being entered is billable to Company (or client) for whom the Project is being done. The amount entered should be a whole number between 0 and 100. [[ back to top ]] |
|||||||||||||||||||||
| Mileage Mileage entries are used to record any driving time / expense incurred while working on a work-related task or Project. As with Receipts, each Mileage record belongs to a corresponding Report and contains some or all of the following data: Report Name: Mileage records are required to be associated with a Report record, meaning that in order to create a Mileage entry a user must first select the desired Report from the Report Name drop down menu. To reduce confusion, all reports displayed are proceeded by the name of the Employee to whom the Report belongs. Example: 'John Doe -> Sample Report' Project Name: Since mileage is only relevant to the Expense Tracker if it is associated with a task or Project, a user must also specify which Project the mileage being entered is most closely related to. As with Receipts, if a Project entry does not exist then the user will be required to contact an Administrator and ask that they create the new Project. Currency Type: Currency Type designates the currency in which the Cost Per Mile value was reported in. When an Expense Report is submitted, all mileage entries are converted to a standard currency type. Date: A user must provide a Date value in order to create a Mileage record. The date given should be the date on which the mileage being entered was incurred and not the current date. Origin / Destination: Although it is not a required attribute, user may choose to specify both origin and destination locations. This is mostly for accountability purposes, but may also be useful for searching or sorting records as well. Cost Per Mile: The Cost Per Mile field will initially contain a default value specified in the configuration file. If this value is incorrect, the user may make adjustments as necessary. The amount of compensation required for each mileage entry is determined by multiplying the Cost Per Mile and Total Mile values and then converting to the appropriate Currency Type. Total Miles: Although origin and destination are both optional Mileage attributes, Total Miles is a required field and must be entered before a new record may be created. Description: As with Receipts, each line item on a submitted report includes comments taken directly from the Description field of a Mileage record. Users should keep in mind this fact while entering receipt descriptions, and make an effort to keep all text entered short, descriptive, and professionally worded. [[ back to top ]] |
|||||||||||||||||||||
| Company Credit Cards If a company credit card has been given to an Employee, then that card should also be entered as a Company Credit Card item. This will allow the user to specify wheter the card was used when entering a Receipt item. Once a credit card has been entered and is in use by one or more Receipt records, that card may not be deleted unless the corresponding Receipt records are first modified to remove reference to the card. This security check is in place to increase accountability and data integrity. It is important to note that a default Company Credit Card entry for 'N/A' comes pre-loaded into the Expense Tracker system. This value should only be removed if a Company Credit Card must be used for each expense entry. If there is any possibility that an employee will be using a personal check or credit card, the default value must be left in the system as it will allow employees to designate which expenses were out of pocket. [[ back to top ]] |
|||||||||||||||||||||
| Currency Types
Administrators should enter any Currency Type which may be used by an Employee, along with the current Conversion Factor, and should make an effort to keep all Conversion Factors up to date. This data will be used to generate administrative expense reports. [[ back to top ]] |
|||||||||||||||||||||
| Receipt Types If a company wishes to keep seperate records for different types of expenses, they may do so by entering one or more Receipt Types. These types will be made available to a user when entering a Receipt record, and will allow for easy searching and sorting of Receipts by system Adminstrators. [[ back to top ]] |
|||||||||||||||||||||
|
Administration Panel The Administration Panel houses most of the custom tracker plugins, and as the name implies is restricted to Admin users only. Although the component is intended as an easy interface to plug additional custom scripts into, it also comes with a few pre-built scripts by default. Those scripts, and their functions, are as follows. Project Associations Cleanup: When running the Time Tracker in conjunction with the Mantis Bug Tracker, it is possible that the Time Tracker may reference entries in the Mantis tracker that were at some point changed or removed from the Mantis system. Running the associations clean-up script checks for any such errors, and corrects them to ensure that both systems are in sync. Administrative Reports: The quickest and easiest way to view the current status of a Project and all of its associated tasks is to generate an Administrative Report. To do this, you will need to select a Project and also a start/stop date range. The system will then display basic project information, along with tables entitled "Accomplishments" and "Next Week's Goals". The Accomplishments table will contain all Mantis Bugs marked "Resolved" within the given date range, as well as the title and summary description of those bugs. The Goals table will display all currently open Mantis Bugs, along with their summary information. The format of the report and the amount of data displayed are easily customized by modifying or overriding the admin_report() function located within 'admin.php'. SU Mode: Although Admin users may easily access other Employee records and information, it may at times be useful for an Admin to login as another user to troubleshoot an error or guide the user through an area of confusion. However, in the event that LDAP Authentication is being used, Time Tracker Admins may not have access to other Employee's passwords. To work around this issue, an Admin may select the SU Mode option presented in the Administrations Panel, choose the appropriate user from the drop down list presented, and click submit. Doing so will destroy the Administrators session information, and automatically log them in as the user they selected for the remainder of their session (or until they choose to logout of the Time Tracker). Note: This is a one-way function. Once an Admin has chosen to SU to another Employee's account, he or she will have to logout and then back in before resuming Admin privileges. [[ back to top ]] |
|||||||||||||||||||||
|
General Configuration Settings There are several generic configuration options that should be specified before using the Time Tracker system for the first time. These options, and their respective purposes, are explained below in detail: User & Company Preference: Although future releases of the Time Tracker plan to offer user-specific preferences, the current release only allows for default-user and company-wide preferences. Those preferences are as follows: # the default page that all users are sent to initially upon logging in $GLOBALS['tt_user_default_page'] = 'times.php'; # the company name to be displayed in the header and title text of each page $GLOBALS['tt_company_name'] = 'Company Name; # default timezone name and offset value for company headquarters $GLOBALS['default_timezone_name'] = 'Eastern'; $GLOBALS['default_timezone_value'] = '-5'; # order, and number, of days to be included for company work week $GLOBALS['days_of_work_week'] = array( 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday' ); Base URL Configuration: In order for both the Time Tracker and Mantis Bug Tracker software to function together properly, each system needs to know the exactly location of the other sytem. To record those locations, you must set the following properties: # absolute URL to timetracker system $GLOBALS['base_tt_url'] = "http://www.yourwebsite.com/timetracker/"; # absolute URL to mantis bug tracker system $GLOBALS['base_mantis_url'] = 'http://www.yourwebsite.com/mantis/'; Switch/Case States: The Time Tracker may treat a given record differently depending on whether it is being viewed, modified, deleted, or searched for. User permissions can and will vary in each of those circumstances as well. To manage these events, the tracker makes use of the following READ-ONLY variables: # switch case variables used for object update/edit modes, etc. $GLOBALS['LOCK_MODE'] = 0; $GLOBALS['EDIT_MODE'] = 1; $GLOBALS['VIEW_MODE'] = 2; # switch case variables used for object update/edit modes, etc. $GLOBALS['VIEW'] = 0; $GLOBALS['SEARCH'] = 1; $GLOBALS['UPDATE'] = 2; $GLOBALS['DELETE'] = 3; $GLOBALS['VALIDATE'] = 4; [[ back to top ]] |
|||||||||||||||||||||
|
Database Configuration Settings Database settings must be made for both the Time Tracker system and the Mantis Bug Tracker system as well (if it is to be used). To configure the Time Tracker database, you must specify the following information: # name of database application used for storage ('mysql', 'postgres', etc.)
$db_tracker_config['tt_db_type'] = 'mysql'; # ('mysql', 'postgres', etc.)
# ip address used to access timetracker sql database
$db_tracker_config['tt_db_ip'] = 'TIMETRACKER_DB_IP';
# username / password details for timetracker database access
$db_tracker_config['tt_db_user'] = 'timetracker_db_username';
$db_tracker_config['tt_db_pass'] = 'timetracker_db_password';
# timetracker database name
$db_tracker_config['tt_db_name'] = 'timetracker_db_name';
# globale pointer to mantis timetracker descripter array
$GLOBALS['db_tracker_config'] = $db_tracker_config;
To learn more about how to configure the Mantis Bug Tracker database, click here. [[ back to top ]] |
|||||||||||||||||||||
|
Mantis Bug Tracker Settings In order to configure the Time Tracker system to run alongside the Mantis Bug Tracker software, you will first need to open the file named 'defaults_inc.php' and copy the following information: # name of database application used for storage ('mysql', 'postgres', etc.)
$db_mantis_config['tt_db_type'] = 'mysql';
# ip address used to access mantis sql database
$db_mantis_config['tt_db_ip'] = 'MANTIS_DB_IP';
# username / password details for mantis database access
$db_mantis_config['tt_db_user'] = 'mantis_db_username';
$db_mantis_config['tt_db_pass'] = 'mantis_db_password';
# mantis database name
$db_mantis_config['tt_db_name'] = 'mantis_db_name';
# globale pointer to mantis database descripter array
$GLOBALS['db_mantis_config'] = $db_tracker_config;
Once you have copied the above information, you will then need to paste it into the file named 'config_inc.php', and fill in all of the required details (database type, IP, login information, etc.). [[ back to top ]] |
|||||||||||||||||||||
|
LDAP Authentication To enabled the Time Tracker to use LDAP Authentication, simply set the following variables inside of the 'config_in.php' file. # TRUE indicates that LDAP authentication is enabled $GLOBALS['tt_ldap_enabled'] = TRUE; # URL and Port Number for LDAP server $GLOBALS['tt_ldap_url'] = 'www.ldap_url.com'; $GLOBALS['tt_ldap_port'] = 389; # Domain Name as configured on LDAP server $GLOBALS['tt_ldap_domain_name'] = 'LDAP_DOMAIN_NAME'; [[ back to top ]] |
|||||||||||||||||||||
|
Database Formats Supported All database access from within the Time Tracker and Expense Tracker systems is done through the use of multiple database abstration layers. The first, a class written specifically for the Time Tracker software, follows the standard Time Tracker coding guidelines and is used to interface with the second, a more generic and widely used set of classes known as ADOdb (Database Abstraction Library for PHP). Through the use of ADOdb, it becomes theoretically possible to use any one of several mainstream database formats to store information in for the Time Tracker. The format you chose would simply need to be specified in the Database Configuration options. However, due to the different ways in which each major database application handles internal operations (such as auto-increment vs. sequence, or true/false WHERE conditions), the Time Tracker may not function the same, or at all, if certain formats are used. At the current time, the only database which has been tested and shown to work fully with the Time Tracker system is MySQL. Future releases of the tracker plan to offer PostgreSQL support, and eventually Oracle and SQL Server as well, but no definitive plans have been made as of yet regarding the release date. Because of this, any users wishing to run the Time Tracker system with a database other than MySQL will for the time being be responsible for modifying all SQL queries as necessary to ensure proper functionality, as well as creating all SQL tables, fields, and associations required by the Time Tracker in order to function. (By default, MySQL and PostgreSQL database creation scripts are included with the tracker, and may be located in the 'sql' folder.) [[ back to top ]] |
|||||||||||||||||||||
|
Company Accountant(s) Settings The Time Tracker system will automatically generate and send Expense Report Emails each time an Expense Report is submitted. If you would like for one or more users to be notified of these reports automatically, you may specify them as follows: # associative array containing Name and Email Address information for company accountants # NOTE: these accountants do not have to be Time Tracker users, or actual people, # but may be created simply for record keeping purposes $GLOBALS['accountant_emails'] = array ( 'first_name' => 'email_address@your_domain.com', 'second_name' => 'email_address@your_domain.com' ); # email address that expense reports will be sent from $GLOBALS['tracker_email'] = 'time_tracker@your_domain.com'; # default subject line for expense reports $GLOBALS['email_subject'] = 'Time Tracker report submitted'; [[ back to top ]] |
|||||||||||||||||||||
|
Expense Report Emails When a user submits an Expense Report, several things happen in addition to the report being marked as submitted. First an email is generated containing all relevant Expense Report data, including a brief description of the report itself, as well as all associated Receipt and Mileage entries. This email is then sent to the user who submitted the report as confirmation that the report was successfully submitted. Once that is done, the Time Tracker checks to see if any Company Accountants have been specified in the configurations file ('config_inc.php'). If one or more accountants are found, the previously generated report is sent to them as well, with additional options to approve or unsubmit the report directly from the email. To change the format of this report email, or the details it provides, simply modify the make_email_body() function located within the file entitled 'reports_submitted_email.php'. [[ back to top ]] |
|||||||||||||||||||||
|
Custom User Thresholds User permissions and restrictions are regulated by the Time Tracker through the use of several Threshold levels. These levels, originally specified in the 'defaults_inc.php' configuration file have since been relocated to their own database table entitled 'tt_employee_thresholds'. Their names and values are as follows: 'CLIENT' = 10; 'USER' = 30; 'REVIEWER' = 50; 'MANAGER' = 70; 'ADMIN' = 90; Each level is intended for a specific type of access, and more information regarding their proper usage may be found here. [[ back to top ]] |
|||||||||||||||||||||
|
Logging / Debugging Settings Whether setting up the Time Tracker for the first time, or modifying it to add custom scripts, there may be times when it is useful to enable detailed event-logging for various types of operations. This logging can provide detail descriptions of Time Tracker operations and queries, as well as user activity logs for increased company security. To enable one or more of the various logging options, you must specify the values shown below: # enables logging for failed LDAP authentication/connection as well as failed SQL queries $GLOBALS['tt_debug_mode'] = TRUE; $GLOBALS['tt_debug_file'] = 'logs/example_debug_file.txt'; # enabled logging for failed user login attempts $GLOBALS['tt_logging_mode'] = TRUE; $GLOBALS['tt_logging_file'] = 'logs/example_log_file.txt'; # enabled logging for successful user login attempts $GLOBALS['tt_access_mode'] = TRUE; $GLOBALS['tt_access_file'] = 'logs/example_access_file.txt'; # enables logging of submitted and approved times: hours submitted, user name, date submitted $GLOBALS['tt_time_mode'] = TRUE; $GLOBALS['tt_time_file']'] = 'logs/example_time_file.txt'; # enables logging of submitted expense reports: report name, user name, date submitted $GLOBALS['tt_reports_mode'] = TRUE; $GLOBALS['tt_reports_file'] = 'logs/example_reports_file.txt'; # enables logging of all SQL queries (used primarily for debugging purposes) $GLOBALS['tt_log_db_mode'] = TRUE; $GLOBALS['tt_log_db_file'] = 'logs/example_db_log_file.txt'; Note: it is important to ensure that PHP has adequate read and write permissions for all log files selected. [[ back to top ]] |
|||||||||||||||||||||
|
Coding Guidelines If you wish to submit custom code to be included in future releases of the Time Tracker system, it is important that you follow the etsablished coding guidelines. Doing so will ensure that all code remain easily readable for future modifications/releases. Class & Method Naming: Class and method/function names should be all lower case letters, with words seperated by underscores. For example, 'login_api' is the name of the class that handles all user login and permissions level functions. Variable Naming: Variable names should follow the same naming scheme as above, with all letters lowercase and all words seperated by underscores. Generally variables names should also be proceeded by a brief descriptive label indicating either the class or function they are intended to be used with or the type of data they contain. For example, '$db_query' could be used to indicate a variable that contains a SQL query to be later used by the 'db_api' class. The title '$employee_record' on the other hand, could be used to indicate the result returned by the previous db query, containing information about a particular employee or user. Variables may in certain conditions also be proceeded by a letter designating their relative scope within the method or function in which they are located. Scope is defined as follows:
|
|||||||||||||||||||||