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

Services

List and Identify services returns eng_active=false records (that is, deleted or deactivated records), in addition to eng_active=true.

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

getInstanceByIdService

Service for getting an instance entity by its ID. For every instance entity Example, there is one service getExampleInstanceById.

A service getEntityInstanceById called with following input:

Sample request

<request>
  <id>1</id>
</request>

might return:

Response

<getentityInstanceByIdResponse>
   <entity>
      <metadata>
         <id>1</id>
         <origin>origin_id</origin>
         <sourceSystem>source_system</sourceSystem>
         <active>false</active>
         <creationTid>123</creationTid>
         <lastUpdateTid>111</lastUpdateTid>
         <creationDate>2013-02-19T10:51:03+01:00</creationDate>
         <lastUpdateDate>2013-02-22T09:07:48+01:00</lastUpdateDate>
      </metadata>
      <attributes>
         <source_id>100</source_id>
         <master_id>2</master_id>
         ....

         ....
      </attributes>
   </entity>
</getentityInstanceByIdResponse>

getMasterByIdService

Service for getting a master entity by its ID. For every master entity Example in master view Mv, there is one service getExampleMvById.

The getExampleMvById service called with the following input:

Sample request

  <request>
    <id>1</id>
  </request>

might return:

Response

<getExampleMvByIdResponse>
   <ExampleMv>
      <metadata>
         <id>1</id>
         <active>true</active>
         <creationTid>10</creationTid>
         <lastUpdateTid>11</lastUpdateTid>
         <creationDate>2013-02-19T10:44:13+01:00</creationDate>
         <lastUpdateDate>2013-02-19T10:48:14+01:00</lastUpdateDate>
      </metadata>
      <attributes>
         <pty_key_mas>100</pty_key_mas>
         <dsid>123</dsid>
         <ref_eng_active>true</ref_eng_active>
         <ref_allowed_flg>false</ref_allowed_flg>
      </attributes>
   </ExampleMv>
</getExampleMvByIdResponse>

genericTraversalMasterService

The most powerful service. It allows retrieving multiple entities connected by relations and traversing the data in the model. For every master view Mv, there is one genericMvTraversal service .

The two basic features are:

Traversing: Allows to change the starting point for entities preloading in model - which record to return as the root element.
Preloading: Allows to preload records connected to the current record by relationship (joins).

Sample requests

<request>
  <startWith entity="Party" id="322" />
  <preloadedRelationships>
    <rel name="Party_Address" />
    <rel name="Party_Party_Contract_role/Contract_Party_Contract_role_rev" /l>
  </preloadedRelationships>
</request>

<request>
  <startWith entity="party" origin="s1#Party" sourceId="2021" />
  <traversal>
    <traverse relationshipName="contracts">
      <filter>
        <eq attribute="std_status" value="active"  />
        <exists>
          <traverse relationshipName="products">  <!-- traverse to contract depending on values on related entity product -->
            <filter>
              <eq attribute="std_type" value="fund"  />
            </filter>
          </traverse>
        </exists>
      </filter>
    </traverse>
    <traverse relationshipName="products" />  <!-- traverse further from contract to product -->
  </traversal>
  <preloadedRelationships>
    <rel name="party" />
    <rel name="products" />
  </preloadedRelationships>
</request>

The request parameters are as follows:

<startWith> - Identification of the record from which the traversing or preloading starts. The record is identified either by ID (ID on master layer contains the <master_id> value) or by the combination of origin and sourceId.
- entity - Name of the entity from which the traversing or preloading starts (required).
- id - NME primary key of the record.
- origin - Identification of the source (for example "KP_climp_in#Party").
- sourceId - Source primary key of the record.

<preloadedRelationships> - Relationships preloaded in the response (that is, entities joined by the relationships listed are included in the response).

<rel> - Name of the relationship preloaded (for example, <rel>Party_address</rel>).

Relations are oriented. If multiple relations are preloaded in a single path, they are separated by a slash, for example, <rel>Party_Party_Contract_role/Contract_Party_Contract_role_rev</rel>.

<traversal> - One or more traversals along the relationships defined in the model.
- <traverse> - Traversal definition.
  - relationshipName - Name of the relationship traversed (for example, <t relationshipName="Party_Address" />).
  - <filter> - Filtering. By default, eq and exists subelements are evaluated as AND. It can be set to OR (operator="OR"). The same works in the filter for preloadedRelationships.
    
    <eq> - For example, <eq attribute="std_type" value="fund" />.
    
    <exists>

listInstancesService

This service lists records of the instance entity with optional filters. For every instance entity Example, there is one service listExampleInstances.

The service list address instances with input:

Sample request

<request>
  <origin>crm#party</origin>
  <range>
    <offset>0</offset>
    <count>30</count>
  </range>
  <search>
    <city>Prague</city>
    <street>Main*</street>
  </search>
</request>

returns addresses that have the city column filled with Prague and the street column starting with Main - all search conditions need to be satisfied.

To search for NULL values, send an empty element (self-closing): <city />.

If you need to use literal asterisk (*) or backslash (\) characters in your search request, they have to be escaped with a backslash (that is, \* and \\ respectively).

The <origin> element (optional) is a special search criterion limiting the results to the records with the given origin.

The <range> element (optional) restricts the number of returned records. Default value is 100. Maximum allowed value is 100 but can be changed via NME Runtime Parameters (see Runtime Parameters, section Other).

listMastersService

This service lists records of the master entity. For every master entity Example in master view Mv, there is one service listExampleMv.

The use is the same as in [listInstanceService], the only difference is that the request cannot contain the element <origin>.

identifyMasterService

The Identify service answers the question "is this record similar to any record stored in the hub?". Input is in the form of the instance entity, while similarity is defined by the matching rules of this entity. Output is either nothing or matching information and master record.

Each element:

<service class="com.ataccama.nme.internal.engine.services.handlers.IdentifyMasterService" entity="example" masterLayer="mv" name="identifyExampleMv" />

creates one service identifyExampleMv.

As an input, the service gets:

One record of instance entity - Attributes of origin SOURCE.
(Optional) Records of related entities - Attributes of origin SOURCE.

The service cleanses input data and tries to match the record to records in the hub using matching rules (under the hood, it runs cleansing and matching plans). If an input record is matched to a master group, a master record is returned, otherwise it returns an empty response.

This requires enabling the identify service in model.xml. For more information, see Model, section Match operation.

The service identifyExampleMv might have this input:

Identify request

<request>
    <sourceSystem>system#1</sourceSystem>
    <record>
        <attributes>
            <src_first_name>Joe</src_first_name>
            <src_last_name>Black</src_last_name>
            <src_sin>1234567890</src_sin>
          </attributes>
        <relationships/>
    </record>
    <preloadedRelationships>
        <rel name="addresses" />
    </preloadedRelationships>
</request>

The request parameters are as follows:

<sourceSystem> - Source system identifier.
<record> - Record for which the master record should be identified.
- <attributes> - Attributes of the record for entity identification.
<preloadedRelationships> - It is possible to return related entities (similarly as in genericTraverseMasterService).

and return:

Response

<response>
    <matchMetadata>
        <matchRelatedId>1008</matchRelatedId>
        <matchQuality>0.0</matchQuality>
        <matchRuleName>name+sin</matchRuleName>
    </matchMetadata>
    <party>
        <metadata>
            <id>1013</id>
            <active>true</active>
             <!-- more metadata -->
        </metadata>
        <attributes>
            <cmo_name>Joe</cmo_name>
             <!-- more attributes -->
        </attributes>
        <relationships>
            <!-- records of related entities as defined in request's preloadedRelationships -->
        </relationships>
    </party>
</response>

If the matching has proposals enabled, proposals are returned as well. It is possible to have only proposals in response (record matches only using proposal rules), for example:

Identify response with proposals

<response>
    <matchMetadata>
        <!-- ... -->
    </matchMetadata>
    <party>
        <!-- ... -->
    </party>
    <proposals>
        <proposal>
            <matchMetadata>
                <matchRelatedId>1006</matchRelatedId>
                <matchQuality>0.0</matchQuality>
                <matchRuleName>name+number</matchRuleName>
            </matchMetadata>
            <party>
                <metadata>
                    <id>1012</id>
                    <active>true</active>
                    <!-- more metadata -->
                </metadata>
                <attributes>
                    <cmo_name>Peter</cmo_name>
                    <!-- more attributes -->
                </attributes>
            </party>
        </proposal>
        <!-- more proposals -->
    </proposals>
</response>

If there are too many proposals (more than what is defined in the runtime parameter nme.services.range.maxCount, default 100), proposals are returned in the short format:

Identify response with proposals - short format

<response>
    <matchMetadata>
        <!-- ... -->
    </matchMetadata>
    <party>
        <!-- ... -->
    </party>
    <proposals>
        <proposalMetadata masterId="1012" matchRuleName="name+number" matchQuality="0.0" matchRelatedId="1006" />
        <!-- more proposals -->
    </proposals>
</response>

identifyMixedMasterService

Running IdentifyMixedMasterService allows you to see if the master record being created in mixed style will be a duplicate. To use this service, you must have authoring enabled and matching configured on the master layer.

Input is in the form of the master entity, while similarity is defined by the matching rules of this entity.

Each element:

<service class="com.ataccama.nme.internal.engine.services.handlers.IdentifyMixedMasterService" entity="party" masterLayer="masters" name="identifyPartyMixed"/>

creates one service, for example, identifyPartyMixed.

As an input, the service gets:

One record of master entity - Attributes of origin SOURCE.
(Optional) Records of related entities - Attributes of origin SOURCE.

If an input record is matched to a master group, a master record is returned, otherwise it returns an empty response.

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:iden="http://www.ataccama.com/ws/nme/identifyPartyMixed">
   <soapenv:Header/>
   <soapenv:Body>
      <iden:identifyPartyMixed>
         <iden:record>
            <iden:attributes>
               <iden:cmo_type>P</iden:cmo_type>
               <iden:cmo_first_name>John</iden:cmo_first_name>
               <iden:cmo_last_name>Smith</iden:cmo_last_name>
               <iden:cmo_sin>111111118</iden:cmo_sin>
            </iden:attributes>
         </iden:record>
      </iden:identifyPartyMixed>
   </soapenv:Body>
</soapenv:Envelope>

The request parameters are as follows:

<record> - Record for which the master record should be identified.
<attributes> - Attributes of the record for entity identification.

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <identifyPartyMixedResponse xmlns="http://www.ataccama.com/ws/nme/identifyPartyMixed">
         <party>
            <metadata>
               <id>202111</id>
               <active>true</active>
               <creationTid>202110</creationTid>
               <lastUpdateTid>202110</lastUpdateTid>
               <creationDate>2019-12-20T13:21:35+01:00</creationDate>
               <lastUpdateDate>2019-12-20T13:21:35+01:00</lastUpdateDate>
            </metadata>
            <attributes>
               <cmo_type>P</cmo_type>
               <cmo_first_name>John</cmo_first_name>
               <cmo_last_name>Smith</cmo_last_name>
               <exp_gender>GENDER_MISSING_INVALID</exp_gender>
               <sco_birth_date>10000000</sco_birth_date>
               <exp_birth_date>DATE_EMPTY_INPUT</exp_birth_date>
               <cmo_sin>111111118</cmo_sin>
               <sco_sin>0</sco_sin>
               <exp_sin>SIN_VALID</exp_sin>
               <sco_company_name>0</sco_company_name>
               <sco_business_number>0</sco_business_number>
               <sco_established_date>0</sco_established_date>
               <exp_full_name>NAME_MIDDLE_EMPTY NAME_PARSED NAME_FIRST_VERIFIED NAME_LAST_VERIFIED NAME_GENDER_FOUND_LKP</exp_full_name>
               <sco_full_name>0</sco_full_name>
            </attributes>
            <relationships/>
         </party>
      </identifyPartyMixedResponse>
   </soapenv:Body>
</soapenv:Envelope>

cleanseService

This service can be used as the data quality firewall. It cleanses instance data of the configured entity in the same way as records are cleansed when processed. Each service element like the following one creates one service cleanseExample.

<service class="com.ataccama.nme.internal.engine.services.handlers.CleanseService" entity="Example" />

The service gets attributes of the instance entity (one record) on the input. Then it runs the cleansing plan and returns a cleansed record.

Sample request

<request>
    <sourceSystem>system#1</sourceSystem>
    <record>
        <attributes>
            <src_first_name>Joe</src_first_name>
            <src_last_name>Black</src_last_name>
            <src_birth_num>1234567890</src_birth_num>
          </attributes>
        <relationships/>
    </record>
</request>

The request parameters are as follows:

sourceSystem - Source system identifier.
record - Record to cleanse.
- attributes - Attributes to be cleansed.

Response

<response>
    <record>
        <attributes>
      <source>
              <src_first_name>Joe</src_first_name>
              <src_last_name>Black</src_last_name>
              <src_birth_num>1234567890</src_birth_num>
      </source>
      <clean>
        <std_first_name>Joe</std_first_name>
              <std_last_name>Black</std_last_name>
              <std_birth_num>1234567890</std_birth_num>
              <exp_birth_num>BN_FAKE</exp_birth_num>
        <sco_birth_num>20000</sco_birth_num>
      </clean>
        </attributes>
  </record>
</response>

Was this page useful?