Exporting and converting records into complex data types

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 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 Exporting and converting records into complex data types

    This guide explains how ServiceNow customers can export table records using URL parameters in HTTP GET requests and convert them into various complex data types such as JSON, XML, PDF, CSV, and XLS. It also covers filtering options to export specific subsets of records and how to post certain data formats directly into tables.

    Show full answer Show less

    Key Features

    • Export Formats: Records can be exported as CSV, Excel (XLS/XLSX), JSON (via JSONv2), PDF, RSS, and XML files by appending specific parameters to the table URL (e.g., ?XLS for Excel).
    • URL Syntax: The general format for exporting data is https://<instance-name>/<table-name>.do?<Data-type-parameter>. For example, to export active incident records as Excel: incident.do?XLS&sysparmquery=active=true.
    • Filtering Data: Use sysparmquery to filter records by encoded query conditions (e.g., active=true). The sysparmview parameter specifies a list view to control which fields are included. For XML exports, useUnloadFormat=true returns an unload XML format suitable for re-import.
    • PDF Export Specifics: To export a list as PDF, use the table name followed by list. Exporting a single record as PDF requires specifying the record’s sysid.
    • Direct POST to Tables: CSV, Excel, and JSON data types can be directly posted into tables. The file headers must align with the table’s field columns.

    Practical Application and Outcomes

    ServiceNow customers can efficiently retrieve and export data in the format best suited for their reporting, integration, or archival needs simply by constructing HTTP GET requests with appropriate URL parameters and filters. This capability enables easy data sharing and manipulation outside the platform.

    Additionally, the ability to post CSV, Excel, and JSON files directly into tables streamlines data import workflows, ensuring data consistency by matching file headers with table fields.

    By using these export and import methods, users can automate data exchange processes, support external analytics, and maintain synchronized datasets with minimal manual effort.

    Use URL parameters to export table records and convert them into complex data types, such as JSON, XML, PDF, CSV, and XLS.

    Exporting records as complex data types

    You can use an HTTP GET request to retrieve records from a table and put them in a specified format. For example, use the PDF parameter in a GET request to export records from a table as PDF files; use the XLS parameter to export records from a table as XLS files. For example, to retrieve a list of incident records as XLS files, issue an HTTP GET using the following URL: https://instance_name.service-now.com/incident.do?XLS. The file returned is incident.xls. incident.do is basically a GET that returns a list of the records from the incident table. The XLS parameter converts those records into XLS files.

    The general syntax is: https://<serviceNow-instance-name>/<table-name>.do?<Data-type-parameter>

    URL parameters

    The following table shows URL parameters you can use in GET requests, filters you can use to filter out unwanted table records in the return, and an indicator of whether you can POST the data type directly to a table. The parameter becomes the extension of the returned file, for example, using the XLS parameter returns a file in the form <table-name>.xls.
    Table 1. URL parameters
    Data type Parameter Valid filters Directly POST to table?
    CSV CSV sysparm_query, sysparm_view Y
    Excel XLS, EXCEL, XLSX sysparm_query, sysparm_view Y
    JSON JSONv2 Various. See JSON data retrieval API. Y
    PDF PDF sysparm_query, sysparm_view N
    RSS RSS sysparm_query, sysparm_view and more. See Limiting results with a view. N
    XML XML, XSD, SCHEMA sysparm_query, useUnloadFormat N

    For more information about retrieving and converting table records into the JSON file format, see JSONv2 Web Service.

    For more information about retrieving and converting table records into the RSS file format, see RSS feed generator.

    Converting records to PDFs

    For PDF export, there is a distinction between targeting a table and targeting its list. To generate a PDF of a list of records, suffix the target with _list. To target a single record, you must specify the sys_id parameter to identify the record for which you are generating the PDF.

    Filters

    All URL parameters work with filters that enable you to export a subset of table records. For example, sysparm_query=active=true in a GET request exports only active records. The following example exports only active incident records in an Excel format: https://instance_name.service-now.com/incident.do?EXCEL&sysparm_query=active=true.

    The general syntax is: https://<serviceNow-instance-name>/<table_list>.do?<Data-type-parameter>&<filter>

    Filters include:
    • sysparm_query—Filters the data using the encoded query before exporting files, for example, sysparm_query=active=true exports only active records.
    • sysparm_view—Specify the name of a list view to control which fields are returned. For example, to return the ESS view, use sysparm_view=ess.
    • useUnloadFormat—Indicates that the XML format returned is an unload format. The unload format is the same format you get when, from a list in the UI, you select Export > XML > ... You can import unload-formatted XML files back into the tables. To enable the unload format from a URL, use the useUnloadFormat=true URL parameter, for example, https://instance_name.service-now.com/incident.do?XML&useUnloadFormat=true.

    Example GET queries

    Table 2. GET request examples
    Data type Example query
    CSV https://instance_name.service-now.com/incident.do?CSV&sysparm_query=active=true
    Excel https://instance_name.service-now.com/incident.do?XLS&sysparm_query=active=true
    PDF https://instance_name.service-now.com/incident.do?PDF&sysparm_view=ess
    RSS https://instance_name.service-now.com/incident.do?RSS&sysparm_view=ess
    XML https://instance_name.service-now.com/incident.do?XML&sysparm_query=active=true

    Returned files

    GET queries return records from a table in the format specified in the request. For example, a query that uses the XLS parameter returns a table record in a file with the .xls extension.

    The Content-Disposition header in the response displays the file name and extension of the returned file. The file name is based on the table you export from, such as incident.xls, incident.pdf, or incident.xml.

    Exporting data into tables

    You can POST the following data types directly into tables:
    • CSV
    • Excel
    • JSON

    The file headers must match the field columns in the targeted table. For more information, see Post CSV or Excel files directly to an import set.