ServiceNow JSON Data Retrieval (JSONv2) — getRecords (modeled core)

This reference is readable without JavaScript. Download the OpenAPI document.

Runtime

/api/purple-suite/{instanceId}/contracts/itsm/servicenow
[
  {
    "method": "get",
    "path": "/:table.do",
    "operationId": "json_data_retrieval_get_records"
  }
]

Credentials

Coverage and limitations

{
  "documentScope": "bounded",
  "runtimeFidelity": "modeled",
  "counts": {
    "operations": 1
  },
  "notes": [
    "The legacy JSON Data Retrieval processor, not part of the pinned REST API artifact. The document is authored from the vendor's JSON Data Retrieval API pages, so its provenance carries no artifact hash.",
    "Only getRecords is served; every other JSONv2 action is 400.",
    "Variables are served for requested items (sc_req_item) only, from the sc_item_option rows a catalog order stored; they have no children and no display-value translation.",
    "Reads share the Table API's encoded-query engine and storage."
  ]
}

The legacy JSON Data Retrieval processor ({table}.do?JSONv2). It is not part of the REST API artifact the other profiles are derived from; this document is authored from the vendor's JSON Data Retrieval API pages, so it carries no artifact hash. Only sysparm_action=getRecords is served (matched in any letter case); every other action is 400. sysparm_query behaves as on the Table API. sysparm_record_count, the vendor's JSONv2 parameter, limits the number of records; sysparm_limit is accepted as on the Table API and applies when sysparm_record_count is absent. displayvalue=false (default) returns stored values, true returns display values, and all returns stored values plus dv_<field> display values; every column is a string. displayvariables=true adds each record's variables, for requested items (sc_req_item) only, ordered by order.

Servers

[
  {
    "url": "/api/purple-suite/{instanceId}/contracts/itsm/servicenow",
    "description": "PurpleSuite instance-scoped ServiceNow emulation"
  }
]

Authentication schemes

{
  "basicAuth": {
    "type": "http",
    "scheme": "basic"
  }
}

Each operation lists its security requirements. An empty security array permits an unauthenticated request. Use the scheme and headers declared for the selected contract.

Operations

GET /{table}.do

JSONv2 getRecords

The legacy JSON Data Retrieval processor ({table}.do?JSONv2). It is not part of the REST API artifact the other profiles are derived from; this document is authored from the vendor's JSON Data Retrieval API pages, so it carries no artifact hash. Only sysparm_action=getRecords is served (matched in any letter case); every other action is 400. sysparm_query behaves as on the Table API. sysparm_record_count, the vendor's JSONv2 parameter, limits the number of records; sysparm_limit is accepted as on the Table API and applies when sysparm_record_count is absent. displayvalue=false (default) returns stored values, true returns display values, and all returns stored values plus dv_<field> display values; every column is a string. displayvariables=true adds each record's variables, for requested items (sc_req_item) only, ordered by order.

Authentication

[
  {
    "basicAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "json_data_retrieval_get_records",
  "summary": "JSONv2 getRecords",
  "description": "The legacy JSON Data Retrieval processor ({table}.do?JSONv2). It is not part of the REST API artifact the other profiles are derived from; this document is authored from the vendor's JSON Data Retrieval API pages, so it carries no artifact hash. Only sysparm_action=getRecords is served (matched in any letter case); every other action is 400. sysparm_query behaves as on the Table API. sysparm_record_count, the vendor's JSONv2 parameter, limits the number of records; sysparm_limit is accepted as on the Table API and applies when sysparm_record_count is absent. displayvalue=false (default) returns stored values, true returns display values, and all returns stored values plus dv_<field> display values; every column is a string. displayvariables=true adds each record's variables, for requested items (sc_req_item) only, ordered by order.",
  "x-purplesuite-classification": "modeled-core",
  "x-docs-topic": "https://www.servicenow.com/docs/r/zZBaGIzc7EPkA0ySnMn5eg/Ts12CWmUsFYAc4F0dD7J7w",
  "parameters": [
    {
      "name": "table",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "JSONv2",
      "in": "query",
      "required": true,
      "allowEmptyValue": true,
      "schema": {
        "type": "string"
      },
      "description": "Selects the JSONv2 processor; its value is ignored."
    },
    {
      "name": "sysparm_action",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^[Gg][Ee][Tt][Rr][Ee][Cc][Oo][Rr][Dd][Ss]$"
      }
    },
    {
      "name": "sysparm_query",
      "in": "query",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "sysparm_record_count",
      "in": "query",
      "schema": {
        "type": "string",
        "pattern": "^\\d+$"
      },
      "description": "An integer that limits the number of records retrieved."
    },
    {
      "name": "sysparm_limit",
      "in": "query",
      "schema": {
        "type": "string",
        "pattern": "^\\d+$"
      }
    },
    {
      "name": "displayvalue",
      "in": "query",
      "schema": {
        "type": "string",
        "pattern": "^(?:[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee]|[Aa][Ll][Ll])$"
      }
    },
    {
      "name": "displayvariables",
      "in": "query",
      "schema": {
        "type": "string",
        "pattern": "^(?:[Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "The matching records.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  },
                  "properties": {
                    "variables": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "name",
                          "question_text",
                          "type",
                          "value",
                          "order",
                          "children"
                        ],
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "question_text": {
                            "type": "string"
                          },
                          "type": {
                            "oneOf": [
                              {
                                "type": "integer"
                              },
                              {
                                "type": "string"
                              }
                            ],
                            "description": "The variable's numeric type code (6 = single line text)."
                          },
                          "value": {
                            "type": "string"
                          },
                          "order": {
                            "type": "integer"
                          },
                          "children": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zZBaGIzc7EPkA0ySnMn5eg/Ts12CWmUsFYAc4F0dD7J7w"
          }
        }
      }
    },
    "400": {
      "description": "Unknown table or an action other than getRecords.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/purplesuite.PlatformError"
          }
        }
      }
    },
    "401": {
      "description": "Missing or wrong Basic credential.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/purplesuite.PlatformError"
          }
        }
      }
    },
    "404": {
      "description": "Unknown PurpleSuite instance.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/purplesuite.PlatformError"
          }
        }
      }
    }
  }
}

Schemas and reusable components

schemas

purplesuite.TableRecord

{
  "type": "object",
  "description": "A table record. Columns depend on the table. Each value is a string when sysparm_display_value is false or true, an object carrying link/value for a reference field, or an object carrying display_value/value when sysparm_display_value=all.",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string"
      },
      {
        "type": "object",
        "properties": {
          "display_value": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "link": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    ]
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html"
}

purplesuite.TableRecordList

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/purplesuite.TableRecord"
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html"
}

purplesuite.TableRecordSingle

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "$ref": "#/components/schemas/purplesuite.TableRecord"
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_TableAPI.html"
}

purplesuite.PlatformError

{
  "type": "object",
  "required": [
    "error",
    "status"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "message",
        "detail"
      ],
      "properties": {
        "message": {
          "type": "string",
          "example": "No Record found"
        },
        "detail": {
          "type": "string",
          "example": "Record doesn't exist or ACL restricts the record retrieval"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "failure"
      ]
    }
  },
  "description": "ServiceNow's platform error envelope. The status codes and their meanings are vendor-documented; the JSON envelope itself is not printed on any reference page and is corroborated from real instance responses. See COVERAGE_LEDGER.md.",
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/bundle/zurich-api-reference/page/integrate/inbound-rest/reference/r_RESTAPIHTTPResponseCodes.html"
}

purplesuite.AggregateResult

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "stats": {
            "type": "object",
            "properties": {
              "count": {
                "type": "string"
              },
              "avg": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "min": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "max": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              },
              "sum": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            }
          },
          "groupby_fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                },
                "display_value": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_AggregateAPI.html"
}

purplesuite.AttachmentMetadata

{
  "type": "object",
  "properties": {
    "sys_id": {
      "type": "string"
    },
    "file_name": {
      "type": "string"
    },
    "table_name": {
      "type": "string"
    },
    "table_sys_id": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "size_bytes": {
      "type": "string"
    },
    "size_compressed": {
      "type": "string"
    },
    "compressed": {
      "type": "string"
    },
    "download_link": {
      "type": "string",
      "format": "uri"
    },
    "average_image_color": {
      "type": "string"
    },
    "image_width": {
      "type": "string"
    },
    "image_height": {
      "type": "string"
    },
    "hash": {
      "type": "string"
    },
    "sys_created_on": {
      "type": "string"
    },
    "sys_updated_on": {
      "type": "string"
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_AttachmentAPI.html"
}

purplesuite.AttachmentList

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/purplesuite.AttachmentMetadata"
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_AttachmentAPI.html"
}

purplesuite.AttachmentSingle

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "$ref": "#/components/schemas/purplesuite.AttachmentMetadata"
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_AttachmentAPI.html"
}

purplesuite.CmdbInstance

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "type": "object",
      "properties": {
        "attributes": {
          "$ref": "#/components/schemas/purplesuite.TableRecord"
        },
        "outbound_relations": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/purplesuite.CmdbRelation"
          }
        },
        "inbound_relations": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/purplesuite.CmdbRelation"
          }
        }
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/cmdb-instance-api.html"
}

purplesuite.CmdbRelation

{
  "type": "object",
  "properties": {
    "sys_id": {
      "type": "string"
    },
    "type": {
      "$ref": "#/components/schemas/purplesuite.CmdbReference"
    },
    "target": {
      "$ref": "#/components/schemas/purplesuite.CmdbReference"
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/cmdb-instance-api.html"
}

purplesuite.CmdbReference

{
  "type": "object",
  "properties": {
    "display_value": {
      "type": "string"
    },
    "link": {
      "type": "string"
    },
    "value": {
      "type": "string"
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/cmdb-instance-api.html"
}

purplesuite.CmdbMeta

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "parent": {
          "type": "string"
        },
        "icon": {
          "type": "string"
        },
        "icon_url": {
          "type": "string"
        },
        "is_extendable": {
          "type": "string"
        },
        "children": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "attributes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "element": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "max_length": {
                "type": "string"
              },
              "is_inherited": {
                "type": "string"
              },
              "is_mandatory": {
                "type": "string"
              },
              "is_display": {
                "type": "string"
              },
              "reference": {
                "type": "string"
              },
              "read_only": {
                "type": "string"
              }
            }
          }
        },
        "relationship_rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "parent": {
                "type": "string"
              },
              "child": {
                "type": "string"
              },
              "relation_type": {
                "type": "string"
              }
            }
          }
        },
        "identification_rules": {
          "type": "object",
          "properties": {
            "applies_to": {
              "type": "string"
            },
            "identifiers": {
              "type": "array",
              "items": {
                "type": "object"
              }
            },
            "related_rules": {
              "type": "array",
              "items": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/cmdb-meta-api.html"
}

purplesuite.ImportSetResult

{
  "type": "object",
  "description": "The Import Set API is the one in-scope operation whose envelope is not solely `result`: `import_set` and `staging_table` are siblings of it.",
  "required": [
    "import_set",
    "staging_table",
    "result"
  ],
  "properties": {
    "import_set": {
      "type": "string",
      "example": "ISET0010001"
    },
    "staging_table": {
      "type": "string",
      "example": "imp_user"
    },
    "result": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "transform_map": {
            "type": "string"
          },
          "table": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "display_value": {
            "type": "string"
          },
          "record_link": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "type": "string"
          },
          "sys_id": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/c_ImportSetAPI.html"
}

purplesuite.DataClasses

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "parent": {
            "type": "string"
          },
          "sys_id": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/data-classification-api.html"
}

purplesuite.CiLifecycleBoolean

{
  "type": "object",
  "description": "These operations document `result` as a bare boolean, not an object.",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "type": "boolean"
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/ci-lifecycle-management-api.html"
}

purplesuite.CiLifecycleResult

{
  "type": "object",
  "required": [
    "result"
  ],
  "properties": {
    "result": {
      "type": "object",
      "properties": {
        "errors": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "result": {
          "type": "string"
        },
        "operationalState": {
          "type": "string"
        },
        "ciActions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/ci-lifecycle-management-api.html"
}

purplesuite.ScimListResponse

{
  "type": "object",
  "required": [
    "schemas",
    "totalResults",
    "Resources"
  ],
  "properties": {
    "schemas": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
      ]
    },
    "totalResults": {
      "type": "integer"
    },
    "startIndex": {
      "type": "integer"
    },
    "itemsPerPage": {
      "type": "integer"
    },
    "Resources": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/scim-api.html"
}

purplesuite.ScimResource

{
  "type": "object",
  "required": [
    "schemas",
    "id"
  ],
  "properties": {
    "schemas": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "id": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    },
    "meta": {
      "type": "object",
      "properties": {
        "resourceType": {
          "type": "string"
        },
        "created": {
          "type": "string"
        },
        "lastModified": {
          "type": "string"
        },
        "location": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      }
    }
  },
  "additionalProperties": true,
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/scim-api.html"
}

purplesuite.ScimError

{
  "type": "object",
  "required": [
    "errors"
  ],
  "properties": {
    "errors": {
      "type": "object",
      "properties": {
        "details": {
          "type": "string"
        },
        "schemas": {
          "type": "string"
        },
        "scimType": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      }
    }
  },
  "description": "SCIM's error envelope is plural `errors` and has no `status: \"failure\"` sibling. It is not interchangeable with purplesuite.PlatformError.",
  "x-purplesuite-response-source": "https://www.servicenow.com/docs/r/zurich/api-reference/rest-apis/scim-api.html"
}

securitySchemes

basicAuth

{
  "type": "http",
  "scheme": "basic"
}

Document metadata and extensions

{
  "openapi": "3.0.3",
  "info": {
    "title": "ServiceNow JSON Data Retrieval (JSONv2) — getRecords",
    "version": "legacy",
    "description": "The legacy JSON Data Retrieval processor ({table}.do?JSONv2). It is not part of the REST API artifact the other profiles are derived from; this document is authored from the vendor's JSON Data Retrieval API pages, so it carries no artifact hash. Only sysparm_action=getRecords is served (matched in any letter case); every other action is 400. sysparm_query behaves as on the Table API. sysparm_record_count, the vendor's JSONv2 parameter, limits the number of records; sysparm_limit is accepted as on the Table API and applies when sysparm_record_count is absent. displayvalue=false (default) returns stored values, true returns display values, and all returns stored values plus dv_<field> display values; every column is a string. displayvariables=true adds each record's variables, for requested items (sc_req_item) only, ordered by order."
  },
  "security": [
    {
      "basicAuth": []
    }
  ]
}
Interactive API explorer (requires JavaScript)