Difference between revisions of "Integrations"

From Resco's Wiki
Jump to navigation Jump to search
 
(8 intermediate revisions by the same user not shown)
Line 7: Line 7:
  
 
The following connectors are available:
 
The following connectors are available:
* OData: Connect to any server that supports the Open Data Protocol (OData v4).
+
* OData: Connect to any server that supports the Open Data Protocol (OData v4), including '''[[Business Central|Microsoft Dynamics 365 Business Central]]'''.
 
* Resco Cloud: Connect to another organization residing on one of the various cloud servers of Resco (including Resco Inspections, Resco Routes, etc.).
 
* Resco Cloud: Connect to another organization residing on one of the various cloud servers of Resco (including Resco Inspections, Resco Routes, etc.).
  
== Woodford configuration ==
+
== Create integration ==
  
 
You can manage your connections to other servers from the [[Woodford#Administration_menu|'''Administration''' menu of Woodford]]: Start Woodford and select '''Integrations (Preview)''' from the menu.
 
You can manage your connections to other servers from the [[Woodford#Administration_menu|'''Administration''' menu of Woodford]]: Start Woodford and select '''Integrations (Preview)''' from the menu.
 
=== Create integration ===
 
  
 
# Click '''New'''.
 
# Click '''New'''.
Line 25: Line 23:
 
* Based on default mapping, External Primary Key fields will be added to the schema.
 
* Based on default mapping, External Primary Key fields will be added to the schema.
  
=== Map metadata ===
+
== Map metadata ==
  
 
As the next step, you need to map external entities to local entities and external fields to local fields.
 
As the next step, you need to map external entities to local entities and external fields to local fields.
Line 42: Line 40:
 
[[File:Mapping of entity fields.png|600px]]
 
[[File:Mapping of entity fields.png|600px]]
  
==== Clean up metadata ====
+
=== Clean up metadata ===
  
 
Administrators of the backend servers can occasionally modify the metadata, either on the local or on the external server. New entities or fields are not a problem. What can affect the integration is when a certain entity or field used in integration is removed.
 
Administrators of the backend servers can occasionally modify the metadata, either on the local or on the external server. New entities or fields are not a problem. What can affect the integration is when a certain entity or field used in integration is removed.
Line 51: Line 49:
 
* If the '''Primary Key''' field goes missing, consider setting up a new primary key.
 
* If the '''Primary Key''' field goes missing, consider setting up a new primary key.
  
=== Set up sync filter ===
+
== Set up sync filter ==
  
 
Optionally, if you want to restrict what data to sync, consider setting up a [[sync filter]]. For each entity, you can define conditions. Only records that match the condition are synchronized. Click '''Sync Filter''' and enter a suitable condition, then click '''Save & Close'''.
 
Optionally, if you want to restrict what data to sync, consider setting up a [[sync filter]]. For each entity, you can define conditions. Only records that match the condition are synchronized. Click '''Sync Filter''' and enter a suitable condition, then click '''Save & Close'''.
Line 57: Line 55:
 
[[File:Sync filter in integrations.png|600px]]
 
[[File:Sync filter in integrations.png|600px]]
  
=== Import/export data ===
+
== Import/export data ==
  
 
Once the mapping is done, you can start using the integration for migrating data.
 
Once the mapping is done, you can start using the integration for migrating data.
Line 72: Line 70:
 
Sample migration result: <code>RESULTS: ALL (15) : IMPORTED (13); UPDATED (2); FAILED (0).</code> In this case, 13 records were imported (created), 2 records were updated, no records failed.
 
Sample migration result: <code>RESULTS: ALL (15) : IMPORTED (13); UPDATED (2); FAILED (0).</code> In this case, 13 records were imported (created), 2 records were updated, no records failed.
  
=== Synchronize data ===
+
== Synchronize data ==
  
 
While importing or exporting data is basically one-and-done, synchronization is used in scenarios where you need to keep up the two environments in sync continuously.
 
While importing or exporting data is basically one-and-done, synchronization is used in scenarios where you need to keep up the two environments in sync continuously.
Line 87: Line 85:
 
* Save all changes and activate the process.
 
* Save all changes and activate the process.
  
=== Import/export mapping ===
+
== Import/export mapping ==
  
 
;Export / Import: If you have multiple similar organizations where you want to reuse an integration, you can export the entire mapping configuration to a file and then import it to a different organization.  
 
;Export / Import: If you have multiple similar organizations where you want to reuse an integration, you can export the entire mapping configuration to a file and then import it to a different organization.  
  
 
;Export Entity / Import Entity: Alternatively, you can export/import mapping for a single entity.
 
;Export Entity / Import Entity: Alternatively, you can export/import mapping for a single entity.
 
== Use case: connect to Business Central ==
 
 
You can use Integrations to connect to [[Business Central|Microsoft Dynamics 365 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.
 
 
# Log in to your Business Central organization and go to the Azure Active Directory Applications.<br>[[File:Bc1.png|600px]]
 
# Click '''New''' and fill out the registration form.<br>[[File:Bc2.png|600px]]
 
# As '''Client ID''', use <code>4abedb2f-19bc-402f-b0b5-b8d17e85aa04</code>.
 
# Add '''User Permission Sets'''.
 
# Grant the necesary consent.<br>[[File:Bc3.png|600px]]
 
 
=== Install Resco extension on Business Central ===
 
 
TBD.
 
 
=== Configure Woodford ===
 
 
# Start Woodford and select '''Integrations''' from the '''Administrator''' menu.
 
# Click '''New''' and enter the following details:<br>[[File:Bc4.png|600px]]
 
#* 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., <code>&company=CRONUS%20USA%2C%20Inc.</code>). It is important to include the correct <code>&company</code> parameter.
 
# Click '''Save'''.
 
 
Double-click this integration to map external entities/fields to local entities/fields.
 
 
For Business Central, some settings are configured by default:
 
* Default mapping will be added. In the preview, only three entities are officially supported: account, contact, and work order.
 
* Based on default mapping, External Primary Key fields will be added to the schema.
 
 
Verify that the three supported entities are enabled, save all changes, and you can start migrating or synchronizing data.
 
 
=== See also ===
 
 
* [https://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/developer/webapi/discover-url-organization-web-api?view=op-9-1 Discover the URL for your Dynamics organization using the Web API]
 
  
 
== Technical information ==
 
== Technical information ==
  
 
When you first create an Integrations connector, these following entities are added to the organization's metadata:
 
When you first create an Integrations connector, these following entities are added to the organization's metadata:
* integrations_log: stores sync logs
+
* integration_log: stores sync logs
* integrations_syncanchor: stores the last version number of the record that was downloaded
+
* integration_syncanchor: stores the last version number of the record that was downloaded
* integrations_transaction: stores information about upload transactions
+
* integration_transaction: stores information about upload transactions
  
  
  
 
[[Category:Resco Cloud]]
 
[[Category:Resco Cloud]]

Latest revision as of 08:07, 13 October 2021

Integration with third-party systems

Resco CRM Connector (web APIs):




The Integrations function of Woodford allows you to connect your Resco Cloud organization to various systems using connectors (Resco Cloud, Dynamics, OData). Match entities and fields between the two servers and exchange data. Configured connections can be used in Resco Cloud jobs and workflows to automate sync process.

Note Integrations are available since release 14.1 as a preview. Contact us if you want to help us shape this function to better match your needs.

Available connectors

The following connectors are available:

  • OData: Connect to any server that supports the Open Data Protocol (OData v4), including Microsoft Dynamics 365 Business Central.
  • Resco Cloud: Connect to another organization residing on one of the various cloud servers of Resco (including Resco Inspections, Resco Routes, etc.).

Create integration

You can manage your connections to other servers from the Administration menu of Woodford: Start Woodford and select Integrations (Preview) from the menu.

  1. Click New.
  2. Name your integration and select which connector to use.
  3. Depending on the selected connector, enter the necessary connection details.
    Create a new integration.png
  4. Click Save.

If you are connecting to Business Central, some settings are configured by default:

  • Default mapping will be added. In the preview, only three entities are officially supported: account, contact, and work order.
  • Based on default mapping, External Primary Key fields will be added to the schema.

Map metadata

As the next step, you need to map external entities to local entities and external fields to local fields.

  1. Double-click a connection (created in the previous section).
  2. Select an entity from the External Entities pane and click Enable.
  3. In the Entity Mapping pane, select the matching Local Entity and optionally the Primary Key.
  4. In the table below, select the fields that you want to import or export (enable the checkbox in the first column) and then select the matching Local Field.
  5. For all fields with the local type "Lookup", enter the lookup Target:
    • For Business Central integration, use the predefined default value.
    • For Resco Cloud integration, it's enough to enter the name of the entity.
  6. Save all changes.

You can repeat these steps for additional external entities as needed.

Mapping of entity fields.png

Clean up metadata

Administrators of the backend servers can occasionally modify the metadata, either on the local or on the external server. New entities or fields are not a problem. What can affect the integration is when a certain entity or field used in integration is removed.

When you open a connection, Woodford checks whether the configured mapping is still valid. If this validation finds some missing entities or fields, a warning message is displayed with the recommended actions.

  • If an external entity or field goes missing, click Clean Up to remove it from the mapping.
  • If a local entity or field goes missing, select a new local entity/field.
  • If the Primary Key field goes missing, consider setting up a new primary key.

Set up sync filter

Optionally, if you want to restrict what data to sync, consider setting up a sync filter. For each entity, you can define conditions. Only records that match the condition are synchronized. Click Sync Filter and enter a suitable condition, then click Save & Close.

Sync filter in integrations.png

Import/export data

Once the mapping is done, you can start using the integration for migrating data.

  1. Click Import Data or Export Data.
  2. Optionally, click Import Preview to verify that you are migrating the right data. Previews do not make any changes on either server.
  3. Click Import or Export to conclude the migration.
  4. Wait for the migration result.
Note Preview does not respect the selected primary key.

Import data preview.png

Sample migration result: RESULTS: ALL (15) : IMPORTED (13); UPDATED (2); FAILED (0). In this case, 13 records were imported (created), 2 records were updated, no records failed.

Synchronize data

While importing or exporting data is basically one-and-done, synchronization is used in scenarios where you need to keep up the two environments in sync continuously.

Warning When you run sync for the first time, local data for the affected entities are deleted.

The first sync is full sync (all data downloaded); later synchronizations are incremental (only changes are transferred). See Synchronization for more information about this process in general. The article is written mostly from the perspective of syncing client (mobile app) and server, but many concepts also apply to the integration sync.

Click Sync in the toolbar to start the sync manually. Or, more likely, you might wish to schedule the sync to run regularly as a server process:

  • Start the Admin Console.
  • Select Processes Center > Processes from the menu.
  • Click New to create a new process.
    Nightly sync job.png
  • Save all changes and activate the process.

Import/export mapping

Export / Import
If you have multiple similar organizations where you want to reuse an integration, you can export the entire mapping configuration to a file and then import it to a different organization.
Export Entity / Import Entity
Alternatively, you can export/import mapping for a single entity.

Technical information

When you first create an Integrations connector, these following entities are added to the organization's metadata:

  • integration_log: stores sync logs
  • integration_syncanchor: stores the last version number of the record that was downloaded
  • integration_transaction: stores information about upload transactions