JSON file import examples

Release version: Xanadu

Updated August 1, 2024

2 minutes to read

Summarize

Summarized using AI

Summary of JSON File Import Examples

This document provides guidelines and examples for importing JSON data into ServiceNow, ensuring compliance with RFC-4627 standards. It outlines the correct paths for various JSON structures and highlights the settings required for successful data import.

Show full answer Show less

Key Features

Path Structure: Each row's path must specify the array root element twice, such as /incidents/incidents for JSON arrays.
Child Array Support: By default, child arrays are not supported; however, support can be enabled by unchecking the Discard Arrays option in the Data Source view.
Error Handling: Specific paths may return errors if they do not conform to expected key-value structures.

Key Outcomes

Successful import of JSON arrays and nested arrays with clear path definitions, leading to accurate record creation in ServiceNow.
Improved data handling by enabling child array support, allowing for richer data structures to be imported.
Awareness of best practices, such as avoiding non-unique names within JSON objects, to prevent import issues.

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"
      }
   }
}