Merge pull request #15 from CMSgov/jfuqian/BB2-1366-Python-SDK-pagination-support

[BB2-1366] Python SDK Pagination Support

Author: James Fuqian

README.md

@@ -37,18 +37,27 @@ The configuration parameters are:
 - The version number of the API
 - The app's environment (the BB2.0 web location where the app is registered)
 - The FHIR call retry settings
+- Enable / Disable Token refresh if FHIR request processing detected the access token expired
 
-| Parameter    | Value                   | Comments                        |
-| ------------ | ----------------------- | ------------------------------- |
-| environment     | "SANDBOX" or "PRODUCTION"                   | BB2 API environment (default="SANDBOX")
-| version  | 1 or 2 | BB2 API version (default=2)  |
-| client_id     | "foo"                   | oauth2 client id of the app     |
-| client_secret | "bar"                   | oauth2 client secret of the app |
-| callback_url  | "https://www.fake.com/callback" | oauth2 callback URL of the app  |
+| Parameter     | Value                           | Comments                                |
+| ------------- | ------------------------------- | --------------------------------------- |
+| environment   | "SANDBOX" or "PRODUCTION"       | BB2 API environment (default="SANDBOX") |
+| version       | 1 or 2                          | BB2 API version (default=2)             |
+| client_id     | "foo"                           | oauth2 client id of the app             |
+| client_secret | "bar"                           | oauth2 client secret of the app         |
+| callback_url  | "https://www.fake.com/callback" | oauth2 callback URL of the app          |
 
 For application registration and client id and client secret, please refer to:
 [Blue Button 2.0 API Docs - Try the API](https://bluebutton.cms.gov/developers/#try-the-api)
 
+Auth Token Refresh on Expire:
+
+SDK FHIR requests will check if the access token is expired before the data end point call, if the access token is expired, then a token refresh is performed with the refresh token in the current auth token object, this behavior can be disabled by setting configuration parameter as below:
+
+"token_refresh_on_expire": false
+
+By default, token_refresh_on_expire is true.
+
 FHIR requests retry:
 
 Retry is enabled by default for FHIR requests, retry_settings: parameters for exponential back off retry algorithm
@@ -178,7 +187,7 @@ def authorization_callback():
     Check the scope
     of the current access token as shown below:
     """
-    scopes = auth_token.scope;
+    scopes = auth_token.scope
 
     # iterate scope entries here or check if a permission is in the scope
     if "patient/Patient.read" in scopes: 
@@ -213,6 +222,22 @@ def authorization_callback():
     try:
         eob_data = bb.get_explaination_of_benefit_data(config)
         result['eob_data'] = eob_data['response'].json()
+        eob_data = eob_data['response'].json()
+        result['eob_data'] = eob_data
+
+        # fhir search response can contain large number of resources,
+        # e.g. it is not unusual an EOB search of a beneficiary would result
+        # in hundreds of EOB resources, by default they are chunked into pages
+        # of 10 resources each, e.g. the above call bb.get_explaination_of_benefit_data(config)
+        # return the 1st page of EOBs, in the format of a FHIR bundle resource
+        # with a link section where page navigation urls with the link name as:
+        # 'first', 'last', 'self', 'next', 'previous', which indicating the 
+        # pagination relation relative to the current page.
+
+        # Use bb.get_pages(data, config) to get all the pages
+        eob_pages = bb.get_pages(eob_data, config)
+        result['eob_pages'] = eob_pages['pages']
+        auth_token = eob_pages['auth_token']
 
         pt_data = bb.get_patient_data(config)
         result['patient_data'] = pt_data['response'].json()

cms_bluebutton/cms_bluebutton.py

@@ -28,6 +28,7 @@ def __init__(self, config=DEFAULT_CONFIG_FILE_LOCATION):
         self.client_secret = None
         self.callback_url = None
         self.version = 2  # Default to BB2 version 2
+        self.token_refresh_on_expire = True
         # initilized with default
         self.retry_config = {"total": 3,
                              "backoff_factor": 5,
@@ -92,6 +93,7 @@ def set_configuration(self, config):
         self.version = config_dict.get("version", 2)
         self.auth_base_url = "{}/v{}/o/authorize".format(self.base_url, self.version)
         self.auth_token_url = "{}/v{}/o/token/".format(self.base_url, self.version)
+        self.token_refresh_on_expire = config_dict.get("token_refresh_on_expire", True)
         retrycfg = config_dict.get("retry_settings")
         if retrycfg:
             # override default with normalization
@@ -115,6 +117,30 @@ def get_profile_data(self, config):
         config["url"] = FHIR_RESOURCE_TYPE["Profile"]
         return fhir_request(self, config)
 
+    def extract_page_nav_url(self, data, relation):
+        if data and data['resourceType'] == "Bundle" and data['type'] == "searchset" and data['link']:
+            for lnk in data['link']:
+                if lnk['relation'] == relation:
+                    return lnk['url']
+        return None
+
+    def extract_next_page_url(self, data):
+        return self.extract_page_nav_url(data, 'next')
+
+    def get_pages(self, data, config):
+        bundle = data
+        pages = [bundle]
+        page_url = self.extract_next_page_url(bundle)
+        auth_token = config["auth_token"]
+        while page_url:
+            config["url"] = page_url
+            next_page = fhir_request(self, config)
+            bundle = next_page['response'].json()
+            auth_token = next_page["auth_token"]
+            pages.append(bundle)
+            page_url = self.extract_next_page_url(bundle)
+        return {"auth_token": auth_token, "pages": pages}
+
     def get_custom_data(self, config):
         return fhir_request(self, config)
 

cms_bluebutton/fhir_request.py

@@ -6,30 +6,37 @@
 
 def fhir_request(bb, config):
     auth_token = config["auth_token"]
-    new_auth_token = handle_expired(bb, auth_token)
+    if bb.token_refresh_on_expire:
+        auth_token = handle_expired(bb, auth_token)
 
-    if new_auth_token is not None:
-        auth_token = new_auth_token
+    url_param = config["url"]
+    full_url = None
+
+    if url_param.startswith(bb.base_url):
+        # allow full url passed in from config as long as it roots from base url
+        full_url = url_param
+    else:
+        full_url = "{}/v{}/{}".format(bb.base_url, bb.version, config["url"])
 
-    retry_config = Retry(
-        total=bb.retry_config.get("total"),
-        backoff_factor=bb.retry_config.get("backoff_factor"),
-        status_forcelist=bb.retry_config.get("status_forcelist")
-    )
-    full_url = "{}/v{}/{}".format(bb.base_url, bb.version, config["url"])
     headers = SDK_HEADERS
     headers["Authorization"] = "Bearer " + auth_token.access_token
-    adapter = HTTPAdapter(max_retries=retry_config)
+
+    adapter = HTTPAdapter()
+
+    if bb.retry_config.get("total") > 0:
+        adapter = HTTPAdapter(max_retries=Retry(
+            total=bb.retry_config.get("total"),
+            backoff_factor=bb.retry_config.get("backoff_factor"),
+            status_forcelist=bb.retry_config.get("status_forcelist")
+        ))
+
     sesh = requests.Session()
     sesh.mount("https://", adapter)
     sesh.mount("http://", adapter)
     response = sesh.get(url=full_url, params=config["params"], headers=headers)
 
-    return {"auth_token": new_auth_token, "response": response}
+    return {"auth_token": auth_token, "response": response}
 
 
 def handle_expired(bb, auth_token):
-    if auth_token.access_token_expired():
-        return refresh_auth_token(bb, auth_token)
-    else:
-        return None
+    return refresh_auth_token(bb, auth_token) if auth_token.access_token_expired() else auth_token