Project Attributes

Warning: legacy API

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.

While Journyx allows custom attributes to be attached to almost any type of object, the most common case in which most client applications will need to use them is when working with projects, since much of the information associated with projects is actually stored as attributes rather than as part of the core project record.

Attribute Overview

Conceptually, an attribute can be thought of as an extra column that is accessed separately from the table it is attached to. The definition of one of these extra columns is referred to in the jxAPI as an Attribute Type, while the term Attribute refers to a single value stored in it. An Attribute Type is associated with a particular table, while an Attribute is associated with its Attribute Type and with a particular record in the corresponding table.

All of these associations are referred to in the jxAPI by unique IDs. Every Attribute and Attribute Type has a unique ID, and each Attribute references the IDs of its Attribute Type and corresponding record.

Available Project Attribute Types

Several Attribute Types for projects are predefined in a typical Journyx installation:

ID	Type	Description
projects_budget	string	Budget
projects_customer_name	string	Customer name
projects_startdate	date	Start date
projects_enddate	date	End date
projects_priority	string	Priority
projects_bill_rate	number	Bill rate in dollars per hour
projects_bill_period_type	string	Bill rate type
projects_pay_rate	number	Pay rate in dollars per hour
projects_pay_period_type	string	Pay rate type
projects_state	string	State of the project

If you have added custom project columns, or if your application needs a way to verify the availability of the predefined project attributes, you can use the queryAttributeTypes jxAPI method to fetch the attribute type definitions for the project table:

AttributeTypeRecord query = new AttributeTypeRecord();
query.setTable_name("projects");

AttributeTypeRecord[] types = jxapi.queryAttributeTypes(session_key, query);

The parameter to queryAttributeTypes is an AttributeTypeRecord to match against, and the return value is the matching records. In this case, the only field that has a non-empty value in the query is the table name ("projects"), so the return is every attribute type defined for the project table. Note that if you do this type of query on a typical Journyx installation you may see additional attributes not listed above in the return list -- most of these are for internal use (MS Project syncing, for example) and should not be modified.

If you have defined custom columns in your Journyx installation, you can use this type of query to locate their IDs, or you can use the pname or description fields of the query record to search for them individually.

Fetching Attribute Values For A Project

Once you know the ID of a project, you can retrieve its attribute values either individually or all at once. To retrieve a single attribute value, use the getAttribute (for string and date attributes), getAttributeInteger, or getAttributeNumber methods. If you are using one of the SOAP-based jxAPI endpoints, you must use the proper method for the type of the attribute you are retrieving; for the XML-RPC and JSON endpoints, getAttribute will work for any type.

The first parameter (after the session key) to the getAttribute family of methods is the table name, in this case "projects". Next is the ID of the project to fetch the attribute value for. Finally, the last parameter is the ID of the attribute type. For example:

String budget = jxapi.getAttribute(session_key, "projects", project_id, "projects_budget");
String start_date = jxapi.getAttribute(session_key, "projects", project_id, "projects_startdate");
double bill_rate = jxapi.getAttributeNumber(session_key, "projects", project_id, "projects_bill_rate");

Making a lot of getAttribute calls isn't very efficient, so if you need to get multiple values at once, you can use the queryAttributes method. queryAttributes is similar to getAttribute, except instead of sending a single record ID and a single attribute type ID, you pass lists of IDs instead, with an empty list meaning "everything". For example, to fetch all attributes for a single project:

AttributeQueryResult[] result;
String[] projects = { project_id };
String[] attributes = {};

result = jxapi.queryAttributes(session_key, "projects", projects, attributes);

for (AttributeQueryResult q : result) {
  System.out.format("%s (%s): %s\n", q.getAttr_pname(), q.getAttrtype_id(), q.getValue());
}

Depending on what you pass in the record and attribute ID lists, you can use queryAttributes to fetch all attributes for one project, all projects, or specific projects; fetch the value of an attribute across all projects; or almost any other combination of possibilities.

The return value of queryAttributes is a list of AttributeQueryResult objects. These objects have fields "object_id", "attrtype_id", "attr_pname" (the printable name of the attribute), and "value". The value is always converted to a string, even if the attribute is actually an integer or floating point number.

Setting Attribute Values For A Project

The simplest way to set attribute values is to use the setAttribute family of jxAPI methods. As with the getAttribute family, there is not only setAttribute for strings and dates, but also setAttributeInteger and setAttributeNumber.

The setAttribute methods take five parameters (plus the session key): the object type (in this case "projects"), the project ID, the attribute type ID, the value, and a boolean which if true allows an existing value to be overwritten, and if false causes a fault if a value already exists.

jxapi.setAttribute(session_key, "projects", project_id, "projects_startdate", "20121201", true);
jxapi.setAttributeNumber(session_key, "projects", project_id, "projects_bill_rate", 100.0, true);

Unfortunately there is no jxAPI call to set multiple attributes at once, so you must use individual setAttribute calls for every one. If you are using the XML-RPC or JSON endpoints, consider using the native batch processing capabilities of those protocols to improve performance if you need to set a lot of attributes at the same time.

If you want to set project attributes immediately after creating a project record, remember that methods such as addFullProject return the ID of the newly created project record. For example:

ProjectRecord newproject;
String project_id;

newproject = jxapi.getDefaultProject(session_key);
// ... fill in project record here
project_id = jxapi.addFullProject(session_key, newproject);
jxapi.setAttribute(session_key, "projects", project_id, "projects_startdate", "20121201", true);
// ... and more setAttribute calls