Bulk import map examples

  • Release version: Xanadu
  • Updated August 1, 2024
  • 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 import maps to bulk import employee documents into ServiceNow Employee Document Management. Properly mapping source data fields from local file names or third-party cloud repositories to the required elements in Employee Document Management ensures successful and accurate bulk imports.

    Show full answer Show less

    Mapping Using File Names

    • Scenario: Source employee documents are stored locally with metadata embedded in the file names (e.g., AbelTutertuition.pdf).
    • Key Mapping Elements:
      • fileName: Extracted directly from the source repository file name using a regular expression matching the format firstlastxxx.pdf.
      • employee: Parsed from the file name via RegEx to convert firstlasttuition.pdf into first.last format, which is required by Employee Document Management.
      • docType: Extracted document type (e.g., "tuition") from the file name to classify the document appropriately.
    • Recommendation: Maintain a central repository with a simple directory structure and consistent file naming conventions to minimize errors during import.
    • Note: Use RegEx testing tools to validate expressions for accurate parsing of file names.

    Mapping Using JSON Output from Cloud-Based Repositories

    • Scenario: Source employee documents reside in third-party, cloud-based repositories that provide JSON metadata outputs.
    • Key Mapping Records:
      • Items: Map arrays of file items (e.g., entries in Box JSON) after directory import stage.
      • Employee: Extract employee names from nested JSON objects using dot notation (e.g., ownedby.name), applying regex or value replacements to format names as fname.lname.
      • docType: Map document types from description or other relevant JSON fields, using value mapping to convert source values (e.g., "verification") to Employee Document Management values (e.g., "employee verifications").
      • fileName and URL: Extract file names and construct URLs from JSON fields such as name and id, supporting document access.
    • Value Mapping: Use value replacement mappings to align source data terms and employee name formats with Employee Document Management requirements.

    Practical Application

    Once the connection to your source repository is established and import maps are configured as demonstrated, you can initiate the bulk import process by starting the staging job. This enables efficient ingestion of large volumes of employee documents while ensuring metadata accuracy and compliance with ServiceNow Employee Document Management standards.

    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.