YC.XRMapper 1.0.0-alpha

XRMapper Guide

Overview

XRMapper is a framework used to map domain models in your application to corresponding CRM entities. It simplifies the process of linking object properties to CRM attributes, managing references, and handling special field types like option sets and money values.

This guide demonstrates how to configure mappings using XRMapper with an example of a Contact entity.

XRMapper Guide

Overview

XRMapper is a framework used to map domain models in your application to corresponding CRM entities. It simplifies the process of linking object properties to CRM attributes, managing references, and handling special field types like option sets and money values.

This guide demonstrates how to configure mappings using XRMapper with an example of a Contact entity.

Key Concepts

1. Domain Model

The domain model represents the structure of your application's data. For example, the Contact class below:

2. Mapping Class

The mapping class extends XRMapper<T> and defines how properties in the domain model map to CRM attributes. For example, the ContactEntity class:

Steps to Use XRMapper

1. Define the Domain Model

Create a class that represents the entity structure in your application (e.g., Contact). This should include all fields required to interact with the CRM.

2. Extend XRMapper

Create a class that extends XRMapper<T> for your domain model. For example, ContactEntity extends XRMapper<Contact>.

3. Configure Mappings

Override the Configure method to map the domain model properties to CRM entity attributes:

Key Mapping Methods:

• LogicalName: Specifies the CRM entity logical name.
• PrimaryId: Maps the primary key.
• Attribute: Maps a property to a CRM attribute. Optionally specify the type (e.g., Options, Money, etc.).
• Reference: Maps a reference to another entity.
• ReferenceTarget: Specifies the target type for a multi-target / polymorphic reference field.

Example Walkthrough

Mapping the Contact Entity

1. Define the Contact class with properties for CRM fields.
2. Create the ContactEntity class and extend XRMapper<Contact>.
3. Configure the mappings using the IConfigurator<Contact>:

Advanced Features

1. Option Sets

To map an option set field:

2. Multi-Select Option Sets

To map a multi-select option set field:

3. Money Fields

To map a currency/money field:

4. References

To map reference fields and their targets:

Conclusion

XRMapper streamlines the process of integrating application models with CRM entities. By defining mappings in a structured way, you can reduce development time and ensure robust integrations.

Feel free to extend this guide or reach out for further clarification!

Prerequisites

• Familiarity with C# and object-oriented programming.
• Basic understanding of CRM systems and their entity structures.
• A project setup with XRMapper library installed.

Key Concepts

1. Domain Model

The domain model represents the structure of your application's data. For example, the Contact class below:

public class Contact
{
    public Guid Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    public string PhoneNumber { get; set; }
    public string Address { get; set; }
    public ContactType Type { get; set; }
    public int Type_Int { get; set; }
    public List<Color> FavoriteColors { get; set; }
    public decimal Salary { get; set; }
    public Guid AccountId { get; set; }
    public string? AccountIdName { get; set; }
}

2. Mapping Class

The mapping class extends XRMapper<T> and defines how properties in the domain model map to CRM attributes. For example, the ContactEntity class:

public partial class ContactEntity : XRMapper<Contact>
{
    public ContactEntity()
    {
    }

    public override void Configure(IConfigurator<Contact> configurator)
    {
        configurator
            .LogicalName("contact")
            .PrimaryId(c => c.Id, "contactid")
            .Attribute(c => c.FirstName, "firstname")
            .Attribute(c => c.LastName, "lastname")
            .Attribute(c => c.Email, "emailaddress1")
            .Attribute(c => c.PhoneNumber, "telephone1")
            .Attribute(c => c.Address, "address1_composite")
            .Attribute(c => c.Type_Int, "new_contacttype_int", XRMapType.Options)
            .Attribute(c => c.Type, "new_contacttype", XRMapType.Options)
            .Attribute(c => c.Salary, "new_salary", XRMapType.Money)
            .Reference(c => c.AccountId, "accountid", "account")
            .Attribute(c => c.AccountIdName, "accountid", XRMapType.Formatted);
    }
}

Steps to Use XRMapper

1. Define the Domain Model

Create a class that represents the entity structure in your application (e.g., Contact). This should include all fields required to interact with the CRM.

2. Extend XRMapper

Create a class that extends XRMapper<T> for your domain model. For example, ContactEntity extends XRMapper<Contact>.

3. Configure Mappings

Override the Configure method to map the domain model properties to CRM entity attributes:

Key Mapping Methods:

• LogicalName(string name): Specifies the CRM entity logical name.
• PrimaryId(Expression<Func<T, object>> property, string attribute): Maps the primary key.
• Attribute(Expression<Func<T, object>> property, string attribute, XRMapType? type = null): Maps a property to a CRM attribute. Optionally specify the type (e.g., Options, Money, etc.).
• Reference(Expression<Func<T, object>> property, string attribute, string targetEntity = null): Maps a reference to another entity.
• ReferenceTarget(Expression<Func<T, object>> property, string attribute): Specifies the target type for a reference field.

4. Compile and Test

Compile your project and verify the mappings using tests or integration with your CRM system.

Example Walkthrough

Mapping the Contact Entity

1. Define the Contact class with properties for CRM fields.
2. Create the ContactEntity class and extend XRMapper<Contact>.
3. Configure the mappings using the IConfigurator<Contact>:

public override void Configure(IConfigurator<Contact> configurator)
{
    configurator
        .LogicalName("contact")
        .PrimaryId(c => c.Id, "contactid")
        .Attribute(c => c.FirstName, "firstname")
        .Attribute(c => c.LastName, "lastname")
        .Attribute(c => c.Email, "emailaddress1")
        .Attribute(c => c.PhoneNumber, "telephone1")
        .Attribute(c => c.Address, "address1_composite")
        .Attribute(c => c.Type_Int, "new_contacttype_int", XRMapType.Options)
        .Reference(c => c.AccountId, "accountid", "account");
}

Advanced Features

1. Option Sets

To map an option set field:

.Attribute(c => c.Type, "new_contacttype", XRMapType.Options)

2. Multi-Select Option Sets

To map a multi-select option set field:

.Attribute(c => c.FavoriteColors, "new_favoritecolors", XRMapType.MultipleOptions)

3. Money Fields

To map a currency/money field:

.Attribute(c => c.Salary, "new_salary", XRMapType.Money)

4. References

To map single reference fields:

.Reference(c => c.AccountId, "accountid", "account")

To map multi-target / polimorphoc reference fields and their targets:

Setting the id:

.Reference(c => c.RegardingId, "regardingobjectid")

Setting the target table

.ReferenceTarget(c => c.RegardingIdTarget, "regardingobjectid")

Conclusion

XRMapper streamlines the process of integrating application models with CRM entities. By defining mappings in a structured way, you can reduce development time and ensure robust integrations.

Feel free to extend this guide or reach out for further clarification!