Journyx Timesheet 5.0 introduced a new API for managing user-configurable object attributes (extra data fields) that replaces the previous Extra Fields implementation. The main technical difference is that, in the old system, each object had only one row in the database for “extra fields,” and adding a new field meant adding a new column to the table. In the new system, each “extra field” (attribute) for every object is its own record for increased flexibility. Also, the new extra fields are fully manageable through the jxAPI. The old system was not supported at all in the jxAPI.
Each Attribute value record contains references to the object Class and ID, the ID of the Attribute Type, and the value itself. The Attribute Type describes the “extra field”, indicating its name, description, data type (numeric, string, date, etc) and possibly a default value.
In the rest of this text, the terms “Extra Field” and “Attributes” are used interchangeably.
So, to assign a value to an “extra field,” you must know four pieces of information. You must have:
Let’s say that we have a Project named “My Project”. We know that the class of Projects is simply projects. We happen to know that the ID of “My Project” is (say) 12345. If we only knew the name of the Project and not the ID, we would have to look that up as well. Let’s say that we want to assign a special “Tax Code” to each Project, so we have created a string Attribute Type named “Tax Code”, and that Type has an ID of (say) ABCDE.
So, to assign the “Tax Code” value of “Deductible” to “My Project”, we have the four key pieces of information we need to make the setAttribute method call:
proxy.setAttribute(skey, ‘projects’, ‘12345’, ‘ABCDE’, ‘Deductible’)
To retrieve the “Tax Code” of “My Project” at a later time, we make this call:
my_project_tax_code = proxy.getAttribute(skey, ‘project’, ‘12345’, ‘ABCDE’) print my_project_tax_code # prints “Deductible”
Only these Object Classes are currently supported in either the jxAPI or the Timesheet product itself: projects, users, and groups. These are the actual names you use, but the authoritative list of names can always seen by calling the getAttributeObjectTypes() method.
In addition to the object classes listed above, these classes can have “Historic” extra field tracking. * time_recs (regular Time Entry record) * expense_recs (Expense Entry record) * travel_recs (Mileage / Travel Entry records)
Every Attribute Type can be designated as “historic” for time, expense, or mileage, which means that when a new time/expense/mileage record is created, the value of the Attribute at the time when the record was created is saved for future reference. Historic attributes for Time, Expense, and Mileage only track the values of the “regular” Attribute Types at the time they were created, and are unaffected by changing the original values later. This is why they are called “Historic.” You cannot attach independent extra fields to Time, Expense, or Mileage; you can only track historical values of the other extra fields, such as for Projects and Users.
For example, let’s say that the user Jane is entering some Time Records, and Jane’s userid is janesmith. The user object janesmith has an Pay Rate extra field value of 25, because this is Jane’s hourly pay rate. If the Timesheet administrator designates the User Pay Rate extra field “historical” for Time entries, then every time Jane creates a time record, the Pay Rate of 25 is recorded with each time record, independently from the actual Pay Rate entry for janesmith.
Now, let’s suppose that Jane gets a promotion, and a subsequent pay rate of 30 per hour. (The Pay Rate extra field for the user object janesmith is changed from 25 to 30.) Jane goes and enters some new time records after her promotion, and these new records will have the new Pay Rate of 30. However, all the time records she entered before her promotion will still have the old Pay Rate of 25, even if those time records are modified in some way, such as if the comment was changed. This is useful for reporting and other analytical purposes.
Extra Fields (Attribute Types) can be designated as “Selection List” or enumerated types. This means that users will be presented with a pre-defined list of acceptable values for the Extra Field, instead of being able to enter any arbitrary values. Multiple selection lists are not supported at this time; only one “choice” per extra field is allowed.
Selection lists may have a default value that is always presented at the top of the list (as the default choice). The default value of selection lists is always assigned to new objects when they are created.
An Attribute Type is designated as a Selection List by creating the type with the ENUM_ prefix for its data-type. (See the Data Types section below.) The actual values in the selection list are managed using the addAttributeTypeSelectionValue and deleteAttributeTypeSelectionValue methods.
Each Attribute Type (or Extra Field defintion) must have a designated “data type.” This determines what kinds of values are acceptable for the field. In the current implementation of this feature, you must supply a string that describes a valid data-type when you create the Attribute Type. You cannot modify the data-type of an Extra Field once it has been defined. (If you wanted to do that, you would have to define a new Extra Field, migrate the values over, and then delete the old Extra Field.)
The data-type is designated by the attr_type field of the AttributeType record, or the data_type parameter to the addAttributeType method. A valid data_type string is made of up the “Base Type” plus any modifying suffixes or prefixes.
There are five different “Base Types” supported in Journyx Timesheet 5.5:
In addition to the “base type”, you may append a length suffix to (only) the STRING and CHAR types. For instance, a string with a maximum length of 30 characters would be the STRING_30 data type. With CHAR types, the length suffix must be included. Note the difference between STRING and CHAR types: if you have a CHAR_30 type, the values returned are always exactly 30 characters, padded with extra spaces if need be. STRING types are returned with any leading or trailing spaces stripped off.
In indicate that the Extra Field should be a selection list, prepend the ENUM_ prefix to the base type (along with any desired length suffix.) For instance, to make a selection list of strings, you can use the ENUM_STRING data-type. To make a selection list of strings with a maximum length of 25 characters, you could use ENUM_STRING_25 for the data-type. Once you have created an ENUM_ type, you can use the addAttributeTypeSelectionValue and deleteAttributeTypeSelectionValue methods to manage the values. Of course, addAttributeTypeSelectionValue will throw an exception if the value does not conform to the data-type of the Extra Field when you created it.
To avoid this problem, you can verify that your values match your data-types ahead of time with the handy checkAttributeValue(data_type, value) method. You can also verify that any particular string is a valid data-type field with the checkAttributeDataType(data_type) method.
Extra Fields may also be marked with a visibility attribute that determines whether the Extra Field is visible, hidden, or read-only. Currently these constants are used for the visibility field:
The WSDL-based interface uses strongly typed arguments and return values. As a result, many of the functions that work with Extra Fields come in three forms: one to operate on Extra Fields with string values (STRING, CHAR, or DATE type), one to operate on Extra Fields with integer values (INTEGER type), and one to operate on Extra Fields with floating-point values (NUMBER type). To avoid SOAP Faults due to type mismatch, you must always use the appropriate function for the type of the Extra Field you are working with.
© Copyright 1997-2007 Journyx