About managed attributes and their values

Managed attribute values represent specific value assignments on managed attributes in your data domain. Through managed attribute values, you can express hierarchical relationships and other useful information (such as synonyms and ranking), on record refinements in your data domain.

Typically, you use managed attribute values for these purposes:
  • To represent hierarchy information on data records. For example, a managed attribute "location" can have values for countries, such as USA and Canada, states, such as MA and NY, and cities, such as Boston and New York City. All these managed attribute values are organized in an hierarchy — they have information about themselves via a unique spec that identifies them in the Endeca Server index, and their parent managed attribute value. In other words, you can create a parent managed attribute value "USA", a child managed attribute value "MA (Massachusetts)", and a grand-child managed attribute value "Boston".
  • To hold a set of predefined values. For example, for a managed attribute "currency", you can define a limited set of values, "dollars" and "euros".
  • To hold a set of synonyms for each value. For example, you can add a synonym "Beantown" to a managed attribute value "Boston".
  • To add predefined static ranks to managed attribute values, to control how they are sorted when displayed to the end users in the front-end application, such as Studio.

You add managed attribute values before loading the source records into the data domain. Next, when you load source records that include these values (such as "MA", or "Boston"), Endeca Server recognizes them as managed attribute values, thus letting your end users navigate and search on them, utilizing their hierarchy, as well as static ranks and synonyms (if specified).

Inside the Endeca Server index for each data domain, each of the added managed attribute values, (such as "MA" and "Boston" in our example), are themselves represented as records. These records are described by the PDRs, DDRs, and Managed Attribute Value Description Records (MAVDRs) that are created in the index, when you add managed attributes and their values.

A request to add a managed attribute value record using the Configuration Web Service has this structure: 
<ns:configTransaction>
   <ns:putManagedAttributeValues>
      <ns1:mav>
         <name>?</name>
         <spec>?</spec>
         <parent>?</parent>
         <managedAttribute>?</managedAttribute>
         <synonym>?</synonym>
         <synonym>?</synonym>
         <rank>?</rank>
      </ns1:mav> 
   </ns:putManagedAttributeValues>
</ns:configTransaction>
In this structure, the spec, parent, and managedAttribute elements are required, all other elements are optional.
The following table describes each of the elements in the mav element of putManagedAttributeValues. For each of these elements, their value represents an assignment on some attribute. The corresponding attribute can belong to one of the description records (PDR, MAVDR) created in the index once you add this particular managed attribute value:
Element Type Description
name string Optional. The display name of the managed attribute value record. You define this property when adding a managed attribute value. For example, you can define a managed attribute value with the name "Boston": 
<mav><name>Boston</name>...</mav>
Inside the schema for your data records, when you create this managed attribute value, its MAVDR is created. The MAVDR gets an assignment on mdex-dimension-value_Name: 
<attribute name="mdex-dimension-value_Name" type="mdex:string">Boston</attribute>
spec string Required. A unique identifier, or a spec, of the managed attribute value record. For example, you can define a managed attribute value with the spec "bos": 
<mav>
 <spec>bos</spec>
 ...
</mav>
Inside the schema for your data records, this value, in turn, is an assignment on the mdex-dimension_my_attr_key_Spec attribute that is created when you add a DDR for the associated managed attribute with the key my_attr_key. For example, for a managed attribute with the key "location", when you create its DDR, another record is automatically created, — namely, a PDR for mdex-dimension_location_Spec. It is always created as unique and single-assign, as values on it uniquely identify managed attribute values that you will be adding. Next, when you add a managed attribute value, such as "bos", the value "bos" becomes an assignment on mdex-dimension_location_Spec: 
<attribute name="mdex-dimension_location_Spec" type="mdex:string">bos</attribute>
Note: If, when creating the DDR for the managed attribute with the key value, you do not specify your own value for its mdex-dimension-value_Spec attribute, the naming structure of the format mdex-dimension_value_Spec is used automatically by Endeca Server when it creates the PDR for the managed attribute value spec.
parent string Required. The spec of the parent managed attribute value. Only one is allowed. To continue with the example, for a managed attribute value with the spec "bos", the parent managed attribute value spec is "MA" (it must already exist, in order to be specified): 
<mav>
 <spec>bos</spec>
 <parent>MA</parent>
 ...
</mav>
Inside the schema for your data records, this value, in turn, is an assignment on the mdex-dimension_my_attr_key_Parent attribute that is created when you add a DDR for the associated managed attribute with the key my_attr_key. For example, for a managed attribute with the key "location", when you create its DDR, another record is automatically created, — namely, a PDR for mdex-dimension_location_Parent. It is always created as single-assign. Next, when you add a managed attribute value, such as "MA", the value "MA" becomes an assignment on mdex-dimension_location_Parent, for another managed attribute value, "bos": 
<attribute name="mdex-dimension_location_Parent" type="mdex:string">MA</attribute>
Note: If, when creating the DDR for the managed attribute with the key value, you don't specify your own value for its mdex-dimension-value_Parent attribute, the naming structure of the format mdex-dimension_value_Parent is used automatically by the Endeca Server, when it creates the PDR for the parent managed attribute value.
managedAttribute string Required. The key (or spec) of the managed attribute to which this managed attribute value relates. Only one is allowed. You define it when adding a managed attribute value. For example, for the value Boston (whose spec is "bos"), the managed attribute key it is associated with is "location": 
<mav>
 <spec>bos</spec>
 <managedAttribute>location</managedAttribute>
 ...
</mav>
Inside the schema for your data records, this value, "location", is a key of the managed attribute "location", in the DDR that defines this managed attribute: 
<mdex-dimension_Key>location</mdex-dimension_Key>
In the MAVDR for a managed attribute value you are adding, it becomes an assignment to the managed attribute "location": 
<attribute name="mdex-dimension-value_Dimension" type="mdex:string">location</attribute>
rank integer Optional. Static rank of the managed attribute value. Only one is allowed. This rank is an integer number according to which the Endeca Server ranks the managed attribute values within each managed attribute's hierarchy, when returning them to the end users. This rank affects the order in which values are displayed in the front-end application, such as Studio. You can optionally specify the rank, when adding a managed attribute value with the putManagedAttributeValue operation. mdex-dimension-value_Rank 
<ns1:mav>
 <spec>bos</spec>
 <rank>3</rank>
  ...
</mav>
Inside the schema for your data records, the value of rank, such as "3", becomes an assignment on the mdex-dimension-value_Rank attribute of the MAVDR for the managed attribute you are adding: 
<attribute name="mdex-dimension-value_Rank" type="mdex:integer">3</attribute>
synonym string Optional. List of one or more synonyms, for the managed attribute value. You can optionally specify one or more synonyms, when adding a managed attribute value. For example, for the value Boston, the synonyms can be "Beantown", and "the Hub": 
<ns1:mav>
 <spec>bos</spec>
 <synonym>Beantown</synonym>
 <synonym>the Hub</synonym>
 ...
</mav>
Inside the schema for your data records, the value of any synonym, such as "Beantown", becomes an assignment on the mdex-dimension-value_Synonyms attribute of the MAVDR for the managed attribute you are adding: 
<attribute name="mdex-dimension-value_Synonyms" type="mdex:string">Beantown</attribute>

To conclude, each managed attribute value record is identified by its own pair of spec and parent values that are unique to this managed attribute value. The following example illustrates how to add a managed attribute value, for a specific managed attribute.

Example

Let's consider an example where you would like to create a managed attribute "location", with a set of managed attribute values associated with it. You start by creating a managed attribute itself. Since each managed attribute requires a PDR and a DDR, you first create the PDR with the spec "location", as in this abbreviated example: 
<mdex-property_Key>location</mdex-property_Key>
Next, you create an associated DDR for this managed attribute, also with the spec "location": 
<mdex-dimension_Key>location</mdex-dimension_Key>
Once you create this DDR, Endeca Server automatically creates two additional PDR records (if you do not specify your own values for them in the DDR): 
<mdex-property_Key type="mdex:string" xmlns="">mdex-dimension_location_Parent</mdex-property_Key>
<mdex-property_Key type="mdex:string" xmlns="">mdex-dimension_location_Spec</mdex-property_Key>
Next, you can add three managed attribute values, using the putManagedAttributeValues operation of the Configuration Web Service (which will create a MAVDR for each added managed attribute value, internally): 
<ns:configTransaction>
 <ns:putManagedAttributeValues>
  <ns1:mav>
     <name>USA</name>
     <spec>US</spec>
     <parent>/</parent>
     <managedAttribute>location</managedAttribute>
  </ns1:mav> 
  <ns1:mav>
     <name>Massachusetts</name>
     <spec>MA</spec>
     <parent>US</parent>
     <managedAttribute>location</managedAttribute>
  </ns1:mav> 
  <ns1:mav>
     <name>Boston</name>
     <spec>bos</spec>
     <parent>MA</parent>
     <managedAttribute>location</managedAttribute>
  </ns1:mav> 
 </ns:putManagedAttributeValues>
</ns:configTransaction>
(For simplicity, namespaces are omitted in this example. They represent xmlns:ns="http://www.endeca.com/MDEX/config/services/types/3/0" and xmlns:ns1="http://www.endeca.com/MDEX/config/XQuery/2009/09", respectively.)

When a managed attribute value is created, Endeca Server "attaches" it to a specific managed attribute. In this example, for a managed attribute "location", when you create a managed attribute value "Boston", the managed attribute's value spec, "bos", is assigned on the mdex-dimension_location_Spec that was created automatically when the "location" managed attribute was created, by adding its DDR. Similarly, the managed attribute's value parent ,"MA", is assigned on the mdex-dimension_location_Parent.

Note: Ranks and synonyms are omitted in this example. For information on how to add synonyms, see Adding managed attribute values. For information on how to add ranks, see Adding and updating ranks.