Web Services | ||
---|---|---|
Previous | ||
Consuming Data from the Hub |
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:
The Platform Services include:
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. |
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. |
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.
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. |
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 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:
<host>
,
<port>
,
<application>
is the location of the Semarchy Convergence for MDM application instance deployed in the application server.
<ws_version>
is the version of the Semarchy data access services: Set this value to
1.0
<data_location>
is the name of the data location into which the data edition is stored.
<data_branch>
is the ID of the data branch of the data edition.
<data_edition>
is the ID of the data edition in this branch.
<web_service_name>
is the name of the data access service:
ActivityService,
GenericDataService, or the Model Name for the Data Access service.
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.
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.
For a given data edition, the data access service is organized as follows:
get<Entity Name>_<Structure>_List
. For example:
getCustomer_MasterData_List.
get<Entity Name>_<Structure>_Record
. For example:
getCustomer_GoldenData_Record
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>
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:
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.
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. |
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>
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>
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>
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.
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.
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. |
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.
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>
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.
Previous | Top | |
Consuming Data from the Hub |