JSON file import examples
Summarize
Summary of JSON file import examples
This guide provides practical examples and best practices for importing JSON files into ServiceNow, focusing on correctly specifying the JSON path for each row during import. It highlights the importance of following JSON standards (RFC-4627) and the structure requirements to ensure successful data import.
Show less
Key Import Path Patterns
- Simple array: The JSON path for each row repeats the array root element twice (e.g.,
/incidents/incidents) to extract each record correctly. - Array at second level: When arrays exist inside nested objects, the array root node is repeated twice at the correct nested path (e.g.,
/problems/data/data). - Nested arrays: For arrays nested within other arrays, all relevant root nodes must be repeated twice in the path (e.g.,
/problems/problems/data/data). - Orphan arrays: Arrays at the root level can be imported by using the root path
//to yield each item as a record. - Multiple elements instead of arrays: This format is not recommended as it violates JSON standards; unique names must be used within objects, and JSON arrays are preferred.
Handling Child (Nested) Arrays
By default, ServiceNow import discards nested arrays, but you can enable support by unchecking the Discard Arrays option in the Data Source configuration. This affects how arrays within records are imported:
- Discard Arrays enabled: Arrays inside records are ignored and not imported as columns.
- Discard Arrays disabled: Arrays are imported as columns containing the array data (e.g., JSON arrays or objects).
Note that arrays containing simple values (not key-value pairs) cannot be imported as separate records and will cause errors regardless of this setting.
Practical Implications for ServiceNow Customers
- Ensure your JSON files conform to RFC-4627 to avoid import errors.
- Specify the JSON path correctly, repeating array root nodes twice, to successfully import array data as multiple records.
- Use the Data Source option to control whether nested arrays are included or discarded, depending on your data requirements.
- Avoid using multiple elements with the same name instead of arrays, as this is unsupported and non-compliant.
Following these guidelines enables accurate and efficient import of JSON data into ServiceNow tables, supporting better data integration and automation.
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], ortext(), as well as Axis such as children, siblings, or ancestors are not supported.
Simple array
- Path for each row:
/incidents/incidents - Result: 2 records
/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
/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
/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]}
}
]
}
}
| Path | Discard Arrays Enabled | Discard Arrays Disabled |
|---|---|---|
| /response/docs/docs | Creates one record with the following columns and values:
|
Creates one record with the following columns and values:
|
| /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
{
"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"
}
}
}