{"id":21619026,"url":"https://github.com/usds/snow","last_synced_at":"2026-02-08T23:03:54.787Z","repository":{"id":37199848,"uuid":"460573707","full_name":"usds/snow","owner":"usds","description":"Python library for interacting with service now APIs","archived":false,"fork":false,"pushed_at":"2024-07-22T15:06:20.000Z","size":263,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-08-01T16:58:42.086Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-02-17T19:14:34.000Z","updated_at":"2025-05-12T06:11:14.000Z","dependencies_parsed_at":"2025-07-16T06:38:53.918Z","dependency_job_id":"3df9927b-5684-4684-963e-d2e13e88dedc","html_url":"https://github.com/usds/snow","commit_stats":{"total_commits":14,"total_committers":3,"mean_commits":4.666666666666667,"dds":0.5,"last_synced_commit":"2df5d8d03aae2d8d0e70eabd8370bf926fea3301"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/usds/snow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fsnow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fsnow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fsnow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fsnow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usds","download_url":"https://codeload.github.com/usds/snow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usds%2Fsnow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29248509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T22:49:53.206Z","status":"ssl_error","status_checked_at":"2026-02-08T22:49:51.384Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T23:07:40.283Z","updated_at":"2026-02-08T23:03:54.768Z","avatar_url":"https://github.com/usds.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Servicenow API Tools\n\nTools to help you build applications against the [ServiceNow REST\nAPI](https://docs.servicenow.com/bundle/rome-application-development/page/build/applications/concept/api-rest.html).\nThis is written in python, so most of the tools will be useful for building\npython applications.\n\n## Setup\n\nInstall [poetry](https://python-poetry.org), and run `poetry install`.\n\nTo verify everything is working, run `tox` to run all the tests\n\n## Python Client Libraries\n\n\u003e NOTE: If you look on github, you'll find many other python client libraries,\n\u003e such as [pysnow](https://github.com/rbw/pysnow). Those might be great as well.\n\u003e These have integration with the [Mock API Server](#mock-api-server) below, but\n\u003e you could still use other client libraries with the [Mock API Server\n\u003e Standalone Mode](#standalone-mode).\n\n\u003e NOTE: The [Mock API Server](#mock-api-server) is used to test the client\n\u003e libraries, but it is currently read-only, so any of the client code that does\n\u003e updates is not currently well tested.\n\n```python\nfrom servicenow_api_tools.clients import (\n    TableAPIClient, AggregateAPIClient, ServicenowRestEndpoint)\n\n# https://developer.servicenow.com/dev.do#!/reference/api/rome/rest/c_TableAPI\ntc = TableAPIClient(\n    # Expands to https://example.servicenowservices.com\n    endpoint=ServicenowRestEndpoint(\"example\"))\ntc.query(table=\"activity_type\", fields=[\"activity_name\"])\n\n# https://developer.servicenow.com/dev.do#!/reference/api/rome/rest/c_AggregateAPI\nac = AggregateAPIClient(\n    # Expands to https://example.servicenowservices.com\n    endpoint=ServicenowRestEndpoint(\"example\"))\nac.query(table=\"activity_type\", group_by=[\"activity_name\"])\n```\n\n## Server Schema Introspection\n\n[Introspection](https://graphql.org/learn/introspection/) (also known as [Reflection](https://docs.sqlalchemy.org/en/14/core/reflection.html)) is the process of extracting information about the server from the server itself, such as database schemas.\n\n\u003e NOTE: The introspection scripts will extract some information, even if you\n\u003e don't have permission to the `sys_dictionary` table. However, the scripts\n\u003e should have an option to use the `sys_dictionary` table directly if the user\n\u003e has permission to access that table, since that [appears to be the real way to\n\u003e get schema information from the\n\u003e API](https://community.servicenow.com/community?id=community_question\u0026sys_id=c8aa472ddb5cdbc01dcaf3231f96190a).\n\nTo quickly try this out, use the [Mock API Server Standalone\nMode](#standalone-mode):\n\n```shell\npoetry run python bin/mock_api_server.py \\\n    --data-directory tests/dataset \\\n    --schemas-directory tests/schemas\n```\n\nThen, in another tab, run:\n\n```\nmkdir newschemas\npoetry run python bin/update_fields_catalogs.py \\\n    --base-url http://localhost:8080 \\\n    --tables-file tests/schemas/introspection/tables.json \\\n    --extra-filters-file tests/schemas/introspection/filters.json \\\n    --extra-mapping-fields-file tests/schemas/introspection/extra-mapping-fields.json \\\n    --table-display-values-file tests/schemas/introspection/table-display-values.json \\\n    --enum-tables-file tests/schemas/introspection/enum-tables.json \\\n    --catalog-directory newschemas\nfor i in newschemas/*.json; do\n    echo $i\n    cat $i | jq\ndone\n```\n\nThis script takes a lot of human curated supplementary information, but can run\nwithout it. See the JSON files referenced in the example above for the format.\n\nNote that if `--catalog-directory` already has some json files in it, the script\nwill try to update those files with the new information found from the API, but\nwill try to preserve any human curated information.\n\n## Fake Dataset Generator\n\nThe dataset generate can generate a fake dataset based on a schema file. For\nlinks between tables, the reference fields will link to a random row in the\nreferenced table. You'll have to create a custom script similar to the one below\nif you want to add more constraints to the generated data.\n\n```shell\nmkdir generated_dataset\npoetry run python bin/generate_test_data.py \\\n    --output-directory generated_dataset \\\n    --schemas-directory tests/schemas\n```\n\n## Mock API Server\n\n### Standalone Mode\n\n```shell\npoetry run python bin/mock_api_server.py \\\n    --data-directory tests/dataset \\\n    --schemas-directory tests/schemas\n```\n\n### Using The Python Client\n\nEverything is the same as the [Python Client\nLibraries](#python-client-libraries) for accessing a remote endpoint, except\nthat you pass in a path to a local dataset and schema instead of remote host\ninformation:\n\n```python\nfrom servicenow_api_tools.mock_api_server import ServicenowRestEndpointLocalDataset\nendpoint = ServicenowRestEndpointLocalDataset(\n    path=\"tests/dataset\",\n    schema_dir=\"tests/schemas\")\n```\n\n## Reporting Tools\n\nThere are some basic reporting tools to generate a report with some statistics\nbased on a list of queries. To do this, create a JSON file that defines some\nattributes of your report. Try this example using the test definitions:\n\n```shell\npoetry run python bin/verify_stats_report_definition.py \\\n    --stats-report-definition-file \\\n    tests/reporting/stats-report-definition.json\nmkdir published_reports\npoetry run python bin/run_stats_report.py \\\n    --stats-report-definition-file \\\n    tests/reporting/stats-report-definition.json \\\n    --publish-directory published_reports \\\n    --base-url http://localhost:8080\nls published_reports\n```\n\nThere is also a utility to parse a CSV with URLs for queries created in the\nservicenow UI and turn that into a report definition:\n\n```shell\npoetry run python bin/generate_report_definition_columns_from_ui_urls.py \\\n    --ui-urls-file tests/reporting/parse_ui_url/urls.csv \\\n    --stats-report-definition-file generated-stats-report.json \\\n    --name-column column_name --url-column servicenow_ui_url\npoetry run python bin/verify_stats_report_definition.py \\\n    --stats-report-definition-file generated-stats-report.json\n```\n\nThere are tools to report on \"data quality\" that use the Table API instead of\nthe Aggregate API (so in theory, those tools in the future could dump datasets\nof \"malformed records\" for manual correction). However, these don't have a nice\ninterface right now, so see the tests for usage details.\n\n## Releasing\n\n1. run `tox` and resolve lint and test failures\n1. update the version in `pyproject.yoml`\n1. commit that change and merge it into main\n1. visit https://github.com/usds/snow/releases\n1. Draft new release\n1. create new tag that matches the version above\n1. roll up change descriptions into summarized change log\n1. publish\n\n## Contributors\n\nThe initial code import represents the work of many people from:\n- [U.S. Digital Service](https://usds.gov)\n- [Center for Analytics](https://www.state.gov/about-us-office-of-management-strategy-and-solutions/#cfa)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusds%2Fsnow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusds%2Fsnow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusds%2Fsnow/lists"}