Help

Page tree

Data Conversion

Data conversion is one of the most useful automation tools in Agiloft. Conversion allows administrators to map fields from one table to another, creating new records or updating existing records in the process. For example, a Contract record could be converted into a Company record after a new contract is created and the company becomes a client.

Data conversion settings

Best Practice Tips

Conversion can be used in many different ways, and each setup is a little different, but it's usually a good idea to follow these best practices:

  • To retain links between tables, map fields in the source table to the fields that link to them in the target table. For instance, if you are converting a Task to a Time Entry, map the ID field in the source Task table to the Task ID field in the target Time Entries table. In this case, the Task ID field is part of a linked set to the Task table. You can see this configuration in many places in the out-of-the-box knowledgebase. If you don't follow this configuration, the system does not link the converted records to the source records, and you may encounter system errors that prevent the conversion entirely.
  • Use rules to trigger conversions when a user performs an action, such as editing a field. For instance, suppose you have a potential new client and create a Lead record. After contacting them, it becomes clear they would like to do business with you, so you change the record's status to Converted. This can automatically trigger an Edit rule with a Data Conversion action that converts the record to Opportunity, Company, and Person records. Because the user doesn't have to manually initiate the conversion process, this configuration helps ensure that certain records always get converted.

Create a Conversion Mapping

Conversion mappings, also known as conversion rules, are created with the Data Conversion wizard. To access the wizard, go to the Conversion tab of the Table wizard or the Conversion tab when creating a Data Conversion action.

You can convert the same record into a target table in multiple ways, at different times, and with different field mappings. 

Table Tab

Use Table tab to set a few primary options for the conversion mapping.

  1. Title the conversion mapping.

    Use a simple title with the name of the target table. For example, you might title a conversion mapping "Company" or "Contract." If you have multiple conversion mappings from the current table to the same target table, be specific enough to differentiate them, such as "Create Renewal Contract" and "Create Related Contract."

  2. Select the target table to which you're converting. This is the table that holds the new or updated records after the conversion is performed.
  3. Define the creation order of conversions. The creation order determines the order in which conversions occur when multiple conversions are run from a single action.
  4. Click Next.

Field Mapping Tab

On the Field Mapping tab, choose the fields from the current table that you want to map onto fields in the target table. 

  1. For each source field on the left that you want to map, choose a target field from the corresponding drop-down list on the right. The available target fields depend on the data type of the source table fields: choice fields can only be mapped into choice or multi-choice fields, date fields into date fields, and so on.

  2. For each field you map, select whether it is used to identity matching records. Using the Match option helps you avoid creating duplicate records. If a matching record does exist, the import overwrites values in the record for all fields included in the conversion mapping. This allows you to use conversion to update existing records with new data, as well as to create new records. Note that all of the fields you select to identify matching records must indeed match in order to update an existing record rather than create a new one.

    Example

    Imagine you're configuring a conversion that updates or creates a new company record and you want to include both the Company Name and the City fields to be sure you have a real match. Also imagine that you're mapping to a Website URL field but aren't using the Match option for it. If a matching record is found based on the Company Name and City fields, the Website URL field is updated with the new web address. A new record is not created.

  3. If you've selected any fields to define matching records, choose the field that's used to display any matches to the user.
  4. Click Next.

Options Tab

The Options tab includes a variety of settings for the conversion.

  1. Select whether to include the current conversion mapping if the user uses the Convert button from the action bar.
  2. If you select the option in step 1, choose whether to allow the user to reject the conversion when running a Data Conversion action.

  3. Select whether the system automatically creates a record necessary for a linked field relationship if a matching record cannot be found. Imagine you're creating a new person record, and the record contains a Company Name field that's a part of a strict linked set to the Company table. If the company does not yet exist, the system creates a new company record and links the person to that company.

    Example

    This is also useful for circular relationships. Suppose you are converting to create first a company and then a person. The company record has a link to the Main Contact field, the person record has a link to the Company Name field, and both are strict links. With the "Create record required..." option checked and the company record is created, a “shell” person record is also created for the company’s Main Contact. But when the system creates the person record, it's smart enough to realize it is the same person, so it updates the "shell" person record with the rest of the mapped fields instead of creating another person.

  4. Select whether null values are not mapped in the conversion. If you don't map null values, the system prevents any field with an empty value from being mapped during conversion. This option is useful when updating an existing record based on a matching criteria, which helps avoid blank values from overwriting existing values in a matching record. In rare cases, you may want to map null values into a matching record and overwrite existing values. For example, if you're converting a Person record into a Company record, you may want to map an empty Phone Number field to prevent the new company contact from having an incorrect phone number.
  5. Select which fields the user can edit in the Conversion dialog, which only applies when the Convert button is used from the action bar. For any selected fields, the user can edit the field's value before the conversion creates or updates records.
  6. Select whether to use a saved search to restrict the available records that can be converted. By default, No restriction is selected.

  7. If you're mapping from a field that contains multiple values or attached files, select whether to create one record for each value in the field. This option is most useful for handling attached files. You can also use it for a multi-choice field to create one record per choice in the target table. This option only works in a conversion rule that runs silently. For more information, see Conversion Permissions below. 

    Example

    Consider an inbound email that's received for a contract with three attached files. A conversion rule can create a separate document record for each attached file. Because the Attached File field is usually limited to hold only one attached file, this approach helps with organization.

  8. Click Finish.

Multiple Conversion Mappings

Multiple conversion mappings can exist on a single table, which allow you to create records in the same target table based on varying criteria or different target tables. When using multiple conversion mappings on a single table, keep the following points in mind:

  • If two mappings exist for the same target table and both allow conversion from the action bar, two records are created when a user clicks Convert from the action bar, one for each mapping.
  • Each conversion mapping may have different search restrictions, or no restrictions, which are selected on the Options tab. Therefore, when performing multiple conversion mappings to the same target table, a record may match the search criteria for one mapping but not any other search restriction. In such a case, clicking Convert from the action bar performs only one conversion, and an error is reported about the second, prohibited conversion mapping. A record that matches one search is not prohibited from conversion if it fails to meet the other search criteria.
  • There are no specific limitations when combining two or more conversion mappings in actions and rules. For example, users may select two or more conversion mappings to run in a single action; the same rule may trigger multiple actions, each containing one or multiple conversions to the same table.

Conversion Permissions

Many administrators use action buttons with Data Conversion actions to allow users to perform record conversion. In these cases, they might not want users to see the Convert button on the action bar, which brings up the Conversion Dialog, but they may want users to interact with Data Conversion actions. For example, some administrators want users to have access to the newly converted record(s) so that the user can make edits.

Two permission options on the Record Permissions tab of the Table Permissions wizard control these aspects of data conversion:

  • Show conversion button on menu action bar: Controls whether the group sees the Convert button on the action bar. If no conversion mappings are defined for the table, or if the "Include this conversion mapping..." checkbox in the Data Conversion wizard is not selected for any existing conversion mappings, the Convert button does not appear on the action bar, even if this option is selected.
  • Allow interaction with conversion rules: Controls whether the group can interact with Data Conversion actions, either through the Conversion Dialog or with the new record.

When using the Convert button on the action bar, the Conversion Dialog is always displayed before completing the conversion, even if the "Allow interaction with conversion rules" checkbox is cleared.

Interacting with Conversion Rules

If the "Allow interaction with conversion rules" checkbox is selected in the Table Permissions wizard, the user can interact with Data Conversion actions based on the selected conversion option. However, if the user doesn't have permission to create records in the target table and the "Interactively, showing the new record page" option is selected, the user cannot save the record and complete the conversion.

If the "Allow interaction with conversion rules" checkbox is cleared, then the following logic is applied when running a Data Conversion action, based on the option selected for running the conversion:

  • The conversion runs silently and creates the new record(s) in the background without the user's knowledge. This logic is used when the "Silently, with no confirmation" option is selected.
  • The conversion runs silently and creates the new record(s) in the background, showing a confirmation when done. This logic is used when any of these options are selected:
    • Interactively, showing the conversion dialog and results
    • Interactively, showing the new record page
    • Automatically, but showing the confirmation screen

Interactive conversions should not be run by rules, since rules cannot interact with the dialog. Interactive conversions also do not apply default values until after the new records are saved.