Each Journyx Timesheet installation is conceptually divided into three parts: a relational database, which stores all time and expense information; a web server, which provides a browser-based user interface; and an application server, which performs the actual work of time, mileage and expense management. The interface described in this document allows client software to bypass the web-based user interface and communicate with the application server directly, to enable the creation of alternate user interfaces and applications that require programmed interaction with time and other business data.
In its current version, this interface is closely related to the internal structure of the Timesheet database. The following sections describe the kinds of data stored in the Timesheet database, and how they relate to each other; a detailed description of individual data items and interface methods is provided later, in the Reference chapter. (Note: This document describes only the parts of the Timesheet database and software that are supported by the current version of this interface.)
Journyx Timesheet stores all data in a relational database. While it is certainly possible for an external program to interact directly with the database, one of the purposes of this interface is to make that unnecessary because of the risks involved. The danger is that the database might be changed in an inconsistent way, possibly rendering the Timesheet installation broken or corrupted. Normally, Timesheet 5.5 will be running with a basic set of Foreign Key Constraints to prevent most cases of referential integrity violation. However, these constraints can be easily disabled with a direct database connection, and furthermore there are certain relationships that are not protected by a constraint. These are some reasons why it is important to use the jxAPI instead of directly modifying the database.
Even though it is not necessary or desirable to interact directly with the database, it is still necessary to understand the relationship between the contents of the database and the information that passes through this interface. The object records that are used by the jxAPI closely resemble their corresponding database tables.
The Timesheet database contains many tables, each of which stores all records of a particular type. Related records are handled in typical relational database fashion, using unique keys to provide a linkage between separate records. This storage layout is reflected here by the use of an individual structure type for each kind of record, making it the responsibility of the client program to comprehend the relations between them. In order to facilitate relational links between records, every record has a column that contains a unique ID for that record.
The core record types used by this interface are:
Users: Each Timesheet user or administrator has a user record which records information such as their name, phone number, pay rate, and user interface preferences. The key field in the user table is the user’s login name.
Projects, Codes (Tasks), Subcodes (Pay Types), and Subsubcodes (Bill Types): When a user reports time, mileage and expenses, they can be assigned to a particular project and to an activity (specified by up to three types of codes) within that project. The Timesheet administrator can define whatever projects and activities are relevant, so the list of possible projects, codes, subcodes, and subsubcodes are stored in the database. Note that since codes, subcodes, and subsubcodes are identical in structure and behavior, the rest of this document will refer to all of them simply as “codes” unless a distinction is important.
Time records: Each time record covers the hours reported for a single user, on a single day, for a single combination of project and codes.
Mileage records: Each mileage record covers a single mileage event, by a single user, on a single day, for a single combination of vehicle and measurement.
Expense records: Each expense record covers a single expenditure, by a single user, on a single day, for a single expense code.
This interface provides a consistent set of functions that allow basic database operations on the tables that hold each of these record types.
The Timesheet server allows users, projects, and codes to be divided into groups, so that each user can be presented with only the project and activity choices that are actually relevant. Each user, project, or code can be a member of more than one group at a time. This interface provides functions to perform basic operations on the group table, as well as functions to manipulate the group membership of users, projects, and codes.
In some installations, the Timesheet server may divide its contents into domains. Although they share a common database, each domain is logically separate from all of the other domains on the same server. (In other words, each domain has its own set of users, groups, projects, codes, etc.) Each user can only belong to one domain, so when a user is logged in he can only see things in his domain. The “top level” domain ID is always “install_root_dom” -- all items belong to this domain unless they are specifically created in a different domain.
The creation and management of the actual Domains themselves is not currently supported in the jxAPI. In other words, you must create and modify Domains from the Timesheet web interface. However, most of the jxAPI record types include a “domain ID” field where appropriate, so it is possible to use the jxAPI with records that are in different domains.
The Journyx Timesheet server uses a user- and session-based authentication scheme to restrict access to the database. Before a client application can do anything that would query or alter the database, it must establish a session using a valid username, password, and (in some cases) domain. The server will prevent the client application from doing anything that exceeds that user’s privileges.
The privileges granted to a user are based on that user’s roles, each of which grants the privileges necessary for the user to fulfill it. As with domains, creating and modifying the roles themselves must be done in the web interface, but there are jxAPI methods to grant and revoke roles from individual users.
A timesheet is a group of time records that may be submitted as a whole to some higher authority for approval. Each sheet covers a range of dates covering a single reporting period, and holds references to the time records (which are stored in the database in the normal manner) that are associated with it. This interface supports submission of time sheets, with limited support for the approval process and other sheet-management tasks.
© Copyright 1997-2007 Journyx