Page tree

Example Microsoft Dynamics Setup

This sample use case describes a full example sync setup to share contracts and contract-related data between  Agiloft and Microsoft Dynamics. You can use this example to guide your own integration. Keep in mind that this example borrows heavily from Microsoft Dynamics Integration, where setup steps are described in full.

This example syncs these tables and entities:

Agiloft

Dynamics
Contract TypeContract Type (not included out-of-the-box)
ContractContract (not included out-of-the-box)
CompanyAccount
AttachmentNote / Annotation

The Contract Type and Contract entities, which aren't available in Dynamics out-of-the-box, are custom entities.

For this sync, we will configure two separate one-way sync configurations, one from  Agiloft to Dynamics and one from Dynamics to  Agiloft, so that each direction can use multi-to-multi table mappings.

This information is provided for those who have already configured a sync with Dynamics using this configuration. For new integrations with Microsoft Dynamics, use the Integration Hub for best results.

Preparing Systems

To prepare the two systems for synchronization, we made a few changes to each system.

Preparing  Agiloft

To prepare  Agiloft for sync, we:

  • Added a Short Text field, Identifier for  Agiloft Sync, to all four  Agiloft tables: Contract Type, Contract, Company, and Attachment
  • Used Mass Edit on the new Identifier field in all four tables to set the field value equal to the record ID (without running rules afterward)
  • Verified that every record has the record ID populated as a value in the new Identifier field

To prepare Dynamics for sync, we:

  • Completed the communication setup and Client ID/Client Secret, as described in Microsoft Dynamics Integration
  • Created a Contract Type entity with the following fields:
    • Name
    • Identifier for  Agiloft Sync (text field)
  • Created a Contract entity with the following fields:
    • Title (required)
    • Description (required)
    • Contract Amount
    • Contract Start Date (required)
    • Contract End Date (not required, to support evergreen contracts)
    • Contract Type (required, look-up field for Contract Type entity)
    • Account (look-up field for Account entity)
    • Identifier for Agiloft Sync (text field)
  • Added an Identifier for  Agiloft Sync text field to the Account entity
  • Created custom buttons for the Contract and Account entities so that users can trigger sync to  Agiloft from the entity page, as described in Microsoft Dynamics Integration

Agiloft to Dynamics

For this use case, we set up three sync configurations in Agiloft.

  1. Sync Contract Types to Dynamics. This syncs only the Contract Type data and nothing else, and will be used only once, when first setting things up. Running this sync first makes sure that Dynamics has the necessary contract types before any contracts are synced.
  2. Agiloft to Dynamics. This sends  Agiloft data to Dynamics.
  3. Dynamics to  Agiloft. This sends Dynamics data to  Agiloft.

Let's look at each sync configuration in more detail. For each one, we'll cover important settings and field mappings.

Sync Contract Types to Dynamics

On the General tab:

  1. Select Microsoft Dynamics as the External System Type.
  2. Set Directions to Update External System Only. Dynamics doesn't have any contract type data, so we don't need to sync both directions. We only need to send the contract types to Dynamics.
  3. In Conflicts, select This system should take precedence.

On the Mapping tab:

  1. Add a mapping for the Contract Type table that points to the Contract Type entity in Dynamics.
  2. Edit the mapping.
  3. Enable External Create, External Update, and External Delete in the Allowed operations.
  4. Clear the "Search for related records" checkbox.
  5. Map the Identifier for  Agiloft Sync fields. In that row, select Update in External and select Identifying.
  6. Map the Name to the Contract Type and select Update in External.

On the Running tab, make sure Manual is enabled in Run Mode.

Agiloft to Dynamics

On the General tab:

  1. Select Microsoft Dynamics as the External System Type.
  2. Enable Allow Multi to Multi Table Mappings.
  3. Set Directions to Update External System Only. Because we are using multi-to-multi table mappings, we are creating two one-way sync configurations, rather than a single two-way configuration.
  4. Select Include records in related tables.
  5. In Conflicts, select This system should take precedence.

On the Mapping tab:

  1. Add a mapping for all four tables: Contract Type, Contract, Company, and Attachment.
  2. Edit the Contract Type mapping:
    1. Set the Allowed operations to update the external side only.
    2. Clear the Search for related records checkbox. If you select this checkbox, the system also starts syncing contracts that have these contract types, which then starts syncing companies and attachments. We will sync this data separately through the other table mappings.
    3. Map the Identifier fields and set the row to Update in External and mark it as Identifying.
    4. Map the Name and Contract Type fields and set the row to Update in External.
  3. Edit the Contract mapping:
    1. Set the Allowed operations to update the external side only.
    2. Select the Search for related records checkbox. We want the Contract record to be the source of the related record updates.
    3. Map the Identifier fields and set the row to Update in External and mark it as Identifying.
    4. Map the Contract Description, Contract End Date, Contract Start Date, and Contract Status fields. Set them all to Update in External only.
    5. Notice that the Account and Contract Type fields aren't mapped. These fields are mapped later, on the Relation Mapping tab, since they are linked relationships.
  4. Edit the Company mapping:
    1. Set the Allowed operations to update the external side only.
    2. Clear the Search for related records checkbox.
    3. Map the Identifier fields and set the row to Update in External and mark it as Identifying.
    4. Map the Account Name and Company Name fields and set the row to Update in External.
    5. Map the Main Phone and Telephone fields and set the row to Update in External.
    6. Notice that the address fields aren't mapped. These fields are mapped later, on the Relation Mapping tab, since they are linked relationships.
  5. Edit the Attachment mapping:
    1. Set the Allowed operations to update the external side only.
    2. Clear the Search for related records checkbox.
    3. Map the Step Id field from Dynamics to the Identifier field in  Agiloft. Since the Notes entity doesn't allow new fields to be added, we use Step Id as the identifier. In this case, set the row to Update in Agiloft and mark the row as Identifying.
    4. Map the Title fields and set the row to Update in Agiloft.
    5. Map Attachments (For Agiloft Sync) to the Attached File field and set the row to Update in Agiloft.

On the Relation Mapping tab:

  1. In the Contract / Contract row, select Contract->Company and select Update External.
  2. In the second Contract / Contract row, select Contract->Contract Type and select Update External.
  3. In the Note / Attachment row, select Attachment->Contract and select Update External.

On the Running tab, select all the options in Run Mode.

Dynamics to Agiloft

This sync configuration is very similar to the  Agiloft to Dynamics setup, with a few differences. A key difference throughout is the direction of sync; where the first sync configuration pushed changes to Dynamics, the external system, this configuration pulls changes from Dynamics, so most of the settings will be inverted.

On the General tab, use the same settings as the prior section, except:

  1. Set Directions to Update Agiloft only.
  2. Set Conflicts to External System should take precedence.

On the Mapping tab, use the same settings as the prior section, except:

  1. Where you selected Update in External last time, select Update in Agiloft this time, and vice versa.
  2. As before, make sure the Contract Type mapping is not set to "Search for related records."

On the Relation Mapping tab, use the same settings as the prior section. Set the relationships to Update External, just like last time.

Making Final Adjustments

As described in detail in Microsoft Dynamics Integration, there are a few finishing touches to setting up the sync.

  1. Define or update rules in the KB for each table that is mapped in the sync.
  2. Generate the hotlink URL for the custom button created in Dynamics.
  3. Update the JavaScript code with the hotlink URL so the custom button can be used.