This chapter covers the following topics:
Use the public business object APIs to perform operations on the seeded business objects. See: Business Objects Overview. Because business objects logically encapsulate specific areas of the Oracle Trading Community Architecture (TCA) data model, these types of business object API procedures let you directly manipulate TCA data:
Create: Creates an instance of the business object in the database.
Update: Updates a specific business object according to provided values.
Save: Either creates or updates a business object, depending if the passed identification information matches an existing business object.
Get: Extracts and returns data for either a single, complete business object, or all objects affected by a specific business event.
Business objects can contain a hierarchy of embedded business objects, business structures, and granular entities. Even though you use business object APIs at the object level, that initial API call triggers subsequent business object or granular API calls down the hierarchy. For example, see: Granular Versus Business Object APIs.
Related Topics
Business object APIs are provided for every seeded business object. For details on each API, including description, PL/SQL procedure, parameters, and validations, see: Oracle Integration Repository. For information about what each API does with the corresponding business object's attributes, see: Business Object API Attributes Information Overview.
The seeded business object APIs are:
Customer Account Business Object API
Customer Account Contact Business Object API
Customer Account Site Business Object API
EDI Business Object API
EFT Business Object API
E-Mail Business Object API
Organization Business Object API
Organization Contact Business Object API
Organization Customer Business Object API
Party Site Business Object API
Person Business Object API
Person Customer Business Object API
Phone Business Object API
Source System Management Business Object API
SMS Business Object API
Telex Business Object API
Web Business Object API
The seeded APIs have all four types of procedures: Create, Update, Save, and Get. See: Business Object API Features.
Note: Unlike the other seeded APIs, the Source System Management Business Object API does not create, update, save, or get a specific seeded business object. You use this API to create and maintain source system mappings for any business object. See: Source System Management Business Object API.
Related Topics
Source System Management (SSM) maintains mappings, or references, of records between source systems, for example between Oracle Trading Community Architecture and a legacy system, or between a data hub and a spoke system. See: Source System Management Overview, Oracle Trading Community Architecture Administration Guide.
The Source System Management Business Object API maps entire business objects, not specific granular entities, to their source systems. This table shows the root TCA entities for each business object or business structure, representing the transition link between entity SSM and business object SSM.
| Business Object or Structure | TCA Entity Table |
|---|---|
| Organization | HZ_PARTIES |
| Person | HZ_PARTIES |
| Party Site | HZ_PARTY_SITES |
| Organization Contact | HZ_ORG_CONTACTS |
| Customer Account | HZ_CUST_ACCOUNTS |
| Customer Account Site | HZ_CUST_ACCT_SITES_ALL |
| Customer Account Contact | HZ_CUST_ACCOUNT_ROLES |
| Phone | HZ_CONTACT_POINTS |
| Telex | HZ_CONTACT_POINTS |
| HZ_CONTACT_POINTS | |
| Web | HZ_CONTACT_POINTS |
| SMS | HZ_CONTACT_POINTS |
| EDI | HZ_CONTACT_POINTS |
| EFT | HZ_CONTACT_POINTS |
| Location | HZ_LOCATIONS |
| Person Contact Information | HZ_PARTIES |
Note: The Organization Customer and Person Customer business objects are not mapped to any TCA entities. Business object SSM support is not available for these business objects.
The Source System Management Business Object API procedures are:
Create Business Object Source System Reference
Update Business Object Source System Reference
Remap Internal Business Object Identifier
For details on these procedures, including description, PL/SQL procedure, parameters, and validations, see: Source System Management Business Object, Oracle Integration Repository.
Related Topics
All business object API procedures of the same type share common features and functionality. See:
Business object API procedures of all types also share common return status and error handling.
The x_return_status output parameter provides the status of the API:
Success (FND_API.G_RET-STS_SUCCESS): The business object API procedure was successful in its operation. The entire business object was created, updated, or retrieved, depending on the procedure, and all of the caller's expected operations occurred.
Error (FND_API.G_RET_STS_ERROR): The business object API procedure did not accomplish its function. Relevant error messages are provided. Common errors include missing attributes or embedded entities.
Unexpected Error (FND_API.G_RET_STS_UNEXP_ERROR): The business object API procedure did not accomplish its function, due to errors that the API could not handle.
Errors can occur at either the business object API level, or at the level of the embedded business object or granular API calls. For example, a business object has an embedded granular entity. When you use an API to update that business object, that initial call triggers a call to the appropriate granular API for the embedded entity. You can get errors from either API call.
Errors from the initial business object API call are reported in the usual way. Examples of errors include not entering mandatory embedded entities, or trying to create a business object that already exists.
Errors from embedded API calls, however, are propagated to the top business object API, which then provides you additional messages regarding the embedded business object, business structure, or granular entity that is the cause of the error. Because a business object can have multiple embedded items, with many levels, these messages help you determine the exact cause of the errors.
For example, you are trying to create a business object, which contains two embedded granular entities. One embedded entity cannot be created because a mandatory value is not passed, so an error message is provided specifying the missing value at the granular level. Another error message is provided at the business object level indicating in which embedded entity the attribute is missing.
Related Topics
Create business object API procedures create an instance of the particular business object in the database, returns the business object identifier to the caller, and provides information communicating the success of the operation. Create procedures are provided for every seeded business object. For details on specific procedures, see: Oracle Integration Repository.
If errors occur with the Create business object procedure call, then all parts of the call fail, including the API calls for embedded items. You cannot partially create a business object.
Any error that occurs in creating embedded items is propagated to the top business object level, and the creation of the entire object fails. See: Business Object API Error Handling.
If the p_validate_bo_flag parameter is set to TRUE, which it is by default, then you must provide all mandatory embedded items in the business object that you want to create. If you do not, then the Create procedure fails. See: Rules for Embedded Items.
Some business objects cannot exist on their own, for example Organization Contact, Party Site, and Customer Account Site. To create such business objects, by calling for example the Create Organization Contact Business Object API procedure, you must pass either a TCA identifier or a combination of source system and source system reference, or both, to identify the parent business object. This table describes the Create procedure behavior depending on the passed information.
| TCA ID Passed | TCA ID Valid and of Correct Type | Source System and Source System Reference Passed | Source System and Source System Reference Valid and of Correct Type | TCA ID and Source System Information Map to Each Other and of Correct Type | API Procedure Behavior |
|---|---|---|---|---|---|
| No | Yes | Yes | Creates business object | ||
| No | Yes | No | Fails with invalid identification error | ||
| Yes | Yes | No | Creates business object | ||
| Yes | No | Fails with invalid identification error | |||
| Yes | Yes | Yes | Yes | Yes | Creates business object |
| Yes | Yes | Yes | Yes | No | Fails with invalid identification error |
| Yes | Yes | Yes | No | No | Fails with invalid identification error |
Optionally provide source system information for the business object that you want to create, to verify that the object does not already exist. If the object exists, then the Create procedure fails. This table describes the Create procedure behavior depending on the passed information.
| TCA ID Passed | Source System and Source System Reference Passed | Passed Source System Information Matches Existing Mapping | API Procedure Behavior |
|---|---|---|---|
| No | Yes | Yes | Fails with error specifying that the business object already exists |
| No | Yes | No | Creates business object and source system mapping |
| No | No | Creates business object | |
| Yes | Fails with invalid identification error |
In most cases, when you call a Create business object API procedure, the business object's embedded business objects and structures are also created, with their own Create business object API procedures called in a nested manner. In the single case where an existing Person business object can be used as an Organization Contact, when you use the Create Organization Contact Business Object API procedure, the Save Person Business Object API procedure is called to check that the person already exists. See: Save Business Object API Procedures.
When you call a Create business object API procedure, corresponding granular APIs are called for embedded granular entities, depending on information, if any, that you pass to identify existing entities.
If you do not pass identification information, or the identifier does not match existing entities, then the granular Create procedure is called to create the entity.
If the entity exists, then the granular Update procedure is called. This can happen for entities, such as locations, that are shared among multiple business objects.
Related Topics
Update business object API procedures modify a particular existing business object according to the provided values, returns the updated portions of the business object to the caller, and provides information communicating the success of the operation. Update procedures are provided for every seeded business object. For details on specific procedures, see: Oracle Integration Repository.
If errors occur with the Update business object procedure call, then all parts of the call fail, including the API calls for embedded items. You cannot partially update a business object.
Any error that occurs in creating or updating embedded items is propagated to the top business object level, and the update of the entire object fails. See: Business Object API Error Handling.
You must pass either a TCA identifier or a combination of source system and source system reference, or both, to identify the existing business object to update. This table describes the Update procedure behavior depending on the passed information.
| TCA ID Passed | TCA ID Valid | Source System and Source System Reference Passed | Passed Source System Information Matches Existing Mapping | TCA ID and Source System Information Map to Each Other | API Procedure Behavior |
|---|---|---|---|---|---|
| No | Yes | Yes | Updates business object | ||
| No | Yes | No | Fails with invalid identification error | ||
| Yes | Yes | No | Updates business object | ||
| Yes | No | Fails with invalid identification error | |||
| Yes | Yes | Yes | Yes | Yes | Updates business object |
| Yes | Yes | Yes | Yes | No | Fails with invalid identification error |
| Yes | Yes | Yes | No | Fails with invalid identification error |
When you call an Update business object API procedure, the business object's embedded business objects and structures are either updated or created, with their own Save business object API procedures called in a nested manner. The Save procedure is called because:
Embedded items can be shared, for example Phone business object between Person business objects.
The Save procedure checks if items already exist.
See: Save Business Object API Procedures.
When you call an Update business object API procedure, corresponding granular APIs are called to create or update embedded granular entities, based on information, if any, that you pass to identify existing entities.
If you pass a valid TCA identifier for the entity, then the entity is updated. If the ID is invalid, then the granular API call returns an error. If you do not pass any TCA identifier, then one of two checks occur:
If Source System Management (SSM) is supported for the granular entity, then the granular API call checks if you provided a source system and source system reference combination. If source system information is:
Valid, then the entity is updated.
Provided but not matching an existing entity, then the entity is created.
Invalid, then the granular API call returns an error.
Not passed at all, then the entity is created.
If SSM is not supported for the entity, the granular API call attempts to identify the entity that the caller is referring to, using a logical key. If the provided logical key attributes uniquely match an existing entity in TCA, then that entity is updated. For that reason, logical key attributes for an entity cannot be updated without the TCA identifier.
If the provided logical key attributes do not uniquely match an existing entity in TCA and no TCA identifier is provided, then the entity is created.
Related Topics
Save business object API procedures are essentially logical wrappings of both Create and Update API procedures for the same business object. For details on specific Save procedures, see: Oracle Integration Repository.
The Save procedure calls either the Create or Update procedure:
Create: If you do not pass identification information, or if the business object does not exist. See: Create Business Object API Procedures.
Update: If you pass valid information to identify an existing business object. See: Update Business Object API Procedures.
You must pass either a TCA identifier or a combination of source system and source system reference, or both, to identify the existing business object to update. This table describes the Save procedure behavior depending on the passed information.
| TCA ID Passed | TCA ID Valid | Source System and Source System Reference Passed | Passed Source System Information Matches Existing Mapping | TCA ID and Source System Information Map to Each Other | API Procedure Behavior |
|---|---|---|---|---|---|
| No | No | Creates business object | |||
| No | Yes | Yes | Updates business object | ||
| No | Yes | No | Fails with invalid identification error | ||
| Yes | Yes | No | Updates business object | ||
| Yes | No | Fails with invalid identification error | |||
| Yes | Yes | Yes | Yes | Yes | Updates business object |
| Yes | Yes | Yes | Yes | No | Fails with invalid identification error |
| Yes | Yes | Yes | No | No | Fails with invalid identification error |
Related Topics
Two types of Get business object API procedures are available:
Event Independent, for all seeded business objects.
Event Dependent, for the seeded Organization Customer, Person Customer, Organization, and Person business objects.
For details on specific procedures, see: Oracle Integration Repository.
Related Topics
Provided for each of the seeded business objects, these procedures retrieve and return business objects, recursively traversing down the business object's hierarchy, gathering the embedded objects, structures, and entities, to provide a complete, packaged business object. The returned object is a wrapping around data structures representing all of the business object's embedded items.
You must pass either a TCA identifier or a combination of source system and source system reference, or both, to identify the existing business object to extract. This table describes the Get procedure behavior depending on the passed information.
| TCA ID Passed | TCA ID Valid | Source System and Source System Reference Passed | Passed Source System Information Matches Existing Mapping | TCA ID and Source System Information Map to Each Other | API Procedure Behavior |
|---|---|---|---|---|---|
| No | Yes | Yes | Gets business object | ||
| No | Yes | No | Fails with invalid identification error | ||
| Yes | Yes | No | Gets business object | ||
| Yes | No | Fails with invalid identification error | |||
| Yes | Yes | Yes | Yes | Yes | Gets business object |
| Yes | Yes | Yes | Yes | No | Fails with invalid identification error |
| Yes | Yes | Yes | No | Fails with invalid identification error |
Related Topics
Get Business Object API Procedures
Provided for the seeded Organization Customer, Person Customer, Organization, and Person business objects, these procedures are affiliated with each seeded Create or Update business event for these objects. See: <link to business events overview>.
For each event, the corresponding Get procedure returns, to the event subscriber in one API call, all the business objects that the single business object affects:
Create Business Event: The entire new business object is returned.
Update Business Event: The entire updated business object is returned, as well as details about what and how specific portions of the object were updated.
For example, when an Organization business object is created, a corresponding Create Organization business event is raised to event subscribers, and the Get Created Organization Business Object API procedure returns the new Organization business object to the subscribers.
Note: The Event Dependent procedures are specifically used only in the context of business object business events. Do not use them otherwise.
These procedures allow systems to retrieve business objects as soon as the business object data is created or updated. Subscribing parties must be able to act on a business event by receiving the created or updated business objects.
The event dependent business object extraction process involves different types of Event Dependent procedures:
Get Business Object IDs
Get Updated Business Object
Get Business Object Data in Bulk
Even though one business event can involve multiple business objects, the event passes a single numeric event identifier to the event subscriber. This ID is then passed to the corresponding Get Business Object IDs procedure and used as a key to access a tracking table, to determine the affected object data for the business event. Given the passed business event ID, the procedure extracts an array of business object IDs.
Important: The business event identifier passed to the Get Business Object IDs procedure must be valid for the business object. An error occurs if the passed ID is not found in the tracking table or is not valid for the business object.
Get Business Object IDs procedures are provided for the Create and Update business events for Organization Customer, Person Customer, Organization, and Person business objects. For example, if the business event is that an Organization business object is created or updated, then either the Get Created Organization Business Object ID or Get Updated Organization Business Object ID procedure is called, respectively.
With business object identifiers extracted by the Get Business Object IDs procedure, another procedure is called next to retrieve each of the business objects in the array of IDs. One procedure is called for each ID in the array, with the business event and object IDs passed in, depending on the type of business event.
Create Business Event: The corresponding Event Independent Get procedure is called. See: Event Independent Get Procedures.
Update Business Event: The corresponding Get Updated Business Object procedure is called to extract not only the business object data, but also indicators that define which pieces of data has changed. See: Get Updated Business Object Procedures.
An error occurs if you attempt to get an updated business object by passing a business event ID and business object ID, but the object was not updated as part of that event.
Alternatively, you can combine these two steps and use the Get Business Object Data in Bulk procedure. As essentially a wrapping of the Get Business Object IDs procedures and the appropriate procedures to retrieve business object data, the Get Business Object Data in Bulk:
Receives the single business event identifier from the business event and retrieves an array of business object IDs.
For each business object ID in the array, calls the appropriate Event Independent or Get Updated Business Object procedure and adds the created or updated business object to a table.
Returns the table of objects to the caller.
Get Updated Business Object procedures are provided for the Update business events for Organization Customer, Person Customers, Organization, and Person business objects. See: Event Dependent Extraction Process.
These procedures extract the entire updated business object, for a specific Update business event. By returning an action type, the procedure also specifies how the business object's root level attributes, as well as the object's embedded items, have changed as a result of the Update business event. See: Business Object Attributes and Business Object Embedded Items.
Note: The procedures provide action types for business objects, business structures, and embedded granular entities at any level of the top business object's hierarchy, except at the root business object level for Organization Customer and Person Customer business objects.
This table describes what each action type means for business objects or structures, at any level of the business object hierarchy, and embedded entities. If an action type indicates that the business object or structure has new or updated embedded items, as a result of the Update business event, you refer to the action type for that embedded item to determine what happened.
| Action Type | Meaning for Business Object or Structure | Meaning for Granular Entity |
|---|---|---|
| CHILD_UPDATED |
|
Not used. |
| CREATED |
|
Attributes of the embedded entity were created. |
| UPDATED |
|
Attributes of the embedded entity were updated. |
| UNCHANGED | No changes were made to business object or structure attributes, nor to any of the embedded items. | No changes were made to attributes of the embedded entity. |
Action Type Example
This example illustrates the action types that are returned based on the changes made as a result of a specific Update business event. For this example, an Organization business object with ID of 1200 has this hierarchy:
Organization business object (ID: 1200)
Party Site business object (ID: 4445)
Location business structure (ID: 11)
Phone business object (ID: 1345)
Organization Contact business object (ID: 98)
Contact Person Information business structure (ID: 5)
Phone Business Object Added to Organization Contact Business Object
If a Phone business object with ID 321 is added to the Organization Contact business object 98, within Organization business object 1200, then an Organization Updated business event is raised. The Get Updated Organization Business Object procedure would return Organization object 1200 with the following action types.
Organization business object (ID: 1200, Action Type: CHILD_UPDATED)
Party Site business object (ID: 4445, Action Type: UNCHANGED)
Location business structure (ID: 11, Action Type: UNCHANGED)
Phone business object (ID: 1345, Action Type: UNCHANGED)
Organization Contact business object (ID: 98, Action Type: CHILD_UPDATED)
Contact Person Information business structure (ID: 5, Action Type: UNCHANGED)
Phone business object (ID: 321, Action Type: CREATED)
Organization Business Object Attributes Updated
If root level attributes of Organization business object 1200 are updated, then an Organization Updated business event is raised. The Get Updated Organization Business Object procedure would return Organization Object 1200 with the following action types.
Organization business object (ID: 1200, Action Type: UPDATED)
Everything else (Action Type: Unchanged)
Location Business Structure Updated and Contact Preference Added
If, within Organization business object 1200, the Location business structure 11 is updated, and Contact Preference entity 117 is added to Phone business object 321, then an Organization Updated business event is raised. The Get Updated Organization Business Object procedure would return Organization object 1200 with the following action types.
Organization business object (ID: 1200, Action Type: CHILD_UPDATED)
Party Site business object (ID: 4445, Action Type: CHILD_UPDATED)
Location business structure (ID: 11, Action Type: UPDATED)
Phone business object (ID: 1345, Action Type: UNCHANGED)
Organization Contact business object (ID: 98, Action Type: CHILD_UPDATED)
Contact Person Information business structure (ID: 5, Action Type: UNCHANGED)
Phone business object (ID: 321, Action Type: CHILD_UPDATED)
Contact Preference entity (ID: 117, Action Type: CREATED)
Related Topics