How to Create and Update Site Terms

The process of updating site terms is almost the same as creating site terms. Both processes build an XML element structure containing the site terms and their definitions. The only difference is that if the site term does not exist, it must be created. After it is created, it can be updated using the same XML structure, but supplying different values.

The XML element structure required to either create or update a site term needs these elements and attributes.

Site Term Element	Description
Term	Root structure of the element. The Term element requires these attributes: xmlns. The namespace of the site term. This will normally be a static value of https://schemas.microsoft.com/CommerceServer/2006/03/SiteTerms. name. The name of the site term. This is the name that is to be used for any API operations on the site term. description. User-friendly description of the site term. displayName. Name to display on the screen for the site term.
Value	One or more Value elements are required to be inside the Term element to indicate which values are to be available to the site term. Each Value element requires these attributes: name. The name of the site term value. description. User-friendly description of the site term value. displayName. Name to display on the screen for the site term value.

To create or update site terms

1. Create a ProfilesServiceAgent object by connecting to the Profiles Web service.

2. Set the credentials on the ProfilesServiceAgent object.

3. Create a ProfileManagementContext object, and pass the instance of the ProfilesServiceAgent object as an argument.

4. Build an XML representation of the desired site term to create or update the site term and store it in a string variable.

5. Load the string into an XML document.

6. Convert the XML document into an XML element.

7. Call the CreateSiteTerm method on the ProfileManagementContext object, and pass it the XML element.

Example

This example creates a new site term with the name Locations. It contains two separate values for the site terms, one for US and one for UK. The following code sample first connects to the Profiles Web service, and creates a ProfileManagementContext object. Then, it calls the CreateSiteTerm method to create the site term.

try
{
    // Connect to the Profiles Web service by using the agent.
    ProfilesServiceAgent agent = new ProfilesServiceAgent("https://localhost/ProfilesWebService/ProfilesWebService.asmx");
    agent.Credentials = CredentialCache.DefaultNetworkCredentials;
    ProfileManagementContext ctxt = ProfileManagementContext.Create(agent);

    // Declare variables.
    XmlDocument profileXmlDoc = new XmlDocument();
    XmlElement siteTermXml = null;
    String Xml = "";


    // Create an XML representation of the site term.
    Xml += "  <Term xmlns='https://schemas.microsoft.com/CommerceServer/2006/03/SiteTerms' name='Locations' description='Service Locations' displayName='Locations'>";
    Xml += "      <Value name='0' description='US' displayName='US' />";
    Xml += "      <Value name='1' description='UK' displayName='UK' />";
    Xml += "  </Term>";

    // Load the site term into an XML document.
    profileXmlDoc.LoadXml(Xml);

    // Convert the XML document to an XML element.
    siteTermXml = profileXmlDoc.DocumentElement;

    // Create the site term.
    ctxt.CreateSiteTerm(siteTermXml);

    // Success!
    Console.WriteLine("Successfully created site term.");
}
catch (Exception ex)
{
    Console.WriteLine("Exception: {0}\r\nMessage: {1}", ex.GetType(), ex.ToString());
    if (ex.InnerException != null)
    {
        Console.WriteLine("\r\nInner Exception: {0}\r\nMessage: {1}", ex.InnerException.GetType(), ex.InnerException.Message);
    }
}

}

This example builds on the prior example and updates the site term named Locations. It adds two more locations, FR and ES. The following code sample first connects to the Profiles Web service and creates a ProfileManagementContext object. Then it calls the UpdateSiteTerm method to update the existing site term.

Note

If you try to update a site term that does not exist, an error will occur.

try
{
    // Connect to the Profiles Web service by using the agent.
    ProfilesServiceAgent agent = new ProfilesServiceAgent("https://localhost/ProfilesWebService/ProfilesWebService.asmx");
    agent.Credentials = CredentialCache.DefaultNetworkCredentials;
    ProfileManagementContext ctxt = ProfileManagementContext.Create(agent);

    // Declare variables.
    XmlDocument profileXmlDoc = new XmlDocument();
    XmlElement siteTermXml = null;
    String Xml = "";


    // Create an XML representation of the site term.
    Xml += "  <Term xmlns='https://schemas.microsoft.com/CommerceServer/2006/03/SiteTerms' name='Locations' description='Service Locations' displayName='Locations'>";
    Xml += "      <Value name='0' description='US' displayName='US' />";
    Xml += "      <Value name='1' description='UK' displayName='UK' />";
    Xml += "      <Value name='2' description='FR' displayName='FR' />";
    Xml += "      <Value name='3' description='ES' displayName='ES' />";
    Xml += "  </Term>";

    // Load the site term into an XML document.
    profileXmlDoc.LoadXml(Xml);

    // Convert the XML document to an XML element.
    siteTermXml = profileXmlDoc.DocumentElement;

    // Update the site term.
    ctxt.UpdateSiteTerm(siteTermXml);

    // Success!
    Console.WriteLine("Successfully updated site term.");
}
catch (Exception ex)
{
    Console.WriteLine("Exception: {0}\r\nMessage: {1}", ex.GetType(), ex.ToString());
    if (ex.InnerException != null)
    {
        Console.WriteLine("\r\nInner Exception: {0}\r\nMessage: {1}", ex.InnerException.GetType(), ex.InnerException.Message);
    }
}

}

Compiling the Code

To compile the code, you need to include these namespace directives:

using Microsoft.CommerceServer.Profiles;
using System.Xml;

See Also

Other Resources

How to Use Site Terms

Site Terms Concepts and Tasks

How to Delete Site Terms