Connect Resco Cloud to Business Central

From Resco's Wiki
Jump to navigation Jump to search
Integration with third-party systems

Resco CRM Connector (web APIs):




Resco Cloud can directly connect to Microsoft Business Central.

Register Resco application in Business Central

Before you can start migrating data between Resco Cloud and Business Central, you must register the Resco application (clientId) in Business Central and grant Resco consent with accessing Business Central data.

  1. Log in to your Business Central organization and go to the Azure Active Directory Applications.
    Register Resco application in Business Central step 1
  2. Click New and fill out the registration form.
  3. As Client ID, use 4abedb2f-19bc-402f-b0b5-b8d17e85aa04.
  4. Grant the necessary consent.
    Register Resco application in Business Central step 4

Install Resco extension on Business Central

The extension is required (but see below) for synchronizing between Resco Cloud and Business Central.

  1. Download the extension.
    Optionally, find the latest version of the extension on GitHub. You can also report issues and review recent commits.
  2. Log in to Business Central and search for "extensions".
    Install Resco extension on Business Central step 2
  3. On the Manage tab, click Upload Extension and upload the zip file.
    Install Resco extension on Business Central step 3
  4. Open Web Services, click New, select Page, select RescoCustomer and write RescoCustomer as Service Name.
  5. Repeat it for every custom page from the Resco extension. (RescoCustomer, RescoContact, RescoServiceOrder).

Can I integrate without extension?

Yes, but... it depends on your customization of Business Central.

The integration offers two modes of synchronization:

  • Full sync: download all records of an entity.
  • Incremental sync: download only changed records.

To take advantage of the faster, incremental sync, Business Central must have a Version Number field on the entity; and this field must be defined in the mapping in Woodford.

To take advantage of the faster, incremental sync, Business Central must have a Version Number field on the entity; and this field must be defined in the mapping in Woodford

You can define the version number using the extension. We recommend using row version number (Big Integer) as the Version number field. You can use Date/DateTime fields as well, but it won't be 100% incremental sync.

Create integration

  1. Start Woodford and select Integrations from the Administrator menu.
  2. Click New and enter the following details:
    Create integration with Business Central: edit integration connection
    • Name - enter a name of your integration
    • Connector - select OData
    • URL - enter the URL of Business Central OData endpoint (e.g., https://api.businesscentral.dynamics.com/v2.0/b8cc0002-2542-46ed-8584-d4868701fbc4/Production/ODataV4/)
    • Username - BC account's email address
    • Password - BC account's password
    • CustomQueryParamaters - custom query, which should be added to the every request (e.g., &company=CRONUS%20USA%2C%20Inc.). It is important to include the correct &company parameter.
  3. Click Save.

You have created the integration; you can now set it up.

Customize integration

How to change default mapping?

Mapping allows you to match entities and fields on Business Central with entities and fields on Resco. Out of the box, three entities are mapped and ready for synchronization: account, contact, and work order.

  1. Double-click the integration.
  2. Select an entity on the External Entities pane (left).
  3. Select the matching local entity, its primary key, and version number.
  4. Create a composite lookup if the relation between 2 external entities is defined by more than 1 field.
  5. In the table below, define the mapping for fields that you want to integrate: select the checkbox and choose a matching Local Field.
  6. For all fields with the local type Lookup, click Manage Lookup Mapping.
  7. Save all changes.

How to enable/disable entity for synchronization? What if I only want to upload or download?

  1. Double-click the integration.
  2. Select an entity from the External Entities pane.
  3. Click Enable or Disable.
  4. Use Sync Direction to control if you want to exchange data in both direction, upload only, or download only.
  5. Save all changes.

How to change Sync Filter?

If you want to restrict what data to sync, consider setting up a Sync Filter.

  1. Double-click the integration.
  2. Select an entity from the External Entities pane.
  3. Click Download Filter or Upload Filter.
  4. Enter custom conditions that serve as a filter for records.
  5. Save all changes.

How to reuse mapping in different Resco Cloud organization?

  1. On the Resco Cloud organization from which you want to export mapping, double-click the existing integration.
  2. Do one of the following:
    • Click Export if you want to export the entire mapping (all entities).
    • Click Export Entity if you only want to export the selected entity.
  1. On the Resco Cloud organization to which you want to import mapping, create a new integration.
  2. Double-click it and import the mapping.
  3. Save all changes.

Can I sync two external entities with one entity on Resco Cloud?

The schema of the external system can be vastly different from your Resco Cloud organization. Fortunately, you can map two (or more) external entities to a single Resco Cloud entity. Use upload sync filter to ensure that the correct records from Resco Cloud end up in the right entity on the external system.

Bussinec central:ou can map two (or more) external entities to a single Resco Cloud entity

Is it possible to setup direction of sync for selected entity?

Yes, you can setup Sync Direction on entity level:

  • Bidirectional (default)
  • Download Only
  • Upload Only

How to define relations between entities?

You can configure lookups using the Manage Lookup Mappings button (available for all fields with Local Type = Lookup).

Basically, we can divide relations to two groups:

Lookups defined by one field

In this scenario you need to select Target External Entity and Target External Field as well.

For example, to define the Service Order > Customer relation:

  1. Select customerid as Local Field (Lookup).
  2. Click Manage Lookup Mappings.
  3. In the Manage Lookup Mapping window, select Target External Entity and Target External Field.

Business Central:Integration - lookup defined by one field

Lookups defined by more than one field

For example, to define the Service Item Line > Service Order relation:

  1. Create a composite lookup, such as "service order".
  2. Select the same local field (with Local Type = Lookup) for documentNo and documentType external fields.
  3. Set up the lookup mappings for both fields. In both cases, select the composite lookup "service order" that you created in the first step.

Business Central:lookup defined by two fields

How to map state/status/picklist values?

If you map an external field to a local field of the type state, status, or picklist (Status, Status Reason, Option Set) the Value Mapping button is displayed in that row. It allows you to map external statuses/options to local ones.

alr=Business Central:Value mapping

How to map time/date fields

Resco Cloud has a single field type for time and date values. If the external system has two fields (one for time, one for date), in Resco Cloud these can be stored in a single field.

Business Central:Date and time mapping

The DateTime Mapping button allows you to set up how the external value should be saved:

Business Central:Date and time mapping 2

How to add a new entity to integration?

Synchronization is effective if the versionnumber of entity (table in Business Central) is compared from the last sync. Therefore we recommend creating a table extension to access field(0) - versionnumber in Business Central.

This is an example of an extension for the Customer table. Apply the same principles to other tables.

tableextension 50101 "Resco Customer" extends Customer
{
    fields
    {
        field(50000; RowVersionNumber; BigInteger)
        {
            Caption = 'RoW Version Number';
            DataClassification = CustomerContent;
        }
    }
    trigger OnAfterInsert()
    begin
        Rec.RowVersionNumber := GetRowVersionNumber(Rec);
        Rec.Modify(false);
    end;

    trigger OnAfterModify()
    begin
        Rec.RowVersionNumber := GetRowVersionNumber(Rec);
        Rec.Modify(false);
    end;

    procedure GetRowVersionNumber(var recordCustomer: Record Customer) RowVersion: BigInteger
    var
        RecRef: RecordRef;
    begin
        RecRef.GetTable(recordCustomer);
        RecRef.GetBySystemId(recordCustomer.SystemId);
        RowVersion := RecRef.Field(0).Value();
    end;
}

Second step is to add this custom field to your Page/new Page:

Some fields will need some special handling, use triggers: OnModifyRecord(), OnAfterGetCurrRecord(), OnInsertRecord() to create your custom logic (e.g., mapping of status).

page 50110 "Resco Customer"
{
    //....
    //your page definition
    //....
    layout
    {
        area(Content)
        {
            repeater(Group)
            {
                //......
                //your fields
                //......

                field(RowVersionNumber; Rec.RowVersionNumber)
                {
                    ApplicationArea = All;
                    Caption = 'VersionNumber', Locked = true;
                }
            }
        }
    }
}

Upload the created table and page extensions to your Business Central organization.

  1. Open Web Services in your Business Central.
    Business Central:Open web services in business central
  2. Click New.
    Business Central:Create a new web service.png
  3. Select Page, Object ID of created Page and define Service Name (it will be displayed in Integration Editor in Woodford) and Save.

Return to Resco Cloud.

  1. Open your integration, enable external entity for integration, and do the mapping.
  2. Select Local entity, Primary Key, Version Number - RowVersionNumber and proceed with field mapping.

Synchronization

The first sync is full sync: all records of enabled local entities are cleaned up on Resco Cloud and all records of external entities are downloaded from Business Central. Every next sync is incremental - only changes are transferred.

On Demand

  1. Double-click the integration in Woodford.
  2. Click Sync to start synchronization manually.

Scheduled

You can set up a server process to schedule the sync (for example, every day at midnight) or set up a trigger (for example, when an account record is created in Resco Cloud).

  1. Start the Admin Console.
  2. Select Processes Center > Processes.
  3. Click New to create a new process.
  4. As Category, select "Workflow" or "Job".
  5. Schedule or define condition when sync should be executed.
  6. Write down the procedure that performs the sync:
    • Click Step > Function.
    • Enter the function: Select Server, then IntegrationSync, then enter the name of your integration defined in Woodford.
      Business Central:Sample sync job
  7. Save, publish, and activate the process.

Web Service

You can use the REST API to trigger sync with a web service.

Basic authorization

https://rescocrm.com/rest/v1/integration/{name of your integration}/$sync
<IntegrationRequest IsSynchronous="false" KeepStatusLog="true">              
    <Ticket></Ticket>
</IntegrationRequest>

See also