Examples of requests with the Entity Configuration Web Service

This topic includes examples of requests for listing, adding, deleting, and validating entities.

Listing entities example

The following example of the request lists all entities that are present in the corpus:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns="http://www.endeca.com/endeca-server/sconfig/1/0">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:listEntities>
      </ns:listEntities>
   </soapenv:Body>
</soapenv:Envelope>

The response to this request returns a list of entities that are already added, including the base entity added by the Oracle Endeca Server for each PDR describing an existing attribute in your data store.

For example, the following abbreviated response lists the Transactions entity:
<listEntitiesResponse xmlns="http://www.endeca.com/endeca-server/sconfig/1/0">
<semanticEntity key="Transactions" displayName="Transactions">
<definition>/*Calculate Total Sales respecting Navigation*/ 
DEFINE GlobalSales as select sum(FactSales_SalesAmount) AS TotalSales Group; 
DEFINE Transactions AS SELECT FactSales_SalesAmount AS "FactSales_SalesAmount", 
DimReseller_ProductLine AS "DimReseller_ProductLine", 
DimSalesTerritory_SalesTerritoryCountry AS "DimSalesTerritory_SalesTerritoryCountry", 
DimDate_FiscalYear AS "DimDate_FiscalYear", 
ProductSubcategoryName AS "ProductSubcategoryName", 
DimReseller_ResellerName AS "DimReseller_ResellerName", 
DimEmployee_FullName AS "DimEmployee_FullName", 
ProductCategoryName AS "ProductCategoryName", 
DimDate_FiscalSemester AS DimDate_FiscalSemester, 
DimDate_FiscalQuarter AS DimDate_FiscalQuarter, 
DimSalesTerritory_SalesTerritoryRegion AS DimSalesTerritory_SalesTerritoryRegion, 
DimDate_FiscalYear*100+DimDate_MonthNumberOfYear as "Year-Month"
</definition><description>Sales Transaction Line Items</description>
...
</semanticEntity>
The Transactions entity contains the following attributes:
<attributes>
<semanticAttribute name="DimDate_FiscalQuarter" displayName="Fiscal Quarter" 
datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="DimDate_FiscalSemester" displayName="Fiscal Semester" 
datatype="mdex:int" isDimension="true"/>
<semanticAttribute name="DimDate_FiscalYear" displayName="Fiscal Year" 
datatype="mdex:int" isDimension="true"/>
<semanticAttribute name="DimEmployee_FullName" displayName="Employee Name" 
datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="DimReseller_ProductLine" displayName="Product Line" 
datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="DimReseller_ResellerName" displayName="Reseller Name" 
datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="DimSalesTerritory_SalesTerritoryCountry" 
displayName="Sale Country" datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="DimSalesTerritory_SalesTerritoryRegion" 
displayName="Sales Region" datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="FactSales_SalesAmount" displayName="Sales Amount" 
datatype="mdex:double" isDimension="false"/>
<semanticAttribute name="ProductCategoryName" displayName="Product Category" 
datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="ProductSubcategoryName" 
displayName="Product Subcategory" datatype="mdex:string" isDimension="true"/>
<semanticAttribute name="Year-Month" displayName="Year - Month" 
datatype="mdex:long" isDimension="true"/>
</attributes>
It also contains the following metrics:
<metrics>
  <metric name="SalesShare" displayName="Sales Share" 
    datatype="mdex:double" 
    description="Ratio of Total Sales of the Group to Total Sales of All Groups">
   <definition>sum(FactSales_SalesAmount)/GlobalSales[].TotalSales
   </definition>
  </metric>
</metrics>

Validating an entity example

Before adding an entity, it is useful to validate the syntax of the EQL statements in the entity definition.

To validate an entity, issue a request either with ValidateEntity, which validates a single entity, or with ValidateEntities, specifying the entities inside the semanticEntity elements. The following abbreviated example illustrates the ValidateEntity request:
<ns:validateEntity>
   <ns:semanticEntity key="Sales" displayName="Sales">
   ...
   </ns:semanticEntity>
</ns:validateEntity>
If the request validates successfully, validateEntityResponse does not contain errors.

Adding an entity example

You can add one entity using a putEntity operation, or add multiple entities using putEntities.

In this abbreviated example, a putEntities operation is used in a request to add one entity, Sales, with two metrics, TotalSales and AvgSales:
<ns:putEntities><ns:semanticEntity key="Sales" displayName="Sales">
<ns:definition>
   DEFINE Sales AS SELECT FactSales_SalesAmount 
   AS SalesAmount, DimReseller_ProductLine AS ProductLine, 
   DimSalesTerritory_SalesTerritoryCountry AS SalesTerritoryCountry, 
   DimDate_FiscalYear AS FiscalYear, 
   FactSales_SalesOrderNumber AS SaleOrderNumber
</ns:definition>
<ns:attributes>
	<ns:semanticAttribute name="SalesAmount" displayName="Sales Amount" datatype="mdex:double" 
 isDimension="false"/>
	<ns:semanticAttribute name="ProductLine" displayName="Product Line" datatype="mdex:string" 
 isDimension="true"/>
	<ns:semanticAttribute name="SalesTerritoryCountry" displayName="Sales Territory Country" 
 datatype="mdex:string" isDimension="true"/>
	<ns:semanticAttribute name="FiscalYear" displayName="Year" datatype="mdex:int" 
 isDimension="true" />
	<ns:semanticAttribute name="SaleOrderNumber" displayName="Sale Order Number" 
 datatype="mdex:string" isDimension="false"/>
</ns:attributes>
  <ns:metrics>
    <ns:metric name="TotalSales" displayName="Total Sale" datatype="mdex:double">
       <ns:definition>sum(SalesAmount)</ns:definition>
    </ns:metric>
	   <ns:metric name="AvgSales" displayName="Average Sale" datatype="mdex:double">
       <ns:definition>avg(SalesAmount)</ns:definition>
    </ns:metric>
  </ns:metrics>
 </ns:semanticEntity>
</ns:putEntities>
The abbreviated example response from the Entity Configuration Web Service informs you how many entities were created or replaced:
<putEntitiesResponse xmlns="http://www.endeca.com/endeca-server/sconfig/1/0">
  <entityAdditionInformation numEntitiesAdded="1" numEntitiesReplaced="0"/>
</putEntitiesResponse>

You cannot add or replace the base entity.

Deleting an entity example

To delete one or more entities, issue a request with the deleteEntities operation, specifying keys for one ore more entities you would like to delete, as in this abbreviated example:
<ns:deleteEntities>
   <ns:semanticEntityKey key="Sales"/>
</ns:deleteEntities>
The response indicates the number of entities deleted:
<deleteEntitiesResponse xmlns="http://www.endeca.com/endeca-server/sconfig/1/0">
   <numEntitiesDeleted>1</numEntitiesDeleted>
</deleteEntitiesResponse>

You cannot delete the base entity.