If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

Read-write Services

We use a placeholder instance entity Example, a placeholder master entity Example, and a placeholder Master View Mv to illustrate the functionality of services.

processDeltaService

Allows remote applications to modify the data in the hub without having to set up and schedule load operations; changed data is transferred in the message payload. The basic configuration creates a service capable of writing into all entities:

<service class="com.ataccama.nme.internal.engine.services.handlers.ProcessDeltaService" />

The input message consists of a sequence of elements (named after entities), each representing a single record updated in the transaction. As an example, if a single Customer record and two Address records should be updated, the message would be:

 <processDelta>
    <Party>
      ...
    </Party>
    <Address>
     ...
    </Address>
    <Address>
     ...
    </Address>
 </processDelta>

Each record element consists of several subelements, giving values of the columns or properties. There are three system properties: origin, source_id, and change_type; the remaining properties correspond to source columns defined on the entity.

<origin> (the "string with hash signs" identifying the source) and source_id (identifier from the source) are used to identify records in the same way as in the batch load interfaces.

change_type can have the following values:

I (insert).
U (update; there is, in fact, no difference between I and U in terms of processing since MDM detects the proper value).
D (deactivation of the record, logical delete).
X (actual delete).

Both delete operations have an equivalent in a batch interface setting (see Batch Interface, section Deletion strategy).

  <request>
    <Party>
      <origin>s2#Party</origin>     <!-- origin -->
      <source_id>8021</source_id>   <!-- identifier in origin/source system -->
      <change_type>I</change_type>   <!-- insert or update -->
      <!-- data columns follow (derived from model) -->
      <src_name>John Smith</src_name>
      <src_inn>2985903432</src_inn>
    </Party>
  </request>

The response is a list of results per every sent record:

Process delta response

<processDeltaResponse>
  <recordList>
    <!-- contains one record element for every record in the input -->
    <record id="39096018" recordChange="INSERT" origin="s2#Party" sourceId="8021" />
    <!-- id is not present below because change_type was X or D and record did not exist in the hub -->
    <record recordChange="NONE" origin="s2#Address" sourceId="782" />
  </recordList>
</processDeltaResponse>

id - Engine internal record ID (usable in getInstanceBydIdService bundle).
recordChange - Result of sent change_type, hub configuration and presence of record in hub, could be NONE, INSERT, UPDATE, DELETE.
origin - Origin of record sent in the input.
sourceId - sourceId of the record sent in the input.

ProcessDeltaService can be further configured to provide the following features:

ChangeDetection with central and dependent entities.
Partial UPDATE and INSERT.

If you configure ProcessDeltaService to non-default behavior, we strongly recommend changing its name by setting the attribute name:

<service class="com.ataccama.nme.internal.engine.services.handlers.ProcessDeltaService" name="processDeltaLimited" />

Change detection

ChangeDetection with central and dependent entities is similar to the batch delta load operation, see Batch Interface. Being provided with a list of entities, the service limits its possible input to only these entities and conforms to the configured ChangeDetection:

<service class="com.ataccama.nme.internal.engine.services.handlers.ProcessDeltaService" name="processDeltaLimited">
  <entities>
    <entity name="contract" class="com.ataccama.nme.internal.engine.services.handlers.rw.AutonomousEntity" />
    <entity name="party" class="com.ataccama.nme.internal.engine.services.handlers.rw.CentralEntity" keyColumn="source_id" />
    <entity name="address" class="com.ataccama.nme.internal.engine.services.handlers.rw.DependentEntity" keyColumn="party_source_id" centralEntity="party" />
  </entities></service>

Every entity configuration has the name of the instance entity. Entities not listed cannot be changed by the service.

Entity processing types are the following:

AutonomousEntity - Default behavior.
CentralEntity - Records processed by this processing type behave in same way those processed by AutonomousEntity, but they also define change processing for dependent entities.
DependentEntity - Records processed by this processing type have no change indication and depend directly on the central entity
- Every record of DependentEntity must come with a corresponding record of a CentralEntity - the relation is defined by the keyColumn attribute.
- Record change is taken from a corresponding CentralEntity record.
- If the central record appears on input, all its dependent records are expected as well. Dependent records not present on input but found in the storage are deactivated (D).

If any DependentEntity is present, attribute sourceDeletionStrategy must be set (either DEACTIVATE or DELETE). That defines how to delete dependent entity records not present on input as well as how to limit possible input change_type for all records. We recommend using the same source deletion strategy for the whole solution (all services and load operations).

<service class="com.ataccama.nme.internal.engine.services.handlers.ProcessDeltaService" sourceDeletionStrategy="DEACTIVATE" />

Partial UPDATE and INSERT

Entities defined inside the service can be configured to update only a subset of input columns:

<service class="com.ataccama.nme.internal.engine.services.handlers.ProcessDeltaService" name="processDeltaLimited">
  <entities>
    <entity name="contract" class="com.ataccama.nme.internal.engine.services.handlers.rw.AutonomousEntity">
      <columns>
        <column>src_additional_info</column>
      </columns>
    </entity>
    ...
  </entities></service>

This configuration creates a service called ProcessDeltaLimited that is able to change only one column of one entity. Inputs from other entities and columns are ignored, that is, columns not listed preserve their values, contrary to the default behavior of being set to NULL.

If an empty list of columns is provided, the service cannot change data (with the exception of delete).

processMatchService

Allows remote applications to modify matching of records in the hub.

<service class="com.ataccama.nme.internal.engine.services.handlers.ProcessMatchService" />

The service is designed for the following manual match operations:

mergeInstance - Moves one instance record to another existing master group.

mergeMaster - Merge one master group with another.

Operations mergeInstances & mergeMasters set the isolate_flag of instance records according to the state of the target group they are merged with. For example, if an isolated group is merged to a non-isolated group, the newly formed group is non-isolated.

Split - Overrides master ID for instance record.
Rematch - Reruns specified records through matching plans. Rematch ignores records with eng_isolate_flag set to true.

Rematch removes overrides from matching columns and from Master ID (therefore reverting split actions).

By removing overrides, the rematch action can affect changes made in the MDM Web Application.
isolateGroup - All records within one master group have eng_isolate_flag set to true and are unavailable for matching.
unIsolateGroup - All records within one master group that had eng_isolate_flag set to true are now available for further matching operations (eng_isolate_flag is set to false).

It is important that operations be carried out in the correct order.

For example, if you rematch then un-isolate, the records will not have been rematched. Always un-isolate prior to rematching and split before isolating.

The service accepts a list of manual match operations.

Sample request

<proc:processMatch>
         <!-- ... more ... -->
         <proc:mergeInstance>
            <proc:entity>party</proc:entity>
            <proc:id>1232</proc:id>
            <proc:target_master_id>1462</proc:target_master_id>
         </proc:mergeInstance>
         <!-- ... more ... -->
        <mergeMaster>
          <masterView>masters</masterView>
            <entity>project</entity>
            <id>{master_id}</id>
            <targetMasterId>{target_master_id}</targetMasterId>
         </mergeMaster>
         <!-- ... more ... -->
         <proc:split>
            <proc:entity>party</proc:entity>
            <!-- ... more ... -->
            <proc:id>1231</proc:id>
            <proc:id>1234</proc:id>
         </proc:split>
         <!-- ... more ... -->
         <proc:rematch>
            <proc:entity>party</proc:entity>
            <!-- ... more ... -->
            <proc:id>1235</proc:id>
         </proc:rematch>
         <!-- ... more ... -->
         <proc:isolateGroup>
            <proc:entity>party</proc:entity>
            <!-- ... more ... -->
            <proc:id>1236</proc:id>
         </proc:isolateGroup>
         <!-- ... more ... -->
         <proc:unIsolateGroup>
            <proc:entity>party</proc:entity>
            <!-- ... more ... -->
            <proc:id>1237</proc:id>
         </proc:unIsolateGroup>
      </proc:processMatch>

The response is similar to [ProcessDeltaService] - the service returns a list of processed records.

Multiple matching steps

In case multiple matching steps are used, the ProcessMatch service by default supports all of them. It can be configured to support only some of them:

<service class="com.ataccama.nme.internal.engine.services.handlers.ProcessMatchService" name="processMatchM1">
  <matchings>
    <matching>m1</matching>
    <!-- more of them -->
  </matchings>
</service>

The Isolate and Un-isolate operations operate on all configured matchings. Moreover, the service interface is altered:

target_master_id - There is target_<masterIdColumn> for every supported matching in mergeInstance and mergeMaster.
master_id - Exactly one masterIdColumn from supported matchings must be filled in mergeMaster.

processPurgeService

Allows remote applications to completely purge records from the hub.

<service class="com.ataccama.nme.internal.engine.services.handlers.ProcessPurgeService" />

The service purges a record of a given entity by ID. Moreover, it purges the following:

Related records if relationships are provided in the request. It is possible to traverse through several levels of relationships and delete related records of related records (see the following example).
All matching keys from the Matching Key Table (for the main record and all related records).
All history versions stored by the History Plugin (for the main record and all related records).

Purge initiates the usual reprocessing:

Several records can be affected: for example, purging an instance record leads to a change (deletion) of its master.
Configured event handlers interpret the purging of a record as a DELETE (plus any other changes of affected records as pointed out previously).

The following sample request purges a party record with ID 1004 and related records via the provided relationships:

All addresses: <rel name="addresses" />
All contacts and all contacts' contact information: <rel name="contacts/contact_infos" />

<request>
    <party>
        <id>1004</id>
        <relationships> <!-- Optional, purge related records as well, same format as in preloadedRelationships. -->
            <rel name="addresses" />
            <rel name="contacts/contact_infos" />
            <!-- more relationships -->
        </relationships>
    </party>
    <!-- more records - of party or any other entity -->
<request>

The service can purge master data as well, the initial record can be a master record. If a master record is purged, all its instance records are purged as well. On the other hand, if all instance records of some master group are purged, their master record is purged as well (to avoid orphan master records).

A master entity is identified by its name and its master view name in the format <entityName view="masterViewName">. Purging related records is possible by three traversing features:

Traversing to other master entities over relationships defined in <masterRelationships>.
Traversing from its instance entity to other entities over relationships defined in <instanceRelationships>.
Traversing first to another master entity and then continue traversing from its instance entity to another instance entity - nest <instanceRelationships> in <rel> element inside <masterRelationships>.

The following sample request purges party master record (of master view masters) with ID 1020 and related records:

All its instance records
- All their related instance records over relationship party_facts.
All related master addresses and all their instance records: <rel name="addresses" />.
All related master contacts and all the contacts' contact information including all instance records of contact and contact information: <rel name="contacts/contact_infos" />.
All related master rel_party_contract records and their instance records plus related instance records relationships.

<request>
    <party view="masters">  <!-- filled view attribute indicates master layer and defines master view of entity -->
        <id>1020</id>
        <masterRelationships> <!-- Traverse on master layer. -->
            <rel name="addresses" />
            <rel name="contacts/contact_infos" />
            <rel name="rel_party_contract">
                <instanceRelationships>   <!-- Traverse from rel_party_contract's instance entity on instance layer. -->
                    <rel name="contract">
                </instanceRelationships>
            </rel>
            <!-- more relationships -->
        </masterRelationships>
        <instanceRelationships>   <!-- Traverse from party's instance entity on instance layer. -->
            <rel name="party_facts" />
        </instanceRelationships>
    </party>
    <!-- more records - of party or any other entity -->
<request>

The initial record can be identified by either id as in the previous examples or by a combination or source_id and origin as in following example:

<request>
    <party>   <!-- to purge master entity, add attribute view -->
        <source_id>1004</source_id>
        <origin>crm#customer#party</origin>
    </party>
<request>

processMasterService

Allows remote applications to add and modify an authored master record.

 <service class="com.ataccama.nme.internal.engine.services.handlers.ProcessMasterService" masterLayer="${masterLayerName}"/>

In the configuration parameters, it is necessary to state the master layer in the IDE consolidation model. The service expects a record from an entity from this master layer as a parent element in the input XML message. The input message consists of a sequence of elements (named after entities), each representing a single record updated in the transaction.

The request consists of the following elements:

change_type can have the following values:

I (insert; do not include the ID as it is assigned automatically).
U (update).
X (actual delete).
N (nothing; use when you are updating a child record but want the parent record to remain unchanged).

The ID is required to identify the record for X, U, and N change types. It is the only parameter required for X. It is not required for an I request as MDM creates the ID itself. Attributes are required for I and U and are the columns defined for this entity in the consolidation logical model; a missing column is considered a NULL value.

The relationships element describes related entities (for example, address for a party parent). For the change type N, the relationship element is required. For other change types, it is optional.

<soapenv:Envelope xmlns:ns1="http://www.ataccama.com/ws/nme/processMastermasters" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns1:processMastermasters>
            <ns1:party>
                <ns1:change_type>I</ns1:change_type>
                <ns1:attributes>
                    <ns1:cmo_type>P</ns1:cmo_type>
                    <ns1:cmo_first_name>X</ns1:cmo_first_name>
                    <ns1:cmo_last_name>X</ns1:cmo_last_name>
                    <ns1:cmo_gender>M</ns1:cmo_gender>
                    <ns1:cmo_sin>123</ns1:cmo_sin>
                </ns1:attributes>
                <ns1:relationships>
                    <ns1:addresses>
                        <ns1:address>
                            <ns1:change_type>I</ns1:change_type>
                            <ns1:attributes>
                                <ns1:cmo_type>1</ns1:cmo_type>
                                <ns1:cmo_street>X</ns1:cmo_street>
                                <ns1:cmo_city>X</ns1:cmo_city>
                                <ns1:cmo_state>X</ns1:cmo_state>
                                <ns1:cmo_zip>789</ns1:cmo_zip>
                            </ns1:attributes>
                        </ns1:address>
                    </ns1:addresses>
                </ns1:relationships>
            </ns1:party>
        </ns1:processMastermasters>
    </soapenv:Body>
</soapenv:Envelope>

The response is a list of results per every sent record:

Process master response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <processMastermastersResponse xmlns="http://www.ataccama.com/ws/nme/processMastermasters">
      <recordList>
        <record id="402009" recordChange="INSERT">
          <relationships>
            <addresses>
              <record id="402010" recordChange="INSERT">
                <relationships/>
              </record>
            </addresses>
          </relationships>
        </record>
      </recordList>
    </processMastermastersResponse>
  </soapenv:Body>
</soapenv:Envelope>

Was this page useful?