JSON file import examples

Release version: Washingtondc

Updated February 1, 2024

2 minutes to read

Summarize

Summarized using AI

Summary of JSON File Import Examples

This guide provides examples and guidelines for importing JSON data into ServiceNow, ensuring compliance with JSON formatting standards, specifically RFC-4627. It covers necessary paths for various JSON structures to facilitate successful data import.

Show full answer Show less

Key Features

Simple Array Import: Use the path /incidents/incidents for importing simple arrays. Each row must reference the array root twice.
Nested Array Support: Enabling child arrays requires unchecking the Discard Arrays option in the Data Source view. This impacts how records are created during import.
Path Guidelines: Paths for importing must be defined correctly, reflecting the structure of the JSON data, including handling of orphan arrays and multiple elements.
Behavior of Discard Arrays: The import process varies significantly based on whether the Discard Arrays option is enabled or disabled, affecting how arrays are represented in the resulting records.

Key Outcomes

By following the outlined paths and guidelines, ServiceNow customers can effectively import JSON data, ensuring that records are created accurately and meet the necessary data structure requirements. This leads to improved data integrity and usability within ServiceNow applications.

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