diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 00000000..2d7d1dc5 Binary files /dev/null and b/.DS_Store differ diff --git a/assets/img/fac-logo-full.svg b/assets/img/fac-logo-full.svg new file mode 100644 index 00000000..0a7cc530 --- /dev/null +++ b/assets/img/fac-logo-full.svg @@ -0,0 +1,7 @@ + + + + + + + \ No newline at end of file diff --git a/assets/img/home/search_for_audits.png b/assets/img/home/search_for_audits.png new file mode 100644 index 00000000..3dff0c53 Binary files /dev/null and b/assets/img/home/search_for_audits.png differ diff --git a/assets/img/home/submit_an_audit.png b/assets/img/home/submit_an_audit.png new file mode 100644 index 00000000..3d16e831 Binary files /dev/null and b/assets/img/home/submit_an_audit.png differ diff --git a/assets/img/sprite.svg b/assets/img/sprite.svg new file mode 100644 index 00000000..b88718ae --- /dev/null +++ b/assets/img/sprite.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/.DS_Store b/src/.DS_Store new file mode 100644 index 00000000..5008ddfc Binary files /dev/null and b/src/.DS_Store differ diff --git a/src/_collections/resources/api/01-getting-started.md b/src/_collections/resources/api/01-getting-started.md new file mode 100644 index 00000000..4da5ea81 --- /dev/null +++ b/src/_collections/resources/api/01-getting-started.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: Getting started +description: Learn how to begin using the FAC API and test your endpoints. +link: 'api/getting-started' +--- \ No newline at end of file diff --git a/src/_collections/resources/api/02-postgrest.md b/src/_collections/resources/api/02-postgrest.md new file mode 100644 index 00000000..25897f58 --- /dev/null +++ b/src/_collections/resources/api/02-postgrest.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: PostgREST server tools +description: The FAC uses PostgREST for our API server. Use their documentation for more help. +link: 'https://postgrest.org/en/v12/' +--- \ No newline at end of file diff --git a/src/_collections/resources/api/03-data-dictionary.md b/src/_collections/resources/api/03-data-dictionary.md new file mode 100644 index 00000000..a2244002 --- /dev/null +++ b/src/_collections/resources/api/03-data-dictionary.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: Data dictionary +description: Get an overview of how the FAC API data compares to the historical Census data. +link: 'api/dictionary' +--- \ No newline at end of file diff --git a/src/_collections/resources/api/04-rollup.md b/src/_collections/resources/api/04-rollup.md new file mode 100644 index 00000000..f5326fa2 --- /dev/null +++ b/src/_collections/resources/api/04-rollup.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: Rollup fields +description: The FAC API combines some data fields that were standalone with the Census Bureau. This guide outlines these fields and shows how to use the FAC API to get the same data. +link: 'api/rollup' +--- \ No newline at end of file diff --git a/src/_collections/resources/api/05-data-differences.md b/src/_collections/resources/api/05-data-differences.md new file mode 100644 index 00000000..f7856a07 --- /dev/null +++ b/src/_collections/resources/api/05-data-differences.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: Data differences +description: Data submitted to the old Census FAC had different field names compared to the GSA FAC. This list outlines the differences between the historical data and new FAC data. +link: 'api/differences' +--- \ No newline at end of file diff --git a/src/_collections/resources/api/06-results-management.md b/src/_collections/resources/api/06-results-management.md new file mode 100644 index 00000000..0ceaca13 --- /dev/null +++ b/src/_collections/resources/api/06-results-management.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: Results management +description: Tips for working within the API's request limit to to retrieve more than 20,000 results at a time. +link: 'api/results-management' +--- \ No newline at end of file diff --git a/src/_collections/resources/api/07-api-versioning.md b/src/_collections/resources/api/07-api-versioning.md new file mode 100644 index 00000000..de2b4dec --- /dev/null +++ b/src/_collections/resources/api/07-api-versioning.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: API versioning +description: Read our change management policy for updating the API. +link: 'api/versioning/' +--- \ No newline at end of file diff --git a/src/_collections/resources/api/08-terms.md b/src/_collections/resources/api/08-terms.md new file mode 100644 index 00000000..29943a83 --- /dev/null +++ b/src/_collections/resources/api/08-terms.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: Terms & conditions +description: Read the terms and conditions of using the FAC API. +link: 'api/terms' +--- \ No newline at end of file diff --git a/src/_collections/resources/api/09-tribal.md b/src/_collections/resources/api/09-tribal.md new file mode 100644 index 00000000..6134cb2d --- /dev/null +++ b/src/_collections/resources/api/09-tribal.md @@ -0,0 +1,6 @@ +--- +tags: resources, api +header: Tribal data access +description: Use the API to access data and Single Audit Reports that Tribes and Tribal Organizations have chosen to suppress. +link: 'api/tribal' +--- \ No newline at end of file diff --git a/src/_collections/resources/audit_submission/01-submission-guide.md b/src/_collections/resources/audit_submission/01-submission-guide.md new file mode 100644 index 00000000..344b2897 --- /dev/null +++ b/src/_collections/resources/audit_submission/01-submission-guide.md @@ -0,0 +1,6 @@ +--- +tags: resources, submission +header: Submission guide +description: An illustrated guide to the single audit process, from login to final submission. +link: 'audit-resources/how-to' +--- diff --git a/src/_collections/resources/audit_submission/02-SF-SAC.md b/src/_collections/resources/audit_submission/02-SF-SAC.md new file mode 100644 index 00000000..284c3e6b --- /dev/null +++ b/src/_collections/resources/audit_submission/02-SF-SAC.md @@ -0,0 +1,6 @@ +--- +tags: resources, submission +header: SF-SAC & instructions +description: Download the SF-SAC workbooks and find instructions for completing them. +link: 'audit-resources/sf-sac/' +--- diff --git a/src/_collections/resources/audit_submission/03-managing-access.md b/src/_collections/resources/audit_submission/03-managing-access.md new file mode 100644 index 00000000..9a481603 --- /dev/null +++ b/src/_collections/resources/audit_submission/03-managing-access.md @@ -0,0 +1,6 @@ +--- +tags: resources, submission +header: Managing submission access +description: Learn how to make changes to your certifying officials and audit submission editors. +link: 'audit-resources/user-access/' +--- diff --git a/src/_collections/resources/audit_submission/04-federal-program-contacts.md b/src/_collections/resources/audit_submission/04-federal-program-contacts.md new file mode 100644 index 00000000..90d4e867 --- /dev/null +++ b/src/_collections/resources/audit_submission/04-federal-program-contacts.md @@ -0,0 +1,6 @@ +--- +tags: resources, submission +header: Federal program contacts +description: Find your federal agency single audit contacts, key management liaisons, and program contacts. +link: 'audit-resources/program-contacts/' +--- diff --git a/src/_collections/resources/audit_submission/05-burden-statement.md b/src/_collections/resources/audit_submission/05-burden-statement.md new file mode 100644 index 00000000..678d9133 --- /dev/null +++ b/src/_collections/resources/audit_submission/05-burden-statement.md @@ -0,0 +1,6 @@ +--- +tags: resources, submission +header: Burden statement +description: The FAC follows the Paperwork Reduction Act. See the estimated burden of completing the single audit submission process. +link: 'audit-resources/burden-statement/' +--- diff --git a/src/_collections/resources/search/01-search-filters.md b/src/_collections/resources/search/01-search-filters.md new file mode 100644 index 00000000..1222babd --- /dev/null +++ b/src/_collections/resources/search/01-search-filters.md @@ -0,0 +1,6 @@ +--- +tags: resources, search +header: Search filters +description: Learn about the FAC’s search filters and how to use them. +link: 'search-resources/filters' +--- \ No newline at end of file diff --git a/src/_collections/resources/search/02-search-results.md b/src/_collections/resources/search/02-search-results.md new file mode 100644 index 00000000..21e5edf0 --- /dev/null +++ b/src/_collections/resources/search/02-search-results.md @@ -0,0 +1,6 @@ +--- +tags: +header: Results tables definitions +description: This guide explains the table headers and data definitions for FAC search results. +link: '' +--- \ No newline at end of file diff --git a/src/_collections/resources/search/03-tribal-audits.md b/src/_collections/resources/search/03-tribal-audits.md new file mode 100644 index 00000000..56df8ef4 --- /dev/null +++ b/src/_collections/resources/search/03-tribal-audits.md @@ -0,0 +1,6 @@ +--- +tags: resources, search +header: Tribal audits +description: Accessing audit data belonging to Tribes and Tribal entities sometimes requires special permissions. These instructions guide you through how to access these audits. +link: 'search-resources/tribal/' +--- \ No newline at end of file diff --git a/src/_collections/updates/2023-09-08-acee.md b/src/_collections/updates/2023-09-08-acee.md index 805e364a..4b5a9250 100644 --- a/src/_collections/updates/2023-09-08-acee.md +++ b/src/_collections/updates/2023-09-08-acee.md @@ -2,4 +2,4 @@ tags: submitters date: "2023-09-08" --- -At this time, the FAC is not accepting submissions for Alternative Compliance Examination Engagements (ACEE). [The Office of Management and Budget (OMB) has granted an automatic extension for these entities for Audit Year 2023]({{ config.baseUrl }}info/announcements). \ No newline at end of file +At this time, the FAC is not accepting submissions for Alternative Compliance Examination Engagements (ACEE). [The Office of Management and Budget (OMB) has granted an automatic extension for these entities for Audit Year 2023]({{ config.baseUrl }}omb). \ No newline at end of file diff --git a/src/_collections/walkthrough/03-create.md b/src/_collections/walkthrough/03-create.md index f94a5ac9..a90b57d9 100644 --- a/src/_collections/walkthrough/03-create.md +++ b/src/_collections/walkthrough/03-create.md @@ -6,4 +6,4 @@ image: walkthrough_03.png Once logged in, you can create a new audit and see the status of audits currently in progress. You'll be able to view the status of all audits associated with your email address. -If you don't see the audits you expect after signing in, have the audit editor confirm the audit lists the email address on your [Login.gov account](https://login.gov/create-an-account/). They can do this by going to the [manage user access]({{ config.baseUrl }}resources/instructions/user-access) section of the audit. +If you don't see the audits you expect after signing in, have the audit editor confirm the audit lists the email address on your [Login.gov account](https://login.gov/create-an-account/). They can do this by going to the [manage user access]({{ config.baseUrl }}audit-resources/user-access) section of the audit. diff --git a/src/_collections/walkthrough/06-audit-access.md b/src/_collections/walkthrough/06-audit-access.md index 50834a76..6e43e50d 100644 --- a/src/_collections/walkthrough/06-audit-access.md +++ b/src/_collections/walkthrough/06-audit-access.md @@ -8,7 +8,7 @@ This is where you will list the auditee and auditor certifying officials, as wel Enter the email address for everyone who will need to edit the audit submission. You should include your email address as well. **Make sure these email addresses match the email addresses connected to the users' Login.gov accounts.** -If you need to make changes to users after creating the audit submission, you can find instructions on [our manage user access page]({{ config.baseUrl }}resources/instructions/user-access). +If you need to make changes to users after creating the audit submission, you can find instructions on [our manage user access page]({{ config.baseUrl }}audit-resources/user-access). The FAC doesn't notify users when they've been added to a submission. We recommend notifying them yourself. diff --git a/src/_collections/walkthrough/11-workbook.md b/src/_collections/walkthrough/11-workbook.md index d007c380..2033b648 100644 --- a/src/_collections/walkthrough/11-workbook.md +++ b/src/_collections/walkthrough/11-workbook.md @@ -6,4 +6,4 @@ image: walkthrough_11.png Next you'll upload the SF-SAC. This is a series of XLSX workbooks that collects the data on any audit findings, corrective action plans, etc. -We've provided [download links and instructions]({{ config.baseUrl }}resources/workbooks) for each of these workbooks. We recommend reading the instructions carefully as you complete the SF-SAC. +We've provided [download links and instructions]({{ config.baseUrl }}audit-resources/sf-sac) for each of these workbooks. We recommend reading the instructions carefully as you complete the SF-SAC. diff --git a/src/_data/global.yaml b/src/_data/global.yaml index b43c05ca..43134321 100644 --- a/src/_data/global.yaml +++ b/src/_data/global.yaml @@ -2,33 +2,35 @@ site_name: Federal Audit Clearinghouse navigation: primary: - - text: Data - id: data + - text: Audit search + id: search links: - - text: Search audits + - text: Search href: 'https://app.fac.gov/dissemination/search/' - - text: Resources - href: 'data/resources' - - text: API - href: 'developers' - - text: Audit Submission + - text: Search resources + href: 'search-resources' + - text: Developer resources + href: 'api' + - text: Audit submission id: audits - href: 'audits' - - text: Policy & News + links: + - text: Submission resources + href: 'audit-resources' + - text: Updates & News id: news links: - - text: Policy - href: 'policy' - - text: OMB Announcements - href: 'info/announcements' - text: FAC updates - href: 'info/updates' - - text: Support - id: support + href: 'updates' + - text: OMB announcements + href: 'omb' + - text: System status + href: 'status' + - text: Policy & Compliance + id: policy links: - - text: Help center - href: 'https://support.fac.gov/hc/en-us' - target: '_blank' - - text: Welcome - href: 'welcome' - + - text: Compliance + href: 'compliance' + - text: Uniform guidance + href: 'uniform-guidance' + - text: Burden statement + href: 'audit-resources/burden-statement' \ No newline at end of file diff --git a/src/_includes/header.njk b/src/_includes/header.njk index 339da8a6..b96aec20 100644 --- a/src/_includes/header.njk +++ b/src/_includes/header.njk @@ -1,97 +1,114 @@ -Skip to main content -{% include 'components/usa-banner.njk' %} -{#
-
This application is currently under active development. Thank you for helping to improve the FAC by participating in user testing.
-
#}
-
-
-
- - +
+ +
+
+ Audit search is currently limited to UEI-only. For more information, visit the FAC status page.
+
-
+ -
-
+ + + + \ No newline at end of file diff --git a/src/_includes/layout.njk b/src/_includes/layout.njk index a9c6ed07..40a28f49 100644 --- a/src/_includes/layout.njk +++ b/src/_includes/layout.njk @@ -14,6 +14,7 @@ + {% include './components/usa-banner.njk' %} {% include 'header.njk' %}
{{ content | safe }} diff --git a/src/_includes/redirect.njk b/src/_includes/redirect.njk new file mode 100644 index 00000000..5352e640 --- /dev/null +++ b/src/_includes/redirect.njk @@ -0,0 +1,10 @@ + + + + + + + + You are being redirected to {{ config.baseUrl }}{{ redirect.to }} + + \ No newline at end of file diff --git a/src/_includes/resources_page.njk b/src/_includes/resources_page.njk new file mode 100644 index 00000000..4ab9bef2 --- /dev/null +++ b/src/_includes/resources_page.njk @@ -0,0 +1,48 @@ +--- +layout: layout.njk +--- + +
+ {# Title and description, separated by a horizontal rule. #} +

{{header}}

+
+
{{content | safe}}
+ + {# Cards are generated from the current pages 'collectionName'. + To add more cards, navigate to collections and ensure the tags match up with the pages collectionName. #} +
    + {% set indexList = collections[collectionName] %} + {% for item in indexList %} +
  • +
    +
    +

    {{item.data.header}}

    +
    +
    +

    + {{item.data.description}} +

    +
    +
    + {% if "https" in item.data.link %} + View + {% else %} + View + {% endif %} +
    +
    +
    • + {% endfor %} +
+ + {# Full-width FAQ page button, common to resource pages. #} + +

+ Still have questions? + Visit our FAQ page + +

+ +
diff --git a/src/developers/dictionary.md b/src/api/dictionary.md similarity index 100% rename from src/developers/dictionary.md rename to src/api/dictionary.md diff --git a/src/developers/differences.md b/src/api/differences.md similarity index 100% rename from src/developers/differences.md rename to src/api/differences.md diff --git a/src/developers/getting-started.md b/src/api/getting-started.md similarity index 100% rename from src/developers/getting-started.md rename to src/api/getting-started.md diff --git a/src/api/index.md b/src/api/index.md new file mode 100644 index 00000000..6c1c42c5 --- /dev/null +++ b/src/api/index.md @@ -0,0 +1,24 @@ +--- +layout: resources_page.njk +title: FAC API resources +header: API resources +collectionName: resources, api +faqLink: https://support.fac.gov/hc/en-us +meta: + name: FAC API resources + description: Find resources for making the most of the FAC API to download single audit data. +--- + +The FAC API shares public data from submitted audit reports. + +To interact with the API, you will need an API key from Data.gov. To get a Data.gov API key, [fill out the Data.gov API key signup form](https://api.data.gov/signup/). This is free and requires a valid email address. When you receive your API key, treat it like any other credential: + +- Don't share your key with other users. +- Don't commit your key into a repository alongside your code. +- Don't store your key in a shared drive where other users have access. +- Don't share your key in helpdesk requests or any other communication. + +Once you have your API key, you can begin exploring the API. Use the resources below to learn more about the API's capabilities. + +For more information on the FAC API and the information it provides, see our [terms and conditions]({{ config.baseUrl }}api/terms/). + diff --git a/src/developers/retrieve-many.md b/src/api/results-management.md similarity index 100% rename from src/developers/retrieve-many.md rename to src/api/results-management.md diff --git a/src/api/retrieve-many.md b/src/api/retrieve-many.md new file mode 100644 index 00000000..0dd5e5df --- /dev/null +++ b/src/api/retrieve-many.md @@ -0,0 +1,118 @@ +--- +layout: home.njk +title: Retrieving many results from the FAC API +meta: + name: Retrieving many results from the FAC API + description: How to use pagination +--- + +# Retriving many results from the FAC API + +Every year, roughly 40,000-50,000 audits are submitted to the FAC. Given that there is data in the FAC database going back to 2016, that means there are more than 200,000 audits, with more than 2.5M `federal_awards` records. + +To keep the FAC running smoothly for all users, we limit requests to 20,000 results at a time. So, how do you search and retrieve more than that? + +## Consider more focused queries + +Our first recommendation is *not* to issue queries that return tens or hundreds of thousands of results. You will likely find the experience to be non-performant. + +Wherever possible, we recommend that partners build systems that issue small, restrictive queries. For small agencies, asking for all of the audits in a month or year may work well; for large agencies, it may not. Therefore, we recommend you consider issuing queries for a single day's or week's worth of audits. While this may mean more queries, each individual request will be more performant. + +### Example + +Assume you want to retrieve all of the awards for which your agency is cognizant in a given year. If you were to do this in SQL, it might be a `JOIN` across two tables. This would be slow, as you would be querying the `general` table, which has hundreds of thousands of rows, against the `federal_awards` table, which has millions of rows. + +Instead, you can issue a sequence of small queries via the API. The following example demonstrates how this might work using Python: + +```python +# Create a function that gets a list of all audits for a +# given agency in a given year. Then, for each audit, +# request its corresponding awards and add them to a list. +def retrieve_cog_awards(year, agency): + general_url = f"{FAC_API_BASE}/general" + federal_awards_url = f"{FAC_API_BASE}/federal_awards" + general_response = requests.get(general_url, + params={ + "select": "report_id", + "audit_year": f"eq.{year}", + "cognizant_agency": f"eq.{agency}" + }, + headers={ "X-API-Key": FAC_API_KEY }) + + print(f"Agency[{agency}] Records: {len(general_response.json())}") + report_ids = set(map(lambda o: o["report_id"], res.json())) + awards = [] + for report_id in report_ids: + awards_response = requests.get(federal_awards_url, + params={ + "report_id": f"eq.{report_id}" + }, + headers={ "X-API-Key": FAC_API_KEY }) + print(f"\treport_id[{report_id}]: {len(awards_response.json())} awards") + awards.append(awards_response.json()) + + return awards + +# Call your function +treasury = retrieve_cog_awards(2020, 21) +``` + +This example prints out the following: + +``` +Agency[21] Records: 18 + report_id[2020-12-CENSUS-0000187886]: 42 awards + report_id[2020-12-CENSUS-0000182305]: 71 awards + report_id[2020-12-CENSUS-0000187776]: 12 awards + report_id[2020-06-CENSUS-0000242068]: 1 awards + report_id[2020-09-CENSUS-0000136906]: 68 awards + report_id[2020-11-CENSUS-0000138628]: 45 awards + report_id[2020-12-CENSUS-0000251225]: 1 awards + report_id[2020-12-CENSUS-0000252841]: 1 awards + report_id[2020-12-CENSUS-0000166851]: 46 awards + report_id[2020-12-CENSUS-0000208943]: 6 awards + report_id[2020-09-CENSUS-0000074286]: 7 awards + report_id[2020-12-CENSUS-0000128618]: 3 awards + report_id[2020-12-CENSUS-0000230310]: 2 awards + report_id[2020-11-CENSUS-0000138705]: 48 awards + report_id[2020-12-CENSUS-0000022772]: 4 awards + report_id[2020-12-CENSUS-0000188333]: 36 awards + report_id[2020-12-CENSUS-0000258107]: 2 awards + report_id[2020-06-CENSUS-0000200809]: 11 awards +``` + +In the first query against `general`, you discover that Treasury was the cognizant agency 18 audits in 2020. In the second set of queries, you requested the `federal_awards` for each audit, where each query returned between 1 and 71 results. + +## Use pagination + +If you cannot restrict your queries in the manner described above, or if your focused queries still return more than 20,000 results, you will need to use pagination to get retrieve all of your results. + +There are two ways to do this. The first is to use the query parameters `limit` and `offset`. The `limit` parameter determines the maximum number of results that will be included in each "page" of results. The `offset` parameter tells the API where to begin its count of results. For example, if you believe a query is going to return 35K results, you could make the following requests in a sequence of queries to get all of your results: + +``` +...url.../...table...?limit=4999&offset=0 +...url.../...table...?limit=4999&offset=5000 +...url.../...table...?limit=4999&offset=10000 +...url.../...table...?limit=4999&offset=15000 +...url.../...table...?limit=4999&offset=20000 +...url.../...table...?limit=4999&offset=25000 +...url.../...table...?limit=4999&offset=30000 +``` + + You can terminate your loop in one of two ways: + +1. Use the [headers that PostgREST supplies to determine where you are in your pagination](https://postgrest.org/en/stable/references/api/pagination_count.html), and stop at the appropriate time. +2. Stop when you get no results. With this method, there is some danger your loop could run forever, consuming your entire API query limit. We recommend you always use an upper limit to prevent this issue. + +The following is an example of how you could use both methods to terminate the loop using Python: + +```python +# Get results from count 0 to 35,000, going in increments of 5,000 +for offset in range(0, 35000, 5000): + ... + results = requests.get(... query using the `offset` variable ...) + if results == []: + break + else: + ... +``` diff --git a/src/developers/rollups.md b/src/api/rollup.md similarity index 94% rename from src/developers/rollups.md rename to src/api/rollup.md index 5227aa6f..94a858b3 100644 --- a/src/developers/rollups.md +++ b/src/api/rollup.md @@ -23,14 +23,14 @@ rollups: rolled: QCOSTS orig: QCOSTS from Findings table criteria: "If any of the auditee's findings have QCOSTS = Y (QCOSTS from Findings Table)" - output: Then QCOSTS in General table = Y otherwise QCOSTS = N + output: Then QCOSTS in General table = Y, otherwise QCOSTS = N censusdesc: Indicate whether or not the audit disclosed any known questioned costs. code: https://github.com/GSA-TTS/fac-api-examples/tree/main/rollups/03-qcosts CYFINDINGS: rolled: CYFINDINGS orig: Findings Table criteria: If any records in the Findings table - output: "CYFINDINGS=Y" + output: "CYFINDINGS = Y" censusdesc: > Indicate whether or not current year findings affecting direct funds were reported code: https://github.com/GSA-TTS/fac-api-examples/tree/main/rollups/04-cyfindings @@ -39,7 +39,7 @@ rollups: orig: TYPEREPORT_MP from CFDA (now `federal_awards`) table criteria: Combines all values (U, D, A, S) entered in the TYPEREPORT_MP field from CFDA output: > - "U" if all TYPEREPORT_MP = U or the non-"U" values listed once + "U" if all TYPEREPORT_MP = U, overwise all non-U values listed once censusdesc: Type of report issued on the major program compliance code: https://github.com/GSA-TTS/fac-api-examples/tree/main/rollups/050-typereportmp MATERIALWEAKNESS_MP: @@ -62,7 +62,7 @@ rollups: rolled: PYSCHEDULE orig: Question 3.d. on the Audit Info tab criteria: If there is any number other than 00 listed - output: PYSCHEDULE=Y + output: PYSCHEDULE = Y censusdesc: > Indicate whether or not the report includes a Summary Schedule of Prior Year Audit Findings code: https://github.com/GSA-TTS/fac-api-examples/tree/main/rollups/08-pysched @@ -101,7 +101,7 @@ The code for this tutorial can be found in the [fac-api-examples](https://github * [REPORTABLECONDITION_MP](#REPORTABLECONDITION_MP) * [PYSCHEDULE](#PYSCHEDULE) -## Example: ALN (previously CFDA) +

Example: ALN (previously CFDA)

{{ rollup("ALN") }} @@ -121,7 +121,7 @@ If you run the sample code provided above, you should get: 2022-12-GSAFAC-0000001061 ['16.557', '16.524', '16.841', '16.526', '93.497', '16.575'] ``` -## Example: Given a report ID, calculate COGOVER +

Example: Given a report ID, calculate COGOVER

{{ rollup("COGOVER") }} @@ -139,7 +139,7 @@ If you run the sample code provided above, you should get: 2022-12-GSAFAC-0000001061 O ``` -## Example: Are there questioned costs? +

Example: Are there questioned costs?

{{ rollup("QCOSTS") }} @@ -178,7 +178,7 @@ If you run the sample code provided above, you should get the following output. ... ``` -## Example: Are there current year findings? +

Example: Are there current year findings?

{{ rollup("CYFINDINGS") }} @@ -197,7 +197,7 @@ If you run the sample code provided above, you should get the following output. 2023-06-GSAFAC-0000001206 N ``` -## Example: Major program report type? +

Example: Major program report type?

{{ rollup("TYPEREPORT_MP") }} @@ -237,7 +237,7 @@ If you run the sample code provided above, you should get: 2023-06-GSAFAC-0000000967 U ``` -## Example: +

Example: Material weakness

{{ rollup("MATERIALWEAKNESS_MP") }} @@ -277,7 +277,7 @@ If you run the sample code provided above, you should get: 2023-06-GSAFAC-0000001644 N ``` -## Example: +

Example: Reportable condition

{{ rollup("REPORTABLECONDITION_MP") }} @@ -310,7 +310,7 @@ If you run the sample code provided above, you should get: 2023-06-GSAFAC-0000001644 N ``` -## Example: Previous year findings? +

Example: Previous year findings?

{{ rollup("PYSCHEDULE") }} @@ -320,14 +320,14 @@ In the Python example provided, you can do this by converting the list to a set, ```python # If there is any number other than 00 listed - # Then PYSCHEDULE=Y + # Then PYSCHEDULE = Y set_of_agencies = set() for find in json: numbers = list(filter(lambda n: n != "00", [n.strip() for n in find[AWPF].split(',')] )) set_of_agencies.update(numbers) - # An empty set is "false" in python + # An empty set is "false" in Python return bool(set_of_agencies) ``` diff --git a/src/developers/terms.md b/src/api/terms.md similarity index 100% rename from src/developers/terms.md rename to src/api/terms.md diff --git a/src/api/tribal.md b/src/api/tribal.md new file mode 100644 index 00000000..16cf4109 --- /dev/null +++ b/src/api/tribal.md @@ -0,0 +1,165 @@ +--- +layout: home.njk +title: Accessing suppressed Tribal data via the API +meta: + name: Accessing Tribal data via the API + description: How to access suppressed SF-SAC data. +--- + +# Accessing suppressed Tribal data via the API + +Tribes and Tribal organizations have the option, per [2 CFR 200.512(b)(2)](https://www.ecfr.gov/current/title-2/part-200/subpart-F#p-200.512(b)(2)), to suppress their Single Audit data. + +For Tribes and Tribal organizations who choose to protect their data, the API will show `is_public` in the `/general` endpoint set to `False`. + +If you believe you should have access to these audits, you will need to request a copy of the Tribal API Access Agreement via the [helpdesk](https://support.fac.gov/hc/en-us). + +## Working with the data + +Your Tribal access API key will let you request a one-time access token. You'll use this token to download suppressed reports. + +Once you have your token, use the instructions below to complete your API set-up: + +### Step 1: Fetch data about a submission + +This step retrieves data about a submission based on the provided report ID. + +#### Endpoint + +`GET /general?report_id=eq.{report_id}` + +#### Parameters + +* `report_id` (required): The ID of the report you want to fetch data for. + +#### Headers + +* `content-profile`: Set to `api_v1_1_0`. +* `x-api-key`: Your Tribal API key. +* `content-type`: Set to `application/json`. + +#### Response + +* `200 OK`: Returns JSON data containing information about the submission. +* Error Responses: + * `404 Not Found`: If the report ID does not exist. + * `401 Unauthorized`: If the request lacks proper authentication. + +#### Code + +``` +import requests + +def fetch_submission_data(report_id): + url = '/api.fac.gov/general?report_id=eq.{report_id}' + response = requests.get(url, headers=headers) + if response.status_code == 200: + submission_data = response.json() + return submission_data +``` + +### Step 2: Request file access + +After fetching submission data, you can request access to download the associated file. + +#### Endpoint + +`POST /api.fac.gov/rpc/request_file_access` + +#### Parameters + +* `report_id (required)`: The ID of the report for which you're requesting file access. + +#### Headers + +* `content-profile`: Set to `api_v1_1_0`. +* `x-api-key`: Your Tribal API key. +* `content-type`: Set to `application/json`. + +#### Response + +* `200 OK`: Returns access information, including an access UUID. +* Error Responses: + * `401 Unauthorized`: If the request lacks proper authentication. + * `404 Not Found`: If the report ID does not exist. + +#### Code + +``` +import json +import requests + +def request_file_access(report_id): + url = '/api.fac.gov/rpc/request_file_access' + headers = { + 'content-Profile': 'admin_api_v1_1_0', + 'x-api-key': f'{API_KEY}', + 'Content-Type': 'application/json', + } + payload = json.dumps({ + "report_id": f'{report_id}' + }) + response = requests.post(url, headers=headers, data=payload) + if response.status_code == 200: + access_info = response.json() + # `access_info` is a JSON object containing + # a one-time token needed to download a suppressed SAR. + return access_info +``` + +### Step 3: Download the file + +Once you have the access information, you can use it to download the associated file. Use the access UUID that was retrieved in the last step to get the file. + +#### Endpoint: +`GET /app.fac.gov/dissemination/report/pdf/ota/{access_uuid}` + +#### Parameters + +`access_uuid (required)`: The access UUID obtained from the `/request_file_access` endpoint. + +#### Headers + +None required; this is a straight `GET` request to download a file. + +#### Response + +* `200 OK`: Downloads the file successfully. +* Error Responses: + * `401 Unauthorized`: If the request lacks proper authentication. + * `404 Not Found`: If the access UUID is invalid or the file doesn't exist. + +Other HTTP status codes indicate various error scenarios. + +#### Code + +``` +import requests + +############################################## +# Note we download the PDF from `app.fac.gov`, +# not from `api.fac.gov`. +############################################## +def download_file(access_info): + access_uuid_value = access_info.get('access_uuid') + url = '/app.fac.gov/dissemination/report/pdf/ota/{access_uuid_value}' + payload = {} + try: + response = requests.get(url, headers=headers, data=payload) + if response.status_code == 200: + with open("downloaded_file.pdf", "wb") as pdf_file: + pdf_file.write(response.content) + print("File downloaded successfully.") + else: + print("Failed to download file. Status code:", response.status_code) + print("Response content:", response.text) + except Exception as e: + print("Error occurred while downloading file:", e) +``` + +### Notes + +- The access token is only good for 1 minute. +- When you access the URL at `pdf/ota/{access_uuid}`, you'll be redirected to a temporary Amazon AWS URL. This is also only good for 1 minute or less. + +**These temporary URLs can't be stored or cached.** Every time you want to access a suppressed report via the API, you'll need to go through the steps outlined above. \ No newline at end of file diff --git a/src/developers/api-versioning.md b/src/api/versioning.md similarity index 100% rename from src/developers/api-versioning.md rename to src/api/versioning.md diff --git a/src/resources/burden-statement.md b/src/audit-resources/burden-statement.md similarity index 100% rename from src/resources/burden-statement.md rename to src/audit-resources/burden-statement.md diff --git a/src/resources/instructions/index.md b/src/audit-resources/how-to.md similarity index 100% rename from src/resources/instructions/index.md rename to src/audit-resources/how-to.md diff --git a/src/audit-resources/index.md b/src/audit-resources/index.md new file mode 100644 index 00000000..75afd2c4 --- /dev/null +++ b/src/audit-resources/index.md @@ -0,0 +1,12 @@ +--- +layout: resources_page.njk +title: Audit submission resources +header: Audit submission resources +collectionName: resources, submission +faqLink: https://support.fac.gov/hc/en-us/categories/18291221922829-Audit-Submission +meta: + name: Audit submission resources + description: Tools and resources for successfully submiting your single audit package to the Federal Audit Clearinghouse. +--- + +We’re here to help make your audit submission as easy as possible. Use our submission resources to complete the process. diff --git a/src/resources/agency-contacts.md b/src/audit-resources/program-contacts.md similarity index 100% rename from src/resources/agency-contacts.md rename to src/audit-resources/program-contacts.md diff --git a/src/resources/workbooks/additional-eins-workbook.md b/src/audit-resources/sf-sac/additional-eins-workbook.md similarity index 100% rename from src/resources/workbooks/additional-eins-workbook.md rename to src/audit-resources/sf-sac/additional-eins-workbook.md diff --git a/src/resources/workbooks/additional-ueis-workbook.md b/src/audit-resources/sf-sac/additional-ueis-workbook.md similarity index 100% rename from src/resources/workbooks/additional-ueis-workbook.md rename to src/audit-resources/sf-sac/additional-ueis-workbook.md diff --git a/src/resources/workbooks/corrective-action-plan.md b/src/audit-resources/sf-sac/corrective-action-plan.md similarity index 100% rename from src/resources/workbooks/corrective-action-plan.md rename to src/audit-resources/sf-sac/corrective-action-plan.md diff --git a/src/resources/workbooks/federal-awards-audit-findings-text.md b/src/audit-resources/sf-sac/federal-awards-audit-findings-text.md similarity index 100% rename from src/resources/workbooks/federal-awards-audit-findings-text.md rename to src/audit-resources/sf-sac/federal-awards-audit-findings-text.md diff --git a/src/resources/workbooks/federal-awards-audit-findings.md b/src/audit-resources/sf-sac/federal-awards-audit-findings.md similarity index 100% rename from src/resources/workbooks/federal-awards-audit-findings.md rename to src/audit-resources/sf-sac/federal-awards-audit-findings.md diff --git a/src/resources/workbooks/federal-awards.md b/src/audit-resources/sf-sac/federal-awards.md similarity index 100% rename from src/resources/workbooks/federal-awards.md rename to src/audit-resources/sf-sac/federal-awards.md diff --git a/src/resources/workbooks/index.md b/src/audit-resources/sf-sac/index.md similarity index 100% rename from src/resources/workbooks/index.md rename to src/audit-resources/sf-sac/index.md diff --git a/src/resources/workbooks/notes-to-sefa.md b/src/audit-resources/sf-sac/notes-to-sefa.md similarity index 100% rename from src/resources/workbooks/notes-to-sefa.md rename to src/audit-resources/sf-sac/notes-to-sefa.md diff --git a/src/resources/workbooks/secondary-auditors-workbook.md b/src/audit-resources/sf-sac/secondary-auditors-workbook.md similarity index 100% rename from src/resources/workbooks/secondary-auditors-workbook.md rename to src/audit-resources/sf-sac/secondary-auditors-workbook.md diff --git a/src/resources/instructions/user-access.md b/src/audit-resources/user-access.md similarity index 100% rename from src/resources/instructions/user-access.md rename to src/audit-resources/user-access.md diff --git a/src/audits/index.md b/src/audits/index.md deleted file mode 100644 index 665a89d0..00000000 --- a/src/audits/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: home.njk -title: Single audit submission resources -meta: - name: Single audit submission resources - description: Find resources and instructions for completing the single audit process. ---- - -# Single audit submission resources - -Our goal is to make the single audit submission process as easy as possible. - -## Submission guide - -Our [submission guide]({{ config.baseUrl }}resources/instructions) will take you through submitting a single audit, from creating a Login.gov account to completing the SF-SAC workbooks to certification and submission. - -## Managing submission access - -These [instructions]({{ config.baseUrl }}resources/instructions/user-access) will walk you through making changes to your certifying officials and adding new audit editors. - -## SF-SAC workbooks - -Download the workbooks needed to complete your SF-SAC and find instructions for completing them below. - -- [SF-SAC Section 1: Federal awards]({{ config.baseUrl }}resources/workbooks/federal-awards) -- [SF-SAC Section 2: Notes to SEFA]({{ config.baseUrl }}resources/workbooks/notes-to-sefa) -- [SF-SAC Section 3: Federal awards findings]({{ config.baseUrl }}resources/workbooks/federal-awards-audit-findings) -- [SF-SAC Section 4: Federal awards findings text]({{ config.baseUrl }}resources/workbooks/federal-awards-audit-findings-text) -- [SF-SAC Section 5: Corrective action plan]({{ config.baseUrl }}resources/workbooks/corrective-action-plan) -- [SF-SAC Section 6: Additional UEIs (optional)]({{ config.baseUrl }}resources/workbooks/additional-ueis-workbook) -- [SF-SAC Section 7: Secondary auditors (optional)]({{ config.baseUrl }}resources/workbooks/secondary-auditors-workbook) -- [SF-SAC Section 8: Additional EINs (optional)]({{ config.baseUrl }}resources/workbooks/additional-eins-workbook) - -## Federal agency program contacts - -[This PDF]({{ config.baseUrl }}assets/agency-contacts/2023-agency-contacts.pdf) provides the contact information for federal agency single audit contacts, key management liaisons, and program contacts. These individuals can answer your audit questions. \ No newline at end of file diff --git a/src/resources/compliance.md b/src/compliance.md similarity index 100% rename from src/resources/compliance.md rename to src/compliance.md diff --git a/src/developers/index.md b/src/developers/index.md deleted file mode 100644 index 13b09e7f..00000000 --- a/src/developers/index.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -layout: home.njk -title: FAC API documentation -meta: - name: FAC API documentation - description: Find developer resources for using the FAC API, including how to obtain a key and terms and conditions. ---- - -# The FAC API - -The FAC API shares public data from submitted audit reports. The FAC API runs on PostgREST and supports its built-in query operations. - -## Migrating from Census-provided data - -The FAC API endpoints mimic the pipe-delimited CSV files historically provided by Census. This means we export a similar set of tables (e.g. `general` as opposed to `gen`) with similar column titles. There are, however, some differences between GSA-provided and Census-provided data. We will provide more detailed migration guidance in the coming months. - -## Interacting with the API - -To interact with the FAC API, you will need an API key from Data.gov. To get a Data.gov API key, fill out the Data.gov API key signup form. This is free and requires a valid email address. When you receive your API key, treat it like any other credential: -- Do not share your key with other users. -- Do not commit your key into a repository alongside your code. -- Do not store your key in a shared drive where other users have access. -- Do not share your key in helpdesk requests or any other communication. - -Once you have your API key, you can begin exploring the API. - -## Resources - -* [Getting started]({{ config.baseUrl }}developers/getting-started/). What you need to get started, with some examples using `curl` on the command line. -* [PostgREST](https://postgrest.org), our API server. We use PostgREST as our API server. That means that you will use their documentation to guide you in formulating queries and interacting with our API server. -* [GSA data dictionary]({{ config.baseUrl }}developers/dictionary/). A mapping from the Census FAC to the GSA FAC API -* [Rollup fields]({{ config.baseUrl }}developers/rollups/) in Census data. A look at fields that existed in the Census data dissemination, and how to compute them from the FAC API. -* [Differences]({{ config.baseUrl }}developers/differences/) between Census data fields and GSA data fields. A list of fields you might be looking for, and where you might find them in the GSA FAC API. -* [Retrieiving many results]({{ config.baseUrl }}developers/retrieve-many/). An example of how to use pagination in PostgREST to retrieve many results from the API. - -## API limits and future updates - -By default, each API key is limited to 1,000 requests per hour. This limit comes from Data.gov, and you can read more about it in the api.data.gov developer manual. - -As the API evolves, we will publish API updates and communicate guidance according to our change management process. You can read more on the [API versioning page]({{ config.baseUrl }}developers/api-versioning/). - -For more information on the FAC API and the information it provides, see our [terms and conditions]({{ config.baseUrl }}developers/terms/). - diff --git a/src/index.md b/src/index.md index 519527ad..7a68bb7b 100644 --- a/src/index.md +++ b/src/index.md @@ -6,81 +6,53 @@ meta: description: The Federal Audit Clearinghouse is the home of the single audit process for the federal government awards system. include_survey: true --- - -
+
-

- The Federal Audit Clearinghouse (FAC) is the place to submit and review federal - grant audits. + {# Title #} +

+ + The Federal Audit Clearinghouse (FAC) + + + is the place to submit and review federal grant audits. +

-

- When an organization spends $750,000 or more in federal grant funds in a fiscal year, they are required to submit an audit. For more information on the features and development of the new FAC, check out our Updates page. -

-
    -
  • -
    -
    - -
    -
    -
    -

    You must log in to continue

    -
    -

    - Submitting information to the Federal Audit Clearinghouse requires authentication - which will now be handled by Login.gov. - You cannot use your old Census FAC credentials to access the new GSA - system. On the next screen you can use an existing Login.gov - account or create a new one to securely sign in. -

    -
    -
    - -
    -
    - -
    -
    + +
    + + {# Cards #} + diff --git a/src/info/announcements/archive.md b/src/omb/archive.md similarity index 100% rename from src/info/announcements/archive.md rename to src/omb/archive.md diff --git a/src/info/announcements/index.md b/src/omb/index.md similarity index 93% rename from src/info/announcements/index.md rename to src/omb/index.md index c8df893d..c4c469be 100644 --- a/src/info/announcements/index.md +++ b/src/omb/index.md @@ -8,7 +8,7 @@ meta: # OMB Announcements -The Office of Management and Budget (OMB) sets the policy for single audit submissions and their deadlines. The announcements below are in effect; for historic decisions, view [our archive]({{ config.baseUrl }}info/announcements/archive). +The Office of Management and Budget (OMB) sets the policy for single audit submissions and their deadlines. The announcements below are in effect; for historic decisions, view [our archive]({{ config.baseUrl }}omb/archive).