A business object is an encapsulation of business data and functionality that usually corresponds to a record in a particular database table. Business objects contain fields, exposed as properties. Get() methods exist for all fields, and set() methods exist only for writable fields. Most business objects contain an ObjectId field, which serves as the primary key for that object.
Note: Client-side business objects are transient and should not be reused. For example, when creating a new instance of a client-side business object, after you call the create() method to create the object in the database, the object should be reloaded from the database if you intend to use it. This will help ensure that the data is valid, based on the server-side business rules. This warning also applies to updating business objects; after calling update(), reload the object if you intend to use it further.
Load methods that cause multiple business objects to be loaded will return a BOIterator (a business object iterator), that can be used to iterate through the returned business objects. Similar to Java's java.util.Iterator class, it has both hasNext() and next() methods. Not all business objects are retrieved from the server at one time. As you iterate through the result set, more business objects are automatically loaded from the server as needed.
When loading an object, the fields to be loaded can be specified. If this parameter is null, the minimal fields necessary will be loaded. You can obtain lists of available fields by calling the following methods:
getAllFields() - Returns an array of all fields for this business object. Code assignment and UDF value field names are not included in this array. For more information, see the Special Handling of Codes and UDFs section below.
getRequiredCreateFields() - Returns an array of fields required to create this business object. Some business objects have fields listed in this array that are OR'ed. These fields will appear in the array separated by the "|" character. For example, the required create fields for Activity are "Id", and "ProjectObjectId|WBSObjectId," meaning the Id field must always be set, and either the ProjectObjectId or the WBSObjectId must be set (setting only the ProjectObjectId will cause the Activity to be created at the project-level).
getSpreadFields() - Returns an array of spread fields (unit and cost) for business objects that support spreads: EPS, Project, WBS, Activity, Role, Resource, and ResourceAssignment.
getMainFields() - Returns all fields supported by the business object, except for summary, code assignment, and UDF fields.
Note: In order to have the API perform optimally, only specify to load the fields that are absolutely needed.
Business objects can be loaded directly using static load() methods of the class itself, from a parent object, from the GlobalObjectManager if the object is global, or from the EnterpriseLoadManager. To run the API using the EnterpriseLoadManager, ensure that both the NLS_COMP and NLS_SORT parameters are set to the same value. Objects can be loaded by specifying an array of ObjectIds or by specifying a "where" clause and/or an "order by" clause. The where clause is used to filter the business objects when loaded.
- Where clauses that use Date data types must use the WhereClauseHelper to format the date value. See Load Activities Example below.
- Complex where clauses can be created using AND and OR.
- Where clauses follow SQL-92 grammar and support function calls of the SQL language, with some exceptions. Join statements and nested select statements are not supported. The DATEADD function of SQL Server is also not supported.
The following code examples demonstrate how to specify a where clause when loading business objects:
Example 1: Load all the projects that have an Id beginning with "API-Project," ordering by Id in ascending order:
EnterpriseLoadManager elm = session.getEnterpriseLoadManager();
BOIterator<Project> boi = elm.loadProjects( new String[]{ "Id", "Status", "StartDate", "FinishDate" },
"Id like 'API-Project%'", "Id asc" );
while ( boi.hasNext() )
{
Project proj = boi.next();
// Add code here to process each Project...
}
Example 2: Load activities from a project where the actual start is within a particular date range, ordering by Name in descending order:
SimpleDateFormat formatter = new SimpleDateFormat( "MM/dd/yyyy" );
Date date = formatter.parse( "03/03/2005" );
String dateBegin = WhereClauseHelper.formatDate( session, date );
date = formatter.parse( "03/09/2005" );
String dateEnd = WhereClauseHelper.formatDate( session, date );
String whereClause = "ActualStartDate between " + dateBegin + " and " + dateEnd;
BOIterator<Activity> boi = project.loadAllActivities( new String[]{ "Id", "Name" }, whereClause, "Name desc" );
while ( boi.hasNext() )
{
Activity act = boi.next();
// Add code here to process each Activity...
}
Example 3: Load all active timesheets from a timesheet period:
BOIterator<Timesheet> boi = timesheetPeriod.loadTimesheets( new String[]{ "ResourceName", "ResourceId", "Status" }, "Status='" + com.primavera.integration.client.bo.enm.TimesheetStatus.ACTIVE.getValue() + "'", "" );
while ( boi.hasNext() )
{
Timesheet ts = boi.next();
// Add code here to process each Timesheet...
}