Adding managed attribute values

Typically, you add more than one managed attribute value. To add a set of them, you first define a managed attribute with which the values will be associated. Next, you add the managed attribute values, associating them with the managed attribute.

The procedure in this topic utilizes an example to illustrate how to add a set of managed attribute values that define a hierarchy. It builds an hierarchy of managed attribute values for the managed attribute "location", by adding parent managed attribute value "USA", followed by managed attribute values "Massachusetts", and "New York State", and their descendant managed attribute values "Boston", and "New York".

Note: You can add managed attribute values using two different web services: Configuration Web Service and Data Ingest Web Service. This topic discusses adding them with putManagedAttributeValues of the Configuration Web Service. Since, after they are added, managed attribute values are represented as records in the Endeca Server index for the data domain, you can also use the Data Ingest Web Service to add them as non-data records, before adding any data records. For information, see the Oracle Endeca Server Data Loading Guide.

The examples of Configuration Web Service requests in this topic are abbreviated and do not show namespaces. They use the following namespaces: xmlns:ns="http://www.endeca.com/MDEX/config/services/types/3/0" and xmlns:ns1="http://www.endeca.com/MDEX/config/XQuery/2009/09".

Before you add one or more managed attribute values, note the following requirements:

A managed attribute must exist in the index of the data domain. This means that its associated PDR and DDR must be created. Note that if a DDR does not exist, you can create it in the same request in which you are adding managed attribute values.
When creating a DDR (as shown in the procedure in this topic), you can omit specifying the values for mdex-dimension-value_Parent and mdex-dimension-value_Spec, as these properties on the DDR are optional. If you do not explicitly provide values for them in the putDimension request that creates a DDR for the managed attribute, Endeca Server automatically creates them and assigns their names. For example, for a managed attribute "location", if parent and spec are not specified, mdex-dimension_location_Parent, and mdex-dimension_location_Spec are created. If you specify these properties, you can provide your own names. Whether or not you specify these properties, once you add a DDR, Endeca Server creates two PDR records in the index, for each of these properties. These two description records represent non-data records, and are needed to provide the internal structure that uniquely identifies each added managed attribute value record (via its value on the spec), and also defines the hierarchy (via its values on both the spec and the parent attributes).
When creating the top-most managed attribute value for the managed attribute, specify the sign "/" for its parent managed attribute value. This is because, when a managed attribute is created, the spec for the root managed attribute value is also created automatically in the index, and its value is "/".
When you add a managed attribute value with putManagedAttributeValues, its name, synonyms, and rank attributes are optional. All other parameters (spec, parent managed attribute value, and managed attribute spec) are required.
You can optionally add its synonyms, which Endeca Server will use in searches. Since it is not possible to change or update synonyms on already added managed attribute values, plan which synonyms you are going to require. If you later need to add more synonyms, delete the existing managed attribute (this deletes all associated managed attribute values), and replace it with new values and synonyms.
You can update a managed attribute value with a new name. In this case, when you use the putManagedAttributeValues for an existing value but specify a new name, the value is updated with this name.
You can also add static ranks (and update them) to the managed attribute values. Ranks are not included in the examples in this topic. For information on adding them, see Adding and updating ranks.
You can add more than one managed value attribute in one operation. However, if any of the values are specified incorrectly, causing Endeca Server to issue an error, the entire Configuration Web Service request fails and no values are added.

To add a set of managed attribute values:

In soapUI or another tool for issuing web service requests, access the Configuration Web Service, as in this example:
```
http://localhost:7001/endeca-server/ws/config/data_domain?wsdl
```
where localhost and 7001 are the Endeca Server host and port, and data_domain is the name of the data domain.
Start by creating a structure needed for the managed attribute.
1. Create a PDR "location":
```
<ns:configTransaction>
  <ns:putProperties>
    <ns1:record>
      <mdex-property_DisplayName>location</mdex-property_DisplayName>
      <mdex-property_IsSingleAssign>false</mdex-property_IsSingleAssign>
      <mdex-property_IsTextSearchable>true</mdex-property_IsTextSearchable>
      <mdex-property_IsUnique>false</mdex-property_IsUnique>
      <mdex-property_IsPropertyValueSearchable>true</mdex-property_IsPropertyValueSearchable>
      <mdex-property_Key>location</mdex-property_Key>
      <mdex-property_TextSearchAllowsWildcards>true</mdex-property_TextSearchAllowsWildcards>
      <mdex-property_Type>mdex:string</mdex-property_Type>
    </ns1:record>
  </ns:putProperties>
</ns:configTransaction>
```
  This creates the standard attribute "location", which is needed to create a managed attribute.
  
  Notice that in this example, the value for the mdex-property_IsSingleAssign property is false. The setting of false is required if you want to assign multiple values on the associated managed attribute.
2. Create a DDR "location":
```
<ns:configTransaction>
  <ns:putDimensions>
    <ns1:record>
      <mdex-dimension_Key>location</mdex-dimension_Key>
      <mdex-dimension_EnableRefinements>true</mdex-dimension_EnableRefinements>
      <mdex-dimension_IsDimensionSearchHierarchical>true</mdex-dimension_IsDimensionSearchHierarchical>
      <mdex-dimension_IsRecordSearchHierarchical>true</mdex-dimension_IsRecordSearchHierarchical>
    </ns1:record>
  </ns:putDimensions>
</ns:configTransaction>
```
  This creates the managed attribute "location" to which you are adding a set of managed attribute values.
  This request also creates two PDRs in the index for spec and parent, as evident if you run listProperties. Namely, this creates:
```
<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>
```
  - The mdex-dimension_location_Spec is the name of the attribute whose assignment is the spec of the managed attribute value you are adding, and it uniquely identifies the managed attribute value record.
  - The mdex-dimension_location_Parent is the name of the attribute whose assignment is the spec of the parent managed attribute value, for this managed attribute value.
  The assignments on spec and parent attributes are important — this is the mechanism by which the Endeca Server creates managed attribute values as records, inside its index for the data domain.
  If you do not include these two attributes in the request for creating a DDR (as shown in the example in step 2.b), the names of the spec and parent PDRs are assigned automatically, by appending the name of the current managed attribute ("location"). However, if you explicitly include them in the request, you can provide your own names, as in the following alternative example. It shows how to add a managed attribute "location" with explicitly specified loc_parent and loc_spec values for these two attributes:
```
<ns:configTransaction>
  <ns:putDimensions>
    <ns1:record>
      <mdex-dimension_Key>location</mdex-dimension_Key>
      <mdex-dimension-value_Parent>loc_parent</mdex-dimension-value_Parent>
      <mdex-dimension-value_Spec>loc_spec</mdex-dimension-value_Spec>
      <mdex-dimension_EnableRefinements>true</mdex-dimension_EnableRefinements>
      <mdex-dimension_IsDimensionSearchHierarchical>true</mdex-dimension_IsDimensionSearchHierarchical>
      <mdex-dimension_IsRecordSearchHierarchical>true</mdex-dimension_IsRecordSearchHierarchical>
    </ns1:record>
  </ns:putDimensions>
</ns:configTransaction>
```
  Note that loc_parent must be of type string, be single-assign and have no assignments from data records. The loc_spec attribute should be of type spring, unique, single-assign and have no assignments from data records.
  This example is not used in the rest of this procedure.
  
  Now that you have added a managed attribute "location", you can start adding managed attribute values to it, organized in a hierarchy.
Add the managed attribute value record, "USA":
```
<ns:configTransaction>
  <ns:putManagedAttributeValues>
    <ns1:mav>
      <name>USA</name>
      <spec>US</spec>
      <parent>/</parent>
      <managedAttribute>location</managedAttribute>
    </ns1:mav> 
  </ns:putManagedAttributeValues>
</ns:configTransaction>
```
Notice that because this is going to be the top-most value in the hierarchy, it includes "/" as its parent managed attribute value. This sign, "/", must be specified for the root managed attribute value. Additionally, the associated managed attribute for this value is "location". It must exist before you create a managed attribute value.

In a similar way, add the "Massachusetts" and "New York State" managed attribute values, under the parent value "USA", for the same managed attribute "location":

<ns:configTransaction>
  <ns:putManagedAttributeValues>
    <ns1:mav>
      <name>Massachusetts</name>
      <spec>MA</spec>
      <parent>US</parent>
      <managedAttribute>location</managedAttribute>
    </ns1:mav>
    <ns1:mav>
      <name>New York State</name>
      <spec>NY</spec>
      <parent>US</parent>
      <managedAttribute>location</managedAttribute>
    </ns1:mav>  
  </ns:putManagedAttributeValues>
</ns:configTransaction>

Add the managed attribute values "Boston" and "New York City", under their respective parent managed attribute values "Massachusetts" and "New York State", for the same managed attribute "location":

<ns:configTransaction>
  <ns:putManagedAttributeValues>
    <ns1:mav>
      <name>Boston</name>
      <spec>bos</spec>
      <parent>MA</parent>
      <managedAttribute>location</managedAttribute>
      <synonym>BeanTown</synonym>
      <synonym>The Hub</synonym>
    </ns1:mav>
    <ns1:mav>
      <name>New York city</name>
      <spec>nyc</spec>
      <parent>NY</parent>
      <managedAttribute>location</managedAttribute>
      <synonym>NYC</synonym>
      <synonym>the Big Apple</synonym>
    </ns1:mav>  
  </ns:putManagedAttributeValues>
</ns:configTransaction>

Alternatively, you could also add all managed attribute values (for country, states and cities) in a single request.

Notice that each of the managed attribute values has two synonyms. For information on synonyms, see Summary of operations.

Now that you have created these managed attribute values, you can list them with listManagedAttributeValues operation of the Configuration Web Service.