Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > SOAP data services
Navigation mode Documentation > 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:

- On request, if the data model property has been changed to `true`, and if the concerned field is present in the WSDL request, an exception will be thrown.

- On response, if the schema property has been changed to `false`, WSDL validation will return an error if it is activated.

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

##### See also

- Hiding a field in Data Services
- Permissions

#### 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. ##### See also `includesMetadata` parameter | 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. ##### See also ebx.dataservices.pagination.pageSize.default The value 0 selects the maximum recommended page size, default is 10000. ##### See also ebx.dataservices.pagination.maxSize.default ##### 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. |

##### See also

- Optimistic locking

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

- `DifferenceHelper`

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

- R: for read-only

- W: for read-write

- H: for hidden

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

- Does not accept a limit on the number of `request` elements.

- The request `id` attribute must be unique in multi-operation requests.

- If all operations are read only (`count`, `select`, `getChanges`, or `getCredentials`) then the whole transaction is set as read-only for performance considerations.

Limitation:

- The `multi` operation applies to one model and one dataset (parameter `instance`).

##### See also

- `Procedure`
- `Repository`

#### 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. ##### See also Replication refresh information | 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