Web Services

SOA-enabled applications use Semarchy Convergence for MDM Web Services to interact with the platform and the data in the MDM Hub.
There are two main types of services:

Platform Services

The Platform Services include:

Platform Web Service

The Platform Web Service provides generic information about the platform. Integrators may use this service to check the platform status and list the data editions available via this platform instance.

This web service provides the following bindings:

Binding Name Description
getAPIVersion Returns the version of the API supported by the platform.
getDataEditionInfo Returns information about a given data edition (identified by the data location name, data branch ID and data edition ID).
getDataEditionInfos Returns information about a one of more data editions (optionally filtered by data location name, data branch ID or data edition ID).
getPlatformBuildID Return the platform build number.
getPlatformStatus Return the platform status. The normal status returned is PLATFORM_READY.
getUserName Returns the name of the connected user.
getUserPlatformRoles Returns the list of roles of the authenticated user.
isUserInRole Returns true if a given user is in a given role.
Ping Simple ping binding.

Administrative Service

The Administrative Service provides administrative operations such as data edition closing, log and data purges.Integrators may use this service to automate purges.

This web service provides the following bindings:

Binding Name Description
closeAndCreateNewDataEdition Closes the currently open data edition in a data location and a branch, and opens a new one with the description provided.
purgeDataBranch Purges a data branch from outdated data according to the model’s data retention policies. The data branch is identified by a data location name and a data branch ID. Optionally purges the job logs with the data.
purgeJobLogByFilter Purges job logs filtered by job name, status, creator name and timeframe.
purgeJobLogByIds Purges job logs identiifed by their unique IDs.

Metadata Web Service

The Metadata Web Service provides a binary serialization of a given data model.
This web service is not for public consumption. It is used exclusively by the Semarchy Convergence for MDM Client API.

Integration Load Web Service

The Integration Load Web Service provides control points for external loads. Integrators may use this service to manage the loads.
For more information about this service, see the Publishing Data into the Hub chapter.

This web service provides the following bindings:

Binding Name Description
getNewLoadID Initializes a new load for the open data edition, identified by a data location and a data branch ID. This service returns a load ID.
submitLoad Submits a load identified by a load ID. This service returns the corresponding batch ID.
cancelLoad Cancels a load identified by a load ID.

Data Services

The data services provide access to the data editions known to the application instance. These data services are generated per data edition, and their capabilities depend on the underlying deployed model edition.

The data services for each data edition include:

Data Services URL

Data access services are accessed at the following URL:
http://<host>:<port>/<application>/ws/<ws_version>/data/<data_location>/<data_branch>.<data_edition>/<web_service_name>?wsdl

where:

For example: http://127.0.0.1:10080/ws/1.0/data/CustomerAndFinancialMDM/0.0/GenericDataService?wsdl

Warning: Make sure that the data access web services are started before attempting to access them. They are not started by default when the data edition is created. You must start them and optionally configure them to automatically start using the Web Service Manager editor in the Administration Console perspective. See the "Managing Web Services" section in the "Semarchy Convergence for MDM Administration Guide" for more information about web service management.

Tip: When a web service is started, you can access its WSDL by double-clicking its WSDL URL in the services list in the Web Service Manager editor. In the Web Service Details dialog that opens, click the WSDL URL link to view the WSDL content.

Data Access Service

This service is named after the model, and its structure depends on the model structure. It provides read-only access to the various views storing golden data, master data, errors detected, etc.

Data Access Web Services Structure

For a given data edition, the data access service is organized as follows:

Requests Examples

Example: Call the getCustomer_GoldenData_List operation to retrieve the first 20 Golden Customers named like “G%”.

<soapenv:Envelope 
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ns="http://www.semarchy.com/xml/ws/1.0/data/CustomerAndFinancialMDM/0.0">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:getCustomer_GoldenData_List>
         <query>
         	<SemQLCondition>CustomerName LIKE 'G%'</SemQLCondition>
         	<StartIndex>1</StartIndex>
         	<PageSize>20</PageSize>
         </query>
      </ns:getCustomer_GoldenData_List>
   </soapenv:Body>
</soapenv:Envelope>

Example: Call the getCustomer_GoldenData_Record operation to retrieve the Golden Customer with CustomerID=20

<soapenv:Envelope 
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ns="http://www.semarchy.com/xml/ws/1.0/data/CustomerAndFinancialMDM/0.0">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:getCustomer_GoldenData_Record>
         <recordKey>
            <CustomerID>20</CustomerID>
         </recordKey>
      </ns:getCustomer_GoldenData_Record>
   </soapenv:Body>
</soapenv:Envelope>

Responses Examples:

Response to the getCustomer_GoldenData_Record call.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getCustomer_GoldenData_RecordResponse ... >
         <return>
            <BatchID>41</BatchID>
            <BranchID>0</BranchID>
            <FromEdition>1</FromEdition>
            <ClassName>Customer</ClassName>
            <CreationDate>2011-09-21T09:37:42.738+02:00</CreationDate>
            <Creator>joeletaxi</Creator>
            <CustomerID>20</CustomerID>
            <CustomerName>GENERAL SERVICES CORPORATION</CustomerName>
            <TotalRevenue>9111</TotalRevenue>
            <InputAddress>
               <Address>1 TERRITORIAL DRIVE</Address>
               <City>BOLINGBROOK</City>
               <Country>USA</Country>
            </InputAddress>
            <GeocodedAddress/>
            <FDN_Employee>Adam FRIPP</FDN_Employee>
            <FID_Employee>121</FID_Employee>
         </return>
      </ns1:getCustomer_GoldenData_RecordResponse>
   </soap:Body>

Note that the returned payload includes:

Generic Data Service

The Generic Data Service allows applications to interact (read/write) with the data in the hub in a generic way. Unlike the Data Access service, this web service provides a generic structure that is model-independent.

The Generic Data Service can be used in conjunction with the Activity Service to manipulate the contents of the transactions managed through the Activity Service.

Generic Data Service Bindings

This web service provides the following bindings:

Binding Name Description
queryRows Queries a view for a given entity, optionally in the context of a load ID. This web service returns a recordset corresponding to the query. See Querying Rows for more details about queries.
queryCount Returns the count of records for a given query. See Querying Rows for more details about queries.
checkoutRows Checkouts records – retrieved using a query – in a transaction attached to a data entry workflow task. The checked out records can be inserted in the transaction under a given node of a business object. See Checking Out Rows for more details.
PersistRow Inserts or updates records in a transaction attached to a workflow task. See Inserting and Updating Records for more information.
RemoveRowFromTx Remove records from a transaction attached to a workflow task.

Querying Rows

A query in the generic data service is composed of:

Note that the expressions mentioned above can use bind variables. Variables used in bind mode in the expressions (through the :<variable_name> syntax) can be specified in the request through Bindings. Bindings are named and typed.

Optionally, the generic data service supports pagination for the resultsets (through a Page Index and a Page Size)

The following code is a query to retrieve the golden customer revenue per country and employees, with a filter on employee names through the EMP binding.

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <gen:RowQuery>
         <QuerySource>
            <!-- Golden Data view for the Customer entity -->
            <gen:EntityName>Customer</gen:EntityName>
            <ViewType>GD</ViewType>
         </QuerySource>
         
         <!-- Select Expressions, incl. an aggregate (SUM) -->
         <SelectExpression>AccountManager.FirstName || ' ' || AccountManager.LastName
           </SelectExpression>
         <SelectExpression>InputAddress.Country</SelectExpression>
         <SelectExpression>SUM(TotalRevenue)</SelectExpression>
         
         <!-- Filter applied on the data, using the EMP biding. -->
         <WhereCondition>AccountManager.FirstName||' '||AccountManager.LastName LIKE :EMP
           </WhereCondition>
         
         <!-- The SUM calls for a group by on the other expressions -->
         <GroupByExpression>InputAddress.Country</GroupByExpression>
         <GroupByExpression>AccountManager.FirstName || ' ' || AccountManager.LastName
           </GroupByExpression>
           
         <!-- Ordering the results -->
         <OrderByCriteria descending="true">SUM(TotalRevenue)
           </OrderByCriteria>
           
         <!-- Definition for the EMP biding with the value -->   
         <Binding name="EMP">
            <String>S%</String>
         </Binding>
         
         <!-- Result pagination -->
         <PageCriteria>
            <StartIndex>1</StartIndex>
            <PageSize>10</PageSize>
         </PageCriteria>
      </gen:RowQuery>
   </soapenv:Body>
</soapenv:Envelope>

The response to this request follows:

<soap:Envelope>
   <soap:Header/>
   <soap:Body>
      <ns2:RowQueryResponse>
         <Row>
            <Value name="AccountManager.FirstName || ' ' || AccountManager.LastName">
               <String>Steven King</String>
            </Value>
            <Value name="InputAddress.Country">
               <String>FRANCE</String>
            </Value>
            <Value name="SUM(TotalRevenue)">
               <Decimal>62904</Decimal>
            </Value>
         </Row>
         <Row>
            <Value name="AccountManager.FirstName || ' ' || AccountManager.LastName">
               <String>Shanta Vollman</String>
            </Value>
            <Value name="InputAddress.Country">
               <String>USA</String>
            </Value>
            <Value name="SUM(TotalRevenue)">
               <Decimal>52978</Decimal>
            </Value>
         </Row>
...
...
      </ns2:RowQueryResponse>
   </soap:Body>
</soap:Envelope>

Checking Out Rows

Records are checked out for a data entry workflow using a query as defined above.
When checking out rows , it is necessary to specify the unique ID (UUID) of the task for which the records are checked out.

Besides, these records are inserted in a given target business object (managed by this workflow). The name of this Business Object must be provided.
In certain cases, the checked out records are in a sub-element of the business object. In this context, the Parent Data Row must be specified as the target of the check out operation.

The following example checks out in the context of a data entry task master data ( MD) for the Customer entity, filtered with CustomerName like 'S%'.

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <gen:CheckoutRows>
         <!-- Task UUID -->
         <DETaskUUID>c2c3e188-650e-4608-b501-d7df832f9ca0</DETaskUUID>
         <CheckoutQuery>
            <QuerySource>
               <gen:EntityName>Customer</gen:EntityName>
               <ViewType>MD</ViewType>
            </QuerySource>
            <WhereCondition>CustomerName like 'S%'</WhereCondition>
         </CheckoutQuery>
         <Target>
            <BusinessObject>CustomerBO</BusinessObject>
         </Target>
      </gen:CheckoutRows>
   </soapenv:Body>
</soapenv:Envelope>

Inserting and Updating Records

New records can be added to a transaction attached to an activity, and records checked out in this activity can also be modified.

To insert or update records, you must provide the unique ID (UUID) of the task, the name of the target entity of the insert/update operation. The New tag must be set to true/false to indicate whether it is a new record or an update.

Finally, you must provide in one or more datarows the various records that you want to update/insert. A datarow is composed of several values (named after the data entry form fields). For an insert, you should provide the Source ID or primary key and the mandatory data fields. For an update you should provide the Source ID or primary key and the data fields to update.

The following request adds a new Customer record through the task identified by the UUID.

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <gen:PersistRow>
         <!-- Task UUID -->
         <DETaskUUID>c2c3e188-650e-4608-b501-d7df832f9ca0</DETaskUUID>
         <!-- Datarow to insert -->
         <DataRow>
            <!-- Target entity -->
            <gen:EntityName>Customer</gen:EntityName>
            <!-- Identifies an insert (new record) -->
            <New>true</New>
            <!-- Content of the data row -->
            <DataRow>
               <Value name="SourceID">
                  <String>654564</String>
               </Value>
               <Value name="CustomerName">
                  <String>SEMARCHY</String>
               </Value>
               <Value name="TotalRevenue">
                  <Integer>200020</Integer>
               </Value>
            </DataRow>
         </DataRow>
      </gen:PersistRow>
   </soapenv:Body>
</soapenv:Envelope> 

Removing Rows from a Transaction

You can only remove records from an identified transaction. You must provide the unique ID (UUID) of the task, the name of the target entity of the insert/update operation. Provide one or more datarows containing the various records that you want to remove. A datarow is composed of several values (named after the data entry form fields). You should provide the Source ID or primary key or the records to remove.

Activity Service

The Activity Service that allows SOA applications to manage workflow instances defined in applications. This Web Service can be used in conjunction with the Generic Data Service to edit the contents of the MDM hub through data entry workflows.

Activity Service Bindings

This web service provides the following bindings:

Binding Name Description
startActivity Starts an activity based on a given workflow and returns the activity and first task’s UUIDs. See Starting an Activity for more details.
getActivity Returns the information about an activity (including the current active task) from its UUID.
getTask Returns the information about a task (including information about the activity) from its UUID.
listTasks List tasks and activities in an application with filtering options. See Listing Tasks for more details.
countTasks Count tasks and activities in an application with filtering options. See Listing Tasks for more details.
claimTask/unclaimTask Claims/unclaims a task identified by its UUID. See Managing Tasks for more details.
completeTask Completes a task and moves the activity to a subsequent task. See Managing Tasks for more details.
submit/cancel Completes a task and submits/cancel the activity. See Managing Tasks for more details.

Starting an Activity

The following example starts the ContactsCreationProcess in the DemoApplication, and claims the CreateOrModifyContacts startup task.

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <act:StartActivity>
         <ApplicationName>DemoApplication</ApplicationName>
         <HumanWorkflowName>ContactsCreationProcess</HumanWorkflowName>
         <StartTaskName>CreateOrModifyContacts</StartTaskName>
         <ActivityLabel>Create a new Contact</ActivityLabel>
         <StartComments>Please create a new contact for Customer X</StartComments>
         <NotifyAssignee>false</NotifyAssignee>
         <ClaimTask>true</ClaimTask>
         <Priority>NORMAL</Priority>
      </act:StartActivity>
   </soapenv:Body>
</soapenv:Envelope>


This request returns the following information.

<soapenv:Envelope>
   <soap:Header/>
   <soap:Body>
      <ns2:StartActivityResponse>
         <Activity>
            <ActivityUUID>7918b318-0214-40cf-b821-015eee11f63e</ActivityUUID>
            <ActivityLabel>Create a new Contact</ActivityLabel>
            <ApplicationName>DemoApplication</ApplicationName>
            <WorkflowName>ContactsCreationProcess</WorkflowName>
            <LoadID>41</LoadID>
            <Type>DATA_ENTRY</Type>
            <Priority>NORMAL</Priority>
            <CreationDate>2012-09-25T12:12:05.021+02:00</CreationDate>
            <Initiator>semadmin</Initiator>
            <StartComments>Please create a new contact for Customer X</StartComments>
            <Status>RUNNING</Status>
         </Activity>
         <Task>
            <TaskUUID>b53f6d1e-e020-41bf-9305-0c71850053df</TaskUUID>
            <ApplicationName>DemoApplication</ApplicationName>
            <WorkflowName>ContactsCreationProcess</WorkflowName>
            <TaskName>CreateOrModifyContacts</TaskName>
            <ActivityUUID>7918b318-0214-40cf-b821-015eee11f63e</ActivityUUID>
            <TaskSequence>0</TaskSequence>
            <TaskCreationDate>2012-09-25T12:12:05.021+02:00</TaskCreationDate>
            <TaskCreationUser>semadmin</TaskCreationUser>
            <TaskPerformer>semadmin</TaskPerformer>
            <TaskRevision>9145</TaskRevision>
            <TaskAssigneeRole>DemoSalesRep</TaskAssigneeRole>
            <TaskClaimDate>2012-09-25T12:12:05.021+02:00</TaskClaimDate>
            <TaskRoleNotified>false</TaskRoleNotified>
         </Task>
      </ns2:StartActivityResponse>
   </soap:Body>
</soap:Envelope>

Note that when working with activities and tasks, the UUID is used to identify the task, including when manipulating transaction data through the Generic Data Service.

Listing Tasks

The following request lists the tasks claimed by the connected user in the DemoApplication application.

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <act:ListTasks>
         <ApplicationName>DemoApplication</ApplicationName>
         <!-- Possible filter types are CLAIMED_BY_ME, CLAIMED_BY_OTHERS, ALL, PENDING --> 
         <FilterType>CLAIMED_BY_ME</FilterType>
      </act:ListTasks>
   </soapenv:Body>
</soapenv:Envelope>

Managing Tasks

The following request claims a task identified by its UUID.

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <act:ClaimTask>
         <TaskUUID>b53f6d1e-e020-41bf-9305-0c71850053df</TaskUUID>
      </act:ClaimTask>
   </soapenv:Body>
</soapenv:Envelope>

This same task can be unclaimed using the following request.

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <act:UnclaimTask>
         <TaskUUID>b53f6d1e-e020-41bf-9305-0c71850053df</TaskUUID>
         <NotifyAssignee>false</NotifyAssignee>
      </act:UnclaimTask>
   </soapenv:Body>
</soapenv:Envelope>

The following request completes the task and passes it to the VerifyDataBeforeSubmit transition. A new task UUID is returned.

<soapenv:Envelope>
   <soapenv:Header/>
   <soapenv:Body>
      <act:CompleteTask>
         <TaskUUID>b53f6d1e-e020-41bf-9305-0c71850053df</TaskUUID>
         <CompletionComments>Completed, ready for verification</CompletionComments>
         <TransitionName>VerifyDataBeforeSubmit</TransitionName>
         <NotifyAssignee>false</NotifyAssignee>
         <ClaimTask>true</ClaimTask>
      </act:CompleteTask>
   </soapenv:Body>
</soapenv:Envelope>

Using web services, it is possible to manage an activity until completion.