Services Integration Framework Guide

10.4 HotFix 2
- 10.5
- 10.4 HotFix 3
- 10.4 HotFix 1
- 10.4
- 10.3 HotFix 3
- 10.3 HotFix 2
- 10.3 HotFix 1
- 10.3

Back Next

Put

Use the Put API to create or update a record. Use an insert operation to create a cross-reference record in the cross-reference table, and then create a base object record in the base object table. Use an update operation to update a cross-reference record. Trust rules and validation rules determine if the base object record is also updated.

A record contains base object fields or package fields. A record can contain all fields or a subset of the fields. For example, a package may contain the fields FIRST_NAME and LAST_NAME. If you want to update only the LAST_NAME field, you can omit the FIRST_NAME field from the Put request. If you have not specified a value for a field, the Put API sets the value to null.

After a Put request,

MDM Hub

calculates the best version of the truth for all columns in the record, even for columns not included in the Put request.

State Management

You can enable state management in the Hub Console. If state management is enabled for a package, you can set the value of HUB_STATE_IND to specify the initial state of a record when you insert the record.

You cannot specify a HUB_STATE_IND value to change the state of an active record to deleted. You cannot specify a HUB_STATE_IND value to change the state of a pending record to active.

You can specify a HUB_STATE_IND value to change the state of an active record to pending. The Put call creates a pending cross-reference record with the same source as the active cross-reference record. The two cross-reference records have the same PKEY_SRC_OBJECT value, but one record is active and the other record is pending.

Use the Delete, Restore, or PromotePendingXrefs APIs to change the state of a record.

The following table lists the possible values for HUB_STATE_IND and the state these values represent:

HUB_STATE_IND Value	State	Description
1	ACTIVE	The record is approved. Default is 1.
0	PENDING	The record is not approved.
-1	DELETED	The record is not used in the MDM Hub processes.

Transaction Support

When executed within an EJB context, this request can be part of a transaction with other requests. If there is a failure in any of the requests within a transaction, the Put API rolls back the entire transaction.

Validation Rule Processing

The Put API applies the applicable rule with the highest downgrade percentage.

Trust Override

You can override the trust settings for a trust-enabled column as part of the Put request.

The following code sample sets the maximum trust to 90%, sets the minimum trust to 40%, sets the unit of time for the trust graph to months, sets the number of units over which the trust decays to 12, and sets the trust graph decay to linear:

field = new TrustOverrideField();
field.setName("CITY");
field.setStringValue(city);
field.setTrustOverride(TrustSetting.createTrustSettingCustom( 90, 40, TrustTimeUnit.MONTH, 12, TrustGraphType.LINEAR));    
data.setField(field);

If the Put request contains a

trustOverrideField

parameter, the parameter must have a value regardless of whether trust is enabled or disabled. The Put response ignores the

trustOverrideField

values for columns that do not have trust enabled.

The Put process updates the value and the trust score in the master record. Any validation rules that downgrade trust still apply, so it is possible for the final trust score to be less than the specified trust score. The Put process calculates the best version of the truth (BVT) for the values in the master record except for the updated value with the trust override. If you want to include the updated value in the BVT calculation, call the ExecuteBatchRecalculateBvt API.

Putable System Columns

A putable column is a system column that you can update or insert data into. A system column can be putable, not putable, or putable enabled by the user.

The following table describes the putable status of the system columns:

System Column	Putable Status
CM_DIRTY_IND	Never putable.
CONSOLIDATION_IND	Never putable.
CREATE_DATE	You can set as putable in the base object column properties.
CREATOR	You can set as putable in the base object column properties.
DELETED_BY	You can set as putable in the base object column properties.
DELETED_DATE	You can set as putable in the base object column properties.
DELETED_IND	You can set as putable in the base object column properties.
HUB_STATE_IND	You can set as putable in the base object column properties.
INTERACTION_ID	Always putable.
LAST_ROWID_SYSTEM	Never putable.
LAST_UPDATE_DATE	Always putable.
ROWID_OBJECT	Never putable.
UPDATED_BY	You can set as putable in the base object column properties.

Put API Behavior for the Create_Date Column

Multiple factors can affect the behavior of the Put API request on the Create_Date column.

The Putable property affects the Put insert operation behavior for Create_Date.: If you set Create_Date to Putable, the Put API populates the base object record and the cross-reference record with the value in the Put request. Null is a permissible value. If you do not provide a value in the request, the Put API populates the base object record and cross-reference record with the SYSDATE value.; If you do not set Create_Date to Putable, the Put API populates the base object record and cross-reference record with the SYSDATE value.
The Putable property affects the Put update operation behavior for Create_Date.: If you set Create_Date to Putable, the Put API populates the base object record and the cross-reference record with the value in the Put request. Null is a permissible value. If you do not provide a value in the request, the column retains the current value.; If you do not set Create_Date to Putable, the base object record and the cross-reference record column retains the current value. If the Hub creates a cross-reference record, the Put API populates the cross-reference record column with the SYSDATE value.

Put API Behavior for the Last_Update_Date Column

The Put API updates the LAST_UPDATE_DATE column with a value you specify in the Put request or with the SYSDATE value.

If LAST_UPDATE_DATE is Putable and you provide a value for the LAST_UPDATE_DATE column in the Put request, the Put API populates the base object record and cross-reference record with this value. Null is a permissible value.

If you do not provide a value for the LAST_UPDATE_DATE column in the Put request, the Put API populates the base object record and cross-reference record with the SYSDATE value.

If LAST_UPDATE_DATE in not Putable, the Put API populates the base object record and cross-reference record with the SYSDATE value.

Put API Behavior for the SRC_LUD Column in the Cross-Reference

Multiple factors can affect the behavior of the Put API request on the SRC_LUD column in the cross-reference record.

If LAST_UPDATE_DATE is Putable and you provide a LAST_UPDATE_DATE value, the Put API populates the SRC_LUD column with the LAST_UPDATE_DATE value.

If you do not provide LAST_UPDATE_DATE value, but the Create_Date column is putable and you provide a Create_Date value, the Put API populates the SRC_LUD column with the Create_Date value.

If you do not provide a LAST_UPDATE_DATE value and you do not provide a Create_Date value, the Put API populates the SRC_LUD column with the SYSDATE value.

Put API Behavior for Foreign Key Columns that are Not Nullable

If you configure a default value for a foreign key column and either specify a null value or do not specify a value, the Put API inserts the default value into the corresponding column of the cross-reference table.

If you do not configure a default value for a foreign key column and either specify a null value or do not specify a value in the Put request, the MDM Hub generates an exception.

Requirements

Consider the following requirements when using the Put API.

You must specify the SystemName field to identify the cross-reference record and the system that provides the data.

You must enable the Put API for the package.

Restrictions

Consider the following restrictions when using the Put API:

You cannot insert a null value into a nonnullable column, such as a unique key column. You must provide a value for nonnullable columns because the Put API sets empty fields to null.

You cannot use Put to insert or update a read-only column.

You cannot use Put to insert or update a system column unless the column is putable.

Validation rules only run if all columns used in the validation rule are present in the Put request.

The Put request fails for packages that are based on base objects flagged for tokenization. A base object record needs to be tokenized if the ROWID_OBJECT value of the base object record is present in the associated dirty table.

A Put request to update relationships can result in improperly formed relationship records. Use the AddRelationship API and the UpdateRelationship API to add or update relationship records.

Escape special characters like ' and ~ with a backslash character.

Required Parameters

Use the required parameters to specify the data to insert or update and to specify which record is to receive the data. The following table describes the required parameters.

Parameter	Description
RecordKey	When you insert a record, use RecordKey to specify the system name of the record to insert. The system generates the ROWID_OBJECT value for the record. You cannot specify the ROWID_OBJECT value for a new record. If you specify the ROWID_OBJECT value for a record that does not exist, the Put request fails. When you update a record, use RecordKey to specify the system name, ROWID_OBJECT, and source key of the record to update. You can also specify the Global Business Identifier (GBID), as applicable.
Record	Contains the data to update or insert. The SiperianObjectUid field for the record specifies the type and the name of the base object or put-enabled package used to identify the affected base object and constrain the fields that you can set.

Parameter

Description

RecordKey

When you insert a record, use

RecordKey

to specify the system name of the record to insert. The system generates the ROWID_OBJECT value for the record. You cannot specify the ROWID_OBJECT value for a new record. If you specify the ROWID_OBJECT value for a record that does not exist, the Put request fails.

When you update a record, use

RecordKey

to specify the system name, ROWID_OBJECT, and source key of the record to update. You can also specify the Global Business Identifier (GBID), as applicable.

Record

Contains the data to update or insert. The SiperianObjectUid field for the record specifies the type and the name of the base object or put-enabled package used to identify the affected base object and constrain the fields that you can set.

Optional Parameters

Use the optional parameters to specify a LastUpdateDate and request a source key.

The following table describes the optional parameters:

Parameter	Description
GenerateSourceKey	Use for keyless systems such as an application that does not persist source data. When set to true , the MDM Hub generates a source key if you do not specify one. If you insert a record from a keyless system, you can request the MDM Hub to generate a unique PKEY_SRC_OBJECT for the record. If you request a primary key when you insert a base object, the key generator generates a key and passes it to the Put part of this request. If the cross-reference ID does not exist when you update a base object, the Put API creates a cross-reference record. If the cross-reference ID exists when you update a base object, the Put API updates the cross-reference record.
BypassPostLoadUE	Determines if Put API calls the PostLoad user exit. Set to true to prevent recursive PostLoad user exit calls. For example, when a batch load calls the PostLoad user exit, which then calls a Put API that also calls the PostLoad user exit.
PeriodStartDate	Applicable for base objects for which you track data change events. Specifies the period start date for record versions.
PeriodEndDate	Applicable for base objects for which you track data change events. Specifies the period end date for record versions.
PeriodReferenceTime	Applicable for base objects for which you track data change events. Specifies a reference date within an effective period to identify a record version that you want to update. Default is null.
timelineAction	Applicable for base objects for which you track data change events. Specifies the action to perform on a record version during the load process. Use one of the following values: 0. Adds a record version for a new effective period without maintaining contiguity between the record versions. 1. Updates data in an existing record version. The effective period of the record does not change. 2. Updates the effective period of a record version. An update to an effective period of a record version is through an increase or decrease of the effective start or end date. 4. Adds a record version for a new effective period while maintaining contiguity between the record versions. Default is 0.
isFillOnGap	Applicable for base objects for which you track data change events. Ensures that contiguity between the effective dates of record versions is maintained when you add new record versions. If set to true , when you can add a new record version to the base object, the MDM Hub maintains the contiguity between effective periods of record versions. If set to false , the MDM Hub rejects any addition of record version that breaks the contiguity between effective periods of record versions. The default is false.

Response Fields

The Put response can contain the information described in the following table:

Field	Description
RecordKey	Contains the ROWID_OBJECT of the base object affected by the Put API. When performing a Put request using a ROWID_OBJECT for a base object record that has merged into another base object record, Put response returns the ROWID_OBJECT of the surviving base object record. RecordKey also contains a primary key if you set GenerateSourceKey to true .
ActionType	Indicates the action that the Put API performed. The possible values are: Insert Update Update cross-reference No Action The Tokenize API requires the value of ActionType. Insert indicates that a record has not yet been tokenized and tokens need to be created. Update and Update cross-reference indicate that a record has been tokenized and the tokens need to be regenerated.

Use Cases

The following examples are the common scenarios for using the Put request:

The user provides data in a UI for creating or updating a record, and then the UI calls the Put API to insert or update the record.

The Put API used in combination with the Tokenize API. A Put request followed by a Tokenize request inserts or updates the record and encodes it for matching. The Put response contains an action type string to use as an input to the Tokenize request. The Put API operation and the Tokenize operation can occur in the same transaction.

The Put API used in combination with the Cleanse API. The most common use of cleanse is when the individual fields are cleansed before the record is passed on to the Put API.

Put Request Usage Example

The following example updates a record with ROWID_OBJECT key 782 using the package ADDRESS_UPDATE:

PutRequest request = new PutRequest();
request.setRecordKey(RecordKey.rowid("782", "SALES"));
Record record = new Record();
record.setSiperianObjectUid(SiperianObjectType.PACKAGE.makeUid("ADDRESS_UPDATE"));
record.setField( new Field("ADDRESS_LINE1", "123 Main St.") );
record.setField( new Field("CITY", "Anytown") );
request.setRecord( record );
PutResponse response = (PutResponse) sipClient.process(request);

Rename Saved Search

Table of Contents

Services Integration Framework Guide

Services Integration Framework Guide

Put

Put

State Management

Transaction Support

Validation Rule Processing

Trust Override

Putable System Columns

Put API Behavior for the Create_Date Column

Put API Behavior for the Last_Update_Date Column

Put API Behavior for the SRC_LUD Column in the Cross-Reference

Put API Behavior for Foreign Key Columns that are Not Nullable

Requirements

Restrictions

Required Parameters

Optional Parameters

Response Fields

Use Cases

Put Request Usage Example