Core Database Functions
This page is about the legacy SOAP-based jxAPI that is no longer updated or recommended for use in new projects. The documentation in this section may be outdated or inaccurate, and is provided for reference purposes only.
Journyx recommends using the REST-based API for new projects in most cases. However, at the current time, there are certain object types that are not available through the REST API.
Much of the data accessible through the jxAPI is tabular, and the jxAPI provides a record type and a standard set of methods for each table. The tables which have the standard methods described below are:
| Table | Record Type | Name In Methods | WithNames? | Group? | Hidden? | Attributes? | Searchable? | Loggable? |
|---|---|---|---|---|---|---|---|---|
| users | UserRecord | User | yes | yes | yes | yes | yes | no |
| projects | ProjectRecord | Project | yes | yes | yes | yes | yes | yes |
| groups | GroupRecord | Group | no | no | no | yes | yes | no |
| time_recs | TimeRecord | TimeRecord | yes | no | no | no | no | no |
| expense_recs | ExpenseRecord | ExpenseRecord | yes | no | no | no | no | no |
| travel_recs | MileageRecord | MileageRecord | yes | no | no | no | no | no |
| codes_tasks | CodeRecord | Code | no | yes | yes | yes | yes | yes |
| codes_pay_types | SubcodeRecord | Subcode | no | yes | yes | yes | yes | yes |
| codes_bill_types | SubsubcodeRecord | Subsubcode | no | yes | yes | yes | yes | yes |
| codes_expenses | ExpenseCodeRecord | ExpenseCode | no | yes | yes | yes | yes | yes |
| codes_currencies | ExpenseCurrencyRecord | ExpenseCurrency | no | yes | yes | yes | yes | yes |
| codes_expense_sources | ExpenseSourceRecord | ExpenseSource | no | yes | yes | yes | yes | yes |
| mileage_reasons | MileageReasonRecord | MileageReason | no | yes | yes | yes | yes | yes |
| mileage_vehicles | MileageVehicleRecord | MileageVehicle | no | yes | yes | yes | yes | yes |
| mileage_measurements | MileageMeasurementRecord | MileageMeasurement | no | yes | yes | yes | yes | yes |
| assignments | AssignmentRecord | Assignment | no | yes | yes | yes | yes | yes |
In the list above, the "Name In Methods" column is the word that is substituted
for "TYPE" in the method names described below. For example, a core method
described as addFullTYPE is actually implemented as addFullUser,
addFullProject, and so forth.
Methods Implemented For Each Type
addFullTYPE
addFullTYPE(record) -> id
Adds a record to the database, generating and returning a new ID.
When a non-administrator calls this method, user roles will be checked in a table-dependent manner to determine if the action will be allowed.
modifyTYPE
modifyTYPE(id, record) -> id
Replaces an existing record in the database, returning its ID.
When a non-administrator calls this method, user roles will be checked in a table-dependent manner to determine if the action will be allowed.
removeTYPE
removeTYPE(id) -> integer
Removes an existing record from the database, returning 1 on success.
When a non-administrator calls this method, user roles will be checked in a table-dependent manner to determine if the action will be allowed.
getDefaultTYPE
getDefaultTYPE() -> record
Returns a record which is partially filled in with appropriate default values, suitable for adding to the database after you have filled in the fields you wish to set. The default values depend on the table, but will normally include blank strings or zeroes in most fields, the ID of the current user where appropriate, and so forth.
getTYPE
getTYPE(record) -> record
Given a pattern record, returns the first record from the database that matches it exactly. (Only fields containing a non-empty string or non-zero value are compared.) If no record matches, a fault will be raised.
This method limits its results to records visible to the user whose credentials
are used to call it. The is_hidden field in the pattern, if present, is
ignored even if the user is an administrator; see the getHiddenTYPEs method to
retrieve hidden records.
getTYPEs
getTYPEs(record) -> list of records
(Note the 's' after the type name.) Like getTYPE, but returns a list of
matching records, which may be empty if no matches were found.
This method returns only visible records; if the table has an is_hidden field,
its value in the search pattern is ignored.
This method limits its results to records visible to the user whose credentials
are used to call it. The is_hidden field in the pattern, if present, is
ignored even if the user is an administrator; see the getHiddenTYPEs method to
retrieve hidden records.
getAllTYPEs
getAllTYPEs() -> list of records
Like getTYPEs but returns a list of all records, as if getTYPEs was called
with an empty pattern record. Like getTYPEs, the results are limited to
records visible to the calling user.
getTYPEById
getTYPEById(id) -> record
Like getTYPE, but returns a record matching the specified ID. This is exactly
equivalent to calling getTYPE with a pattern with the only non-empty field
being the ID, and is intended as a convenience for this very common operation.
countTYPEs
countTYPEs() -> int
Counts the number of visible records in the table.
addFullTYPEWithNames
addFullTYPEWithNames(record) -> id
Like addFullTYPE, but for fields that reference another record, names are
converted to IDs on the server side before the record is added.
At least the following fields are subject to name conversion:
| Table | Fields |
|---|---|
| users | time_gui, expense_gui, mileage_gui |
| projects | parent, creator |
| time_recs | user, project, code, subcode, subsubcode |
| expense_recs | user, project, expense_code, currency, source |
| travel_recs | user, project, vehicle, reason, measurement |
When a non-administrator calls this method, user roles will be checked in a table-dependent manner to determine if the action will be allowed.
modifyTYPEWithNames
modifyTYPEWithNames(id, record) -> id
Like modifyTYPE, but for fields that reference another record, names are
converted to IDs on the server side before the record is modified.
When a non-administrator calls this method, user roles will be checked in a table-dependent manner to determine if the action will be allowed.
getTYPEWithNames
getTYPEWithNames(record) -> record
Like getTYPE, but for fields that reference another record, names are returned
instead of IDs.
This method limits its results to records visible to the user whose credentials
are used to call it. The is_hidden field in the pattern, if present, is
ignored even if the user is an administrator; see the getHiddenTYPEs method to
retrieve hidden records.
getTYPEsWithNames
getTYPEsWithNames(record) -> list of records
Like getTYPEs (note the 's' after the type name) but returns names instead of
IDs in fields that reference other records.
This method limits its results to records visible to the user whose credentials
are used to call it. The is_hidden field in the pattern, if present, is
ignored even if the user is an administrator; see the getHiddenTYPEs method to
retrieve hidden records.
addTYPEToGroup
addTYPEToGroup(id, group_id) -> integer
Adds a record to a group. Returns 1 on success.
This method requires administrative privileges.
removeTYPEFromGroup
removeTYPEFromGroup(id, group_id) -> integer
Removes a record from a group. Returns 1 on success.
This method requires administrative privileges.
getHiddenTYPEs
getHiddenTYPEs(record) -> list of records
(Note the 's' after the type name.) Like getTYPEs but instead of returning
only visible records, this method returns only the hidden records from the table
instead. (The value of the is_hidden field in the pattern is ignored; this
method always returns hidden records.)
This method requires administrative privileges.
getHiddenTYPEsWithNames
getHiddenTYPEsWithNames(record) -> list of records
(Note the 's' after the type name.) Like getTYPEsWithNames but instead of
returning only visible records, this method returns only the hidden records from
the table instead. (The value of the is_hidden field in the pattern is
ignored; this method always returns hidden records.)
This method requires administrative privileges.
hideTYPE
hideTYPE(id) -> 0
Hides a record, given its ID. This method requires administrative privileges.
unhideTYPE
unhideTYPE(id) -> 0
Unhides a record, given its ID. This method requires administrative privileges.
getLoggableTYPEs
getLoggableTYPEs(pattern) -> list of records
Returns a list of visible and loggable records from the table.
countLoggableTYPEs
countLoggableTYPEs() -> int
Returns a count of visible and loggable records from the table.
getLoggableTYPEsWithNames
getLoggableTYPEsWithNames(pattern) -> list of records
Like getTYPEsWithNames but returns only loggable records.
getTYPEAttributeTypes
getTYPEAttributeTypes() -> list of AttributeTypeRecord
Return a list of AttributeTypeRecords associated with the table.
getTYPEAttributes
getTYPEAttributes(id) -> list of AttributeQueryResult
Returns a list of attributes, similar to that returned by queryAttributes, for
a specific record in the table.
setTYPEAttributes
setTYPEAttributes(id, list of AttributeValue) -> 0
Sets one or more attributes on a specific record of the table. The AttributeValue structure passed to this method has two fields, "name" and "value", both strings; values of non-string attributes must be passed as strings and will be converted to the proper type on the server side.
searchTYPEs
searchTYPEs(string) -> list of records
Searches for a string in the table, returning visible matching records. Fields searched for the string are table dependent, but typically include display name (pname) and description fields if available.
searchTYPEsWithNames
searchTYPEsWithNames(string) -> list of records
Like searchTYPEs but converts IDs to names in the same manner as the other
"...WithNames" methods described here.
Generic Methods
In addition to the per-type methods described above, there is a set of generic methods which can operate on every table the jxAPI supports, not just the ones for which the per-type methods are provided. Because the types of the arguments and returns of these methods can vary, however, they are not supported by most typed endpoints -- it may be possible to use them, but doing so may require the client to manually construct SOAP requests and parse responses.
addFullRecord
addFullRecord(table_name, record, withNames=False) -> id
Adds a record to a table, returning its ID.
If the withNames parameter is true, name to ID conversion is performed on some
or all fields which reference other tables; see the documentation for
addFullTYPEWithNames for more information.
Note that for compatibility with previous versions of the jxAPI, the withNames
parameter is not available through typed endpoints.
When a non-administrator calls this method, user roles will be checked in a table-dependent manner to determine if the action will be allowed.
modifyRecord
modifyRecord(table_name, id, record) -> id
Modifies an existing record, returning its ID.
If the withNames parameter is true, name to ID conversion is performed on some
or all fields which reference other tables; see the documentation for
addFullTYPEWithNames for more information.
Note that for compatibility with previous versions of the jxAPI, the withNames
parameter is not available through typed endpoints.
When a non-administrator calls this method, user roles will be checked in a table-dependent manner to determine if the action will be allowed.
getDefaultRecord
getDefaultRecord(table_name) -> record
Returns a blank record with appropriate default values filled in.
getRecordsList
getRecordsList(table_name, pattern, withNames=False, only_hidden=False) -> list of records
Returns visible (to the calling user) records which match the provided pattern;
any field (other than is_hidden, which is ignored) which does not contain an
empty or zero value is compared exactly.
If the withNames parameter is true, ID to name conversion is performed on some
or all fields which reference other tables; see the documentation for
addFullTYPEWithNames for more information.
If the only_hidden parameter is true, this method returns hidden records
instead of visible ones.
Note that for compatibility with previous versions of the jxAPI, the withNames
and only_hidden parameters are not available through typed endpoints.
removeRecord
removeRecord(table_name, pattern) -> integer
Removes records matching the provided pattern.
When a non-administrator calls this method, user roles will be checked in a table-dependent manner to determine if the action will be allowed.
addObjectToGroup
addObjectToGroup(group_id, table_name, object_id) -> integer
Adds a record to a group, returning 1 on success.
This method requires administrative privileges.
removeObjectFromGroup
removeObjectFromGroup(group_id, table_name, object_id) -> integer
Removes a record from a group, returning 1 on success.
This method requires administrative privileges.
getSearchableTables
getSearchableTables() -> list of table names
Returns a list of all of the table names the jxAPI knows about.
getRecordsListWithDictString
getRecordsListWithDictString(table_name, dict_string) -> list of records
Returns records that match a query specified by a dictionary, which is passed as its string representation. See the method reference for more details.