Walkthrough: Customizing Microsoft Dynamics 365 for Sales Integration in Dynamics NAV

  • Article

This walkthrough introduces customizing the integration of Dynamics NAV and Microsoft Dynamics 365 for Sales. The walkthrough will guide you through setting up integration of campaigns in Dynamics NAV and campaigns in Microsoft Dynamics 365 for Sales.

The customization in this walkthrough is done entirely in Dynamics NAV, and does not describe how to modify your Microsoft Dynamics 365 for Sales solution, such as adding or modify entities and forms.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics 365 for Sales, including the following:

    • Campaign entity.

    • URL of the Microsoft Dynamics 365 for Sales Server.

    • User name and password of a user account that has full permissions to add and modify entities.

  • Dynamics NAV, including the following:

    • CRONUS International Ltd. demonstration database.

    • Microsoft Dynamics 365 for Sales integration enabled, including the default synchronization setup and a working connection from Dynamics NAV to Microsoft Dynamics 365 for Sales.

      For more information, see How to: Set Up a Microsoft Dynamics 365 for Sales Connection.

    • Microsoft Dynamics NAV Development Environment.

    • Microsoft Dynamics NAV Development Shell.

About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating an integration table object in Dynamics NAV for mapping a Microsoft Dynamics 365 for Sales entity to a Dynamics NAV record type (table).

  • Using a Microsoft Dynamics 365 for Sales integration table as source of a Dynamics NAV page to display Microsoft Dynamics 365 for Sales entity records.

  • Creating a page for coupling Microsoft Dynamics 365 for Sales entity records to Dynamics NAV table records.

  • Creating an integration table and field mappings between a Dynamics NAV table and an integration table for Microsoft Dynamics 365 for Sales entity.

  • Using events to develop custom code to transform data when synchronizing between Dynamics NAV and Microsoft Dynamics 365 for Sales.

Creating an Integration Table in Dynamics NAV for the Dynamics 365 for Sales Entity

To integrate data from a Microsoft Dynamics 365 for Sales entity into Dynamics NAV, you must create a Dynamics NAV table object that is based on the Microsoft Dynamics 365 for Sales entity, and then import the new table into the Dynamics NAV database. For this walkthrough, you will create a Dynamics NAV table object for the Microsoft Dynamics 365 for SalesCampaign entity. This table describes the schema of the Microsoft Dynamics 365 for Sales entity in Dynamics NAV database. The table can contain all or some of the fields from the Microsoft Dynamics 365 for Sales entity. However, if you intend to write back to Microsoft Dynamics 365 for Sales, you should include all fields in the table.

Apart from creating a table object for the entity, you must also create a table object for any relationships that the entity has. For example, the Campaign entity has a relationship to the ModifiedOn and CreatedBy fields of the Systemuser entity. Therefore, you will also have to create a Dynamics NAV table for this entity as well. However, the default Microsoft Dynamics 365 for Sales integration in Dynamics NAV already includes the integration table 5340 CRM Systemuser for the Systemuser entity. Therefore, you will only have to create the table object for the Systemuser entity to establish the relationships; you do not have to import this table into the Dynamics NAV database.

To create the integration table for the Microsoft Dynamics 365 for Sales Campaign entity

  1. Open the Microsoft Dynamics NAV Development Shell.

  2. At the command prompt, run the New-NAVCrmTable cmdlet as shown in the following example. Include parameters that specify the Microsoft Dynamics 365 for Sales Server URL, the logical names of the Microsoft Dynamics 365 for SalesSystemuser and Campaign entities, the ID and name of the corresponding business data table objects in Dynamics NAV, and the path in which to store the generated text files for the table objects.

    New-NAVCRMTable –CRMServer MyOrg.Crm4.Dynamics.Com –EntityLogicalName systemuser,campaign –ObjectId 5340,50001 –Name “CRM Systemuser”,“CRM Campaign” –OutputPath c:\CRMObjects

    Replace MyOrg.Crm4.Dynamics.Com with the URL to your Microsoft Dynamics 365 for Sales Server. Replace c:\CRMObjects with the path on your computer or network where you want to save the .txt files for the created tables.

  3. When prompted, enter credentials of the Microsoft Dynamics 365 for Sales user account.

    The process for creating the tables starts. When the process is completed, the output path contains the files TAB5342.txt and TAB50001.txt. The TAB50001.txt contains the description of the integration table 50001 CRM Campaign. These tables are set to the type CRM, as specified by the TableType Property.

  4. In the Microsoft Dynamics NAV Development Environment, import the TAB50001.txt into the Dynamics NAV database to add the integration table 50001 CRM Campaign, and then compile the new object.

    You can compile the object by using the development environment or by using finsql.exe. For more information, see Importing and Exporting Objects.

Creating a Page for Displaying Dynamics 365 for Sales Data

For scenarios where you want to view Microsoft Dynamics 365 for Sales data for a specific entity, you can create a page object that uses the integration table for the Microsoft Dynamics 365 for Sales entity as its source. For example, you might want to have a page that displays a list of the current records in a Microsoft Dynamics 365 for Sales entity. In this walkthrough, you will create a list page that uses table 50001 CRM Campaigns as its source.

To create a list page to display Dynamics 365 for Sales campaigns

  1. In development environment, add a new List page.

  2. Set the source table to the integration table 50001 CRM Campaign.

  3. Add the table fields that you want to display on the page.

  4. Save and compile the page. For purposes of this walkthrough, give the page the name CRM Campaign List and ID 50001.

  5. Run the page to view the Microsoft Dynamics 365 for Sales campaign list.

Enabling Coupling between Dynamics 365 for Sales Campaigns and Dynamics NAV Campaigns

To establish a relationship between a Dynamics NAV table record and a Dynamics 365 for Sales entity record, you create a coupling. A coupling consists of the primary ID (typically a GUID) from Dynamics 365 for Sales record and the Integration ID (GUID) from Dynamics NAV.

To enable users to create couplings between records in the two systems, you implement a coupling page in Dynamics NAV for the Microsoft Dynamics 365 for Sales entity. The coupling page provides the user interface that users can use to couple a Dynamics NAV record to a Microsoft Dynamics 365 for Sales record. The default Microsoft Dynamics 365 for Sales integration includes several coupling pages. To create a coupling page for Microsoft Dynamics 365 for Sales Campaigns, you will use page 5241 CRM Coupling Customer and adapt it the campaign integration. The coupling page that you set up will use the integration table 50001 CRM Campaign to retrieve campaign data from Microsoft Dynamics 365 for Sales. It will use page 50001 CRM Campaign List that you created previously to display a list of the campaigns from which to choose.

Before you create the coupling page, you must enable integration records for Dynamics NAV table that will be used for integration with Microsoft Dynamics 365 for Sales, in this case, table 5071 Campaign. After you create the coupling page, you will add actions on the campaign card and list pages that open the coupling page. You will also have to modify codeunit 5331 CRM Coupling Management.

To enable integration records on the Dynamics NAV Campaign table

  1. In development environment, open codeunit 5150 Integration Management.

  2. In the IsIntegrationRecord trigger, add the code DATABASE::Campaign to the database list as illustrated in the following code example:

    EXIT(TableID IN  
  [DATABASE::Campaign,  
   DATABASE::Resource,  
   DATABASE::"Payment Terms",  
   DATABASE::"Shipment Method",  
...

  3. In the CreateIntegrationPageList trigger, add the code AddToIntegrationPageList(PAGE::"Campaign Card",DATABASE::Campaign,TempNameValueBuffer,NextId); as illustrated in the following code example:

    AddToIntegrationPageList(PAGE::"Contact Card",DATABASE::Contact,TempNameValueBuffer,NextId);  
AddToIntegrationPageList(PAGE::"Countries/Regions",DATABASE::"Country/Region",TempNameValueBuffer,NextId);  
AddToIntegrationPageList(PAGE::"Campaign Сard",DATABASE::Campaign,TempNameValueBuffer,NextId);

  4. Restart the Microsoft Dynamics NAV Server instance.

    For more information, see How to: Start, Stop, Restart, or Remove a Microsoft Dynamics NAV Server Instance.

    When changes occur in the table 5071 Campaign, an integration record will be created or updated with a timestamp. You can now use the table to create a page for coupling Dynamics NAV records with Microsoft Dynamics 365 for Sales records.

To create actions on the campaign page for managing the coupling

  1. Open page 5086 Campaign Card in Page Designer, and then open Action Designer.

    For more information about how to add actions, see How to: Add Actions to a Page.

  2. Add an ActionGroup control that is caption Dynamics 365 for Sales.

  3. Add another ActionGroup control under Dynamics 365 for Sales that has the caption Coupling.

  4. In the Coupling action group, add the following actions:

    Name Caption
    ManageCRMCoupling Manage Coupling
    DeleteCRMCoupling Delete Coupling

  5. Open the C/AL code for the actions, and follow these steps:

    1. In the code for the action ManageCRMCoupling, add a local variable that has name CRMIntegrationManagement and references codeunit 5330 CRM Integration Management as its subtype, and then add the following line of code:

      CRMIntegrationManagement.DefineCoupling(RECORDID);

    2. In the code for the action DeleteCRMCoupling, add a local variable that has the name CRMCouplingManagement and references codeunit 5331 CRM Coupling Management as its subtype, and then add the following line of code:

      CRMCouplingManagement.RemoveCoupling(RECORDID);

  6. Save and compile the page.

  7. Open codeunit 5334 CRM Setup Defaults.

  8. In the GetCRMTableNo function, add the following code as a case after the CRM Opportunity case:

DATABASE::Campaign:  
EXIT(DATABASE::"CRM Campaign");

The coupling page is now available from the Campaign page.

To enable users to open the Microsoft Dynamics 365 for Sales Campaign record from the Dynamics NAV Campaign, the next step is to add an additional action to the Campaign Card page.

To add actions to open the Dynamics 365 for Sales campaign record

  1. Open page 5086 Campaign Card in Page Designer, and then open Action Designer.

  2. In the Dynamics 365 for Sales action group, before the Coupling action group, add a new action that has the name GotoCRMCampaign and caption Campaign.

  3. In the C/AL code for the action, add a variable that has the name CRMIntegrationManagement and references codeunit 5330 CRM Integration Management, and then add the following line of code:

    CRMIntegrationManagement.ShowCRMEntityFromRecordID(RECORDID);

  4. Save and compile the card page.

  5. Open codeunit 5334 CRM Setup Defaults in Codeunit Designer.

  6. Add the following code to the GetTableIDCRMEntityNameMapping function to add an entity table mapping for table 5081 Campaign and integration table 50001 CRM Campaign:

    AddEntityTableMapping('campaign',DATABASE::Campaign,TempNameValueBuffer);  
AddEntityTableMapping('campaign',DATABASE::"CRM Campaign",TempNameValueBuffer);

  7. Save and compile the codeunit.

    The coupling and links between Microsoft Dynamics 365 for Sales Campaign records and Dynamics NAV Campaign records are now completed. Users can easily open the coupled Microsoft Dynamics 365 for Sales record directly from Dynamics NAV.

Creating an Integration Table Mapping for Synchronizing Dynamics 365 for Sales Campaigns and Dynamics NAV Campaigns

For synchronization of data between Dynamics NAV and Microsoft Dynamics 365 for Sales to work, mappings must exist to associate the table ID and fields of the integration table (in this case table 50001 CRM Campaign) with the Dynamics NAV business data table (in this case table 5081 Campaign). To accomplish this, you must create to types of mappings: integration table mapping and integration field mapping.

  • An integration table mapping links the Dynamics NAV business data table to the integration table for the Microsoft Dynamics 365 for Sales entity.

  • A field mapping associates a field in a Microsoft Dynamics 365 for Sales entity record with a field in a Dynamics NAV record. It basically determines which field in Dynamics NAV corresponds to which field in Microsoft Dynamics 365 for Sales. You will typically have multiple field mappings for an entity.

    You can create the integration table mapping directly in table 5335 Integration Table Mapping and integration field mappings directly in table 5336 Integration Field Mappings or you can add the mappings by modifying codeunit 5334 CRM Setup Defaults. For a repeatable solution, we recommend that you integrate your changes in codeunit 5334 CRM Setup Defaults.

To Create an Integration Table Mapping

To create an integration table mapping directly in the table 5335 Integration Table Mapping, follow these steps:

  1. Open the integration table 50001 CRM Campaign in Table Designer, and then make a note the field numbers of the CampaignId and ModifiedOn fields. You will use these numbers later in this procedure.

  2. From Object Designer in the development environment, run table 5335 Integration Table Mapping to open it in the Microsoft Dynamics NAV Windows client.

  3. Add a new record and fill in the following fields:

    Field Value
    Name CAMPAIGN
    Table ID 5071
    Integration Table ID 50001
    Synch. Codeunit ID 5340 (CRM Integration Table Synch.)
    Integration Table UID Fld. No. [The field number of the primary key field CampaignId in table CRM Campaign]
    Int. Tbl. Modified On Fld. No. [The field number of the ModifiedOn field in the integration table CRM Campaign]
    Direction Bidirectional (synchronizes from Dynamics NAV to Microsoft Dynamics 365 for Sales and from Microsoft Dynamics 365 for Sales to Dynamics NAV).

To add an integration table mapping in codeunit 5334 CRM Setup Defaults, follow these steps:

  1. Open the codeunit in Codeunit Designer.

  2. Add a local function called ResetCampaignMapping with the following parameters:

    Name DataType SubType Length
    IntegrationTableMappingName Code 20
    EnqueueJobQueEntry Boolean

  3. Add the following local variables:

    Name DataType SubType
    IntegrationTableMapping Record Integration Table Mapping
    IntegrationFieldMapping Record Integration Field Mapping
    CRMCampaign Record CRM Campaign
    Campaign Record Campaign

  4. Add the following code to the function:

    InsertIntegrationTableMapping(
  IntegrationTableMapping,IntegrationTableMappingName,
  DATABASE::Campaign,DATABASE::"CRM Campaign",
  CRMCampaign.FIELDNO(CampaignId),CRMCampaign.FIELDNO(ModifiedOn),
  '','',TRUE);

RecreateJobQueueEntryFromIntTableMapping(IntegrationTableMapping,30,EnqueueJobQueEntry);

    For each integration table mapping entry, there must be integration field mapping entries to map the individual fields of the records in the business table and integration table. The next step is to add integration field mappings for each field in the Dynamics NAV Campaign table that you want to map to the Microsoft Dynamics 365 for Sales Campaign entity.

To Create Integration Fields Mappings

To create an integration field mapping directly in table 5336 Integration Field Mapping, follow these steps:

  1. From Object Designer, run table 5336 Integration Field Mapping to open it in the Microsoft Dynamics NAV Windows client.

  2. Add a new record and fill in the following fields:

    Field Value
    No. [An identification number for the field mapping entry, such as 1]
    Integration Table Map Name CAMPAIGN
    Field No. [Field number for the Description field of the table Campaign, for example 2]
    Integration Table Field No. [Field number for the Name field of the integration table CRM Campaign, for example 3]
    Direction Bidirectional

  3. Repeat these steps for each field that you want to map.

    Tip

    If a field in one of the tables does not have a corresponding field in the other table, you can use a constant value. For an example of this, see the CONTACTS Integration Table Mapping.

To add an integration field mapping in codeunit 5334 CRM Setup Defaults, follow these steps:

  1. Open the codeunit in Codeunit Designer.

  2. In the function ResetCampaignMapping, add the following code. As an example, this code maps the Description field in the Campaign table to the Name field in the CRM Campaign integration table.

    InsertIntegrationFieldMapping(  
  IntegrationTableMappingName,  
  Campaign.FIELDNO("Description"),  
  CRMCampaign.FIELDNO(Name),  
  IntegrationFieldMapping.Direction::Bidirectional,  
  '',FALSE,FALSE);

    Repeat this step for all fields that you want to map.

  3. After you make the changes to the CRM Setup Defaults, you can update the mappings by running the Microsoft Dynamics 365 for Sales Connection Setup page and choosing Use Default Synchronization Setup.

    The next step is to add an action on page 5086 Campaign Card that lets users to manually synchronize data between coupled campaign records in Dynamics NAV and Microsoft Dynamics 365 for Sales.

To add an action for manual synchronization

  1. Open page 5086 Campaign Card in Page Designer, and then open the Action Designer for the page.

  2. In the Dynamics 365 For Sales action group, before the Coupling action group, add a new action that has the name CRMSynchronizeNow and the caption Synchronize Now.

  3. In the C/AL code for the action, add a global variable that has the name CRMIntegrationManagement and references codeunit 5330 CRM Integration Management, and then add the following line of code:

    CRMIntegrationManagement.UpdateOneNow(RECORDID);

  4. Save and compile the page.

    Users can now manually synchronize Dynamics NAV Campaign records with Microsoft Dynamics 365 for Sales Campaign entity records from the Dynamics NAV client.

Tip

If you want to learn how to schedule the synchronization by using a job queue entry, examine the code on the RecreateJobQueueEntry function in codeunit 5330 CRM Integration Management and see how it is called by the integration code for other Microsoft Dynamics 365 for Sales entities in the codeunit.

Customizing Synchronization

When synchronizing data, some entities may require custom code to successfully synchronize data. Other entities might require the initialization of fields, the validation of relationships, or the transformation of data.

During the synchronization process, certain events are published and raised by codeunit 5335 Integration Table Synch.. You can add code that subscribes to these events, which enables you to add custom logic at different stages of the synchronization process. The following table describes the events that are published by codeunit 5345.

Event Description
OnFindUnCoupledDestinationRecord Occurs when the process tries to synchronize an uncoupled record (new record). Use this event to implement custom resolution algorithms for automatic mapping between records. For example, you can use this event to automatically map records by fields. You can see an example in codeunit 5341 CRM Int. Table. Subscriber, which includes the event subscriber function CRMTransactionCurrencyFindUncoupledDestinationRecord. The event is used to resolve Dynamics NAV currency codes with ISO currency codes in Microsoft Dynamics 365 for Sales.
OnBeforeApplyRecordTemplate Occurs before applying configuration templates to new records, and can be used to implement algorithms for determining what configuration template to use.
OnAfterApplyRecordTemplate Occurs after configuration templates are applied to new records, and can be used to change data after configuration templates have been applied.
OnBeforeTransferRecordFields Occurs before transferring data in modified fields (which are defined in the Integration Field Mapping table) from the source table to the destination table. It can be used to validate the source or destination before the data is moved.
OnAfterTransferRecordFields Occurs after transferring modified field data (which are defined in the Integration Field Mapping table) from the source table to the destination table. It can be used to transfer additional data, validate lookups, and so on. Setting the AdditionalFieldsWereModified parameter will cause a destination record modification even if no fields were modified.
OnBeforeInsertRecord Occurs before inserting a new destination record, and can be used to initialize fields, such as primary keys.
OnAfterInsertRecord Occurs after new destination record is inserted, and can be used to perform post-insert operations such as updating related data.
OnBeforeModifyRecord Occurs before modifying an existing destination record, and can be used to validate/change data before modification.
OnAfterModifyRecord Occurs after an existing destination record is modified, and can be used to perform post-modify operations such as updating related data.
OnTransferFieldData Occurs before an existing destination field value is going to be transferred to a source field, and can be used to perform specific transformations of data when types of the source and the destination field are different but can be mapped.

For the synchronization of campaigns, you will use an event to create a custom rule that sets the Comment field in a Dynamics NAV campaign to TRUE if the Message field in a Microsoft Dynamics 365 for Sales campaign has data. You do this by subscribing to the OnAfterTransferRecordFields event that is published by codeunit 5335 Integration Table Synch.

For more general information about how to subscribe to events, see Subscribing to Events.

To subscribe to the Integration Table Synch. OnAfterTransferRecordFields event

  1. In the development environment, open the codeunit that has the ID 5341 and the name CRM Int. Table. Subscriber.

  2. Add a new function with the name UpdateCampaignComment.

  3. Add the following locals to the function:

    Function Variable Name DataType SubType
    CRMCampaign Record CRM Campaign
    Campaign Record Campaign
    Function Return Value Name Return Type
    AdditionalFieldsWereModified Boolean
    Function Parameter Name Data Type
    SourceRecordRef RecordRef
    DestinationRecordRef RecordRef

  4. Add the following code to implement the logic to determine whether the Message field has a value:

    SourceRecordRef.SETTABLE(CRMCampaign);  
DestinationRecordRef.SETTABLE(Campaign);  

IF (CRMCampaign.Message <> '') AND (NOT Campaign.Comment) THEN BEGIN  
  Campaign.Comment := TRUE;  
  AdditionalFieldsWereModified := TRUE;  
END ELSE BEGIN  
  IF (CRMCampaign.Message = '') AND Campaign.Comment THEN BEGIN  
    Campaign.Comment := FALSE;  
    AdditionalFieldsWereModified := TRUE;  
  END;  
END;  

IF AdditionalFieldsWereModified THEN  
  DestinationRecordRef.GETTABLE(Campaign);

  5. Locate the OnAfterTransferRecordFields function, which is an EventSubscriber. Add the following code as a case after the Unit of Measure case:

    'CRM Campaign-Campaign':
  AdditionalFieldsWereModified :=
    UpdateCampaignComment(SourceRecordRef,DestinationRecordRef);

  6. Save and compile the codeunit.

    When you choose Synchronize Now on the Campaign page, and then choose to synchronize from Microsoft Dynamics 365 for Sales to Dynamics NAV, the Comment field should be updated to indicate whether the Message field in the Microsoft Dynamics 365 for Sales campaign has a value.

See Also

Customizing Dynamics 365 for Sales and Dynamics NAV Integration
Introduction to Dynamics 365 for Sales Integration Customization in Dynamics NAV