Record Add Modify Services - Inputs

Command type

The valid command types are:

  • Add – Use when the root record in a bundle is being added.
  • Modify – Use when the root record in a bundle is being modified.

Set the entity command qualifier to any of the following:

  • Validate/Process – Causes the records to be validated before saving. This also initiates New Record Introduction Edit (NRIE) workflows. This is the default.
  • Validate/NoProcess – Validates records and save them without starting the NRIE workflows.
  • NoValidate/Process – Does not validate the records, but saves them, and also starts NRIE workflows.
  • NoValidate/NoProcess – Does not validate the records or start the workflow, but saves them.
  • NoValidate/ProcessOnDataChange (only for the Modify command type) – Does not validate records, however processes and saves the records when the data has changed for the specified records. If the data has not changed, an error is returned.
  • Validate/ProcessOnDataChange (only for the Modify command type) – Validates the records, however processes and saves the records only when the data has changed for the specified records. If the data has not changed, an error is returned.

Execution Mode

Set the execmode to either SYNCHR or ASYNCHR. For more information, refer to Execution Modes.

Handling File Type Attributes

TIBCO MDM can handle file type attributes either as attachments or as relative paths into the application. To perform this, specify the FILE_TYPE_ATTRIBUTES context variable with the following two valid values:

  • ATTACHMENT – Indicates that the client has sent the file type attributes as SOAP attachments.
  • HREF – Indicates that the client had already loaded the files onto the server (using HTTP post), and wants the server file type attributes to be processed as relative paths into the application. This is the default. 
    <Context>
  <Variable name="FILE_TYPE_ATTRIBUTES"   type="string">ATTACHMENT</Attribute>
</Context>

Handling System Generated Attributes

You cannot change the following system-generated attributes. If any of the following attributes are specified in the request XML, an error is returned. 

Active, creation date, moddate, version number, product keyID, modmemberID, checksum, importtime stamp, ownerID, ownerType, lastConfirmedVersion, processLogID, batchID, parentVersion, catalogVersionNumber
Note: The CREATIONDATE and MODDATE system attributes do not provide the time details. This is a limitation. For example, the value for these attributes do not display the time ID along with the date and time, that is, 2013-05-08 03:19:46.0 Asia/Shanghai.

Query Directives

None.

Support for Bundles

This web service can work on more than one record, as part of a record bundle.

Support for Correction

TIBCO MDM creates a new version of the record whenever you change any attribute value. You can manage these versions using the VERSION_POLICY context variable. Specify the following valid values:
  • New: creates a new version of the record
  • Correct: updates the existing version of a record instead of creating a new one
  • Optimize: combination of both New and Correct values. TIBCO MDM automatically decides whether or not to correct a record, or create a new version. If the VERSION_POLICY context variable is specified as Optimize, some rules are used. To know about the rules, refer to the VersionPolicy parameter mentioned in workflow activities of the TIBCO MDM Workflow Reference on TIBCO MDM product documentation page. 
<Context>
   <Variable name="VERSION_POLICY" type="string">Correct</Variable>
</Context>
For information on the use of the Correction option on UI, refer to TIBCO MDM User's Guide.

Support for Perspective

You can use the PERSPECTIVENAME context variable to retrieve only a small subset of data. If you specify the PERSPECTIVENAME context variable in the Record Add or Modify web service request, the record operation processes only those relationships and attributes that are part of the perspective definition. For others an error is shown. You can specify only one perspective in a request file. If you specify an incorrect perspective name, the perspective definition error is displayed. 
<Context>
      <Variable name="PERSPECTIVENAME" type="string">PerspEmpAddress</Variable>
</Context>
  • For information on the use of perspective from UI, refer to TIBCO MDM User's Guide.
  • For information on the use of PerspectiveName parameter in the workflow activities, refer to TIBCO MDM Workflow Reference on TIBCO MDM product documentation page.
  • For information on the perspective cache, refer to TIBCO MDM Installation and Configuration Guide on TIBCO MDM product documentation page.

Support for Omitting Change in Data Validation

You can use the SKIPDATACHANGEVALIDATION context variable to override the validation for change in record data based on the command qualifier. This functionality updates the record state without any changes to record payload. 
<Context>
										<Variable name="SKIPDATACHANGEVALIDATION" type="string">true</Variable>
</Context>>
  • When you set the SKIPDATACHANGEVALIDATION context variable to true, the validation to check change in record data is skipped and the record state is updated without the record version increment.
  • When you set the SKIPDATACHANGEVALIDATION context variable to false or if you do not specify this context variable, the existing default behavior is restored. That is, the Record Modify request succeeds only if the record payload changes and the record version is incremented.
Note: Use the SKIPDATACHANGEVALIDATION context variable only to update the record state of a particular record without any changes to its data. You cannot confirm a record along with its related records in the unconfirmed state in a single request (by setting theSKIPDATACHANGEVALIDATION context variable to true). An incorrect usage of this context variable may result in the undesired outcomes.

External Keys

Each record in the record bundle must be external keys. The external keys have the following semantics:

Key Meaning Required 
MASTERCATALOGNAME
 The name of the repository which contains the records. Mandatory. 
PRODUCTID
 PRODUCTID of the record for which the valid values are sought. Mandatory. 
PRODUCTIDEXT
 This is an optional key used to identify a record. Optional.

Entity Data

Entity data section contains the attribute values corresponding to a record.

RECORD_STATE

The request can provide the state in which the records need to be saved. The state is accepted as an attribute in the entity data with the name RECORD_STATE. The valid states are:

  • UNCONFIRMED: If the Validate/NoProcess command type is specified, by default the UNCONFIRMED state is considered.
  • CONFIRMED: If the Validate/Process command type is specified, by default the CONFIRMED state is considered.
  • DRAFT

If an attribute is a multi-value attribute, it is represented as follows: 

<MultiValueAttribute type="string" name="COLOR">
     <Value>red</Value>
     <Value>green</Value>
     <Value>yellow</Value>
</MultiValueAttribute
In this example, COLOR is a multi-value attribute.

If an attribute is defined as a relationship attribute, it is represented as follows: 

<Relationship>
<RelationType>Contains</RelationType>
<RelatedEntities>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME" type="string">Customer1</Key>
<Key name="PRODUCTID" type="string">a2-demo1TEST3</Key>
<Key name="PRODUCTIDEXT" type="string">a2-demo1TEST3</Key>
</ExternalKeys>
<EntityData>
<Attribute name="QUANTITY" type="integer">1</Attribute>
</EntityData>
</MasterCatalogRecord>
</RelatedEntities>
</Relationship>

In this example, QUANTITY is a relationship attribute.

For a sample of multi-value attributes and relationship attributes, navigate to the Support Tools menu, click Configuration Viewer. The Configuration Viewer page is displayed. Click common > standard > samples and download schemas.zip. Extract the schemas.zip file and go to schemas/home/mdmuser/tibco/mdm/version/schema/DataService/2.0/samples.

WorkItem Reference

When a record is modified in the context of a work item, the request must contain the context variable WORKITEMREFERENCE that references the work item before the <Transaction> element. 

<Context>
	 <Variable name="WORKITEMREFERENCE" type="string">10001</Variable>
</Context>

The work item reference is usually obtained from the Record Query/ValidValues or Work Item Query service.