About the Entity Configuration Web Service

The Entity Configuration Web Service lets you create, replace, delete and update entities.

Entity Configuration Web Service overview

The Entity Configuration Web Service is a WS-I compliant SOAP/HTTP Web service that also supports the wrapped-document/literal pattern of binding. The service is declared in sconfig.wsdl. The service supports creation and management of entities, as well as validation of statements in them.

To view the WSDL document for the service, issue the following command:
http://localhost:<port>/ws/sconfig/<DataStore>?wsdl
where the host and port represent the Oracle Endeca Server, and DataStore is the name of the data store created on the server.
The service's version is listed in one of its namespaces included in the WSDL, as shown in the following example (the version in this example may not match the version of the service you have installed):
xmlns:v1_0="http://www.endeca.com/endeca-server/sconfig/1/0"
In this example, 1 is the major version; 0 is the minor version. If more than one minor version is supported, it is listed in its own namespace in the WSDL document.

For reference information on the Entity Configuration Web Service operations and for schema elements, see the Oracle Endeca Server API Reference.

Operation description

A request to the Entity Configuration Web Service depends on the operation. The operations perform actions on entities, listing them, adding and removing them, and validating them.

The effect of an Entity Configuration Web Service request that contains put operations is to add entities to the corpus of records in the Oracle Endeca Server for this data store:
  • If an entity with the specified key already exists in the corpus, it is replaced by the new entity with the same key (if the EQL statements defining the entity are valid).
  • If an entity does not exist, and if its EQL definition is valid, it is created.

After creation, each entity is represented as a single logical record in the Endeca data store. The on-disk storage of these records means that they persist across restarts of the Endeca data store, as they are loaded into the Dgraph process at start-up time.

Request

The input to the Entity Configuration Web Service depends on the operation used. It can include a key and an EQL statement that defines an entity, for put operations; it can include the key only, for deleteEntities operation; or it can include the definition of the entity, for validate operations.

Any request to the Entity Configuration Web Service can contain an optional element OuterTransactionId that specifies the ID of an outer transaction (if it has been started by the Transaction Web Service). The following statements describe the interaction of configuration requests with outer transactions:
  • If an outer transaction has been started by the Transaction Web Service, the request may be run against either the latest version of the data files inside the transaction, or against the pre-transaction version of the data files:
    • To run a request against the latest version, the OuterTransactionId element in your request must specify the ID issued by the Transaction Web Service when the transaction was started. This element must be the first element specified in your request.
    • To run against the published version (it could be the version published prior to the outer transaction, or the version published after the outer transaction has been committed or rolled back), the OuterTransactionId element must be empty or omitted.

It is incorrect to specify an outer transaction ID when an outer transaction is not in progress. All configuration requests with incorrectly specified outer transaction IDs fail with a SOAP fault.

Response

Not all operations in the Entity Configuration Web Service return data.

If the operation returns data, the response to the Entity Configuration Web Service is a results element, within which each of the submitted operations produces an element showing its own results.

If any operation does not succeed, the whole web service transaction returns a SOAP fault and none of the operations are applied. An operation may not succeed if an outer transaction has been started by a Transaction Web Service, but an incorrect ID has been specified within a request sent to the Entity Configuration Web Service.