The Journyx Timesheet database contains many different record types, but the basic operations on each are the same: addition, deletion, modification, and retrieval. To handle all of these record types, the session object has a number of methods that are almost identical in operation, differing only in what kind of data they handle.
Passing and returning records: Whenever a record is passed to, or returned from, one of these methods it is in the form of a complex type object defined in the WSDL service description. The contents of each record type are described in more detail below. (The formal XML Schema for these objects can be found in the WSDL document.) In most SOAP libraries (including Axis and MS-SOAP) records will be translated to native objects, so it will not be necessary to work directly with the XML Schema. The schema for these types defines them all to be subtypes of a generic Record type; in some languages (Java with Axis, for example) this means that all of the record classes will be subclasses of a common ancestor.
String sizes: In the record definitions below, strings are referred to as “small”, “medium”, or “large”. A “small” string is limited to 30 characters in length, a “medium” string is limited to 60 characters, and a “large” string is limited to 252 characters. If you try to pass in a string that exceeds the field’s size limit, the server will throw an exception (which in turn generates a SOAP Fault message.) You must keep in mind that these are the “hard” limits that the database imposes on a given’s field length. Extra characters may be used to quote or “escape” special characters, including single quotes. Issues like these may make a “30 character string” really become a 35 character string when it is time to insert into the database, so err on the side of caution.
ID Fields: Every record has an id field, which is a short alphanumeric string that uniquely identifies that record. The ID field must be unique among all records of the same type. In most record types, the ID has no real significance other than its usage as a way to refer to a particular record; if no ID is supplied when a record is created, the server will generate a new one. Please note that in the user record, the ID is used as the user’s login name, so it must be specified when creating a new user.
Please note: it is important to realize that IDs are case-sensitive. That is, xyzzy, xYzzY, and XyZZy are three different and unique IDs. This is also true for User IDs.
The following methods are available for every record type. In each case, replace Type with the appropriate type of item: (User, Project, Code, Subcode, Subsubcode). Manipulation of the other Journyx Code types (mostly related to Expense and Mileage records) are not currently supported except where explicitly noted. Also note that in the below descriptions, “record” parameters are actually objects of the appropriate type; for example, the parameter to addFullTimeRecord is a TimeRecord object.
string addFullType
(skey, new_record: record)
Adds a complete record to the database. All calls to these methods are now passed to the new method addFullRecord(table_name, record) with the appropriate table_name parameter filled in. See that method for more information.
string
addFullRecord
(skey, table_name: string, new_record: record)
Adds a complete record belonging to the given table_name to the database. The record passed to this function must be complete; it will not be filled in with default values, but it will be checked for validity.
The only exception to this is the id and domain fields: for most types, if it is empty the server will generate a value for it. The return value is the record’s ID, whether or not it was generated by the server. (You are allowed to generate your own IDs, but they will be rejected if they conflict with an existing record in the same table.)
If the table_name parameter is not in the list of legal tables defined by the getSearchableTables method, a ValueError fault will be raised. You will also get ValueError if a column that is defined as not-null has a null value in it. Foreign key constraint and other low-level database violations will be passed back as a SOAP Fault, usually named JXDBQueryException.
string addType
(skey, name: string)
For all different types of records, calling this method is like making two other method calls: first getting a default record with the given name by calling getDefaultRecord() and then adding the record with addFullRecord(). In fact, the addType methods are implemented by calling those methods for you using the correct table name and the name parameter.
Please note that the name parameter of this method may refer different fields depending on the record. For instance, for code records, the name parameter refers to the pretty_name field. (A “Pretty name” is the name that users see in the GUI, as opposed to the internal unique ID of the record.) However, for User records, the name parameter refers to the User ID. For Groups, it refers to the literal name field.
string modifyType
(skey, id: string, existing_record: record)
Modifies the existing record with the given id, replacing its contents with the given record.
struct getType
(skey, a_pattern: record)
Retrieves a record by matching it against a pattern. The pattern is simply a prototype record: the return from this function is the first record that exactly matches all of the non-zero (for numeric fields) and non-empty (for string fields) field values in the prototype.
void removeType
(skey, id: string)
Removes a record that is identified by its id, or by a pattern match similar to the one used for retrieving records. See the description of getType, above.
void addTypeToGroup (skey, id: string, group: string)
Adds a record, identified by its key, to a group. Grouping applies only to User, Project, Code, Subcode, and Subsubcode records.
void removeTypeFromGroup (skey, id: string, group: string)
Removes a record, identified by its key, from a group. Grouping applies only to User, Project, Code, Subcode, and Subsubcode records.
record getDefaultType
(skey)
Returns a prototype record filled in with default values. Note that some fields might not have a meaningful default, and will be filled with zeroes or empty strings. In particular, the id field of this default record will be empty, since the server will fill it in when a record is added to the database (except for UserRecords â the user ID must be supplied for those.)
© Copyright 1997-2007 Journyx