We’ve added to our portfolio of sample client applications. Check out our new sample applications. The links to the GitHub repositories are in an earlier blog post here https://bluebutton.cms.gov/blog/More-Sample-Applications.html
As promised in that post, this is the third in a series of posts where we work step-by-step through installing and configuring each sample application.
Today we will focus on the Ruby on Rails client. This post is slightly different from the previous posts because it takes you through installing the Ruby on Rails app in a Docker Container.
You can get the code for the Ruby on Rails client app here: https://github.com/CMSgov/bluebutton-sample-client-rails
Installing the application on your own desktop is a quick and easy process and is well documented in the README.md file.
However, the installation does have a series of prerequisites: - Docker - Docker-compose - Virtualbox
For the purposes of this article I am installing the application on a MacBook Pro running a current version of MacOS. We will therefore be using a unix-style shell for terminal access.
The steps we will go through are:
- Get your Blue Button sandbox credentials
- Prepare your environment
- Get the ruby on rails code from Github
- Configure the application credentials
- Launch the virtual machine
- Open your web browser and access the client application
1. Get Your Sandbox Credentials
Anyone can register for an account in the Blue Button 2.0 Developer Sandbox. Go to https://bluebutton.cms.gov and click on the “Sign up for the Developer Sandbox” link to create an account. You will receive an email notification that your account has been created. Click on the link in the email to validate and activate your account. Then you can log in at https://sandbox.bluebutton.cms.gov.
Once you log in to your Developer sandbox account you can create an application. Click on “Application Registration” and register a new application . Give your application a descriptive name. For example: “My Organization’s Claims Analyzer” Set the Client Type and Authorization Grant fields as follows:
Client Type: “Confidential” Authorization Grant: “Authorization Code”
The Redirect URIs field is where you can enter multiple URIs separated by a space or on a new line / carriage return / Enter key. You will need the path to an endpoint where your application will be listening for a request from our API to provide you the results of an authorization request. In the case of the Spring Boot client application we are installing the callback path for the redirect_uri is: http://localhost:3000/bluebutton/callback
The above redirect_uri setting is critically important. If this does not match the IP Address or domain name and path that your application is responding to you will get an “Error: invalid_request” after authorizing a user. Copy the Client ID and Client Secret values. You will need these to setup your application. Fill out the other fields in the form and click “Save”.
2. Prepare your environment
Installing the sample client requires Docker, Docker-compose and VirtualBox. VirtualBox enables linux virtual machines to be run on your machine.
Here are the steps to go through to install this application on MacOS. In this post we are assuming you are comfortable with working in a terminal session on a Linux Server or your Mac.
- Download and install the Docker package. (On MacOS and Windows Docker and Docker-Compose are bundled in one package)
3. Get the ruby on rails code from Github
After installing Docker the next step is to create a folder for the client code and pull the latest version of the code from GitHub.
mkdir ~/Dev cd ~/Dev git clone https://github.com/CMSgov/bluebutton-sample-client-rails.git cd bluebutton-sample-client-rails
4. Configure the application credentials
Copy a sample configuration file and then edit the file:
cp config/local_env_sample.yml config/local_env.yml
Open the config/local_env.yml file in the editor of your choice.
update the following entries in the development section of config/local_env.yml with your application’s client id and secret:
BB_CLIENT_ID: "<enter client id here>" BB_CLIENT_SECRET: "<enter client secret here>"
Save the file.
5. Launch the virtual machine
Make sure Docker is running. Go to the terminal window you should still have open and make sure you are in the top level directory for the sample client code:
cd ~/Dev/bluebutton-sample-client-rails docker-compose up
When you build the docker image for the first time it will run through an 8 step build process. This can take about 5 minutes. Time to make a cup of tea…
The process will be complete when you see messages that look something like this:
Creating bluebutton-sample-client-rails_web_1 ... done Attaching to bluebutton-sample-client-rails_web_1
6. Open your web browser and access the client application
Open your browser and go to: http://localhost:3000
If your application loaded successfully you will see a screen like this:
Click on the “Click here to authorize!” link and login to the Blue Button 2.0 sandbox using one of the synthetic beneficiary accounts. For example:
- User: BBUser12345
- Password: PW12345!
After Authenticating and authorizing your application you should be returned to the Sample App information screen.
From this page you can click on links to various Blue Button 2.0 resources such as:
The sample application is intended to provide sample code for the behind-the-scenes tasks involved in interacting with the secure Blue Button 2.0 FHIR-based API. The emphasis was not on creating a slick user interface. We leave that to you as developers. However, if you are interested in implementing an interface that is accessible for people with disabilities, what is often referred to as “508-compliant”, then check out the CMS Design System ( https://design.cms.gov ). It is a set of open source design and front-end development resources for creating Section 508 compliant, responsive, and consistent websites, building on the U.S. Web Design Standards.
As always, we welcome your comments and feedback. Just head over to the Google Support Forum and post a message there.