Skip to content

Field Map

Jump to bottom
jayoungers edited this page Oct 12, 2018 · 4 revisions

A FieldMap is used to map a single field in your Source object:

fieldmap_basic

Fieldmap has several optional hooks, the first of which is PostMap, which will run whenever the target field has changed:

postmap_defined

Like all of the hooks, you can also define the method inline anonymously:

postmap_anonymous

Common usages for PostMap would be enforcing validation and triggers (i.e. 'if this field changes then this field should be updated like so' or 'if this field changes the values should be logged'), and also any time you need to handle properties in your source that do not exist as an individual field on the target (i.e. Collections, calculated fields, etc). In those cases, PostMap will run every time:

fieldmap_postmap_indirect

A Converter is a hook that will take a source field (that is usually of a different type than the target field), and convert it to the target type. This is commonly used in situations where your source field is itself an object, and the target field is an entity id. Another common use case would be when both fields are strings, but you need to ensure the value is of a certain format.

fieldmap_converter

The Converter will run anytime the passed in value is not null. If the method returns a Value it will be mapped to the target, if a FailureReason is returned the map will stop processing.

Required and Enabled are hooks that control the flow of when and how the map is executed.

Depending on how you've setup the mapper, it will automatically handle Required fields; however, there will likely be situations where your data model indicates a field as optional, but you need to treat it as required in certain contexts.

Additionally, you may have fields that you only want processed in certain situations (i.e. only certain users can change the value, etc).

For example, let's add a new Url property to our Blog object:

fieldmap_required_enabled

Here we're saying the field is required during any update (entity is not new), but it's only enabled for newer blogs (id greater than 100).

Generally, an Entity's child entities should be handled with their own Mapper; however, for simple collections (such as strings), it may make sense to handle those at the parent Entity level. You can handle these collections in one of two ways (or both):

mapper.AddMap(vm => vm.Tags).HasPostMap(PostMapTagsCollection);
mapper.AddMap(vm => vm.Tags).IsCollectionItem().HasPostMap(PostMapIndividualTag);

Where the first map deals with the entire collection, which would map to a JsonPatch such as:

[{ "operation": "replace", "path": "Tags", "value": ["A", "B", "C"]}]

And the second map handles individual updates, such as:

[{ "operation": "remove", "path": "Tags/A"}]

How you choose to handle collections in your API is entirely up to your particular use case.

The last setting of a FieldMap is the Label. The label does not impact mapping in any way, but is intended to help with validation messages.

By default, the Label will be the name of the last property of the source, with spaces added prior to capitalized letters: the map of Address.PostalCode would have a label of Postal Code.

This default can be overwritten like so:

fieldmap_label

Concepts

PatchMap Library

Examples

Clone this wiki locally