Services Integration Framework Guide

10.3

Back Next

CleansePut

cleanses the specified record and updates or inserts the record into the specified table in a single request.

CleansePut

replicates the Stage and Load batch processes that move data from the landing table, through the cleansing process, into the staging table, and into the base object.

CleansePut

can also perform the lookups required to translate source system foreign keys into Hub foreign keys. The physical landing and staging tables are not used by

CleansePut

The record is put into the base object based on a mapping, which defines the transformation of data from a landing table structure to a staging table structure. The staging table associated with the mapping determines which base object the resulting data is inserted or updated in.

You can configure

CleansePut

requests in all systems when using the Hub Console Audit Manager to audit requests made by external applications. Once auditing for a particular SIF API request is enabled, the MDM Hub captures each SIF request invocation and response in the audit log. For more information, see the

Multidomain MDM Configuration Guide

Filtered Requests

CleansePut

request can be filtered so that no changes are made in the ORS. If

CleansePut

is filtered, an ActionType of

No Action

is returned in the

CleansePut

response.

CleansePut

can be filtered in two ways:

Filtered by the mapping. The mapping can include a condition that must be true before allowing

CleansePut

to process a record.

Filtered by delta detection. In the Hub, you can enable delta detection on the staging table. With delta detection enabled,

CleansePut

requests are filtered if the data does not differ from the data in the previous request.

State Management

If a package has state management enabled, you can specify a record's initial state when you insert a record by setting the value of HUB_STATE_IND. When you insert a new record and do not specify a HUB_STATE_IND value, the HUB_STATE_IND is set to 1 (ACTIVE). You cannot use

CleansePut

to change the state of a record by updating the HUB_STATE_IND value. State management is enabled in the Hub Console.

The possible values for HUB_STATE_IND and the state these values represent are outlined in the following table:

HUB_STATE_IND Value	State
1	ACTIVE
0	PENDING
-1	DELETED

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 entire transaction is rolled back.

Restrictions

Consider the following restrictions when using the

CleansePut

API.

Special characters do not need to be escaped before making the

CleansePut

API call. However, if you have custom code that used escaped special characters in the past, you must update your custom code to remove the escaped special characters.

Both

Put

and

CleansePut

requests process null values. For example, when no value is specified for a field, the field is set to null. However,

CleansePut

does not process records that contain a reference not found in a lookup table.

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 empty fields are set to null.

You cannot use

CleansePut

to insert or update a read-only column.

You cannot use

CleansePut

to insert or update a system column unless it is enabled in the Hub to be Putable. See the Column Properties in the

Multidomain MDM Configuration Guide

for information about which system columns can be putable.

You can specify a value for HUB_STATE_IND when inserting a new record, but you cannot change the state of an existing record by changing the HUB_STATE_IND value using the

Put

API. If you provide a value for the HUB_STATE_IND column when updating a record, the

Put

API throws an exception. To change the state of a record, refer to the following classes: Delete, Restore, and PromotePendingXrefs.

If you use special characters like ' and ~ in CleansePut calls, you must escape them with a backslash character.

If the foreign key column for a child base object is not specified or is specified as NULL in the

CleansePut

request, the lookup is on the parent key of the foreign key column instead of the lookup column defined on the staging table.

If you use a CleansePut call to insert a lookup into a base object, the lookup will be case-sensitive. For example, the Gender column in the lookup C_LU_GENDER|GENDER_CD only accepts values of M, F, and UNK. Lowercase values (m, f, or unk) in the Gender column are not accepted.

When an omitted field is mapped from the landing table to the staging table through a cleanse function, the MDM Hub sets the field to NULL.

Required Parameters

The following table lists and describes the parameters that are required by the

CleansePut

API:

Parameter	Description
Record	This parameter contains the data to be cleansed and inserted.
SiperianObjectUid	Name and type of mapping to use in the CleansePut request. The mapping defines the structure of the record.

Optional Parameters

The following table lists and describes the optional parameters that are used by the CleansePut API:

Parameter	Description
SystemName	The system name of the record to be cleansed. A staging table is associated with a source system. If the system name is not specified by this parameter, the staging table's source system is used.
GenerateSourceKey	Useful for keyless systems (for example, an application that does not persist source data). When set to true , a source key is generated if one is not already specified.
PeriodStartDate	Specifies the period start date for timeline-enabled base objects.
PeriodEndDate	Specifies the period end date for timeline-enabled base objects.
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. 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 CleansePut . When performing a CleansePut request using a ROWID_OBJECT for a base object record that has been merged into another base object record, CleansePut response returns the ROWID_OBJECT of the surviving base object record. RecordKey also contains a new primary key created by the key generator if GenerateSourceKey in the request was set to true .
ActionType	Indicates the action that the Put performed. The possible values are: Insert Update Update XREF No Action Tokenize requires the value of ActionType. Insert indicates that a record has not yet been tokenized and new tokens need to be created. Update and Update XREF indicate that a record has already been tokenized and the existing tokens need to be regenerated.

Field

Description

RecordKey

Contains the ROWID_OBJECT of the base object affected by

CleansePut

When performing a

CleansePut

request using a ROWID_OBJECT for a base object record that has been merged into another base object record,

CleansePut

response returns the ROWID_OBJECT of the surviving base object record.

RecordKey also contains a new primary key created by the key generator if GenerateSourceKey in the request was set to

true

ActionType

Indicates the action that the

Put

performed. The possible values are:

Insert

Update

Update XREF

No Action

Tokenize

requires the value of ActionType.

Insert

indicates that a record has not yet been tokenized and new tokens need to be created.

Update

and

Update XREF

indicate that a record has already been tokenized and the existing tokens need to be regenerated.

Use Case

The following is a typical scenario for using the CleansePut request:

Cleanse a record and update or insert it in the specified table. You can cleanse a specified record and update or insert it in the specified table in a single request. This increases performance, when compared to doing the a

Cleanse

and then a

Put

, by reducing round trips between the client and the MDM Hub.

CleansePut

used in combination with

Tokenize

CleansePut

, followed by

Tokenize

, cleanses the new row of data, inserts or updates it in the base object, and then encodes the base object so it is ready for matching. The

CleansePut

response contains an ActionType value used as an input to the

Tokenize

request.

CleansePut

and

Tokenize

can occur in the same transaction.

Usage Example

The following example shows how a record with ROWID_OBJECT key 782 is updated by using the mapping, Stage CRM Address:

CleansePutRequest request = new CleansePutRequest();Record record = new Record();
record.setSiperianObjectUid("MAPPING.Stage CRM Address");
record.setField( new Field("ADDRESS_ID", "782") );
record.setField( new Field("ADDRESS_LINE", "123 Main St.") );
record.setField( new Field("CITY_NAME", "Anytown") );
record.setField( new Field("LAST_UPDATE_DATE", new Date()) );
request.setRecord( record );
CleansePutResponse response = (CleansePutResponse) sipClient.process(request)