Integration Platform Technologies: Siebel Enterprise Application Integration > Integration Objects > About the Structure of Integration Objects >

About Integration Component Keys

There are multiple types of integration component keys:

• User Key. See About User Keys.
• Status Key. See About Status Keys.
• Hierarchy Parent Key. See About Using the Hierarchy Parent Key.
• Hierarchy Root Key. See About Using the Hierarchy Root Key.
• Modification Key. See Configuring the EAI Siebel Adapter for Concurrency Control.
• Foreign Key. See the Siebel Connector for Oracle Applications guide.
• Target Key. See the Siebel Connector for Oracle Applications guide.

NOTE:  There should be just one integration component key for every type of key except the user key. For example, if there are two Hierarchy Parent Keys defined for an integration component, the EAI Siebel Adapter picks the first one and ignores the second one.

About User Keys

User key is a group of fields whose values must uniquely identify a Siebel business component record. During inbound integration, user keys are used to determine whether the incoming data updates an existing record or inserts a new one. The Integration Object Builder wizard automatically creates some user keys based on characteristics discussed in About User Key Generation Algorithm. Make sure that the generated user keys match your business requirements; otherwise, inactivate them or add new user keys as appropriate.

Integration component keys are built by the Integration Object Builder wizard, based on values in the underlying table of the business component that the integration component is based on. Integration objects that represent Siebel business objects, and that are used in insert, update, synchronize, or execute operations, must have at least one user key defined for each integration component.

In Siebel Tools, user keys are defined as integration component key objects, with Key Type property set to User Key.

A sequence of integration component user keys is defined on each integration component definition, each of which contains a set of fields. During processing of integration component instance, the EAI Siebel Adapter chooses to use the first user key in the sequence that satisfies the condition that all the fields of that user key are present in an integration component instance. The first instance of each integration component type determines the user key used by all instances of that type.

For example, consider the Account integration object instance with only Account Name and Account Integration Id field present. When the EAI Siebel Adapter performs validation, it first checks the Account Name and Account Location field (the first user key for the Account integration component). In this example, because the Account Location field is missing, the EAI Siebel Adapter moves to the second user key—Account Integration Id. The Account Integration Id field is present in the integration component instance and has a value, so the EAI Siebel Adapter uses that as the user key to match the record. Now if the same instance also had Account Location field present, but set to null, then the EAI Siebel Adapter picks the Account Name and Account Location combination as the user key. This is because Account Location is not a required field.

A new user key is picked for each integration object instance (root component instance). However, for the child component instances, the user key is picked based on the first child instance, and then used for matching all instances of that integration component within the parent integration component instance.

For example, if a Siebel Message contains two orders, then the user key for order items is picked twice, once for each order. Each time, the user key is selected based on the first order item record and then used for all the siblings.

NOTE:  The EAI Siebel Adapter uses user keys to match integration component instances with business component records. Because the match is case sensitive there is a chance that records are not matched if the case of the user key fields do not match. To avoid this, use the Force Case property on the business component field to make sure that user key fields are always stored in one case.

About User Key Generation Algorithm

The Integration Object Builder wizard computes the user keys by traversing several Siebel objects, including the business object, business component, table, and link. This is because not every table user key meets the requirements to be used as the basis for integration object user keys.

To understand how the Integration Object Builder wizard determines valid integration component keys, you can simulate the process of validating the user keys. For example, determine the table on which your business component is based. In Siebel Tools, you can look up this information yourself. Navigate to the Business Components screen, and select a business component and check the Table column.

You can then navigate to the Tables screen, locate the table you want (in this example use S_CONTACT), and open the User Keys applet to see the user keys defined for that table.

For example, as shown in Figure 11, the table S_CONTACT has several user keys.

Figure 11. User Keys for Table S_CONTACT

Not every user key will necessarily be valid for a given business component. Multiple business components can map to the same underlying table; therefore, it is possible that a table's user key is not valid for a particular business component, but is specific to another business component.

Each User Key Column defined for a given user key must be exposed to the business component in which you are interested. For example, Figure 12 shows three user key columns for the user key S_CONTACT_U1.

Figure 12. User Key Columns for the S_CONTACT_U1 User Key

If the columns of the user key are exposed in the business component, and those columns are not foreign keys, the Integration Object Builder wizard creates an integration component key based on the table's user key. The Integration Object Builder wizard also defines one integration component key field corresponding to each of the table's user key columns. For example, in Figure 13, the user key columns are exposed in the Integration Component Fields applet for the Contact integration component.

Figure 13. Integration Component Field List

The Integration Object Builder wizard, for the preceding example, builds the integration component keys based on these table user keys. As illustrated in Figure 14, the wizard defines one integration component key field for each table user key column.

Figure 14. Integration Component Keys for Each Table User Key Column

Each valid integration component key contains fields. For example, as shown in Figure 15, for the Contact integration component, User Key 3 is made up of five fields: CSN, First Name, Last Name, Middle Name, and Personal Contact.

NOTE:  Only modify user keys if you have a good understanding of the business component and integration logic.

Figure 15. Contact Integration Component Key Fields

When the Integration Object Builder wizard creates these integration component keys, it attempts to use the appropriate table user keys; that is, the user keys that help to uniquely identify a given record. In some cases, you may find that certain integration component keys created by the Integration Object Builder wizard are not useful for your particular needs. In that case, you can manually inactivate the keys you do not want to use by checking the Inactive flag on that particular user key in Siebel Tools. You can also inactivate user key fields within a given user key.

NOTE:  For ease of maintenance and upgrade, inactivate unnecessary generated user keys and user key fields instead of deleting them.

About Status Keys

In the context of Siebel business objects, user keys are a group of fields whose values must uniquely identify only one Siebel business component record. Integration components within a corresponding integration object also contain user keys.

For many integrations, you want to know the status. For example, if you are sending an order request you want to know the ID of the Order created so that you can query on the order in the future. You can set the Status Object of the EAI Siebel Adapter to True to return an integration object instance as a status object.

The status returned is defined in the Integration Component using Status Keys. A Status Key is an Integration Component key of the type Status Key. Fields defined as part of the Status Key are included in the returned Status Object. If a Status Key is not defined for the Integration Component then neither the component nor any of its children are included in the returned object:

• To include descendants of an Integration Component without including any of its fields in the returned status object, specify an empty Status Key.
• To include information about which one of the update, insert, or delete operations was performed during an upsert request or synchronize request, include a field named Operation in the Status Key.

About Using the Hierarchy Parent Key

The Hierarchy Parent Key is used for integration objects that have a homogeneous hierarchy. This key should only have the Parent Id. The Hierarchy Parent Key is used for maintaining the hierarchy and keeping the data normalized.

For example, when you insert quotes, each quote item in turn can have more quote items. In this case, the first quote item inserted by the EAI Siebel Adapter has the Parent Id set to blank, but for each child quote item, the EAI Siebel Adapter checks the keys to figure out which fields are to be set. If the Hierarchy Parent Key is not defined, then the child quote item is inserted as a new quote item without a link to its parent (denormalized).

About Using the Hierarchy Root Key

The Hierarchy Root Key is an optional key that is useful only when integration objects have a homogeneous hierarchy. You can use this key to improve performance. The Hierarchy Root Key must have only one field, Root Id, which the EAI Siebel Adapter populates with the value of the ID field in the component instance that is in the root of the homogenous hierarchy. For example, assume quote Q1 has quote items A, B, and C where each of the quote items has child quote items (A1, A2, B1, B2,...). If you want to update the quantity requested for all quote items starting with the root quote item B, then it is faster if the data is denormalized. Using the Hierarchy Root Key, you can search for all records with Root Id equal to the Row Id of B, and set the QuantityRequested field for each item.

NOTE:  When the business component is hierarchy enabled, then the wizard automatically sets the Hierarchy Parent Key for the complex integration component. To have a business component hierarchy enabled you must set the property Hierarchy Parent Field.