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

Native Services

Native services are services provided by the service engine as a layer for accessing data persisted in MDM.

These services can be called directly or through an integration component such as ESB. The actual service names and parameters are derived directly from the data model.

For history native services, see History Plugin.

Native services configuration file

Services are configured in the model project and are generated into the nme-services.gen.xml file. It contains two main elements:

Services: Defines which services are available.
Endpoints: Defines what interfaces can be used to call them.

Currently, services are exposed as SOAP over HTTP, or XML-RPC calls. WSDLs are pre-generated for SOAP services.

nme-services.gen.xml

<serviceConfig>
  <services>
    <service class="com.ataccama.nme.internal.engine.services.handlers.GetInstanceByIdServiceBundle" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.GetMasterByIdServiceBundle" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.TraverseMasterServiceBundle" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.GenericTraversalMasterService" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.ListInstancesServiceBundle" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.ListMastersServiceBundle" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.IdentifyMasterService" entity="party_mas" masterLayer="gen" name="identifyPartyGen" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.ProcessDeltaService" />
        <!-- SoR model services -->
    <service class="com.ataccama.nme.internal.engine.services.handlers.GetRecordByIdServiceBundle" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.ListRecordsServiceBundle" />
    <service class="com.ataccama.nme.internal.engine.services.handlers.ProcessUpsertService" entity="party"/>
  </services>
  <endpoints>
    <endpoint class="com.ataccama.nme.internal.engine.services.endpoints.HttpEndpoint" pathPrefix="/soapOverHttp/*" listenerNames="all">
    <format class="com.ataccama.nme.internal.engine.services.endpoints.SoapFormat" />
  </endpoint>
  </endpoints>
</serviceConfig>

This configuration shows all available data-related native services (special control services are described in the following chapters). Services are available through defined endpoints at http://localhost:8051/pathPrefix. The endpoint can be referring to ports defined in the MDM Server application.properties using listenerNames attribute (this feature is deprecated, the services are available on all ports by default).

A list of services provided is accessible via the Admin Center (Interfaces > Services) or direct link: 8050:admin/services. In case of SOAP services, the list of available services is available at http://localhost:8051/soapOverHttp/. WSDL per each shown service is also available.

Endpoints

Native services are available at configured endpoints in configured formats. MDM supports the following endpoints and formats:

HttpEndpoint - Standard HTTP protocol.
SoapFormat - Standard SOAP 1.1 format.
XmlRpcFormat - Plain XML.

HttpEndpoint

HttpEndpoint allows to call native services via the standard HTTP protocol.

The following configuration creates an HttpEndpoint providing services on http://<serverAddress>:<serverPort>/xmlRpcOverHttp:

<endpoint class="com.ataccama.nme.internal.engine.services.endpoints.HttpEndpoint" pathPrefix="/soapOverHttp/*" listenerNames="all">
  <format class="com.ataccama.nme.internal.engine.services.endpoints.SoapFormat" />
</endpoint>

The following configuration creates an HttpEndpoint providing services on http://<serverAddress>:<serverPort>/xmlRpcOverHttp:

<endpoint class="com.ataccama.nme.internal.engine.services.endpoints.HttpEndpoint" pathPrefix="/xmlRpcOverHttp" listenerNames="all">
  <format class="com.ataccama.nme.internal.engine.services.endpoints.XmlRpcFormat"/>
</endpoint>

listenerNames (deprecated): The only value available is all, services are available on all server ports as defined in the application properties. Other values are ignored, and all is used instead.
pathPrefix: Prefix of the URL where native services are available.

The Endpoint Path Prefix configuration will be discontinued in the future and replaced with hardcoded values of /api/soap and /api/xml respectively.

If format is SOAP, the services' WSDL are available at http://<serverAddress>:<serverPort>/soapOverHttp.

Security

By default, HttpEndpoint (for both SoapFormat and XmlRpCFormat) requires some form of authentication (basic, Bearer token, or internal JWT).

To further secure access to data based on Keycloak user roles in nme-security.xml, see Security and Audit.

After you define the necessary roles you should create a service account in Keycloak and use one of the recommended authentication methods. For more information, see API Requests Authentication.

Services

This section describes all services that can be used with MDM. The examples given are for XmlRpcFormat. For SoapFormat, you can get WSDL in the MDM Web App Admin Center (see MDM Web App Admin Center) or you can simply change examples this way (the example is for getExampleInstanceById):

XmlRpc example

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

SOAP example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:get="http://www.ataccama.com/ws/nme/getExampleInstanceById">
   <soapenv:Header/>
   <soapenv:Body>
      <get:getExampleInstanceById>
         <get:id>1</get:id>
      </get:getExampleInstanceById>
   </soapenv:Body>
</soapenv:Envelope>

Error response from MDM SOAP/XML API (for example, HTTP 401 or 404) might not have a SOAP format and might be in JSON or HTML format instead.

For the following sections, we use a placeholder instance entity Example, a placeholder master entity Example, and a placeholder Master View Mv to illustrate the functionality of services.

Was this page useful?