Mapping Page Properties to Occurrences

Top  Previous  Next

The TMCore EPiServer Module also allows the administrator to map page properties to occurrence values, so that when an editor updates a property on the page an occurrence is created on the topic for the page containing either the value of the page property, or a derivation of it.

The mappings are specified in the web.config file using a new configuration section. At the top of the web.config file declare the following configuration section:

<sectionGroup name="TMCoreEPiServerModule">

  <section name="OccurrenceMappings" 

           allowLocation="false" 

           type="NetworkedPlanet.EPiServerModule.FieldMapper.ConfigurationSectionHandler, NetworkedPlanet.EPiServerModule, Culture=neutral, PublicKeyToken=da294bc4e1ae447d"/>

</sectionGroup>

Then as a direct child of the <configuration> top-level element add the following:

<TMCoreEPiServerModule>

  <OccurrenceMappings>

  </OccurrenceMappings>

</TMCoreEPiServerModule>

Within the <OccurrenceMappings> element you may define individual mappings in the following format:

<mapping

  pageTypeName="epiPageTypeName"

  pageFieldName="epiPropertyName"

  occurrenceTypeSI="subjectIdentifier"

  occurrenceData="resource|value"

  addOnPublish="true|false"

  serializerType="typeName"

/>

<mapping> elements may not be nested. The attributes are interpreted as follows:

Attribute Name

Attribute Description

Required/Default

Example values

pageTypeName

Specifies the name of the an EPiServer Page Type. This mapping will apply only to this page type.

This value is required, there is no default. If not specified, or invalid then this mapping will be ignored.

Person

pagePropertyName

Specifies the name of the page property that will be stored in the occurrence.

This value is required, there is no default. If not specified, or invalid then this mapping will be ignored.

Photo

Age

occurrenceTypeSI

The subject identifier of an existing occurrence type that will be used to type the occurrence created for this mapping.

This value is required, there is no default. If not specified, or invalid then this mapping will be ignored.

http://psi.networkedplanet.com/occType/Photo

occurrenceData

Specifies whether the occurrence data stored should be stored as a value or a resource (URI). To specify a resource set this to the word resource (case insensitive), for all other values a value occurrence is created.

This value is not required, the default behaviour is to store the property data as a value occurrence.

resource

value

addOnPublish

Specifies when the occurrence value is to be updated. If true (case insensitive) then the occurrence will only be update at the point of publication. Otherwise, the occurrence will be created as soon a a value is present for the property, and will be updated whenever an editor updates the page.

This value is not required, the default behaviour is to update the occurrence whenever the page is saved.

true

false

serializerType

Specifies a fully qualified type name that will be used to serialize the value to the occurrence. This is useful when some processing or formatting needs to be. Instances of the type specified must implement the NetworkedPlanet.EPiServerModule.FieldMapper.IOccurrenceValueSerializer interface.

This value is not required, the default behaviour is to serialize the result of calling on the property value: PropertyData.Value.ToString(). If this results in the empty string, or null, then the occurrence is not created.

NetworkedPlanet.EPiServerModule.FieldMapper.DefaultSerializer,NetworkedPlanet.EPiServerModule,Culture=Neutral,PublicKeyToken=da294bc4e1ae447d

Attributes of the mapping element for defining occurrence mappings

If an invalid mapping is detected, then an error message will be printed out in the EPiServer log. No other cues are given to the administrator that a mapping has failed (i.e. if a mapping fails then EPiServer will continue to function normally).

Example Mappings

The following is a very simple mapping that makes use of all the defaults to create a value occurrence for the value of the name property on any instance of page Person.

 <mapping

   pageTypeName="Person"

   pageFieldName="name"

   occurrenceTypeSI="http://psi.networkedplanet.com/occurrences/name"

 />

The following mapping shows how you can use a custom serializer to process an occurrence value. This serialize takes a date of birth field for a person and stores in the topic map the name of the season that user was born. The code for the serializer is shown below:

 <mapping

   pageTypeName="Person"

   pageFieldName="dateofbirth"

   occurrenceTypeSI="http://psi.networkedplanet.com/occurrences/seasonBorn"

   addOnPublish="false"

   serializerType="NetworkedPlanet.EPiServerModule.FieldMapper.SeasonBornSerializer,NetworkedPlanet.EPiServerModule, Culture=Neutral, PublicKeyToken=da294bc4e1ae447d"

 />

 

using System;

using EPiServer.Core;

namespace NetworkedPlanet.EPiServerModule.FieldMapper

{

    /// <summary>

    /// Converts the <see cref="DateTime"/> property passed to the name of a season.

    /// </summary>

    public class SeasonBornSerializer : IOccurrenceValueSerializer

    {

        /// <summary>

        /// Serializes a property value to be serialized to a string in the form of an occurrence.

        /// </summary>

        /// <param name="page">The page containing the property.  This is included in case the occurrence value needs derivation from other page properties.</param>

        /// <param name="property">The property that is being serialized.</param>

        /// <returns>A string value that will be placed in to the occurrence.</returns>

        public string Serialize(PageData page, PropertyData property)

        {

            string season = String.Empty;

            if (property.Value!=null)

            {

                DateTime dt = (DateTime) property.Value;

                switch(dt.Month)

                {

                    case 12:

                    case 1:

                    case 2:

                        season = "Winter";

                        break;

                    case 3:

                    case 4:

                    case 5:

                        season = "Spring";

                        break;

                    case 6:

                    case 7:

                    case 8:

                        season = "Summer";

                        break;

                    case 9:

                    case 10:

                    case 11:

                        season = "Autumn (Fall)";

                        break;

                }

            }

            return season;

        }

    }

}

As you can see from the code, if the value for the month cannot be parsed (for example, because no date has been specified), then the empty string is returned, which is equivalent to returning null, which instructs the TMCore EPiServer Module to not create an occurrence (or remove an existing one).

Restrictions & Caveats

DO NOT use different values for addOnPublish when using the same occurrence type and same page type.

An example of this would be:

<mapping

   pageTypeName="Person"

   pageFieldName="firstName"

   occurrenceTypeSI="http://psi.networkedplanet.com/occurrences/name"

   addOnPublish="false"

 />

<mapping

   pageTypeName="Person"

   pageFieldName="secondName"

   occurrenceTypeSI="http://psi.networkedplanet.com/occurrences/name"

   addOnPublish="true"

 />

Here, the mapping is trying to instruct the TMCore EPiServer Module to update the occurrence for someone's first name whenever the page is saved, but only update their last name when the page is published. This will not work and you will observe the following effect:

1.When the page is saved, things appear to work; the firstName occurrence will appear in the topic map.
2.When the page is published, things still appear to work, the secondName occurrence will appear in the topic map.
3.When the firstName is changed this is where things break. Instead of updating the old occurrence value, a new occurrence will be created each time the property is updated.
4.When the page is published all occurrences are reset and things will be back to normal.

This happens because the TMCore EPiServer Module can't tell whether an occurrence on the topic is meant to be there or not. When the page is saved the TMCore EPiServer Module needs a way to ignore occurrences that are only meant to be updated on publish (i.e. not update them). When a page property is updated the old value of the property is not available, therefore it is not possible to find the occurrence that was created for the old values -  the best we can do if look for an occurrence of the correct type. If the occurrence created with addOnPublish=false has the same type as the occurrence created with addOnPublish=true the TMCore EPiServer Module cannot determine whether an existing occurrence is the old value of the "secondName" property or if it is an old value of the "firstName" property that should be overwritten.

To work around this either:

1.Use a different occurrence type for the mappings or
2.Set the occurrence types to both update on edit or update on publish.