The intent of this document is to guide step by step how to deploy and configure healthapix custom features on a default (out of the box) Apigee developer Portal.
To know more about Apigee developer portal, refer http://apigee.com/docs/developer-services/content/what-developer-portal.
On successful deployment of customized site, you will be able to access following:
- Apigee Edge Developer Portal with a customized theme for Healthcare.
- FHIR API Documentation for easy understanding.
- FHIR Sandbox for trying out FHIR APIs.
- App Gallery to promote App ecosystem of your API program.
The deployment of custom changes would result into a similar site as Apigee HealthAPIx.
- You have created an Apigee developer portal either in the cloud or on-prem. On-prem instance is assumed to be created on a Linux server.
- You have an Apigee Edge gateway exposing FHIR APIs.
The details to setup an Apigee Edge gateway instance with FHIR APIs is covered in <HealthAPIx_Deploy_APIs> document in /flame/docs folder. - If you have In-Cloud Instance:
1. Apigee dev-portal admin access.
2. Pantheon access to your site’s Git repo.
-Refer http://docs.apigee.com/developer-services/content/working-pantheon.
-You will need to connect with Apigee support team to request them to associate your Apigee dev portal with your created pantheon account.
Clone flame repo.
Go to /flame/src/developerportal – This contains custom portal source code.
Initially, before flame code migration to the default portal, default developer portal website will look like as below:
Fig 1.
The default portal code to be modified is in sites folder.
- Get the default site’s code from git via pantheon service.
Note: Here, you can get clone of site’s code by using “git clone ” command followed by pantheon service credentials. - The code will be downloaded on your local system at .
You will find the default developer code at /var/www/html/sites.
A backup of default portal’s code is recommended before importing custom changes.
For In-Cloud instance,
Login Pantheon -> goto your portal site -> Backups -> and create a new backup.
For On-prem instance, Take a backup of /var/www/html/sites directory.
The all folder from default portal code now has to be replaced with the all folder from the flame source code.
Replace(Overwrite) /sites/all directory with /flame/src/developerportal/all directory.
For In-Cloud instance, you will need to push the custom changes back to git.
Note : All the changes can be reflect on Cloud instance, by using Git commands like $git add, $git commit, $git push followed by pantheon credentials.
We further need to do few manual configurations.
Access the developer portal website and login with admin credentials.
• Go to Configuration -> SmartDocs -> Advanced settings -> Click on Choose File button to select the .hbr file from cloned/downloaded flame source code i.e. /flame/src/developerportal/smartdocTemplate.hbr
Fig 2.
• Click Upload Button
• Save Configuration
• Clear Cache [hover Home icon of admin bar ->click Flush all caches ]
• Check the changes reflecting on SmartDoc page. [Apigee default theme changes to current theme as below]
NOTE: If there are pre-existing swagger models, one need to republish and render it, to reflect theme changes.
Fig 3.
To enable FHIR Swagger or any other module, go to admin -> modules and enable them.
-
Select fhir_swagger module from the list of modules, enable it.
-
Save the configuration.
-
Clear Cache [hover Home icon of admin bar ->click Flush all caches ]
The FHIR APIs description are available in Swagger JSON formats. These APIs description defines requests that point to the FHIR resources deployed on the Apigee edge gateway instance.
Swagger files are available at: ~\flame\src\developerportal\all\modules\custom\fhir_swagger\swaggers
You will need to modify the host field in all the swagger JSON files to point to the Apigee Edge gateway URL where the FHIR APIs are deployed.
-
Goto MY ACCOUNT -> My Apps. -
Select My Apps. -
Click on Add a new App and specify the following values. -
Specify any Name -
Do not add Callback URL. -
Select testFHIRproduct from the list of products
NOTE: Creating all models and import swagger feature is only to be used for first time deployment. For subsequent imports, manual steps would be needed.
-
Goto address bar > enter dev-{org-name}.devportal.apigee.com**/swagger/import** -
replace {org-name} in above url with your portal organization name -
Creation of models and import of swagger will start and the progress of the same will be seen on UI.
Fig 5.
-
Clear Cache -
Select Content->SmartDocs. -
You’ll find list of all FHIR APIs models which are unpublished.
-
Goto address bar > enter dev-{org-name}.devportal.apigee.com**/swagger/publish** -
Rendering and publishing of models will start and the progress of the same will be seen on UI.
Fig 6.
-
Clear Cache. -
Select Content->SmartDocs. -
You’ll find list of all FHIR APIs models, rendered and published.
Fig 7.
This section is applicable to all FHIR resources only i.e. should not be applied to OAuth and Basepath API documentation. OAuth 2.0 authentication can be used to secure the access to the API. Following steps need to be done to accomplish this.
- Select Content > SmartDocs.
- For the API model which needs to be configured, select API Revisions from Operations drop-down.
- For an API revision, select Security Settings from Operations drop-down.
Fig 8.
- Select Edit for outhB2C security scheme.
Fig 9.
- In Advanced Settings section set Authorization Request Method to Header.
Fig 10.
- Select Submit.
- Select Content > SmartDocs.
- For the same model, select Settings from Operations drop-down.
- In Template authentication schemes, set Client Id & Client Secret to the previously created App’s Consumer key and Secret respectively. The app creation is explained in Section 4.3.1.
- Click the "Save template authentication schemes" button.
Fig 11.
- Go to modules -> Enable Quicktab Module
- Go to Structure -> Quicktabs -> Add Quicktabs Instance
- Fill the details as highlighted in RED
Fig 12.
- Add Tabs for all APIs (e.g. Vaccination API) as shown in Fig.
(Ref. entries in RED colour box) - Click “Save” Button.
Fig 13.
- Configure to display Quicktab block on SmartDoc Page.
-
Go to Structures -> Blocks -> Search for Created Quicktab name e.g. **FHIR_API** -
Select the region as a **SECONDARY** -
Click on **Configure** hyperlink as shown in below screenshot as BLUE
Fig 14.
-
Fill the following details for “FHIR APIs” block as shown in below image-
Css : all-patient-left-nav -
FHIR Responsive theme : Secondary -
Content Type : SmartDocs Method -
Click on **Save** button.
-
Fig 15.
<img src="../../readme-images/devportal/Fig19.jpg"width="700px" height="350px"/>
Fig 16.
- Resultant screen should be as below.
Fig 17.
This completes configuration of Smartdocs.
Following all sections and steps above would enable a customized developer-portal similar to https://healthapix.apigee.com/
Fhir_responsive theme contains all fhir related customisation for the portal, and hence needs to be enabled and set as default.
- Goto {your_portal_site}/admin/appearance.
- Choose fhir_responsive responsive theme, enable it and set it as default.
To enable module, go to admin -> modules and enable them.
- Select fhir_responsive module from the list of modules, enable it.
- Select fhir_blocks module from the list of modules, enable it.
- Select fhir_custom module from the list of modules, enable it.
- Save the configuration.
- Set APIS menu weight, goto - Structure->Menus->Main menu->Show row weights ->Set APIS weight to -50->Save.
- Select fhir_install module from the list of modules, enable it.
- Save the configuration.
- Clear Cache [hover Home icon of admin bar ->click Flush all caches ]
Here we go, now refresh you portal site and you will see all changes of flame code on your portal.
See reference image below:
Fig 18.
Site owner will share a GTM container id [GTM-XXXXXX] created using a google application i.e Google analytics tag manager URL https://tagmanager.google.com, which has to be configured on the apigee portal to analyze site statistics.
Follow below step to configure container id on apigee portal :- • Login portal with admin credentials -> Admin menu bar -> Configurations -> System -> Google Tag Manager -> General Tab -> Container ID -> Fill in the text box with container id. -> Save configuration
That’s it, now using your google tag manager application you can track your statistics.
Have fun!