Table of Contents

Search

  1. Preface
  2. Introduction to Services Integration Framework
  3. Setting Up the SIF SDK
  4. Request and Response Objects
  5. Transactions and Exception Handling
  6. ORS-Specific SIF API
  7. Asynchronous SIF Requests
  8. ORS-Specific JMS Event Messages
  9. Using Security Access Manager
  10. Using Dynamic Data Masking
  11. SIF API Reference
  12. Troubleshooting
  13. Appendix A: Identifiers
  14. Appendix B: Frequently Asked Questions

Services Integration Framework Guide

Services Integration Framework Guide

Put

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.

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);

0 COMMENTS

We’d like to hear from you!