JSON file import examples

  • 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 JSON file import examples

    This content explains how to import JSON files into ServiceNow, focusing on the correct path syntax for different JSON structures and guidelines to ensure successful import. It highlights that JSON files must comply with RFC-4627 standards and that the path for each imported row typically repeats the array root element twice.

    Show full answer Show less

    Key Details for Importing JSON Files

    • Path for each row: When importing JSON arrays, specify the array root element twice in the path, e.g., /incidents/incidents.
    • JSON format: JSON must be well-formed according to RFC-4627, with unique names within objects and comma-separated values. Unsupported features include predicates like @element or axes such as children or siblings.
    • Examples of paths:
      • Simple array: /incidents/incidents yields 2 records.
      • Array at second level: /problems/data/data yields 3 records.
      • Nested arrays: /problems/problems/data/data yields 3 records.

    Handling Child (Nested) Arrays

    By default, ServiceNow import discards nested arrays. To import child arrays:

    • Disable the Discard Arrays option in the Data Source settings.
    • When enabled, nested arrays are imported as columns with array values preserved.
    • When disabled, arrays within records are omitted from the import table.
    • Importing arrays of simple values (not key-value pairs) is unsupported and results in errors.

    Special Cases and Recommendations

    • Orphan arrays: JSON arrays at the root level can be imported using // as the path.
    • Multiple elements instead of arrays: JSON files with repeated keys instead of arrays are not recommended because they violate RFC-4627; use arrays to represent multiple records.

    Practical Takeaways for ServiceNow Customers

    • Ensure JSON files adhere to RFC-4627 and structure data with arrays for multiple records.
    • Use correct path syntax that repeats the array root element twice to correctly map JSON arrays to import rows.
    • Enable or disable the Discard Arrays option based on whether you want to preserve nested arrays during import.
    • Avoid unsupported JSON features and structures to prevent import errors.

    These examples demonstrate how to import various types of JSON data and the necessary path for each row. JSON files that you import should follow these guidelines.

    For step-by-step instructions on creating a File type data source see, Create a File type data source.

    • For JSON arrays, the path for each row must specify the array root element twice, such as /incidents/incidents.
    • JSON files should follow RFC-4627. For example, a single comma should separate a value from the following name. Names within an object should be unique.
    • Predicates such as @element, [index], or text(), as well as Axis such as children, siblings, or ancestors are not supported.

    Simple array

    • Path for each row: /incidents/incidents
    • Result: 2 records
    In this example, the path for each row includes the array root node /incidents twice. This is necessary when importing an array.
    {  
   "source":"HI",
   "incidents":[  
      {  
         "number":"INC0000001",
         "short_description":"Can't read email"
      },
      {  
         "number":"INC0000002",
         "short_description":"Error loading XML file"
      }
   ]
}

    Array in 2nd level

    • Path for each row: /problems/data/data
    • Result: 3 records
    In this example, the path for each row includes the array root node /data twice.
    {  
   "problems":{  
      "id":"0",
      "data":[  
         {  
            "number":"PRBTEST001",
            "short_description":"testsd1"
         },
         {  
            "number":"PRBTEST002",
            "short_description":"testsd2"
         },
         {  
            "number":"PRBTEST003",
            "short_description":"testsd3"
         }
      ]
   }
}

    Nested array

    • Path for each row: /problems/problems/data/data
    • Result: 3 records
    In this example, the path for each row includes the root nodes for both arrays twice, /problems and /data.
    {  
   "problems": [  
         {
      "id":0,
      "data":[  
            {  
               "number":"PRBTEST001",
               "short_description":"testsd1"
            },
            {  
               "number":"PRBTEST002",
               "short_description":"testsd2"
            },
            {  
               "number":"PRBTEST003",
               "short_description":"testsd3"
            }
          ]
       }
    ]	
}

    Supporting child (nested) arrays

    By default, import does not support child (nested) arrays. You can enable support by unchecking the Discard Arrays check box in the Data Source view. The following table describes different behaviors when enabling and disabling child array support.

    { 
  "response":{
    "docs":[ 
      { 
        "id":"id_val",
        "childrenArray":[1,2,3],
        "anotherArray":[{"key1":"value1"}, {"key1": "value2"}],
        "elementWithArray":{"childrenArray":[1,2,3]}
      }
    ]
  }
}
    Table 1. Child array behavior
    Path Discard Arrays Enabled Discard Arrays Disabled
    /response/docs/docs Creates one record with the following columns and values:
    • Id : id_val
    • elementWithArray : {}
    Any arrays found in a record, such as childrenArray or anotherArray, are not created as columns in the import table.
    Creates one record with the following columns and values:
    • Id : id_val
    • childrenArray : [1, 2, 3]
    • anotherArray : [{"key1" : "value1"}, {"key1" : "value2"}]
    • elementWithArray : {"childrenArray" : [1, 2, 3]}
    /response/docs/docs/anotherArray/anotherArray Creates two records, each with one column: key1. Creates two records, each with one column: key1.
    /response/docs/docs/childrenArray/childrenArray Does not work and returns a Path should always refer JSON Objects error because the values in the array are not in a key-value structure. Does not work and returns a Path should always refer JSON Objects error because the values in the array are not in a key-value structure.

    Orphan array

    • Path for each row: //
    • Result: 2 records
    [  
   {  
      "number":"PRBTEST001",
      "short_description":"testsd1"
   },
   {  
      "number":"PRBTEST002",
      "short_description":"testsd2"
   }
]

    Multiple elements instead of an array

    • Path for each row: /problems/problem
    • Result: 3 records
    Important:
    This format is not recommended. JSON files should follow RFC-4627, which states that names within an object should be unique. Use JSON arrays instead.
    {  
   "problems":{  
      "title":"2 problems",
      "problem":{  
         "number":"PRBTEST001",
         "short_description":"testsd1"
      },
      "problem":{  
         "number":"PRBTEST002",
         "short_description":"testsd2"
      }
   },
   "problems":{  
      "title":"1 problem",
      "problem":{  
         "number":"PRBTEST005",
         "short_description":"testsd5"
      }
   }
}