Skip to content

Commit

Permalink
[AB2D-6114] Update with _until parameter documentation (#41)
Browse files Browse the repository at this point in the history
## 🎫 Ticket

https://jira.cms.gov/browse/AB2D-6114

## 🛠 Changes

- Updates `advanced-user-guide` with `_until` parameter documentation.
- Updates `tutorial-postman-swagger` with screenshot showing `_until`
parameter.

## ℹ️ Context

Updates our website documentation to include `_until` parameter which is
introduced by Time Interval Based Query work.

Screenshots:
updated section of `advanced-user-guide`:
<img width="912" alt="Screenshot 2024-08-13 at 11 23 33 AM"
src="https://github.com/user-attachments/assets/9c10c7f5-d00d-4982-943e-eb263222ecb0">

updated section of `tutorial-postman-swagger`:
<img width="723" alt="Screenshot 2024-09-25 at 3 28 48 PM"
src="https://github.com/user-attachments/assets/b93579f4-e9f4-4d79-a8a0-5c5922504537">

## 🧪 Validation

Website was modified and tested locally, and will be deployed to lower
environments.
  • Loading branch information
Rwolfe-Nava authored Oct 23, 2024
1 parent 5c0b426 commit 1037636
Show file tree
Hide file tree
Showing 4 changed files with 30 additions and 17 deletions.
38 changes: 25 additions & 13 deletions advanced-user-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ was used to implement the [HL7 FHIR standard](https://www.hl7.org/fhir/overview.
[FHIR Bulk Data Export](https://hl7.org/fhir/uv/bulkdata/export/index.html) pattern to perform data export. Errors come
back in the [Resource OperationOutcome](errors come back in the https://www.hl7.org/fhir/operationoutcome.html) format.

AB2D supports both R4 and STU3 versions of the FHIR standard. FHIR R4 is available using v2 of AB2D while FHIR STU3 can
be accessed via AB2D v1. Both API versions return new line delimited JSON (ndjson) objects of the FHIR
AB2D supports both R4 and STU3 versions of the FHIR standard. FHIR R4 is available using V2 of AB2D while FHIR STU3 can
be accessed via AB2D V1. Both API versions return new line delimited JSON (ndjson) objects of the FHIR
[ExplanationOfBenefit](https://www.hl7.org/fhir/r4/explanationofbenefit.html) Resource.

### Sandbox
Expand Down Expand Up @@ -254,23 +254,35 @@ GET /api/v2/fhir/Patient/$export

#### Parameters

The `_since` parameter can be used to limit data to only data that has been updated since the specified parameter.
The format is the [ISO 8601 DateTime standard](https://www.w3.org/TR/NOTE-datetime) e.g. YYYY-MM-DDThh:mm:ssTZD
The `_since` and `_until` parameters allow you to filter claims data by date, which reduces duplication and speeds up job times. They follow the ISO datetime format (e.g: ```yyyy-MM-dd'T'hh:mm:ss[+/-]hh:mm``` ). Time zone must be specified using + or - followed by hh:mm. These optional parameters can be used separately or together.

Separately, these parameters allow you to pull data that was last updated since or until a specified date. You can use the meta/lastUpdated property of each ExplanationofBenefit (EOB) resource to find when each record was last updated. This will help you compare claims data when using the _since and _until parameters.

```
GET /api/v2/fhir/Patient/$export?_since=2020-03-16T00:00:00-05:00
GET /api/v2/fhir/Patient/$export?_since=2020-03-16T00:00:00-05:00&_until=2020-06-16T00:00:00-5:00
```

`_since`:

Dates prior to 2020-02-13 are not supported and will result in a failure response.

- AB2D v2/FHIR R4:
- If no `_since` parameter is provided, the value defaults to the date and time of the last successfully and fully
downloaded job that was created for the contract. If this is the first job run, the `_since` date becomes the
organization’s attestation date. Users can override this functionality by supplying their own `_since` date. This
feature is not supported for FHIR STU3.
Please note - Always supply a `_since` date in the Sandbox environment when using AB2D v2 as sandbox test contracts are shared resources used by other people and will use extraneous default since dates.
- AB2D v1/FHIR STU3:
- A `_since` value must be added to each call in order to use the `_since` parameter. If no `_since` value is specified, the value defaults to a contract's attestation date. It is highly recommended and considered best practice to use the `_since` parameter on v1 API calls.
- AB2D V2/FHIR R4:
- If no `_since` parameter is provided, the value defaults to the date and time of your organization's last successfully and fully
downloaded job. If this is the first job run, it will default to your organization's attestation date or 2020-02-13, whichever is later.
Note: Always use the `_since` parameter in the V2 sandbox environment. This will prevent the default value from changing for others as sample contracts are shared resources.
- AB2D V1/FHIR STU3:
- If no `_since` parameter is provided, the value defaults to your organization's attestation date. We highly recommend using the `_since` parameter on V1 API calls.

`_until`:

- AB2D V2/FHIR R4:
- If no `_until` parameter is provided, the value defaults to the current date.
- `_until` dates in the future are invalid. The job will still run, but the `_until` date will default to the current date.
- If `_until` is provided and `_since` is not, the range of dates will be from the last successfully and fully downloaded job date to the `_until` date.
- Providing an `_until` date that is prior to the `_since` date is invalid. This will result in an error and no data will be exported.

Note: The `_until` parameter is currently only supported by the AB2D V2 API. Passing the `_until` parameter to the AB2D V1/FHIR STU3 API is invalid and not supported.


### Status
Once a job has been created, the user can/should request the status of the submitted job.
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 5 additions & 4 deletions tutorial-postman-swagger.md
Original file line number Diff line number Diff line change
Expand Up @@ -556,11 +556,12 @@ landing-page: live
<strong>Try it out</strong> in the right hand corner.
</p>

<img src="./assets/img/sandbox/swagger-6-v2.png" alt="swagger export parameters">
<img src="./assets/img/sandbox/swagger_parameters_V2_TIBQ.png" alt="swagger export parameters">

<p>The default options are fine in this case with the exception of the _since date. A good
value for this contract is <pre>2021-01-01T00:00:00.000-05:00</pre>
Enter this value and click the big blue bar to <strong> Execute.</strong>
<p>The default options are fine in this case with the exception of the _since date and _until date. A good
value for the _since date for this contract is <pre>2021-01-01T00:00:00.000-05:00</pre>
<p>_until uses the same format as _since. A good value for the _until date is to use the current date and time, but you can enter any date as long as it is a date between _since and the current date and time.</p>
<p>Enter both of these values and click the big blue bar to <strong> Execute.</strong></p>
</p>

<img src="./assets/img/sandbox/swagger-7-v2.png" alt="swagger execute">
Expand Down

0 comments on commit 1037636

Please sign in to comment.