jziesing / launchpad_api

The LaunchPad add-on allows Salesforce customers to build and launch integrated web and mobile applications 2x faster. The add-on is used in conjunction with Heroku Connect, which means that a Salesforce customer can generate a REST API based on their existing Salesforce schema, greatly accelerating the process of building a Salesforce-integrated web or mobile solution.

Unlike traditional add-ons, this add-on is only useful when attached to the LaunchPad API application that is generated from the Deploy to Heroku button. The add-on itself simply provides a license key. Without a license key, the installation process will not succeed.

Key Features:

• Ruby on Rails REST API
• Active Record ORM
• Postgres Database
• Salesforce Integration
• Security
• Authorization
• Authentication
• API Documentation
• Pagination
• Serialization
• Params Sanitization and Transformation

Provisioning the add-on

Unlike other Heroku add-ons that can be attached to an existing Heroku app, the LaunchPad add-on must be attached to the LaunchPad API. Because of this, the first step is to deploy the LaunchPad API application to Heroku using the Deploy to Heroku button found below.

1. Deploy LaunchPad API to Heroku
2. Configure Heroku Connect
3. Set up API locally
4. Deploy the API

1. Deploy LaunchPad API to Heroku

2. Configure Heroku Connect

note We highly recommend using a Sandbox Salesforce environment until you are comfortable with how the add-on is performing. Once testing is complete, you can generate a second Heroku app using the Deploy to Heroku button and link that app to your Production Salesforce environment in Heroku Connect.

1. Click Manage App to go to your app's Heroku dashboard
2. Click Resources then "Heroku Connect"
3. Click Setup Connection then Next
4. Authorize your Salesforce account.
5. Click Mappings then Create Mapping (you'll do this for each object you want to sync)
6. Select the object you want to sync (e.g. "Account")
7. Select Accelerate Polling for optimal performance
8. Pick the columns you'd like to sync
9. Click Save

3. Set up API locally

note The API is a Ruby on Rails application that requires Ruby to be installed on your machine. Please make sure Ruby v2.5.1 is installed before proceeding.

In the below commands, replace APPNAME with the name of the Heroku app you just deployed:

$ git clone [e-mail]:LaunchPadLab/launchpad_api.git APPNAME
$ cd APPNAME
$ bundle install
$ heroku git:remote -a APPNAME
$ heroku addons:create launchpad:test
$ bundle exec rake launchpad:pull
$ bundle exec rake launchpad:install

Follow the terminal instructions to select the objects you'd like to add to the API. Once that completes, start your server:

$ rails s

To access the Admin Panel:

$ open localhost:3000

note By default, your email and password for the admin panel is set to [e-mail] and password, respectively. We'll show you how to change these to something more secure in the next step.

To visit the API documentation:

$ open localhost:3000/api/docs

4. Deploy the API

Before deploying to Heroku, we highly recommend that you modify the following environment variables in Heroku: ADMIN_EMAIL and ADMIN_PASSWORD. To do so, execute the following commands after modifying the email and password:

$ heroku config:set ADMIN_EMAIL=[e-mail]
$ heroku config:set ADMIN_PASSWORD=password

Now you're ready to deploy. Please enter these commands:

git add -A
commit -m "first commit"
git push heroku master
heroku open /api/docs

Enter the following credentials:

username: launchpad
password: <your LaunchPad License Key found in config/application.yml>

Using the add-on

• Ruby on Rails
• Active Record ORM
• Postgres Database
• Salesforce Integration
• Security
• Authorization
• Authentication
• API Documentation
• Pagination
• Serialization
• Params Sanitization and Transformation

Ruby on Rails

The LaunchPad API leverages Ruby on Rails as the underlying application framework. If you are unsure whether Ruby on Rails is a fit for your project, we highly recommend that you read the Rails Doctrine to determine if the framework aligns philosophically with your development team.

Active Record ORM

Each object generated in the LaunchPad API will have a corresponding Active Record ORM object which can be found in app/models/.

To learn more about Active Record, please read the Active Record Basics Guide. As described in this guide, Active Record provides the following key mechanisms:

• Represent models and their data.
• Represent associations between these models.
• Represent inheritance hierarchies through related models.
• Validate models before they get persisted to the database.
• Perform database operations in an object-oriented fashion.

Postgres

By default the LaunchPad API connects directly to your Heroku Postgres database in development mode. You can change this by modifying the config/database.yml file or simply changing the DATABASE_URL environment variable for a given environment. You can read more about configuring databases here and managing environment variables here.

Salesforce integration

The LaunchPad API depends on Heroku Connect for the Salesforce Integration. Each ORM object inherits from app/models/salesforce_model.rb to provide one place to manage the integration with Salesforce.

Security

Ruby on Rails comes with excellent security. We highly recommend you read this article to learn more about security in Ruby on Rails.

Authorization

The LaunchPad API comes installed with the popular CanCanCan Authorization Gem. Authorization of objects and their RESTful actions is built into the API by default. To customize authorization behavior, you can simply modify the app/models/ability.rb file.

For example, to prevent users from creating a new Account, you could add the following line at the bottom of the initialize method.

  cannot :create, Account

To learn more about configuring Authorization for your application, see the CanCanCan Wiki.

Authentication

The LaunchPad API leverages Basic Auth for authenticating incoming API requests and web traffic to the API documentation. By default, the username is launchpad and the password is your LaunchPad License Key.

API requests should be sent with the following header:

Key: Authorization
Value: Bearer <your Basic Auth token>

To get your Basic Auth token, run the following commands:

$ rails c
$ Base64.strict_encode64("launchpad:#{ENV['LAUNCHPAD_LICENSE_KEY']}")

API documentation

The API documentation is generated using RSpec API Doc Generator. You can customize your API Documentation in spec/acceptance/api/. Please read here to learn more about creating and modifying your API Documentation.

Pagination

The LaunchPad API leverages Kaminari in conjunction with the API Pagination gem to provide pagination within your API. This approach follows the proposed RFC-8288 standard for Web linking by using headers for pagination instead of the response body.

Serialization

Serialization allows the LaunchPad API to define the JSON that is returned for each object in the API. For example, you may only want to respond with certain attributes or adjust how attributes are formatted in the response.

The LaunchPad API leverages the popular Active Model Serializers for providing this serialization behavior. You can customize this behavior in app/serializers/.

Params sanitization and transformation

One of the core responsibilities for every REST API is to handle incoming data in a secure and reliable way. There are two core aspects to accomplishing this:

1. Remove all incoming data that is not explicitly whitelisted by the application
2. Transform incoming data to the format that your database expects.

The LaunchPad API handles this requirement by leveraging the Decanter gem. Every object generated by the API will have a corresponding Decanter object that can be customized in app/decanters/.

Removing the add-on

You can remove launchpad via the CLI:

warning This will destroy all associated data and cannot be undone!

$ heroku addons:destroy launchpad:test

Support

All launchpad support and runtime issues should be submitted via one of the Heroku Support channels.