Bulk import map examples

  • Release version: Zurich
  • Updated July 31, 2025
  • 5 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 Bulk import map examples

    This guide provides practical examples for configuring bulk import maps to successfully map source employee documents to the required elements in ServiceNow Employee Document Management. It covers mapping strategies for both local repositories using file names and third-party cloud-based repositories using JSON outputs. Proper mapping ensures employee documents are accurately imported and organized within Employee Document Management.

    Show full answer Show less

    Mapping Using File Names from Local Repositories

    When employee documents are stored locally, using consistent file naming conventions is recommended. File names such as abeltutertuition.pdf can be parsed to extract metadata like employee names and document types via regular expressions (RegEx). For example:

    • Extract fileName directly from the source.
    • Parse employee name in the format firstlast, converting it to first.last.
    • Extract docType (e.g., tuition) from the file name.

    Using RegEx test tools is recommended to validate parsing rules. Maintaining a centralized repository with a simple directory structure and consistent file naming reduces errors.

    Mapping Using JSON Output from Cloud-Based Repositories

    For cloud-based or third-party repositories, JSON outputs are used to map documents. The import map identifies elements in JSON arrays (e.g., items or entries) and extracts relevant fields for import:

    • Employee: Extracted from nested JSON fields such as ownedby.name, using dot notation to bypass nested objects.
    • Document Type (docType): Mapped from description or specific JSON fields representing document categories, with value mappings converting source terms (e.g., verification, school) to required terms in Employee Document Management (e.g., employee verifications, transcripts).
    • File Name (fileName) and URL (url): Extracted from JSON fields such as name and id. Some repositories use file IDs to construct URLs for document access.

    Value mapping is used to convert source-specific values to the standardized format required by Employee Document Management, ensuring consistency and accuracy.

    Practical Application and Next Steps

    Once your source repository connection is confirmed and import maps are configured following these examples, you can initiate the bulk import process by starting the staging job. This process will import employee documents with correctly mapped employee names, document types, file names, and URLs, facilitating accurate and organized employee document management within ServiceNow.

    Mapping your source employee documents to required elements in Employee Document Management is crucial for a successful bulk import.

    This topic provides examples on how to map your source employee documents to the required elements in Employee Document Management. The values provided are examples designed to guide you through the import map configuration.

    Map fields and values directly from existing file names

    Using your existing employee document file names is recommended when your source employee documents reside in a local repository.

    For example, an employee document can have all the meta data in the file name Abel_Tuter_tuition.pdf to map to Employee Document Management.
    Note:
    When using regular expressions (RegEx) to define the replacement value, use a regular expression test site to ensure correct parsing.
    File name example
    The example file name is abel_tuter_tuition.pdf.
    To find and extract the file name from the source repository, see this example:
    Import Map — File name
    The import map is looking for a source element called fileName.
    The import map is going to translate this source element to a mapped element called fileName.
    The Regex is looking for the format of the file name first_last_xxx.pdf.
    File name to employee name example
    From the file name, the employee name is extracted. Employee name is a requirement for Employee Document Management.
    Import Map — Employee Name
    The import map is looking for a source element called fileName.
    The import map is going to translate this source element to a mapped element called employee.
    The Regex is looking for the format of the file name to be first_last_tuition.pdf (\w+)_(\w+)_(\w+).(\w+).
    It replaces the original file name with first.last ($1.$2)
    File name to document type example
    From the file name, the document type is extracted. Document type is a requirement for Employee Document Management.
    Import Map — docType
    The import map is looking for a source element called fileName.
    The import map is going to translate this source element to a mapped element called docType.
    The Regex is looking for the format of the file name to be first_last_tuition.pdf (\w+)_(\w+)_(\w+).(\w+).
    It creates a docType of tuition ($3).
    Note:
    Having the source employee documents in a central repository, simple directory structure, and consistent file naming convention are highly recommended and reduces errors.

    Parse and map fields and values from a JSON output

    Using a JSON output is recommended when your source employee documents reside in a third-party, cloud-based repository.

    Table 1. Map record for element item
    Field Description
    Mapping type Field
    Mapped element items

    Looks for the items mapping element in an array of items in the folder.

    This mapping is used after Stage — Directory import source.
    Source element entries

    Source element in the JSON output and represents the items in a folder. For example, Box uses entries as the source element.

    JSON — entries

    Table 2. Map record for element employee
    Field Description
    Mapping type Field
    Mapped element item

    Looks for item, an entry in an array of items in the folder.

    This mapping is used after Stage — Directory import source to run operations against a single item.
    Source element id

    For each item in the array, find the file ID in the JSON output.
    Filter regex file

    Combined with the Filter field to exclude subfolders.
    Filter field type

    Filter output to where the type field is equal to file to exclude subfolders.

    JSON — item

    Table 3. Add map records for element employee (continued)
    Field Description
    Mapping type Field
    Regex (\w+)\s(\w+)

    String translation to convert fname lname to fname.lname.
    Replace $1.$2

    Converts files found in Regex field fname lname to fname.lname.
    Mapped element employee

    Looks for employee mapping element. Employee is a field in the file item.

    This mapping is used after Stage — file import source.
    Source element owned_by.name

    Looks for name in owned_by object. Bypass nested objects with a dot notation.
    Filter regex
    JSON — Owned by and Name
    Table 4. Add map record for element employee (alternative)
    Field Description
    Mapping type Value

    Selecting Value maps the employee element within an array of information from your source document to a specific value in Employee Document Management.
    Replace david.loo

    The value you want to replace the source element with in Employee Document Management.

    Employee Document Management requires employee names to be formatted fname.lname.
    Mapped element employee

    Looks for the employee mapping element that is a field in the file item.

    This mapping is used after Stage — file import source.
    Source element davidl

    Looks for the source value of davidl.
    This example illustrates how to use Value mapping to take an employee name from your source document and map it to the format that Employee Document Management requires.
    Table 5. Add map records for element docType
    Field Description
    Mapping type Field
    Mapped element docType

    Looks for the docType mapping element embedded in the description field in the file item.

    This mapping is used after Stage — file import source.
    Source element description

    Looks for name in description.
    Filter regex
    JSON — description
    Table 6. Add map records for element docType (continued)
    Field Description
    Mapping type Value

    Use Value to map a specific value in your third-party, cloud-based repository to a value in Employee Document Management.
    Replace employee verifications

    Replace verification (source) with employee verifications (Employee Document Management).
    Mapped element docType

    Looks for the docType mapping element embedded in the description field in the file item.

    This mapping is used after Stage — file import source.
    Source element verification

    Look for the name value of verification in the JSON.
    Table 7. Add map records for element docType (continued)
    Field Description
    Mapping type Value

    Use Value to map a specific value in your third-party, cloud-based repository to a value in Employee Document Management.
    Replace transcripts

    Replace school (source) with transcripts (Employee Document Management).
    Mapped element docType

    Looks for the docType mapping element embedded in the description field in the file item.

    This mapping is used after the Stage — file import source.
    Source element school

    Looks for the name value school.
    Table 8. Add map record for element fileName
    Field Description
    Mapping type field
    Mapped element fileName

    Looks for the fileName mapping element embedded in the name field in the file item.

    This mapping is used after Stage — file import source.
    Source element name

    Looks for filename in the description in the JSON output.
    Filter regex

    JSON — Name

    Table 9. Add map record for element url
    Field Description
    Mapping type field
    Mapped element url

    Looks for the url mapping element embedded in the id field in the file item.

    This mapping is used after Stage — file import source.
    Source element Looks for id in JSON output.
    Note:
    some third-party, cloud-based repositories use the file ID. The capture import source builds a URL from this value.
    JSON — id

    Bulk import mapping records

    An example of Employee Document Import Map.

    Import map

    When a connection to your source repository is confirmed and import maps are set up correctly, you can click Start staging job from Related Links.