Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > SOAP data services
Navigation modeDocumentation > Developer Guide > SOAP data services

SOAP operations

Operations generated from a data model

For a data model used in an TIBCO EBX® repository, it is possible to dynamically generate a corresponding WSDL, that defines its operations. When using this WSDL, it will be possible to read and/or write in the EBX® repository. For example, for a table located at the path /root/XX/exampleTable, the generated requests would follow the structure of its underlying data model and include the name of the table <m:{operation}_exampleTable xmlns:m="urn:ebx-schemas:dataservices_1.0">.

Attention

Since the WSDL and the SOAP operations tightly depend on the data model structure, it is important to redistribute the up-to-date WSDL after any data model change.

Content policy

Access to the content of records, the presence or absence of XML elements, depend on the resolved permissions of the authenticated user session. Additional aspects, detailed below, can impact the content.

Disabling fields from data model

The hiddenInDataServices property, defined in the data model, allows always hiding fields in data services, regardless of the user profile. This parameter has an impact on the generated WSDL: any hidden field or group will be absent from the request and response structure.

Modifying the hiddenInDataServices parameter value has the following impact on a client which would still use the former WSDL:

This setting of "Default view" is defined inside data model.

Association field

Read-access on table records can export the association fields as displayed in UI Manager. This feature can be coupled with the 'hiddenInDataServices' model parameter.

Note

Limitations: change and update operations do not manage association fields. Also, the select operation only exports the first level of association elements (the content of associated objects cannot contain association elements).

Common request parameters

Several parameters are common to several operations and are detailed below.

Element

Description

Required

branch

The identifier of the dataspace to which the dataset belongs.

Either this parameter or the 'version' parameter must be defined. Required for the 'insert', 'update' and 'delete' operations.

version

The identifier of the snapshot to which the dataset belongs.

Either this parameter or the 'branch' parameter must be defined

instance

The unique name of the dataset which contains the table to query.

Yes

predicate

XPath predicate defines the records on which the request is applied. If empty, all records will be retrieved, except for the 'delete' operation where this field is mandatory.

Only required for the 'delete' operation

data

Contains the records to be modified, represented within the structure of their data model. The whole operation is equivalent to an XML import. The details of the operations performed on data content are specified in the section Import.

Only required for the insert and update operations

viewPublication

This parameter can be combined with the predicate parameter as a logical AND operation.

The behavior of this parameter is described in the section EBX® as a Web Component.

It cannot be used if the 'viewId' parameter is used, and cannot be used on hierarchical nor tile views.

No

viewId

Deprecated since version 5.2.3. This parameter has been replaced by the parameter 'viewPublication'. While it remains available for backward compatibility, it will eventually be removed in a future version.

This parameter cannot be used if the 'viewPublication' parameter is used.

No

blockingConstraintsDisabled

This property is available for all table updates data service operations.

If true, the validation process disables blocking constraints defined in the data model.

If this parameter is not present, the default is false.

See Blocking and non-blocking constraints for more information.

No

details

The details element specifies the following option:

The optional attribute locale (default 'en-US') defines the language of the blockingConstraintsDisabled parameter in which the validation messages must be returned.

No

disableRedirectionToLastBroadcast

This property is available for all data service operations.

If true, access to a delivery dataspace on a D3 primary node is not redirected to the last broadcast snapshot. Otherwise, access to such a dataspace is always redirected to the last snapshot broadcast.

If this parameter is not present, the default is false (redirection on a D3 master enabled), unless the configuration property ebx.dataservices.disableRedirectionToLastBroadcast.default has been set.

If the specified dataspace is not a delivery dataspace on a D3 primary node, this parameter is ignored.

No

Select operations

Select request on table

<m:select_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<version>String</version>
	<instance>String</instance>
	<predicate>String</predicate>
	<includesMetadata>String</includesMetadata>
	<viewPublication>String</viewPublication>
	<exportCredentials>boolean</exportCredentials>
	<pagination>
		<previousPageLastRecordPredicate>String</previousPageLastRecordPredicate>
		<pageSize>Integer</pageSize>
	</pagination>
	<disableRedirectionToLastBroadcast>boolean</disableRedirectionToLastBroadcast>
</m:select_{TableName}>

with:

Element

Description

Required

branch

See the description under Common parameters.

version

See the description under Common parameters.

instance

See the description under Common parameters.

predicate

See the description under Common parameters.

This parameter can be combined with the viewPublication parameter as a logical AND operation.

viewPublication

See the description under Common parameters.

includesMetadata

The response contains the specified metadata. Each returned record contains additional elements called steps under the ebx-metadata root element.

For instance, a 'system' step value will contain technical data. See also the optimistic locking section:

<system>
  <uuid>7FE03810-6A67-11ED-A892-00FF20216100</uuid>
  <creator>Uadmin</creator>
  <creation_time>2022-11-12T00:07:40.858</creation_time>
  <updater>Uadmin</updater>
  <update_time>2022-11-12T00:07:40.831</update_time>
</system>

String value steps (default value is empty) must be separated by a comma: system, teamUp. All steps can be returned using the ebx-all value.

No

includesTechnicalData

Deprecated since version 6.1.0 and replaced by includesMetadata request parameter. The response will contain technical data if true. See also the optimistic locking section.

Each returned record will contain additional attributes for this technical information, for instance:

...<table
ebxd:lastTime="2010-06-28T10:10:31.046" ebxd:lastUser="Uadmin"
ebxd:uuid="9E7D0530-828C-11DF-B733-0012D01B6E76">... .

No

exportCredentials

If true the select will also return the credentials for each record.

No

pagination

Specifies the pagination configuration, see child elements below.

No

pageSize (nested under the pagination element)

Specifies the maximum number of records per page.

Integer type, default value is 10.

The value 0 selects the maximum recommended page size, default is 10000.

Note

If the specified or default page size value exceeds the maximum recommended page size, the maximum page size is used.

No

previousPageLastRecordPredicate (nested under the pagination element)

When pagination is enabled, XPath predicate that defines the record after which the page must fetched, this value is provided by the previous response, as the element lastRecordPredicate. If the passed record is not found, the first page will be returned.

No

disableRedirectionToLastBroadcast

See the description under Common parameters.

Select response on table

<ns1:select_{TableName}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<data>
		<XX>
			<TableName>
				<a>key1</a>
				<b>valueb</b>
				<c>1</c>
				<d>1</d>
			</TableName>
		</XX>
	</data>
	<credentials>
		<XX>
			<TableName predicate="./a='key1'">
				<a>W</a>
				<b>W</b>
				<c>W</c>
				<d>W</d>
			</TableName>
		</XX>
	</credentials>
	<lastRecordPredicate>./a='key1'</lastRecordPredicate>
</ns1:select_{TableName}Response>

with:

Element

Description

data

Content of records that are displayed following the table path.

credentials

Contains the access right for each node of each record.

lastRecordPredicate

Only returned if the pagination is enabled, this defines the last records in order to be used on the next request in the element previousPageLastRecordPredicated.

See also the optimistic locking section.

Select request on dataset

This operation returns dataset content without table.

<m:selectInstance xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<version>String</version>
	<instance>String</instance>
</m:selectInstance>

with:

Element

Description

Required

branch

See the description under Common parameters.

version

See the description under Common parameters.

instance

See the description under Common parameters.

disableRedirectionToLastBroadcast

See the description under Common parameters.

Select response on dataset

<ns1:selectInstanceResponse xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<data>
		<settings>
			<XX>
				<a>key1</a>
				<b>valueb</b>
				<c>1</c>
				<d>true</d>
			</XX>
		</settings>
	</data>
</ns1:selectInstanceResponse>

with:

Element

Description

data

Dataset content without table.

Delete operation

Deletes records or, for a child dataset, defines the record state as "occulting" or "inherited" according to the record context. Records are selected by the predicate parameter.

Delete request

<m:delete_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<instance>String</instance>
	<predicate>String</predicate>
	<includeOcculting>boolean</includeOcculting>
	<inheritIfInOccultingMode>boolean</inheritIfInOccultingMode>
	<checkNotChangedSinceLastTime>dateTime</checkNotChangedSinceLastTime>
	<blockingConstraintsDisabled>boolean</blockingConstraintsDisabled>
	<details locale="Locale"/>
	<disableRedirectionToLastBroadcast>Boolean</disableRedirectionToLastBroadcast>
</m:delete_{TableName}>

with:

Element

Description

Required

branch

See the description under Common parameters.

instance

See the description under Common parameters.

predicate

See the description under Common parameters.

includeOcculting

Includes the records in occulting mode.

Default value is false.

No

inheritIfInOccultingMode

Inherits the record from its parent if it is in occulting mode.

Default value is false.

No

occultIfInherit

Deprecated since version 5.7.0 Occults the record if it is in inherit mode.

Default value is false.

No

checkNotChangedSinceLastTime

Timestamp used to ensure that the record has not been modified since the last read. Also see the optimistic locking section.

No

blockingConstraintsDisabled

See the description under Common parameters.

details

See the description under Common parameters.

disableRedirectionToLastBroadcast

See the description under Common parameters.

Delete response

If one of the provided parameters is illegal, if a required parameter is missing, if the action is not authorized or if no record is selected, an exception is returned. Otherwise, the specific response is returned:

<ns1:delete_{TableName}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
	<blockingConstraintMessage>String</blockingConstraintMessage>
</ns1:delete_{TableName}Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

'95' indicates that at least one operation has violated a blocking constraint, resulting in the overall operation being aborted.

blockingConstraintMessage

This element is present if the status is equal to '95' with a localized message. The locale of the message is retrieved from the request parameter or from the user session.

Count operation

Count request

<m:count_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<branch>String</branch> 
	<version>String</version> 
	<instance>String</instance> 
	<predicate>String</predicate>
	<disableRedirectionToLastBroadcast>boolean</disableRedirectionToLastBroadcast>
</m:count_{TableName}>

with:

Element

Description

branch

See the description under Common parameters.

version

See the description under Common parameters.

instance

See the description under Common parameters.

predicate

See the description under Common parameters.

disableRedirectionToLastBroadcast

See the description under Common parameters.

Count response

<ns1:count_{TableName}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<count>Integer</count>
</ns1:count_{TableName}Response>

with:

Element

Description

count

The number of records that correspond to the predicate in the request.

Update operation

Update request

<m:update_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<instance>String</instance>
	<updateOrInsert>boolean</updateOrInsert>
	<byDelta>boolean</byDelta>
	<blockingConstraintsDisabled>boolean</blockingConstraintsDisabled>
	<details locale="Locale"/>
	<disableRedirectionToLastBroadcast>boolean</disableRedirectionToLastBroadcast>
	<data>
		<XX>
			<TableName>
				<a>String</a>
				<b>String</b>
				<c>String</c>
				<d>String</d>
				...
			</TableName>
		</XX>
	</data>
</m:update_{TableName}>

with:

Element

Description

Required

branch

See the description under Common parameters.

instance

See the description under Common parameters.

updateOrInsert

If true and the record does not currently exist, the operation creates the record.

boolean type, the default value is false.

No

byDelta

If true and an element does not currently exist in the incoming message, the target value is not changed.

If false and node is declared hiddenInDataServices, the target value is not changed.

The complete behavior is described in the sections Insert and update operations.

No

blockingConstraintsDisabled

See the description under Common parameters.

details

See the description under Common parameters.

disableRedirectionToLastBroadcast

See the description under Common parameters.

data

See the description under Common parameters.

Update response

<ns1:update_{TableName}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
	<blockingConstraintMessage>String</blockingConstraintMessage>
</ns1:update_{TableName}Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

'95' indicates that at least one operation has violated a blocking constraint, resulting in the overall operation being aborted.

blockingConstraintMessage

This element is present if the status is equal to '95' with a localized message. The locale of the message is retrieved from the request parameter or from the user session.

Insert operation

Insert request

<m:insert_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<instance>String</instance>
	<byDelta>boolean</byDelta>
	<blockingConstraintsDisabled>boolean</blockingConstraintsDisabled>
	<details locale="Locale"/>
	<disableRedirectionToLastBroadcast>boolean</disableRedirectionToLastBroadcast>
	<data>
		<XX>
			<TableName>
				<a>String</a>
				<b>String</b>
				<c>String</c>
				<d>String</d>
				...
			</TableName>
		</XX>
	</data>
</m:insert_{TableName}>

with:

Element

Description

Required

branch

See the description under Common parameters.

instance

See the description under Common parameters.

byDelta

If true and an element does not currently exist in the incoming message, the target value is not changed.

If false and node is declared hiddenInDataServices, the target value is not changed.

The complete behavior is described in the sections Insert and update operations.

No

blockingConstraintsDisabled

See the description under Common parameters.

details

See the description under Common parameters.

disableRedirectionToLastBroadcast

See the description under Common parameters.

data

See the description under Common parameters.

Insert response

<ns1:insert_{TableName}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
	<blockingConstraintMessage>String</blockingConstraintMessage>
	<inserted>
		<predicate>./a='String'</predicate>
	</inserted>
</ns1:insert_{TableName}Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

'95' indicates that at least one operation has violated a blocking constraint, resulting in the overall operation being aborted.

blockingConstraintMessage

This element is present if the status is equal to '95' with a localized message. The locale of the message is retrieved from the request parameter or from the user session.

predicate

A predicate matching the primary key of the inserted record. When several records are inserted, the predicates follow the declaration order of the records in the input message.

Get changes operations

Returns changes according to the Content policy.

Get changes requests

Changes between two datasets:

<m:getChangesOnDataSet_{schemaName} xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<version>String</version>
	<instance>String</instance>
	<compareWithBranch>String</compareWithBranch>
	<compareWithVersion>String</compareWithVersion>
	<compareWithInstance>String</compareWithInstance>
	<resolvedMode>boolean</resolvedMode>
	<includeInstanceUpdates>boolean</includeInstanceUpdates>
</m:getChangesOnDataSet_{schemaName}>

Changes between two tables:

<m:getChanges_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<version>String</version>
	<instance>String</instance>
	<compareWithBranch>String</compareWithBranch>
	<compareWithVersion>String</compareWithVersion>
	<resolvedMode>boolean</resolvedMode>
	<pagination>
		<pageSize>Integer</pageSize>
	</pagination>
	<disableRedirectionToLastBroadcast>boolean</disableRedirectionToLastBroadcast>
</m:getChanges_{TableName}> 

with:

Element

Description

Required

branch

See the description under Common parameters.

version

See the description under Common parameters.

instance

See the description under Common parameters.

compareWithBranch

The identifier of the dataspace with which to compare.

One of either this parameter or the 'compareWithVersion' parameter must be defined.

compareWithVersion

The identifier of the snapshot with which to compare.

One of either this parameter or the 'compareWithBranch' parameter must be defined.

compareWithInstance

The identifier of the dataset with which to compare. If it is undefined, instance parameter is used.

No

resolvedMode

Defines whether or not the difference is calculated in resolved mode. Default is true.

See Resolved mode for more information.

No

includeInstanceUpdates

Defines if the content updates of the dataset are included. Default is false.

No

pagination

Enables pagination context for the operations getChanges and getChangesOnDataSet.

Allows client to define pagination context size. Each page contains a collection of inserted, updated and/or deleted records of tables according to the maximum size.

Get changes persisted context is built at first call according to the page size parameter in request.

The pagination context is persisted on the server file system and allows invoking the next page until last page or when a timeout is reached.

For creation: Defines pageSize parameter.

For next: Defines context element with identifier from previous response.

Enables pagination, see child elements below.

No

pageSize (nested under pagination element)

Defines maximum number of records in each page. Minimal size is 50.

No (Only for creation)

context (nested under pagination element)

Defines content of pagination context.

No (Only for next)

identifier (nested under context element)

Pagination context identifier.

Yes

disableRedirectionToLastBroadcast

See the description under Common parameters.

Note

If none of the compareWithBranch or compareWithVersion parameters are specified, the comparison will be made with their parent:

  • if the current dataspace or snapshot is a dataspace, the comparison is made with its initial snapshot (includes all changes made in the dataspace);

  • if the current dataspace or snapshot is a snapshot, the comparison is made with its parent dataspace (includes all changes made in the parent dataspace since the current snapshot was created);

  • returns an exception if the current dataspace is the 'Reference' dataspace.

See also

Get changes responses

Changes between two datasets:

<ns1:getChangesOnDataSet_{schemaName}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<updated>
		<changes>
			<path>... Path of changed terminal value ...</path>
			<path>...</path>
		</changes>
		<data>
			... see the whole content of dataset values (without table) ...
		</data>
	</updated>
	<getChanges_{TableName1}>
		... see the getChanges between tables response example ...
	</getChanges_{TableName1}>
	<getChanges_{TableName2}>
		... see the getChanges between tables response example ...
	</getChanges_{TableName2}>
	...
</ns1:getChangesOnDataSet_{schemaName}Response>

Changes between two tables:

<ns1:getChanges_{TableName}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<inserted>
		<XX>
			<TableName>
				<a>AVALUE3</a>
				<b>BVALUE3</b>
				<c>CVALUE3</c>
				<d>DVALUE3</d>
			</TableName>
		</XX>
	</inserted>
	<updated>
		<changes>
			<change predicate="./a='AVALUE2'">
				<path>/b</path>
				<path>/c</path>
			</change>
		</changes>
		<data>
			<XX>
				<TableName>
					<a>AVALUE2</a>
					<b>BVALUE2.1</b>
					<c>CVALUE2.1</c>
					<d>DVALUE2</d>
				</TableName>
			</XX>
		</data>
	</updated>
	<deleted>
		<predicate>./a='AVALUE1'</predicate>
	</deleted>
</ns1:getChanges_{TableName}Response>

with:

Element

Description

Required

inserted

Contains inserted record(s) from choice compareWithBranch or compareWithVersion.

Content under this element corresponding to an XML export of inserted records.

No

updated

Contains updated record(s) or dataset content.

No

changes (nested under updated element)

Only the group of field have been updated.

Yes

change (nested under changes element)

Group of fields have been updated with own XPath predicate attribute of the record.

Yes

path (nested under change element)

Path in the record.

Yes

path (nested under changes element)

Path in the dataset.

Yes

data (nested under updated element)

Content under this element corresponding to an XML export of dataset or updated records.

No

deleted

Records have been deleted from context of request.

Content corresponding to a list of predicate element who contains the XPath predicate of record.

No

pagination

When pagination is enabled on request.

Get changes persisted context allows invoking the next page until last page or when the context timeout is reached.

Contains a next page: Defines context element with identifier.

Is the last page: Defines context element without identifier.

Enables pagination, see child elements below.

No

context (nested under pagination element)

Defines content of pagination context.

Yes (Only for next and last)

identifier (nested under context element)

Pagination context identifier. Not defined at last returned page.

No

pageNumber (nested under context element)

Current page number in pagination context.

Yes

totalPages (nested under context element)

Total pages in pagination context.

Yes

Get changes operation with pagination enabled

Only pagination element and sub elements have been described.

For creation:

Extract of request:

...
	<pagination>
		<!-- on first request for creation -->
		<pageSize>Integer</pageSize>
	</pagination>
...

Extract of response:

...
	<pagination>
		<!-- on next request to continue -->
		<context>
			<identifier>String</identifier> 
			<pageNumber>Integer</pageNumber> 
			<totalPages>Integer</totalPages> 
		</context>
	</pagination>	
...

For next:

Extract of request:

...
	<pagination>
		<context>
			<identifier>String</identifier>
		</context> 
	</pagination>
...

Extract of response:

...
	<pagination>
		<!-- on next request to continue -->
		<context>
			<identifier>String</identifier> 
			<pageNumber>Integer</pageNumber> 
			<totalPages>Integer</totalPages> 
		</context>
	</pagination>	
...

For last:

Extract of request:

...
	<pagination>
		<context>
			<identifier>String</identifier>
		</context> 
	</pagination>
...

Extract of response:

...
	<pagination>
		<context>
			<pageNumber>Integer</pageNumber> 
			<totalPages>Integer</totalPages> 
		</context>
	</pagination>	
...

Get credentials operation

Get credentials request

<m:getCredentials_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<version>String</version>
	<instance>String</instance>
	<predicate>String</predicate>
	<viewPublication>String</viewPublication>
	<disableRedirectionToLastBroadcast>boolean</disableRedirectionToLastBroadcast>
</m:getCredentials_{TableName}>

with:

Element

Description

Required

branch

See the description under Common parameters.

version

See the description under Common parameters.

instance

See the description under Common parameters.

predicate

See the description under Common parameters.

viewPublication

See the description under Common parameters.

Get credentials response

<ns1:getCredentials_{TableName}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<XX>
		<TableName>
			<a>R</a>
			<b>W</b>
			<c>H</c>
			<d>W</d>
			...
		</TableName>
	</XX>
</ns1:getCredentials_{TableName}Response>

With the following possible values:

Multiple chained operations

Multiple operations request

It is possible to run multiple operations across tables in the dataset, while ensuring a consistent response. The operations are executed sequentially, according to the order defined on the client side.

All operations are executed in a single transaction with a SERIALIZABLE isolation level. If all requests in the multiple operation are read-only, they are allowed to run fully concurrently along with other read-only transactions, even in the same dataspace.

When an error occurs during one operation in the sequence, all updates are rolled back and the client receives a StandardException error message with details.

See Concurrency.

<m:multi_ xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<version>String</version>
	<instance>String</instance>
	<blockingConstraintsDisabled>boolean</blockingConstraintsDisabled>
	<disableRedirectionToLastBroadcast>boolean</disableRedirectionToLastBroadcast>
	<details locale="Locale"/>
	<request id="id1">
		<{operation}_{TableName}>
		...
		</{operation}_{TableName}>
	</request>
	<request id="id2">
		<{operation}_{TableName}>
		...
		</{operation}_{TableName}>
	</request>
</m:multi_>

with:

Element

Description

Required

branch

See the description under Common parameters.

version

See the description under Common parameters.

instance

See the description under Common parameters.

blockingConstraintsDisabled

See the description under Common parameters.

details

See the description under Common parameters.

disableRedirectionToLastBroadcast

See the description under Common parameters.

request

This element contains one operation, like a single operation without branch, version and instance parameters. This element can be repeated multiple times for additional operations. Each request can be identified by an 'id' attribute. In a response, this 'id' attribute is returned for identification purposes.

Operations such as count, select, getChanges, getCredentials, insert, delete or update.

Yes

Note:

Limitation:

Multiple operations response

See each response operation for details.

<ns1:multi_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<response id="id1">
		<{operation}_{TableName}Response>
		...
		</{operation}_{TableName}Response>
	</response>
	<response id="id2">
		<{operation}_{TableName}Response>
		...
		</{operation}_{TableName}Response>
	</response>
</ns1:multi_Response>

with:

Element

Description

response

This element contains the response of one operation. It is be repeated multiple times for additional operations. Each response is identified by an 'id' attribute set in the request or automatically generated.

The content of the element corresponds to the response of a single operation, such as count, select, getChanges, getCredentials, insert, delete or update.

Optimistic locking

To prevent an update or a delete operation on a record that was read earlier but may have changed in the meantime, an optimistic locking mechanism is provided.

A select request can include technical information by adding the element includesMetadata with system value:

<m:select_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<branch>String</branch> 
	<version>String</version> 
	<instance>String</instance> 
	<predicate>String</predicate> 
	<includesMetadata>system</includesMetadata> 
</m:select_{TableName}>

Use the value of the ebx-metadata/system/update_time element in the following update request. If the record was changed since the specified time, the update cancels. To prevent update of a modified record, add the ebx-metadata/system/update_time element value.

<m:update_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<branch>String</branch> 
   	<version>String</version> 
	<instance>String</instance> 
	<updateOrInsert>true</updateOrInsert> 
	<data> 
		<XX> 
			<TableName> 
				<a>String</a> 
				<b>String</b> 
				<c>String</c> 
				<d>String</d> 
				...
				<ebx-metadata>
					<system>
						...
						<update_time>2010-06-28T10:10:31.046</update_time>
					</system>
				</ebx-metadata>
			</TableName> 
		</XX> 
	</data> 
</m:update_{TableName}>

The value of the lastTime attribute can also be used to prevent deletion on a modified record:

<m:delete_{TableName} xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<branch>String</branch> 
	<version>String</version> 
	<instance>String</instance> 
	<predicate>String</predicate> 
	<checkNotChangedSinceLastTime>2010-06-28T10:10:31.046</checkNotChangedSinceLastTime> 
</m:delete_{TableName}>
Note

You can use the checkNotChangedSinceLastTime element more than once, but only for the same record. This implies that if the predicate element returns more than one record, the request will fail.

Operations on datasets and dataspaces

Parameters for operations on dataspaces and snapshots are as follows:

Element

Description

Required

branch

Identifier of the target dataspace on which the operation is applied. When not specified, the 'Reference' dataspace is used except for the merge dataspace operation where it is required.

One of either this parameter or the 'version' parameter must be defined. Required for the dataspace merge, locking, unlocking and replication refresh operations.

version

Identifier of the target snapshot on which the operation is applied.

One of either this parameter or the 'branch' parameter must be defined

versionName

Identifier of the snapshot to create. If empty, it will be defined on the server side.

No

childBranchName

Identifier of the dataspace child to create. If empty, it will be defined on the server side.

No

instance

The unique name of the dataset on which the operation is applied.

Required for the replication refresh operation.

ensureActivation

Defines if validation must also check whether this instance is activated.

Yes

details

Defines if validation returns details.

The optional attribute severityThreshold defines the lowest severity level of message to return. The possible values are, in descending order of severity, 'fatal', 'error', 'warning', or 'info'. For example, setting the value to 'error' will return error and fatal validation messages. If this attribute is not defined, all levels of messages are returned by default.

The optional attribute locale (default 'en-US') defines the language in which the validation messages are to be returned.

No. If not specified, no details are returned.

owner

Defines the owner.

Must respect the inner format as returned by Profile.format.

No

branchToCopyPermissionFrom

Defines the identifier of the dataspace from which to copy the permissions.

No

documentation

Documentation for a dedicated language.

Multiple documentation elements may be used for several languages.

No

locale (nested under the documentation element)

Locale of the documentation.

Only required when the documentation element is used

label (nested under the documentation element)

Label for the language.

No

description (nested under the documentation element)

Description for the language.

No

Validate a dataspace

Validate dataspace request

<m:validate xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<branch>String</branch>
	<version>String</version> 
</m:validate>

Validate dataspace response

<ns1:validate_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<validationReport>
		<instanceName>String</instanceName>
		<fatals>boolean</fatals>
		<errors>boolean</errors>
		<infos>boolean</infos>
		<warnings>boolean</warnings>
	</validationReport>
</ns1:validate_Response>

Validate a dataset

Validate dataset request

<m:validateInstance xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<branch>String</branch> 
	<version>String</version> 
	<instance>String</instance> 
	<ensureActivation>boolean</ensureActivation> 
	<details severityThreshold="fatal|error|warning|info" locale="Locale"/>
</m:validateInstance>

Validate dataset response

<ns1:validateInstance_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<validationReport>
		<instanceName>String</instanceName>
		<fatals>boolean</fatals>
		<errors>boolean</errors>
		<infos>boolean</infos>
		<warnings>boolean</warnings>
		<details>
			<reportItem>
				<severity>{fatal|error|warning|info}</severity>
				<message>
					<internalId />
					<text>String</text>
				</message>
				<subject>
					<table>Path</table>
					<predicate>String</predicate>
					<path>Path</path>
				</subject>
			</reportItem>
		</details>
	</validationReport>
</ns1:validateInstance_Response>

Create a dataspace

Create dataspace request

<m:createBranch xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<owner>String</owner>
	<branchToCopyPermissionFrom>String</branchToCopyPermissionFrom>
	<documentation>
		<locale>Locale</locale>
		<label>String</label>
		<description>String</description>
	</documentation>
	<childBranchName>String</childBranchName>
</m:createBranch>

Create dataspace response

<ns1:createBranch_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
	<childBranchName>String</childBranchName>
</ns1:createBranch_Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

Create a snapshot

Create snapshot request

<m:createVersion xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<versionName>String</versionName>
	<owner>String</owner>
	<documentation>
		<locale>Locale</locale>
		<label>String</label>
		<description>String</description>
	</documentation>
</m:createVersion>

Create snapshot response

<ns1:createVersion_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
	<versionName>String</versionName>
</ns1:createVersion_Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

Locking a dataspace

Lock dataspace request

<m:lockBranch xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<durationToWaitForLock>Integer</durationToWaitForLock>
	<message>
		<locale>Locale</locale>
		<label>String</label>
	</message>
</m:lockBranch>

with:

Element

Description

Required

durationToWaitForLock

This parameter defines the maximum duration (in seconds) that the operation waits for a lock before aborting.

No, does not wait by default

message

User message of the lock. Multiple message elements may be used.

No

locale (nested under the message element)

Locale of the user message.

Only required when the message element is used

label (nested under the message element)

The user message.

No

Lock dataspace response

<ns1:lockBranch_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
</ns1:lockBranch_Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

'94' indicates that the dataspace has been already locked by another user.

Otherwise, a SOAP exception is thrown.

Unlocking a dataspace

Unlock dataspace request

<m:unlockBranch xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
</m:unlockBranch>

Unlock dataspace response

<ns1:unlockBranch_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
</ns1:unlockBranch_Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

Otherwise, a SOAP exception is thrown.

Merge a dataspace

Merge dataspace request

<m:mergeBranch xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<branch>String</branch>
	<deleteDataOnMerge>boolean</deleteDataOnMerge>
	<deleteHistoryOnMerge>boolean</deleteHistoryOnMerge>
</m:mergeBranch>

with:

Element

Description

Required

deleteDataOnMerge

This parameter is available for the merge dataspace operation. Sets whether the specified dataspace and its associated snapshots will be deleted upon merge.

When this parameter is not specified in the request, the default value is false. It is possible to redefine the default value by specifying the property ebx.dataservices.dataDeletionOnCloseOrMerge.default in the EBX® main configuration file.

See Deleting data and history for more information.

No

deleteHistoryOnMerge

This parameter is available for the merge dataspace operation. Sets whether the history associated with the specified dataspace will be deleted upon merge. Default value is false.

When this parameter is not specified in the request, the default value is false. It is possible to redefine the default value by specifying the property ebx.dataservices.historyDeletionOnCloseOrMerge.default in the EBX® main configuration file.

See Deleting data and history for more information.

No

Note

The merge decision step is bypassed during merges performed through data services. In such cases, the data in the child dataspace automatically overrides the data in the parent dataspace.

Merge dataspace response

<ns1:mergeBranch_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
</ns1:mergeBranch_Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

Close a dataspace or snapshot

Close dataspace or snapshot request

Close dataspace request:

<m:closeBranch xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<deleteDataOnClose>boolean</deleteDataOnClose>
	<deleteHistoryOnClose>boolean</deleteHistoryOnClose>
</m:closeBranch>

Close snapshot request:

<m:closeVersion xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<version>String</version>
	<deleteDataOnClose>boolean</deleteDataOnClose>
</m:closeVersion>

with:

Element

Description

Required

deleteDataOnClose

This parameter is available for the close dataspace and close snapshot operations. Sets whether the specified snapshot, or dataspace and its associated snapshots, will be deleted upon closure.

When this parameter is not specified in the request, the default value is false. It is possible to redefine this default value by specifying the property ebx.dataservices.dataDeletionOnCloseOrMerge.default in the EBX® main configuration file.

See Deleting data and history for more information.

No

deleteHistoryOnClose

This parameter is available for the close dataspace operation. Sets whether the history associated with the specified dataspace will be deleted upon closure. Default value is false.

When this parameter is not specified in the request, the default value is false. It is possible to redefine the default value by specifying the property ebx.dataservices.historyDeletionOnCloseOrMerge.default in the EBX® main configuration file.

See Deleting data and history for more information.

No

Close dataspace or snapshot response

Close dataspace response:

<ns1:closeBranch_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
</ns1:closeBranch_Response>

Close snapshot request:

<ns1:closeVersion_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
</ns1:closeVersion_Response>

Replication refresh

Replication refresh request

<m:replicationRefresh_${schema} xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>String</branch>
	<instance>String</instance>
	<unitName>String</unitName>
</m:replicationRefresh_${schema}>

with:

Element

Description

Required

branch

See the description under Common parameters.

Yes

instance

See the description under Common parameters.

Yes

unitName

Name of the replication unit.

Yes

Replication refresh response

<ns1:replicationRefresh_${schema}Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
</ns1:replicationRefresh_${schema}Response>

with:

Element

Description

status

'00' indicates that the operation has been executed successfully.

Operations on data workflows

Parameters for data workflows operations are retrieved from the SOAP header in the session.

Deprecated since version 5.7.0 to define parameters in the SOAP message body.

See session parameters for more information.

Element

Description

Required

parameters

Deprecated since version 5.7.0 While it remains available for backward compatibility, it will eventually be removed in a future major version.

Note

The parameters element is ignored if at least one session parameter has been defined.

No

parameter (nested under the parameters element). Multiple parameter elements may be used.

An input parameter for the workflow.

No

name (nested under the parameter element)

Name of the parameter.

Yes

value (nested under the parameter element)

Value of the parameter.

No

Start a workflow

Start a workflow from a workflow launcher. It is possible to start a workflow with localized documentation and specific input parameters (with name and optional value).

Note

The workflow creator is initialized from the session and the workflow priority is retrieved from the last published version.

Sample request:

<m:workflowProcessInstanceStart xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<publishedProcessKey>String</publishedProcessKey>
	<documentation>
		<locale>Locale</locale>
		<label>String</label>
		<description>String</description>
	</documentation>
</m:workflowProcessInstanceStart>

with:

Element

Description

Required

publishedProcessKey

Identifier of the workflow launcher.

Yes

documentation

See the description under Common parameters.

No

parameters

Deprecated since version 5.7.0 See the description under Common parameters.

No

Sample response:

<m:workflowProcessInstanceStart_Response xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<processInstanceKey>String</processInstanceKey>
</m:workflowProcessInstanceStart_Response>

with:

Element

Description

Required

processInstanceId

Deprecated since version 5.6.1 This parameter has been replaced by the 'processInstanceKey' parameter. While it remains available for backward compatibility, it will eventually be removed in a future major version.

No

processInstanceKey

Workflow identifier.

No

Resume a workflow

Resume a workflow in a wait step from a resume identifier. It is possible to define specific input parameters (with name and optional value).

Sample request:

<m:workflowProcessInstanceResume xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<resumeId>String</resumeId>
</m:workflowProcessInstanceResume>

with:

Element

Description

Required

resumeId

Resume identifier of the waiting task.

Yes

parameters

Deprecated since version 5.7.0 See the description under Common parameters.

No

Sample response:

<m:workflowProcessInstanceResume_Response xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
	<processInstanceKey>String</processInstanceKey>
</m:workflowProcessInstanceResume_Response>

with:

Element

Description

Required

status

'00' indicates that the operation has been executed successfully.

'20' indicates that the workflow has not been found.

'21' indicates that the event has already been received.

Yes

processInstanceKey

Identifier of the workflow. This parameter is returned if the operation has been executed successfully.

No

End a workflow

End a workflow from its identifier.

Sample request:

<m:workflowProcessInstanceEnd xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<processInstanceKey>String</processInstanceKey>
</m:workflowProcessInstanceEnd>

with:

Element

Description

Required

processInstanceKey

Identifier of the workflow.

Either this parameter or 'publishedProcessKey' and 'processInstanceId' parameters must be defined.

publishedProcessKey

Deprecated since version 5.6.1 Due to a limitation this parameter has been replaced by the 'processInstanceKey' parameter. While it remains available for backward compatibility, it will eventually be removed in a future major version.

No

processInstanceId

Deprecated since version 5.6.1 Due to a limitation this parameter has been replaced by the 'processInstanceKey' parameter. While it remains available for backward compatibility, it will eventually be removed in a future major version.

No

Sample response:

<m:workflowProcessInstanceEnd_Response xmlns:m="urn:ebx-schemas:dataservices_1.0"> 
	<status>String</status> 
</m:workflowProcessInstanceEnd_Response>

with:

Element

Description

Required

status

'00' indicates that the operation has been executed successfully.

Yes

Administrative services

Directory services

The services on directory provide operations on the 'Users' and 'Roles' tables of the default directory. To execute an operation related to these services, the authenticated user must be a member of the built-in role 'Administrator'.

The technical dataspace and dataset must be set to ebx-directory. For all SOAP operation syntaxes, see Operations generated from a data model for more information.

Create a user in the directory

This example of a SOAP insert request adds a user to the EBX® directory.

<m:insert_user xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<branch>ebx-directory</branch>
	<instance>ebx-directory</instance>
	<data>
	<directory>
		<users>
			<login>login</login>
			<lastName>lastname</lastName>
			<firstName>firstname</firstName>
			<email>firstname.lastname@email.com</email>
			<password>***</password>
			<passwordMustChange>true</passwordMustChange>
			<builtInRoles>
				<administrator>false</administrator>
				<readOnly>false</readOnly>
			</builtInRoles>
			<comments>a comment</comments>
		</users>
	</directory>
	</data>
</m:insert_user>

For the insert SOAP response syntax, see insert response for more information.

User interface operations

See Application locking for more information.

Parameters for operations on the user interface are as follows:

Element

Description

Required

closedMessage

Message to be displayed to users when the user interface is closed to access.

No

Close user interface request

The close operation removes all user sessions that are not acceptable in this mode.

<m:close xmlns:m="urn:ebx-schemas:dataservices_1.0">
	<closedMessage>Access is temporarily forbidden.</closedMessage>
</m:close>

Close user interface response

<ns1:close_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
</ns1:close_Response>

Open user interface request

<m:open xmlns:m="urn:ebx-schemas:dataservices_1.0"/>

Open user interface response

<ns1:open_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
	<status>String</status>
</ns1:open_Response>

System information operation

This operation returns the EBX® system information. The information returned is the same as the information contained in the log header kernel.log or in the UI tab 'Administration' > 'System Information'. The response contains several keys, labels, and values representing the configuration and status of EBX®. To execute this operation, the authenticated user must be a member of the built-in role 'Administrator'.

Parameters

The following parameter is applicable.

Parameter

Description

Required

details

Defines attributes that must be applied to response messages.

The attribute locale (default: EBX® default locale) defines the language in which the system item messages must be returned.

No, but if specified, the locale attribute must be provided.

System information request

This SOAP request will return all EBX® instance's system information and format them using "en_US" locale.

<m:systemInformation xmlns:m="urn:ebx-schemas:dataservices_1.0">
    <details locale="en_US" />
</m:systemInformation>

System information response

<ns1:systemInformation_Response xmlns:ns1="urn:ebx-schemas:dataservices_1.0">
    <bootInfoEBX>
        <label>String</label>
        <infoItem>
            <key>String</key>
            <label>String</label>
            <content>String</content>
            <content>String</content>
            ...
        </infoItem>
        ...            
    </bootInfoEBX>
    <repositoryInfo>
        <label>String</label>
        <infoItem>
            <key>String</key>
            <label>String</label>
            <content>String</content>
            <content>String</content>
            ... 
        </infoItem>
        ...
    </repositoryInfo>
    <bootInfoVM>
        <label>String</label>
        <infoItem>
            <key>String</key>
            <label>String</label>
            <content>String</content>
            ...
        </infoItem>
        ...
    </bootInfoVM>
</ns1:systemInformation_Response>
Documentation > Developer Guide > SOAP data services