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="nmeNative">
    <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:8888/pathPrefix. This endpoint is referring to the listeners (defined in the main Server Configuration file) in the listenerNames attribute .

A list of services provided is accessible via the admin console (MD Interfaces > Services) or direct link: localhost:8888/console/nmeInterfaces/services. In case of SOAP services, the list of available services is available at localhost:8888/soap/. WSDL per each shown service is also available.

Endpoints

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

HttpEndpoint - standard HTTP protocol
JmsEndPoint - Java Messaging Services

and following formats:

SoapFormat - standard SOAP 1.1 format
XmlRpcFormat - plain XML

All four combinations of these formats and endpoints are supported.

HttpEndpoint

HttpEndpoint allows for the calling of native services via standard HTTP protocol. Following configuration, it creates HttpEndpoint attached to listener nmeNative providing services on http://<serverAddress>:<listenerPort>/xmlRpcOverHttp:

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

listenerNames (optional): Comma-separated list of listener names where native services are available, default value is "all" listeners.
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>:<listenerPort>/soapOverHttp.

JmsEndpoint

JmsEndpoint allows accessing native services via JMS. It requires JMS Provider Component. Following configuration creates JmsEndpoint connected to JMS server defined in ActiveMQ connection (configuration is in JmsProviderComponent), endpoint reads requests from destination MQ_in and sends responses to destination MQ_out:

<endpoint class="com.ataccama.nme.internal.engine.services.endpoints.JmsEndpoint" pathPrefix="/xmlRpcOverJms/*">
  <format class="com.ataccama.nme.internal.engine.services.endpoints.XmlRpcFormat" serviceNameHeader="SOAPJMS_soapAction" />
  <connectionName>ActiveMQ</connectionName>
  <activityByReadWriteMode>true</activityByReadWriteMode>
  <inputDestination>MQ_in</inputDestination>
  <outputDestination>MQ_out</outputDestination>
  <outputParameters>
    <outputParameter name="stringParamName" value="stringValue" type="STRING"/>
    <outputParameter name="intParamName" value="123" type="INT"/>
    <outputParameter name="longParamName" value="10010101001012" type="LONG"/>
    <outputParameter name="booleanParamName" value="false" type="BOOLEAN"/>
  </outputParameters>
</endpoint>

connectionName - name of connection is defined in JmsProviderComponent in the server configuration file.
activityByReadWriteMode - (boolean, default: false) if set to true, allows to control endpoint activity when MDM is switching between RO/RW modes:
- if the engine is switched to the RO mode, the endpoint is stopped.
- if the engine is switched to the RW mode, the endpoint is started.
inputDestination - destination from which endpoint is reading requests.
outputDestination - destination to which endpoint is sending responses.
outputParameters - allows to add some additional information into JMS properties (that is, header).

Optional attributes pathPrefix and listenerNames have same meaning as for HttpEndpoint but are used only for SoapFormat to configure location where WSDL is available.

For XmlRpcFormat under JmsEndpoint, serviceNameHeader is used to define what header contains name of service, default is SOAPJMS_soapAction.

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 ROOT:mdm-web-app-admin-center.adoc) 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?