Mapping Contacts Between Your External Data Sources and InterAction

When you bring in contact information from Application Collaboration, you are either adding new contacts into InterAction or updating existing contacts.

When you first deploy the InterAction software, there are no contacts in InterAction. Typically, you bring in your contacts from your human resources system through Application Collaboration. Also, as new employees join your organization and are added to your human resources system, they will be added into InterAction through Application Collaboration.

In some cases, contacts already exist in InterAction when you run Application Collaboration. To prevent Application Collaboration from creating duplicate contacts, specify your mapping option.

Application Collaboration can map existing InterAction contacts if the same contact is in both InterAction and the external system. Once mapped, the contact works just like a contact added by Application Collaboration. You can update the contact with changes from the external system.

There are four different mapping options. These options essentially define the criteria that Application Collaboration uses when comparing the harvested contacts with existing contacts in InterAction:

  • None
  • Additional Information
  • Name
  • InterAction Contact ID

In addition to selecting your mapping option, determine whether Application Collaboration claims the contact. When you claim a contact, only one external data source can update the contact. A SYS_ID is set on the contact so the external data source can identify the applicable contact to update. When you do not claim a contact, multiple data sources can update the contact and no SYS_ID is set. See To Claim or Not to Claim for more information.

This section covers the following topics:

Using the None Mapping Option

In this option, Application Collaboration does not attempt to map any existing contacts. If the same contact exists in both InterAction and the external system, Application Collaboration creates a duplicate.

Select this option if your InterAction database contains no data the first time you transform data using Application Collaboration. In this case, the other map options are not needed since there is no data to map to.

Mapping by Additional Information Field

In this option, Application Collaboration maps contacts by comparing the value in a specified InterAction additional field with a field value harvested from the external system. If the value harvested from the external system matches the value in InterAction, the InterAction contact is mapped.

You can select the InterAction additional field to use. Application Collaboration then adds an additional column to the data set table. This column is named using the label name of the InterAction additional field.

You also have two additional options to use when mapping by additional field:

  • Map by contact name if no match is found by additional field mapping
  • If No Match Is Found options

If you select the Map by contact name... check box on the Claim tab, Application Collaboration maps by contact name if the additional field cannot be found. If the contact name is found, the additional field is added to the contact.

If no match is found, you can either specify from the Claim tab to Add a new contact or Write an error to the SQL Results log. If you decide to add the contact, the contact is added and the additional field is set on the contact.

During harvesting, populate this column with the value to match in InterAction.

Mapping by Additional Field

When selecting the InterAction additional field to use for mapping, note that the field must contain a unique value for each contact in InterAction. If the value is not unique, Application Collaboration generates an error during transformation.

Furthermore, the additional field value must be unique for both people and companies. For example, if you select to map by a global additional field called Client Code and both a person and a company contact have the same value in this field, Application Collaboration is unable to map either contact and generates a conflict. This occurs regardless of whether you are populating InterAction with people, companies, or both.

You can use either a global or a folder-specific additional field. It can be either a single-value or multiple-value additional field.

For example, if your Clients folder has a folder-specific field for client code, you can use it to map the contacts. In this example, Application Collaboration maps a contact if both of the following are true:

  • It has a value in the client code field that matches the client code harvested from the external system.
  • It is already linked into the Clients folder (this is required for the folder-specific additional field to have any value).

Note: You can map by both active and inactive global additional fields.

Client code is typically a good field to use for time and billing systems, while social security or employee number is useful for human resources systems.

Mapping by Name

For this option, Application Collaboration maps contacts by comparing the contact name harvested from the external system with the contact names in InterAction.

This method is not as reliable as using the additional field, since contact names in InterAction do not have to be unique and the names may have been entered differently in the two systems. This method also takes longer.

However, this method is typically useful for mapping on an ongoing basis. For details, see Mapping During Ongoing Integration. This method is also useful when you are not claiming the contact. See To Claim or Not to Claim for more information.

If multiple contacts are returned as potential matches and the data set is set for the external data source to claim the contact, Application Collaboration creates outstanding claims. An administrator needs to manually select which of the potential matches to map.

For more about resolving outstanding claims, see Reconciling Claims.

Including Company Names in the Search

If you choose the map by name option for a person data set, you can select to include the company name as part of the criteria for matching contacts. If you select this option, a contact is only found and mapped if both the person name and the company in InterAction match the person and company information harvested into the data set table.

For example, with this option, the following two contacts are not considered duplicates:

  • John Smith at Telenorth Financial Services
  • John Smith at Justus Software, Inc.

Note that when harvesting people, you do not harvest company names - you harvest the SYS_ID for the company into the COMPANY_SYS_ID column of the person data set. Therefore, selecting to include companies when mapping people does not use the company name to match the person, it uses the company system ID. Therefore, you can only use this option if you are also bringing in the companies for the people from the same data source and you are claiming the company. If you are not claiming the company, there is not SYS_ID.

Mapping by InterAction Contact ID

This option lets you export contacts from InterAction, make updates externally, then bring the data back into InterAction.

When this option is selected, the data set table includes the following two columns:

  • LISTING_SRC_ID - populates this column with the contact source ID.
  • LISTING_ID - populates this column with the contact ID.

For example, if the LISTING_ID column for one row contains 90, and the LISTING_SRC_ID column contains 2, the existing InterAction contact with those same ID values is found and mapped. The combination of contact source ID and contact ID uniquely identifies contacts in InterAction.

When using this mapping option, Application Collaboration does not create any new contacts. Since the contact IDs to use must come from InterAction, an ID that does not match any existing contacts is either incorrect or represents a contact that was deleted from InterAction and should not be added back.

Mapping by Internal InterAction Contact ID

Note that the LISTING_ID and LISTING_SRC_ID columns are used with firm contacts, not with user contacts. In InterAction, firm contacts are stored in the INT_AUX_LISTING table.

What If the Contact I am Updating Has Been Merged Into Another Contact?

When using Application Collaboration to update contacts by contact ID, it is possible that the IDs specified in the data set table might point to a contact that lost in a duplicate merge. For example, suppose your person data included two versions of the contact John Smith. You exported this data to perform cleanup externally. Within InterAction, a user merged the two John Smith records, creating a single contact.

When updating the data with the data set, you now have two different contact IDs for John Smith, one pointing to the contact that won in the merge, and the other pointing to the version that lost. Application Collaboration handles this situation by looking up the merge history for each contact and finding the version that won in the merge. Therefore, any updates for the version of John Smith that lost are applied to the merged good contact. This only applies when mapping based on contact ID.

Mapping Contacts Not in the Source Folder

Normally, any existing contacts in InterAction that match contacts in the external system are sourced in the designated source folder. For example, if you are sourcing companies in Firm Contacts - Companies, any companies that match the harvested data are likely also in the Firm Contacts - Companies folder. This is the recommended configuration for InterAction.

However, if a matching contact exists in InterAction, but not in the designated source folder, it is mapped but not moved. After the transformation is complete, the mapped contact is still sourced in its original source folder.

In a standard InterAction installation, this should not be an issue because all business contacts (the contacts most likely to match contacts in an external system) should be in one of the main public source folders.

Choosing the Best Mapping Option

The best mapping option to use in your scenario may change depending on what you are currently doing with Application Collaboration. There are two basic scenarios:

  • The initial data load - This is first time you transform the bulk of the contacts from an external system.
  • Ongoing integration - This is after the initial data load, when you are refreshing InterAction with updated data from the external system on a regular basis.

You may need to use one mapping option during the initial data load and a different one for ongoing integration. To change the mapping option for an existing company or person data set, see Set the Mapping Options for a Company or Person Data Set.

Mapping During the Initial Data Load

You only need to choose a mapping option during the initial data load if InterAction already contains contacts that may duplicate those in the external system. If you are populating an empty InterAction system, you can select the None mapping option and let Application Collaboration create the contacts without checking for duplicates.

You can also choose None if the data from the external system and the existing InterAction data do not overlap. For example, if you are using Application Collaboration to populate companies and InterAction currently contains only people.

If your existing InterAction system contains data that might overlap with the external system, you need to choose a mapping option. The best option depends on the state of your data in both systems:

  • If the existing InterAction data has any additional fields populated with identifying information such as client code, choose to map by additional field. This is far more accurate than mapping by name. Remember, the identifier must be unique - more than one contact cannot have the same identifier. Good choices include client code, social security number, or employee code.

  • If the existing InterAction data does not have any identifying information, you must select to map by name.

    Note that this method is much slower for a first time transformation. It is also less accurate - if a contact in the external system matches multiple names in InterAction, someone needs to manually choose the right contact to map.

Mapping During Ongoing Integration

If you use Application Collaboration for ongoing integration, it is very likely that duplicates may be introduced regularly.

For example, a user might enter a new company in InterAction as a prospect. When that company becomes a client, it is added to the accounting system. The next time the billing data is harvested and transformed, the prospect previously entered needs to be matched to the new client from the accounting system and mapped.

The best option for this situation is typically mapping by Name. This is because the identifying field frequently does not exist until the contact becomes part of the external system. For example, prospects do not normally have client numbers that tie to your accounting system and prospective employees do not have employee numbers that tie to your human resources system.

Note: If the InterAction users are adding the unique identifier (such as client code), you can map the contacts by additional field instead. This situation is rare.

Note that mapping by Name may not automatically map all contacts. For example, if the name in the external system is formatted differently and does not match the information in InterAction, the InterAction contact is not mapped and Application Collaboration creates a new contact. In this case, you can use InterAction’s duplicate merge features to merge the existing InterAction contact into the new contact created by Application Collaboration.

Set the Mapping Options for a Company or Person Data Set

For details about how the mapping options work, see Mapping Contacts Between Your External Data Sources and InterAction.

  1. In the console list, right-click the company or person data set you want to change and choose Edit.

  2. Choose the Claim tab.

  3. Under Map Contact Based On, select the method to use to match the harvested contacts with existing InterAction contacts:

    To Do This
    Match contacts based on Name Select Contact Name.
    Match contacts based on a global additional field Select Additional Information, then select the additional field from the drop-down list.
    Match contacts based on a folder-specific additional field
    • Select Additional Information, then choose Browse.
    • Enter criteria to find the folder and choose Search, then select the folder and choose OK.
    • Select the additional field from the drop-down list. The list includes both global and folder-specific additional fields for the selected folder.
    Match contacts based on the InterAction Contact ID. Select InterAction Contact (Listing ID). Note that you can only use this option to update existing contacts; it does not add new contacts.

  4. Choose OK.

  5. Making this change can alter the columns used in the table for the data set. Modify your harvesting routine as needed to account for this change.

Control Whether InterAction Users Can Edit the Company or Person Names

This option only controls the name information for the contacts populated using the data set. For a company, this includes the company name fields. For a person, this includes the name, job title, department, and assistant fields.

This option only applies in the Windows Client; the ability of Web Client users to edit the data is controlled by data change management. For details, see Application Collaboration and Data Change Management.

For more information about this option, see Allowing InterAction Users to Edit the Data.

Note that this only lets users edit the InterAction data; any changes made in InterAction are not transferred to the external system.

  1. In the console list, right-click the Company () or Person () data set you want to change and choose Edit.

  2. Choose the Claim tab.

  3. Do one of the following:

    To Do This
    Let InterAction users with appropriate access rights edit the data from the external system. Select the Allow users to edit... check box.
    Lock down the data from the external system so InterAction users cannot edit it. Clear the Allow users to edit... check box.

  4. Choose OK.

    Changing this option for the data set does not change the editability of any contacts previously populated with the data set. You must reharvest the data from the external system and transform it to see the change for existing contacts.

To Claim or Not to Claim

When you are creating your company or person data sets, there are two Claiming Options on the Claim tab to choose from. You can choose one of the following:

  • Claim contacts added or updated by this data set
  • Update or add contacts without claiming them by this data set

Select the Claim contacts... option if your contacts are only going to be updated by a single, external data source. This option sets a SYS_ID on each contact so Application Collaboration can easily match the external data source contacts with the equivalent contacts in InterAction.

For ongoing updates, if you selected Claim contacts added or updated by this data set, Application Collaboration maps by SYS_ID first, regardless of what mapping option is selected on the Claim tab.

Select the Update or add contacts without claiming... option if your contacts are going to be updated by multiple, external data sources. The first time that you bring contacts in, map the contact using the None option. The contacts are added, but no SYS_ID is set on the contact.

For ongoing updates, make sure you change the mapping option to Contact Name. If the option is kept as None, the same contacts are added again as duplicates. Any new contacts that were added to the external data source are added in InterAction if you set the If No Match Found option to Add a new contact.