Business object application-specific information

Application-specific information in business object definitions provides the connector with application-dependent instructions on how to process business objects. The connector parses the application-specific information from the attributes or verb of a business object or from the business object itself to generate queries for Create, Update, Retrieve, and Delete operations.

The connector stores some of the business object's application-specific information in cache and uses this information to build queries for all the verbs.

If you extend or modify an application-specific business object, you must make sure that the application-specific information in the business object definition matches the syntax that the connector expects.

This section provides information on the application-specific information format for business objects supported by the connector.

Table 7 provides an overview of the functionality available in business object application-specific information.

Table 7. Overview of application-specific information in supported business objects

Scope of application-specific information Functionality
Entire business object Specifies:
  • The name of the corresponding Component Interface
  • Whether triggering of online Field PeopleCode edits is immediate or batch
  • Whether all rows associated with component interface are retrieved or only the most recent instance
Simple attributes Specifies:
  • Whether the application generates unique identifier values or whether the connector provides them
  • Whether an attribute should be used as a key for retrieving data
Business object verb The connector does not specify functionality based on the verb.

The following sections discuss this functionality in more detail.

Application-specific information at the business object level

Application-specific information at the business-object level allows you to:

At the business-object level, application-specific information format consists of four parameters separated by a colon (:) delimiter. The format is:

cIName=<ComponentInterface>
 :EFFDT=[true|false]:setInteractiveMode=[true|false]:GetHistoryItems
 =[true|false]:setEditHistoryItems=[true|false]
 :GetDummyRows=[true|false]:InsAtOldestEffDtPos=[true]
 :InsAtCurrentEffDtPos=[true]
 

Table 8 describes these parameters.

Table 8. AppSpecificInfo at the business-object level

AppSpecificinfo parameter Description
cIName Specifies the name of the Component Interface defined in the PeopleSoft application.
EFFDT (isEffectiveDated) Specifies whether the business object (or child business object) uses an Effective Date:
  • If the EFFDT parameter evaluates to true, the connector uses the CurrentItem() method to return only the record with the latest effective date.
  • If the EFFDT parameter evaluates to false, the connector uses the Item(index) method to return only the first record, regardless of the effective date. For example, the connector returns a future date, if one is listed.

The default value is true.

setInteractiveMode Determines when the connector sends changes to the Application Server. This property is typically used to enhance performance.
  • When set to true, the connector processes each time the value of a property or attribute changes; in other words, all online Field PeopleCode immediately triggers after the connector calls setPropertyName() on each attribute.
  • When set to false, the PeopleSoft application batches the processing, sending changes to the Application Server only when the connector calls Save() on a Component Interface.

The default value is true.

GetHistoryItems Determines how much data the connector retrieves.
  • When set to true, the connector retrieves all data rows, regardless of effective date, for the corresponding Component Interface.
  • When set to false, the connector retrieves only the current data (the effective row).

The default value is true.

GetDummyRows Supports the GetDummyRowsproperty in PeopleTools 8.4 and higher. Do not set this if you are using older versions of PeopleTools. For information about this property, see your PeopleSoft documentation.
InsAtOldestEffDtPos This parameter is provided to address limitations in older versions of PeopleTools where the call getEffectiveItemNum()returns an insert position of -1 for effective-dated rows. When InsAtOldestEffDtPos is set, the connector inserts the row at the highest index, which has the oldest effective date. If you set this parameter, do not set InsAtCurrentEffDtPos.
InsAtCurrentEffDtPos This parameter is provided to address limitations in older versions of PeopleTools where the call getEffectiveItemNum()returns an insert position of -1 for effective-dated rows. When InsAtCurrentEffDtPos is set, the connector inserts the row at the lowest index zero, which has the current effective date. If you set this parameter, do not set InsAtOldestEffDtPos.
SetEditHistoryItems Enables editing and saving of history data. Applies to effective-dated fields only.

For more information about the setInteractiveMode and GetHistoryItems properties, see the documentation from PeopleSoft.

For example, the PSFT_EmergencyContact business object might have the following value specified for its business object application-specific information:

cINAME=EMER_CONTACT_PROFILE:setInteractiveMode=false:
 GetHistoryItems=true:isEffectiveDated=false
 

Application-specific information at the attribute level

Application-specific information at the attribute level specifies the connector's behavior on an attribute-by-attribute level. The format of the application-specific information is a set of five name-value parameters, each of which includes the parameter name and its value. Each parameter set is separated from the next by a colon (:) delimiter. A vertical bar (|) separates the members of a set of options. The format is:

get=getFieldName:set=setFieldName:UID=[true|false]:GetKey=[true|false]:KeepRelationship
 =[true|false]:findKey=[true|false]:bigDec=true:EFFDT=[true|false]
 :EFFDTSEQ=[true|false]
 
Important:
Case is significant when the connector evaluates application-specific information.

For example, for a Read-Only simple attribute that should be used in addition to the key fields when retrieving data, you might specify the following format:

get=getBusinessUnit:GetKey=true
 

For a multiple-cardinality attribute whose children should be preserved even if they are not included in an Update business object request, you might specify the following format:

get=getEmergencyPhone:set=setEmergencyPhone:KeepRelationship=true
 

Table 9 describes each name-value parameter.

Table 9. Name-value parameters in attribute application-specific information

Parameter Description
get=getFieldName This parameter specifies the method to use when retrieving a value from a Component Interface field or Component Interface Collection to the current attribute.
set=setFieldName This parameter specifies the method to use when setting a value in a Component Interface field or Component Interface Collection, based on the value in the current attribute.
UID=[true|false] If this parameter is set to false, a unique value for the attribute must be provided by the business process that creates the business object. If the attribute does not contain a value, the connector sends an error message.

If this parameter is set to true, the application is responsible for generating a unique ID (using auto-numbering). Identifier generation requires the attribute's value to contain the String NEXT. The business process that creates the business object must populate its value as NEXT, or this value can be specified in the attribute's Default Value property. If the business object uses the Default Value property to provide the String NEXT, the connector's UseDefaults property must evaluate to true. For more information, see "UseDefaults".

If the key value is set to anything other than varchar, and you want the application to generate the IDs, leave the value blank and UID=True. Only set the value to NEXT when the key value is set to a varchar datatype.

When the application generates the unique ID, the connector retrieves the generated ID from the application after the Save operation completes and the data has been committed.

When ICS is the integration broker, the connector uses the retrieved ID in cross-referencing the business object.

If an attribute does not require the application to generate a unique ID, set this value to false, or do not include this parameter in the application-specific information.

GetKey=[true|false] If this parameter is set to true and the attribute's Key and Required properties evaluate to true, the connector includes the attribute as part of the key during a retrieve or retrieve-for-update operation.

The connector uses this parameter to differentiate a retrieval key from a create key when a distinction is necessary. When executing a create operation, the connector provides as keys only those attributes whose Key and Required properties evaluate to true. Because the create-key fields alone do not always uniquely retrieve required data, the connector adds to the keys all attributes whose GetKey parameter evaluates to true when it executes a retrieve operation.

KeepRelationship=[true|false] Used only on an attribute that represents an array of child business objects, this parameter specifies whether the connector deletes existing child business objects that are not represented in the source business object during an update operation.
  • Set to true to prevent deletion.
  • Set to false to allow deletion.

For example, assume an existing phone number is associated with an existing contact. Assume further that the connector receives a request to update a PSFT_EmergencyContact business object that contains a single child business object. The child associates an emergency phone number with the contact. If KeepRelationship evaluates to true for the EmergencyPhone[n] attribute, the connector updates the contact by adding its new association without deleting its existing association.

However, if KeepRelationship evaluates to false, the connector deletes all existing child data that is not contained in the source business object. In such a case, the contact is associated only with the new phone number.

findKey=[true|false] If this parameter is set to true, the connector includes the attribute as a key during a retrieve-by-content operation. Set this parameter for attributes that are find keys in the Component Interface.
bigDec=[true|false] This parameter identifies bigdecimal type attributes. Set this parameter to true for bigdecimal attributes in the Component Interface.
EFFDT=[true|false] This parameter identifies effective-dated attributes in the Component Interface. The connector only uses this if, at the business object level, application-specific information has EFFDT set to true.
EFFDTSEQ=[true|false] This parameter identifies the sequence of effective-dated attributes based on which insert position getEffectiveItemNum returns. The connector only uses this if the business object definition includes an effective-dated attribute.

Copyright IBM Corp. 1997, 2003