| layout | title | date | description | landing-page |
|---|---|---|---|---|
tutorial_layout |
Postman Tutorial |
2019-11-02 09:21:12 -0500 |
Postman and Swagger Tutorial |
live |
Postman Instructions
Sandbox and the Onboarding Process
What does this instruction guide contain?
Step 1: Postman Instructions
Downloading Postman
Creating a new collection
Saving a request
Posting a request
Step 2: Swagger Instructions
Export a Job ID
Check the status of your job
Download your Job ID
Questions?
<h5 id="SandboxandtheOnboardingProcess-content">Sandbox and the Onboarding Process</h5>
<p>
After attesting and electing an AB2D Data Operations Specialist (ADOS), a PDP organization must
demonstrate their ability to use the API to access Production by successfully retrieving synthetic
claims data from the test (Sandbox) environment. In order to verify this requirement, PDP
organizations must provide the AB2D team with the Job ID from a successful run in the test (Sandbox)
environment.
</p>
<h5>AB2D Synthetic Data</h5>
<p>
AB2D provides four sample contracts that have been designed to provide synthetic data for testing purposes.
</p>
<p>
<b>Simple Datasets- Two Contracts</b>
</p>
<p>
This dataset provides contracts with a varying number of beneficiaries containing simple
approximations of AB2D data. These contracts are ideal to test the stress of retrieving and
downloading different sized data files. The data in these API payloads will not reflect the
distribution of disease and demographic information you can expect from production data.
</p>
<table class="ds-c-table">
<thead>
<tr>
<th>PDP Sponsor</th>
<th>Contract</th>
<th>Number of Benes</th>
</tr>
</thead>
<tbody>
<tr>
<td>PDP-100</td>
<td>Z0000</td>
<td>100</td>
</tr>
<tr>
<td>PDP-10000</td>
<td>Z0010</td>
<td>10,000</td>
</tr>
</tbody>
</table>
<p>
<b>Advanced Datasets- Two Contracts</b>
</p>
<p>
This dataset provides contracts with sample data that is a more accurate representation of AB2D
production data. They follow AB2D’s Bulk FHIR format and contain a more realistic distribution of
disease and demographic information.
</p>
<table class="ds-c-table">
<thead>
<tr>
<th>PDP Sponsor</th>
<th>Contract</th>
<th>Number of Benes</th>
</tr>
</thead>
<tbody>
<tr>
<td>PDP-1001</td>
<td>Z1001</td>
<td>600-800</td>
</tr>
<tr>
<td>PDP-1002</td>
<td>Z1002</td>
<td>600-800</td>
</tr>
</tbody>
</table>
<h5 id="Whatdoesthisinstructionguidecontain-content">What does this instruction guide contain?</h5>
<p>These instructions will guide you through the process of obtaining a JSON web token (JWT), also
referred to as a bearer token, using Postman. Postman offers a Graphical User Interface (GUI) and
provides an easy entrance point for users. Once complete, this token will be used to pull synthetic
claims data by accessing test (Sandbox) API endpoints using another application called Swagger. The
instructions below: Postman (Step 1) + Swagger (Step 2) are needed to access the Sandbox
environment. </p>
<h4 id="step1-content">Step 1: Postman Instructions</h4>
<p>The Postman directions below are broken up into the following sections:</p>
<ul>
<li>Downloading Postman</li>
<li>Creating a new collection</li>
<li>Saving a request</li>
<li>Posting a request</li>
</ul>
<h5 id="DownloadingPostman-content">Downloading Postman</h5>
<p>
Go to the Postman site <a target="_blank" href="https://www.postman.com/downloads/">here</a> to
download and install the app
version of Postman. Because only the app version of Postman is allowed in Production, we promote the
use of this version in Sandbox as well. The web version is available to you in Sandbox, but it will
not
be in Production. The directions below follow along with the app version of Postman.
</p>
<img src="./assets/img/sandbox/postman-1.png" alt="download postman">
<p>You will then be directed to an account sign-in page. Note, you are able to directly access the app
and
skip sign-in by clicking the link at the bottom of the page as shown below.
</p>
<img src="./assets/img/sandbox/postman-2.png" alt="postman signin">
<h5 id="Creatinganewcollection-content">Creating a new collection</h5>
<p>Click on the orange <strong>+ New</strong> button in the top left corner of the app.</p>
<img src="./assets/img/sandbox/postman-3.png" alt="postman create new button">
<p>Choose <strong>Create New</strong> to create a new Collection:</p>
<img src="./assets/img/sandbox/postman-4.png" alt="postman create new collection">
<p>
Configure as follows: <br />
Name: <strong>ab2d</strong> <br />
Choose: <strong>Create.</strong> <br />
</p>
<img src="./assets/img/sandbox/postman-5.png" alt="postman create new
collection details">
<p>In the left hand panel, click on the three dot’s next the ab2d node you just created and choose
<strong>Add
Request:</strong>
</p>
<img src="./assets/img/sandbox/postman-6.png" alt="postman new request">
<h5 id="Savingarequest-content">Saving a request</h5>
<p>Configure the “SAVE REQUEST” page as follows:</p>
<ul>
<li>Request name: <strong>retrieve-a-token</strong></li>
<li>Select: <strong>Save to ab2d</strong> at bottom right corner.</li>
</ul>
<img src="./assets/img/sandbox/postman-7.png" alt="postman save new request">
<h5 id="Postingarequest-content">Posting a request</h5>
<p>Click on <strong>GET, retrieve-a-token</strong> under the ab2d node and immediately, a new tab will
appear to the
right.</p>
<img src="./assets/img/sandbox/postman-8.png" alt="postman post a request">
<p>Alter the <strong>GET</strong> request to a <strong>POST</strong> request:</p>
<img src="./assets/img/sandbox/postman-9.png" alt="postman change get to post">
<p>
In the bar next to <strong>POST</strong> enter the following URL: <br />
https://test.idp.idm.cms.gov/oauth2/aus2r7y3gdaFMKBol297/v1/token
</p>
<img src="./assets/img/sandbox/postman-10.png" alt="postman enter url">
<p>Configure the Params tab as follows:</p>
<table class="ds-c-table">
<thead>
<tr>
<th>Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>grant_type</td>
<td>client_credentials</td>
</tr>
<tr>
<td>scope</td>
<td>clientCreds</td>
</tr>
</tbody>
</table>
<br />
<img src="./assets/img/sandbox/postman-11.png" alt="postman enter params">
<p>
Configure the Headers tab as follows: <br>
Choose one of the sample Base64-encoded credentials from a sample PDP Sponsor. This will be placed
under
the <strong>Value</strong> column by <strong>Authorization</strong>.
</p>
<table class="ds-c-table">
<thead>
<tr>
<th colspan="2">Simple Datasets</th>
</tr>
<tr>
<th>PDP Sponsor</th>
<th>Base64-encoded id: password</th>
</tr>
</thead>
<tbody>
<tr>
<td>PDP-100</td>
<td>MG9hMnQwbHNyZFp3NXVXUngyOTc6SEhkdVdHNkxvZ0l2RElRdVdncDNabG85T1lNVmFsVHRINU9CY3VIdw==
</td>
</tr>
<tr>
<td>PDP-10000</td>
<td>MG9hMnQwbG05cW9BdEpIcUMyOTc6eWJSNjBKbXRjcFJ0NlNBZUxtdmJxNmwtM1lEUkNaUC1XTjFBdDZ0Xw==</td>
</tr>
</tbody>
</table>
<table class="ds-c-table">
<thead>
<tr>
<th colspan="2">Advanced Datasets</th>
</tr>
<tr>
<th>PDP Sponsor</th>
<th>Base64-encoded id: password</th>
</tr>
</thead>
<br/>
<tbody>
<tr>
<td>PDP-1001</td>
<td>MG9hOWp5eDJ3OVowQW50TEUyOTc6aHNrYlB1LVlvV2ZHRFkxZ2NRcTM0QmZJRXlNVnVheXU4N3pXRGxpRw==</td>
</tr>
<tr>
<td>PDP-1002</td>
<td>MG9hOWp6MGUxZHlOZlJNbTYyOTc6c2huRzZOR2tIY3UyOXB0RHNLS1JXNnE1dUZKU1NwSXBkbF9LNWZWVw==</td>
</tr>
</tbody>
</table>
<br />
<table class="ds-c-table">
<thead>
<tr>
<th>Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content-Type</td>
<td>application/x-www-form-urlencoded</td>
</tr>
<tr>
<td>Accept</td>
<td>application/json</td>
</tr>
<tr>
<td>Authorization</td>
<td>Basic {Base64-encoded id:password}</td>
</tr>
</tbody>
</table>
<br />
<img src="./assets/img/sandbox/postman-12.png" alt="postman headers filled">
<p>
Select <strong>Send.</strong> <br>
In the body below you should see a token type, expires in statement, an access token, and scope
statement as shown below:
</p>
<img src="./assets/img/sandbox/postman-13.png" alt="postman response body">
<p>
You will use this bearer token, specified by the <strong>access_token</strong> value (in the next
hour), to access
Sandbox endpoints in Swagger, which we explain how to use below.
</p>
<h4 id="Step2-content">Step 2: Swagger Instructions</h4>
<p>The Swagger directions below are broken into the following sections:</p>
<ul>
<li>Authorize your bearer token</li>
<li>Export a Job ID</li>
<li>Check the status of a job</li>
<li>Download your Job ID</li>
</ul>
<h5 id="Authorizeabearertoken-content">Authorize a bearer token</h5>
<p>First - you must access the AB2D Swagger site by going <a target="_blank"
href="https://sandbox.ab2d.cms.gov/swagger-ui/index.html">here</a>. Click
“authorize” in the top right corner.</p>
<img src="./assets/img/sandbox/swagger-1-v2.png" alt="swagger authorize">
<p>
Use the bearer token (retrieved in the last 24 hours by you, and no other user) to authorize entry
into
the Sandbox endpoints. You will place this in the box under Value, adding the word <strong>Bearer
before the
token.</strong>
</p>
<img src="./assets/img/sandbox/swagger-2.png" alt="swagger authorize api key">
<p>Be sure to leave a space between the word <strong>Bearer</strong> and the actual bearer token. Also
remove any quotes
from the token itself. Click <strong>Authorize</strong>.</p>
<img src="./assets/img/sandbox/swagger-3.png" alt="swagger enter api key">
<p>You will see the following message:</p>
<img src="./assets/img/sandbox/swagger-4.png" alt="swagger authorize response">
<p>Click Close to <strong>close</strong> the window.</p>
<h5 id="ExportaJobID-content">Export a Job ID</h5>
<p>
AB2D supports both <a href="https://www.hl7.org/fhir/R4/explanationofbenefit.html">R4</a> and
<a href="https://hl7.org/fhir/STU3/explanationofbenefit.html">STU3</a> versions of the FHIR standard
in both sandbox and production environments. FHIR R4 is available using v2 of AB2D while FHIR STU3 can
be accessed via AB2D v1 which is typically indicated in an endpoint’s URL. Users are recommended to use
AB2D v2 thus we will use that version in the examples/screenshots provided below. Users can select the AB2D API version they’d like to use in the Swagger interface by navigating to the dropdown menu in the right-hand corner of the page.
Detailed descriptions of AB2D v1 (STU3) and AB2D v2 (R4) can be accessed in the AB2D Document Repository
in <a href="https://github.com/CMSgov/ab2d-pdp-documentation">Github</a>.
</p>
<p>
Open the <strong>Export</strong> menu to view all possible endpoints:
</p>
<img src="./assets/img/sandbox/swagger-5-v2.png" alt="swagger export menu">
<p>Choose <strong> /api/v2/fhir/Patient/$export</strong> to initiate a Part A & B bulk claim export job.
Then choose to
<strong>Try it out</strong> in the right hand corner.
</p>
<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 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">
<p>In the responses, look at the first code provided under <strong>Server response</strong>. Below that
are all the
other possible responses. The correct response should be a <strong>202</strong>, which means
<strong>Accepted</strong>. This means
the job has been created.
</p>
<img src="./assets/img/sandbox/swagger-8-v2.png" alt="swagger response">
<p>
From the information provided in the response, copy the Job ID from within the status request.
Format:
<br>
<em>content-location: http://sandbox.ab2d.cms.gov/api/v2/fhir/Job/<strong>{job
id}</strong>/$status</em>
</p>
<p>
Example: <br>
<em>content-location:</em> <br>
<em>http://sandbox.ab2d.cms.gov/api/v2/fhir/Job/eeb77c0d-d9e2-4a7c-b6e6-c4ab8e0917ca/$status</em>
</p>
<h5 id="Checkthestatusofyourjob-content">Check the status of your job</h5>
<p>While these are test jobs and most will run quickly, it is good practice to understand the steps
associated with running a job, including checking its status.</p>
<p>Click on the <strong>Status</strong> menu to view the status endpoints:</p>
<img src="./assets/img/sandbox/swagger-9-v2.png" alt="swagger job status">
<p>Copy the Job ID from the Export step. Click on the <strong>GET
/api/v2/fhir/{jobUuid}/$status</strong> endpoint,
click <strong>Try it out</strong> and paste the Job ID into the box provided.</p>
<img src="./assets/img/sandbox/swagger-10-v2.png " alt="swagger endpoint status">
<p>Click on the big blue bar labeled <strong>Execute</strong>.</p>
<img src="./assets/img/sandbox/swagger-11-v2.png" alt="swagger try it out">
<p>
In the responses, view the first value. This is the server response. There are two possible values,
202
or 200. If the response is 202, this means that the job is still in progress. It will give you an
indication of the job progress from 1 to 100%.
</p>
<p>An example of a partially finished job (36%) would be:</p>
<img src="./assets/img/sandbox/swagger-8b-v2.png" alt="partially finished status">
<p>You will need to re-click on the Execute blue bar periodically until the status returns a 200. This
means the job is done and the response will contain a list of files</p>
<img src="./assets/img/sandbox/swagger-12-v2.png" alt="swagger response">
<p>These files can then be downloaded and contain the claim records for our sample job.</p>
<h5 id="DownloadyourJobID-content">Download your Job Files</h5>
<p>Click on the <strong>Download</strong> menu in swagger. Select the <strong>GET
/api/v2/fhir/Job/{jobUuid}/file/{filename}</strong>
endpoint to download a file. Click <strong>Try it out</strong>. Enter the Job ID of the job you
created and the file name returned in the status, then press the <strong>Execute</strong> big blue bar.</p>
<img src="./assets/img/sandbox/swagger-13-v2.png" alt="swagger download">
<p>
It might take a while for the file to be downloaded depending on how big the job is.
The <strong>Server response</strong> value should be a <strong>200</strong>
and the <strong>Response body</strong> will contain a link to the claims data. To download the
data into a file, click on the
<strong>Download file</strong> link. This will be saved as an ndjson (new line delimited JSON,
also known as JSON lines)
file in your downloads. This data format will be identical to the production data. Only the Job ID
from
this file is needed - please send the Job ID to the AB2D team per the instructions emailed to your
organizations assigned ADOS.
</p>
<img src="./assets/img/sandbox/swagger-15-v2.png" alt="swagger response body">
<h1 id="Questions-content">Questions?</h1>
<p>
Having issues or concerns - please get in touch. <br>
<a href="mailto:[email protected]">[email protected]</a> - direct email <br>
<a href="https://groups.google.com/u/1/g/cms-ab2d-api">AB2D Google Group</a> - join the conversation
</p>
</div>
</div>
</div>