Integration Platform Technologies: Siebel Enterprise Application Integration > Integration Objects > About Integration Component Keys >

User Keys

A 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 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.

In Siebel Tools, user keys are defined as Integration Component Key objects, with the Key Type property set to User Key.

Integration component keys are built by the Integration Object Builder wizard, based on values in the underlying table of the business component on which the integration component is based. 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.

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 the Account Name and Account Integration Id fields present. When the EAI Siebel Adapter performs validation, it first checks the Account Name and Account Location fields (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 the Account Location field present, but set to null, then the EAI Siebel Adapter would pick 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 cases of the user key fields do not match. You can use the Force Case property on the business component field to make sure that user key fields are always stored in one case, but only if you require case-insensitive matching for performance reasons. Routine use of the Force Case property is not recommended.

NOTE:  For performance reasons, user keys for child integration components are not included in the WHERE clause of the SQL generated to query for child component records in the Siebel database. If you must query the child component to find matching records, then consider redesigning your integration objects, such as creating a new integration object where the child component becomes the parent. For example, if Account is the parent and Asset the child, and you to query for specific assets, then create a new integration object where Asset is the parent and Account is the child.

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, you can determine the table on which your business component is based by looking in Siebel Tools.

To find the user keys for a table

1. Select the Business Component object in the Object Explorer.

   The Business Components list appears in the Object List Editor.

2. Select a business component.
3. Click the link in the Table column.

   The Tables list appears, displaying the table associated with the business component (for example S_CONTACT).

4. Expand the Tables object in the Object Explorer, and then select User Key.

   The User Keys list displays 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 child object 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, then 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.

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

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

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

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

Figure 14. 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 might 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.