NME Native Services

In this section:

Native services are services provided by the NME service engine as a layer for accessing data persisted in NME. These services may be called directly or through an integration component such as PME. The actual service names and parameters are derived directly from the data model.

Services are configured in the nme-services.gen.xml file. It contains two main elements:

For example:

<serviceConfig>
	<services>
		<service
class="com.ataccama.nme.internal.engine.services.handlers.GetInstanceBy
IdServiceBundle"/>
		<service
class="com.ataccama.nme.internal.engine.services.handlers.GetMasterById
ServiceBundle"/>
		<service
class="com.ataccama.nme.internal.engine.services.handlers.TraverseMaster
ServiceBundle" />
		<service
class="com.ataccama.nme.internal.engine.services.handlers.Generic
TraversalMasterService"/>
		<service
class="com.ataccama.nme.internal.engine.services.handlers.ListInstances
ServiceBundle" />
		<service
class="com.ataccama.nme.internal.engine.services.handlers.ListMasters
ServiceBundle"/>
		<service
class="com.ataccama.nme.internal.engine.services.handlers.Search
InstancesServiceBundle" />
		<service
class="com.ataccama.nme.internal.engine.services.handlers.SearchMasters
ServiceBundle" />
		<service
class="com.ataccama.nme.internal.engine.services.handlers.IdentifyMaster
Service" entity="party_mas" masterLayer="gen" name="identifyPartyGen" />
		<service
class="com.ataccama.nme.internal.engine.services.handlers.ProcessDelta
Service" />
	</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>
		<endpoint
class="com.ataccama.nme.internal.engine.services.endpoints.JmsEndpoint"
pathPrefix="/xmlRpcOverJms/*">
		<format
class="com.ataccama.nme.internal.engine.services.endpoints.XmlRpcFormat"
/>
			<connectionName>ActiveMQ</connectionName>
			<inputDestination>MQ_in</inputDestination>
			<outputDestination>MQ_out</outputDestination>
		</endpoint>
	</endpoints>
</serviceConfig>

The above configuration shows all available data-related native services. The services will be available through defined endpoints at http://localhost:8888/[pathPrefix]. Endpoint is referring to listener(s) (defined in the main server configuration file, usually serverConfig.xml) in the listenerNames attribute.

A list of services provided by the current instance of NME is accessible through the web console (click MD Interfaces and then select Services) or direct link: http://localhost:8888/console/nmeInterfaces/services. In case of SOAP services, the list of available services is available at http://localhost:8888/soap/. The WSDL per each shown service is also available.


Top of page

x
Endpoints

NME native services are available on configured endpoints in configured formats. NME supports the following endpoints:

NME also supports the following formats:

NME supports all four combinations of these formats and endpoints.



x
HttpEndpoint

HttpEndpoint allows calling native services using standard HTTP protocol. The following configuration creates an HttpEndpoint attached to listener nmeNative providing services on http://<serverAddress>:<listenerPort>/soapOverHttp:

<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>

If the format is SOAP, the WSDL services will be available on http://<serverAddress>:<listenerPort>/soapOverHttp.



x
JmsEndpoint

JmsEndpoint allows accessing native services using JMS. It requires the JmsProviderComponent server component. The following configuration creates a JmsEndpoint connected to a JMS server, defined in an ActiveMQ connection (the configuration is in JmsProviderComponent). The endpoint reads requests from destination MQ_in and sends responses to destination MQ_out, as shown in the following syntax.

<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>
	<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>

where:

connectionName

Is the name of the connection defined in the JmsProviderComponent in the server configuration file.

inputDestination

Is the destination from which the endpoint is reading requests.

outputDestination

Is the destination to which the endpoint is sending responses.

outputParameters

Allows you to add some additional information into the JMS properties (for example, header).

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

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


Top of page

x
Services

This section describes all NME services. The following examples are for XmlRpcFormat. For SoapFormat, you can get a WSDL or you can change examples as shown in the following syntax (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>

For the rest of this section, a dummy instance entity Example, a dummy master entity Example, and a dummy Master View Mv will be used to illustrate the functionality of services.



x
Read-only Services

This section lists and describes the read-only services.



x
Read-write Services

This section lists and describes the read-write services.

The following table describes the asynchronous variant of RW services. Both RW services have asynchronous variants.

Synchronous Service

Asynchronous Variant

Get Result of Asynchronous Service

processDelta

processDeltaAsync

processDeltaAsyncGet

processUpsert<entity>

processUpsert<entity>Async

processUpsert<entity>AsyncGet

Those services are automatically available with their synchronous variants. No extra configuration is required. These services are visible on the web console including the WSDL if appropriate (for SOAP format).

The difference between synchronous and asynchronous services are:

  • Asynchronous services have the same input as synchronous.
  • Asynchronous services returns only taskId.
  • The result of asynchronous call can be obtained by calling another service (<asynchronous_service>Get).

Sample response of processDeltaAsync:

<processDeltaAsyncResponse
 xmlns="http://www.ataccama.com/ws/nme/processDeltaAsync">
	<taskId>1403</taskId>
</processDeltaAsyncResponse>

Sample request to processDeltaAsyncGet:

<processDeltaAsyncGet>
	<taskId>1403</taskId>
</processDeltaAsyncGet>

Sample response of processDeltaAsyncGet (result element has the same structure as the response of synchronous processDelta):

<processDeltaAsyncGetResponse
 xmlns="http://www.ataccama.com/ws/nme/processDeltaAsyncGet">
		<id>601</id>
		<typeId>service.processDeltaAsync</typeId>
		<status>FINISHED_OK</status>
		<result>
			<recordList>
				<record id="401003" recordChange="NONE" origin="crm#customer#party"sourceId="34590835"/>
			</recordList>
		</result>
</processDeltaAsyncGetResponse>


x
Task Execution and Monitoring Services

These services are located in the com.ataccama.nme.internal.engine.services.handlers.BatchControlServiceBundle service bundle. The services allow external applications to schedule load and export operations without the need to interact with the workflow component or parse the pages in the web console.

The service bundle has one parameter, requiredRole, that can (and should) be used to restrict access to the services.

<service class="com.ataccama.nme.internal.engine.services.handlers.
BatchControlServiceBundle" requiredRole="remote" />

invokeLoadOperation

This operation invokes a load operation with the given parameters. The request consists of the operation name and an optional list of operation parameters.

Sample request:

<invokeLoadOperation>
	<name>crm_in</name> <!-- load operation name -->
	<parameters> <!-- zero or more parameters -->
		<parameter name="fileSuffix" value="20110812"/>
	</parameters>
</invokeLoadOperation>

The service will return immediately, placing the operation into a task queue. The response consists of a single value, taskId, assigned to the task. The getTaskStatus service can be used to query the state of the task.

Sample response:

<invokeLoadOperationResponse>
	<taskId>4</taskId>
</invokeLoadOperationResponse>

invokeMultiLoadOperation

Invokes a multi load operation with the given parameters. The request consists of list of operations' names and an optional list of operation parameters.

Sample request:

<invokeMultiLoadOperation>
	<operations>
		<operation>crm_full</operation>
		<operation>life_full</operation>
	</operations>
	<parameters>
		<parameter name="someParam" value="someValue" />
	</parameters>
</invokeMultiLoadOperation>

The service will return immediately, placing the operation into task queue. The response consists of a single value, taskId, assigned to the task. The getTaskStatus service can be used to query the state of the task.

Sample response:

<invokeMultiLoadOperationResponse>
	<taskId>4</taskId>
</invokeMultiLoadOperationResponse>

invokeExportOperation

This operation invokes an export operation with the given parameters. The semantics of the request and response is the same as in the case of invokeLoadOperation.

Sample request:

<invokeExportOperation>
	<name>full</name> <!-- export operation name -->
	<parameters> <!-- zero or more parameters -->
		<parameter name="referenceTransactionId" value="6226117"/>
	</parameters>
</invokeExportOperation>

Sample response:

<invokeExportOperationResponse>
	<taskId>12</taskId>
</invokeExportOperationResponse>

getTaskStatus

For a given <taskId>, this retrieves the status details for that task.

Sample Request:

<getTaskStatus>
	<taskId>12</taskId>
</getTaskStatus>

If the task is not found, then the response will contain the status with the value NOT_FOUND (other fields are empty). Otherwise, the structure containing the task ID, metadata, and status is returned. The status can be one of WAITING (task in queue), RUNNING (currently being executed), FINISHED_OK (finished successfully), FINISHED_FAILURE (finished with a failure), ABORTING (task has been cancelled by a user but has not yet terminated),or ABORTED (task has been aborted by a user).

Sample Response:

<getTaskStatusResponse>
	<id>12</id>
	<typeId>batchExport.full</typeId>
	<status>FINISHED_OK</status>
</getTaskStatusResponse>


x
Data Statistics Services

These services are located in the com.ataccama.nme.internal.engine.services.handlers.ModelStatiticsServiceBundle service bundle. The services provide statistics about data in the hub, or a count of active and inactive records for every entity. Records physically deleted in iWay MDS (records with eng_existing=0) are not counted nor displayed.

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

getInstanceStatistics

Returns a count of active and inactive records for every instance entity, in addition to every combination of source systems and instance entities. This service answers the question to the number of active party records from CRM systems in the hub.

The request is empty:

<getInstanceStatistics>
</getInstanceStatistics>

Sample response:

<getInstanceStatisticsResponse>
	<entities>
		<entity inactive="0" name="party" active="32">
			<systems>
				<system inactive="0" name="life" active="0"/>
				<system inactive="0" name="crm" active="32"/>
				...
			</systems>
		</entity>
		<entity inactive="0" name="contract" active="0">
			<systems>
				<system inactive="0" name="life" active="0"/>
				<system inactive="0" name="crm" active="0"/>
				...
			</systems>
		</entity>
		...
	</entities>
</getInstanceStatisticsResponse>

getMasterStatistics

Returns a count of active and inactive records for every master entity. This service answers the question to the number of active master party records in the hub.

The request is empty:

<getInstanceStatistics>
</getInstanceStatistics>

Sample response:

<getInstanceStatisticsResponse>
	<entities>
		<entity inactive="0" name="party" active="32">
			<systems>
				<system inactive="0" name="life" active="0"/>
				<system inactive="0" name="crm" active="32"/>
				...
			</systems>
		</entity>
		<entity inactive="0" name="contract" active="0">
			<systems>
				<system inactive="0" name="life" active="0"/>
				<system inactive="0" name="crm" active="0"/>
				...
			</systems>
		</entity>
		...
	</entities>
</getInstanceStatisticsResponse>

getMasterStatistics

Returns a count of active and inactive records for every master entity. This service answers the question to the number of active master party records in the hub.

The request is empty:

<getMasterStatistics>
</getMasterStatistics>

Sample response:

<getMasterStatisticsResponse>
	<entities>
		<entity inactive="0" name="party" active="18" view="mas"/>
		<entity inactive="0" name="rel_party_party" active="3" view="mas"/>
		<entity inactive="0" name="contact" active="49" view="mas"/>
		<entity inactive="0" name="address" active="32" view="mas"/>
	</entities>
</getMasterStatisticsResponse>


x
RW/RO Mode Switching Services

These services are located in the com.ataccama.nme.internal.engine.services.handlers.ReadWriteControlServiceBundle service bundle and are available only if VLDB persistence is used. They allow external applications to switch data access mode between RW and RO.

Note: Only one NME instance can operate on a DB storage in the RW mode at a time. An external application should guarantee this (otherwise data corruption and inconsistencies can occur). The service bundle has one parameter, requiredRole, that can (and should) be used to restrict access to the services.

Initial data access mode is defined by NME runtimes parameters. For more information, see NME Runtime Parameters.

<service class="com.ataccama.nme.internal.engine.services.handlers.
ReadWriteControlServiceBundle" requiredRole="remote" />

switchReadWriteMode

This service starts the switch to the given target mode.

Sample request:

<switchReadWriteMode>
	<targetMode>RO</targetMode> <!-- target mode can be RO (read-only) or RW (read-write) -->
	<switchMode>WAIT</switchMode> <!-- must be WAIT in this version, reserved for future use -->
</switchReadWriteMode>

The service will return immediately, and starts the switch action asynchronously. The response contains either OK and current mode, or ERROR and an error message (if the start of switch failed).

Note: The OK response does not mean the switch will be successful. The switch action is complex and can fail after response.

A switch to RO waits for completion of the active RW operation (load, export, processDelta). The switch to RW checks the transaction state of the NME storage and can perform a recovery.

Sample response:

<switchReadWriteModeResponse>
	<result>OK</result>
	<message>SWITCHING_TO_RO</message> <!-- if switch has already finished,
 message is "RO" -->
</switchReadWriteModeResponse>

getReadWriteMode

Returns the data access mode of this NME instance. The request is empty.

Sample request:

<getReadWriteMode>
</getReadWriteMode>

The service will return the current data access mode, which can be one of the following:

Sample response:

<getReadWriteModeResponse>
	<readWriteMode>RO</readWriteMode>
</getReadWriteModeResponse>


x
MetaModel Services

This service bundle provides detailed information on underlying MDM hub data model. Services are read only and the model cannot be changed this way.

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

getModel

The service retrieves complete MDM hub data model (all entities and their relationships, master views, dictionaries, and so on). The request is empty.

Sample request:

<getModel/>

Sample response:

<getModelResponse>
	<instanceLayer>
		<entities>
				...
			<entity name="address">
				<columns>
					<column name="id" type="LONG_INT"/>
					<column name="source_id" type="STRING" size="1000"/>
					<column name="master_id" type="LONG_INT"/>
					<column name="party_source_id" type="STRING" size="200"/>
					<column name="src_type" type="STRING" size="2000"/>
					<column name="std_type" type="STRING" size="30"/>
					<column name="exp_type" type="STRING" size="500"/>
					<column name="sco_type" type="INTEGER"/>
					<column name="dic_type" type="STRING" size="30"/>
					<column name="src_street" type="STRING" size="2000"/>
					<column name="cio_street" type="STRING" size="100"/>
					<column name="src_city" type="STRING" size="2000"/>
					<column name="cio_city" type="STRING" size="100"/>
					<column name="src_state" type="STRING" size="2000"/>
					<column name="cio_state" type="STRING" size="100"/>
					<column name="src_zip" type="STRING" size="2000"/>
					<column name="cio_zip" type="STRING" size="100"/>
					<column name="exp_address" type="STRING" size="500"/>
					<column name="sco_address" type="INTEGER"/>
					<column name="cio_address_comp" type="STRING" size="1000"/>
					<column name="meta_last_mod_date" type="DATETIME"/>
					<column name="uni_can_id" type="LONG"/>
					<column name="uni_rule_name" type="STRING" size="100"/>
					<column name="uni_role" type="STRING" size="10"/>
					<column name="party_master_id" type="LONG_INT"/>
				</columns>
				<relationships>
					<relationship parentEntity="party" name="party"
 parentKeyColumn="source_id"
 childEntity="address" childKeyColumn="party_source_id"/>
				</relationships>
			</entity>
			<entity name="rd_address_type">
				<columns>
					<column name="id" type="LONG_INT"/>
					<column name="source_id" type="STRING" size="1000"/>
					<column name="master_code" type="STRING" size="1000"/>
					<column name="master_name" type="STRING" size="1000"/>
				</columns>
				<relationships/>
			</entity>
				...
		</entities>
		<sourceSystems>
			<system name="crm"/>
			<system name="life"/>
			<system name="hub_reference_data"/>
		</sourceSystems>
	</instanceLayer>
	<masterLayer>
		<masterView name="masters">
			<entities>
				...
			<entity name="address">
				<columns>
					<column name="id" type="LONG_INT"/>
					<column name="party_master_id" type="LONG_INT"/>
					<column name="cmo_type" type="STRING" size="30"/>
					<column name="cmo_street" type="STRING" size="100"/>
					<column name="cmo_city" type="STRING" size="100"/>
					<column name="cmo_state" type="STRING" size="100"/>
					<column name="cmo_zip" type="STRING" size="100"/>
				</columns>
				<relationships>
					<relationship parentEntity="party" name="party" parentKeyColumn="id"
childEntity="address" childKeyColumn="party_master_id"/>
					<relationship parentEntity="address" name="instances"
parentKeyColumn="id" childEntity="address_instance"
 childKeyColumn="master_id"/>
				</relationships>
			</entity>
				...
			<entity name="rd_gender">
				<columns>
					<column name="id" type="LONG_INT"/>
					<column name="source_id" type="STRING" size="1000"/>
					<column name="master_code" type="STRING" size="1000"/>
					<column name="master_name" type="STRING" size="1000"/>
				</columns>
				<relationships>
					<relationship parentEntity="rd_gender" name="master_codes_cmo_gender"
parentKeyColumn="master_code" childEntity="party" childKeyColumn="cmo_gender"/>
				</relationships>
			</entity>
		</entities>
	</masterView>
		...
	</masterLayer>
</getModelResponse>

iWay Software