Custom Field Types

Custom Field Types

In this topic:

• Introduction to Custom Fields
• Declaring Custom Fields
• Custom Field Data Types
• Custom Field Converters

Introduction to Custom Fields

Custom fields are special fields that typically require some kind of processing or formatting in order that they become readable or meaningful to an external consumer, or so that they comply with accepted modern standards.

For example, some applications store Boolean values in an A1 field with a value of Y representing true and a value of N representing false. When this type of field is exposed through a modern REST API it is desirable to expose the value as an actual Boolean value, and also to allow API consumers to specify a Boolean value when performing operations like CREATE or UPDATE, and have the value translated to the appropriate Y or N values.

Declaring Custom Fields

Custom fields are declared in the repository by adding special tokens that are detected and processed by the Harmony Core extensions to CodeGen. To declare a field as a custom field you must add special token in the fields user defined text or long description fields, like this:

HARMONYCORE_CUSTOM_FIELD_TYPE=YnBoolean;

This token declares that the field is a custom field of the type YnBoolean. The beginning part of the token MUST be specified in uppercase and the semi-colon following the name of the custom type is required.

Custom Field Data Types

Some types of custom field may also require a change to the data type of the associated property in the resulting data model class. This can also be achieved via a second custom token:

HARMONYCORE_CUSTOM_FIELD_DATATYPE=boolean;

Note that the data type specified should be the Synergy .NET data type of the public property that is exposed to consumers, so typical values might be things like string, int, long, boolean, DateTime, etc.

It should be noted that when you change the data type of an exposed property in this way, some of the data validation attributes that might previously have been included (attributes like {StringLength} and {Range}) will no longer be present.

Custom Field Converters

In order to actually add support for a custom field type to Harmony Core you must provide a converter class for that custom type, and the name of the converter class must follow a specific convention <CustomType>Converter. For example, the converter for a custom field type of YnBoolean must be named YnBooleanConverter.

Furthermore the converter must be a member of the Harmony.Core.Converters namespace.

Typically you should code your converters in a .NET Standard Class Library that has its Target Framework set to .NET Standard 2.1, and you will need to add a NuGet package reference to the same version of the Harmony.Core library that is being used in the rest of your solution. Then reference the library from the Services.Models project in your Harmony Core development solution.

Here is an example of the actual code for YnBooleanConverter:

import System
import Harmony.Core.Converters

namespace Harmony.Core.Converters

    ;;; <summary>
    ;;; Convert between an A1 Y/N field and a boolean.
    ;;; </summary>
    public static class YnBooleanConverter

        ;;; <summary>
        ;;; Convert from the STORAGE format to the EXPOSED format.
        ;;; Convert from a Y/N value to a Boolean value.
        ;;; </summary>
        ;;; <param name="ynValue">Y/N value to convert.</param>
        ;;; <returns>Returns the boolean equivalent of the Y/N value passed in.</returns>
        public static method Convert, boolean
            ynValue, a
        proc
            mreturn Convert.ToString(ynValue).ToUpper() == "Y"
        endmethod

        ;;; <summary>
        ;;; Convert from the EXPOSED format to the STORAGE format.
        ;;; Convert from a Boolean value to a Y/N value.
        ;;; </summary>
        ;;; <param name="booleanValue">Boolean value to convert.</param>
        ;;; <returns>Returns the Y/N value of the boolean passed in.</returns>
        public static method ConvertBack, a
            booleanValue, boolean
        proc
            mreturn booleanValue ? "Y" : "N"
        endmethod

        ;;; <summary>
        ;;; Convert from the publicly exposed value back to the storage value.
        ;;; </summary>
        public class LiteralFormatter implements ILiteralFormatter

            public virtual method FormatLiteral, string
                inputLiteral, string 
            proc
                mreturn YnBooleanConverter.ConvertBack(inputLiteral.ToLower()=="true")
            endmethod

        endclass

    endclass

endnamespace