Transform maps

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Transform maps

    Transform maps in ServiceNow define how fields from an import set correspond to fields in existing tables, such as Incident or User tables. They enable administrators to specify destination fields for imported data and can be reused to map data from multiple import sets to the same target table. Mapping can be performed simply via drag and drop or dynamically through scripting.

    Show full answer Show less

    Key Features

    • Reusability: Once created, transform maps can be reused for other import sets targeting the same table.
    • Auto-mapping: The system can automatically map fields, but customers should verify that automatically mapped fields, such as encrypted passwords, are appropriate to import.
    • Reference field mapping: When mapping reference fields, if the referenced sysid does not exist, the sysid may be incorrectly displayed as the DisplayValue. Mapping many reference fields impacts performance due to validation checks, but this can be optimized using transform scripts like onBefore.
    • Multiple transform maps: Customers can apply multiple transform maps to a single import set. Each transform map creates its own import set row, potentially generating many temporary records. Multiple maps execute sequentially in the order specified during data import.
    • Transform map scripting: Provides a programming interface to customize and add advanced logic during data import. There are two script types:
      • Explicit scripts that define mapping relationships
      • Transformation event scripts that modify processing at different transformation stages

    Practical Considerations for Customers

    • Review and confirm auto-mapped fields to ensure only relevant data is imported.
    • Use transform scripts to optimize performance when importing large numbers of reference fields by bypassing reference existence checks if validation is not required.
    • Be cautious when using multiple transform maps with the same import set, as it increases temporary records and processing overhead.
    • Leverage transform map scripts to tailor complex import scenarios and enforce business rules during data transformation.

    A transform map is a set of field maps that determine the relationships between fields in an import set and fields in an existing ServiceNow table, such as Incident [incident] or User [sys_user].

    Figure 1. Import process transform
    Import process transform

    After creating a transform map, you can reuse it to map data from another import set to the same table.

    The Transform Maps module enables an administrator to define destinations for imported data on any tables. Transform mapping can be as simple as a drag and drop operation to specify linking between source fields on an import set table and destination fields on any table. Use transform mapping to map source and destination fields dynamically.

    For a video overview of transform maps, see the Transform Maps video on the ServiceNow Dev Program YouTube channel.

    Transform considerations

    Auto-mapping
    Double-check that fields the system maps automatically are actually required. For example, encrypted passwords probably should not be mapped.
    Mapping reference fields
    If you are mapping reference field data and the sys_id does not exist, the sys_id could potentially appear in the target record as the DisplayValue, and this may be undesirable.
    Field mapping a large number of reference fields incurs additional performance overhead because the system checks that the referenced sys_id actually exists before performing choice actions at the field level.
    Note:
    You can bypass the performance overhead using transform scripts such as onBefore (on the assumption that there is no requirement to validate the import of reference fields). For example, target.<field_name> = source.<field_name>.

    Using multiple transform maps

    Multiple transform maps can be applied to a single data source.

    One import set row is created per transform map, which can cause a large number of temporary records to be generated.
    Note:
    If you use multiple transform maps for the same import set, the transform creates multiple entries in the import set table.

    Run multiple transforms off a single import set

    Users can select multiple transform maps during data import.

    The selected transform maps will be executed on the same import set in the order specified.

    Figure 2. Multi-map transform
    Multi-map transform

    Transform map scripts

    Transform Map scripts allow you to customize import operations using a robust programming interface to introduce advanced logic.

    A transform map script executes as events occur while an import set is being transformed onto a ServiceNow table. Transform Map scripting is fully integrated into the ServiceNow scripting environment. There are two types of Transform Map scripts:
    • Explicit Transform Map scripts, which explicitly define mapping relationships
    • Transformation Event scripts, which modify the processing of events at different stages of a transformation