Loading managed attribute values

The ingestDimensionValues operation allows you to load managed values into the data store.

Within the ingestDimensionValues structure, the ingestDimensionValue element specifies the managed attribute to which each managed value belongs. If the managed attribute does not exist in the data store, the service automatically creates the managed attribute. For the default values of the managed attribute's PDR and DDR, see Default values for new attributes in the data store.

You can use the ingestDimensionValues operation to load an externally managed taxonomy (EMT) into the data store. When loaded, externally managed taxonomies are added as managed attributes and managed values.

ingestDimensionValues request

An ingestDimensionValues operation request uses this format:
<ingest:ingestDimensionValues 
      xmlns:ingest="http://www.endeca.com/MDEX/ingest/1/0" 
      xmlns:mdex="http://www.endeca.com/MDEX/XQuery/2009/09">
   <!--Zero or more repetitions:-->
   <ingest:dimensionValue dimension="dimName" displayName="dimValName"
         parentSpec="pSpec" spec="dimValId">
      <!--Zero or more repetitions:-->
      <ingest:synonym>synName</ingest:synonym>
      <!--Optional:-->
      <ingest:properties>
         <!--Zero or more repetitions:-->
         <propName type="mdex:string">propValue</propName>
      </ingest:properties>
   </ingest:dimensionValue>
</ingest:ingestDimensionValues>
Each DimensionValue element defines one managed value. The meanings of the attributes and sub-elements are:
Element/Attribute Purpose
dimension The name of the managed attribute to which the managed value belongs. The name must use the NCName format.
displayName The name for the managed value.
parentSpec Specifies the parent ID (managed attribute spec) for this managed value, If this is a root managed value, use a forward slash (/) as the ID. If this is a child managed value, specify the unique ID of the parent managed value.
spec A unique string identifier for the managed value. It is the responsibility of the client to provide the identifier for the request.
synonym Optionally defines the name of a synonym. You can add synonyms to a managed value so that users can search for other text strings and still get the same records as a search for the original managed value name. Synonyms can be added to both root and child managed values.
properties Optionally defines a property for a managed value. Managed value properties provide descriptive information about a given managed value and are intended to be used for display purposes by the application.
The following example creates the Component managed attribute and adds three managed values (Derailleur, Tire, and Michelin) to it:
<ingest:ingestDimensionValues 
      xmlns:ingest="http://www.endeca.com/MDEX/ingest/1/0" 
      xmlns:mdex="http://www.endeca.com/MDEX/XQuery/2009/09">
    <ingest:dimensionValue 
          dimension="Component" 
          displayName="Derailleur"
          parentSpec="/" 
          spec="22">
        <ingest:synonym>Chain</ingest:synonym>
        <ingest:synonym>Gear</ingest:synonym>
    </ingest:dimensionValue>
    <ingest:dimensionValue 
          dimension="Component" 
          displayName="Tire" 
          parentSpec="/" 
          spec="47">
        <ingest:properties>
            <myStrProp type="mdex:string">source:CAS</myStrProp>
        </ingest:properties>
    </ingest:dimensionValue>
    <ingest:dimensionValue 
          dimension="Component" 
          displayName="Michelin" 
          parentSpec="47" 
          spec="35" />
</ingest:ingestDimensionValues>

In the example, the Derailleur and Tire managed values are at the root of the managed attribute, while the Michelin managed value is a child of the Tire managed value. Note also that two synonyms were created for the Derailleur managed value and a string property (named myStrProp) was created for the Tire managed values.

ingestDimensionValuesResponse

An ingestDimensionValuesResponse for a successful operation would look like this example:
<ingest:ingestDimensionValuesResponse 
      xmlns:ingest="http://www.endeca.com/MDEX/ingest/1/0">
   <ingest:numDimensionsCreated>1</ingest:numDimensionsCreated>
   <ingest:numDimensionValuesCreated>3</ingest:numDimensionValuesCreated>
</ingest:ingestDimensionValuesResponse>

In the sample response, the numDimensionsCreated element shows that one managed attribute was created, while the numDimensionValuesCreated element shows that three managed values were created.

Failure response

On failure, a SOAP fault is returned. The ingest:ingestFault and ingest:errorDetail elements should contain the error that caused the failure.

For example, assume that the following request was made to create the Saddle child managed value:
<ingest:ingestDimensionValues>
    <ingest:dimensionValue dimension="Component" displayName="Saddle"
        parentSpec="58" spec="39" />
</ingest:ingestDimensionValues>
The ingest:errorDetail element would return an error similar to this:
<soapenv:Fault>
   <faultcode>soapenv:Client</faultcode>
   <faultstring>Error applying updates: Dimension value put refers to parent spec "58", 
       which does not exist in dimension "Component"
   </faultstring>
   <detail>
      <ingest:ingestFault xmlns:ingest="http://www.endeca.com/MDEX/ingest/1/0">
         <ingest:errorDetail>Error applying updates: Dimension value put refers to 
            parent spec "58", which does not exist in dimension "Component"
         </ingest:errorDetail>
      </ingest:ingestFault>
   </detail>
</soapenv:Fault>

In this example, the reason for the error is that the request refers to a non-existent parent managed value (58 in the example).