Skip to content
This repository has been archived by the owner on May 14, 2024. It is now read-only.

Latest commit

 

History

History
242 lines (160 loc) · 12.8 KB

README.md

File metadata and controls

242 lines (160 loc) · 12.8 KB
Raw

eCars

CI Workflow codecov lerna

ecars-logo

Sample car sales and service application. Pulsar is a fictitious electric car manufacturer company. This application helps Pulsar to sell cars on-site, and through their customer-facing website. Event-driven patterns allow to build loosely coupled integrations using multiple programming languages and systems. Regardless of the industry you work in, this app demonstrates how to build rich and immersive user experiences with the connected compute and runtime capabilities of the Salesforce Platform.

eCars Architecture Diagram

Table of Contents

Installation

Prerequisites

You will need the following to deploy this sample app.

  • git (download here)
  • node >= v12 and < v19 (download here)
  • Salesforce Dev Hub
    • If you don't have one, sign up for a Developer Edition org and then follow the instructions to enable Dev Hub.
  • sfdx CLI >= 7.11.0 (download here)
  • Heroku account (signup)
  • heroku CLI (download here)

Disclaimer: You'll need to have a paid Heroku Account and be subscribed to the Heroku Eco and Heroku Postgres Mini plans, for more information visit the Heroku Pricing page.

Automated Deploy

This project consists of multiple "apps" consolidated into one monorepo so that they are easier to deploy. The simplest way to configure and deploy all the apps is to run the following commands. The scripts/ecarsDeploy.js file is what automates all the deploys and integrates them with various configuration values.

The ecarsDeploy.js script will create and deploy code to a Salesforce scratch org and then deploy four Heroku apps along with some Postgres databases.

$ sf org login web -d -a DevHub  # Authenticate using your Dev Hub org credentials
$ heroku login  # Login with your Heroku account (or create one)
$ git clone https://github.com/trailheadapps/ecars.git
$ cd ecars/scripts
$ npm install
$ cd ..
$ node scripts/ecarsDeploy.js

If instead you want to perform all the deploy and configuration steps manually, see the Manual Deploy section below.

When the deploy is finished follow the last few instructions provided by the script, and then go to Demo Highlights below.

If you'd like to perform all the steps in the deploy script manually, you can follow the instructions below.

Manual Deploy

The below steps do everything the Automated Deploy does. It's recommended that you use the Automated Deploy to make the deploy easier for you and reduce the chance of error. If at any time, you are having a problem with the below steps and would like to start over, follow the steps in the Teardown section below.

  1. Authenticate with the sfdx and heroku CLI commands and get the eCars code onto your computer.

    $ sf org login web -d -a DevHub  # Authenticate using your Dev Hub org credentials
$ heroku login  # Login with your Heroku account (or create one)
$ git clone https://github.com/trailheadapps/ecars.git

  2. Create a scratch org

    $ sf org create scratch -d -f config/project-scratch-def.json -a ecars -v DevHub

  3. Generate a password for the scratch org user. Save both the username and password for later.

    $ sf org generate password -o ecars

  4. Generate a Security Token for the scratch org user. Run the following command and then click Reset Security Token. You will receive the security token in an email. This will be used later for the SF_TOKEN config var in the Heroku apps.

    $ sf org open -o ecars -p /lightning/settings/personal/ResetApiToken/home

  5. (Optional) Activate the Pulsar_Bold theme on the Themes and Branding page by running the following command:

    $ sf org open -o ecars -p /lightning/setup/ThemingAndBranding/home

  6. Deploy and configure the Heroku MQTT application

    1. Click the Heroku Deploy Button to deploy the application to Heroku. Provide a unique application name to be used as [MQTT APP NAME] below. Leave all other inputs as the defaults.

      Deploy

  7. Deploy and configure the Heroku Streaming application

    1. Click the Heroku Deploy Button to deploy the streaming data application to Heroku. Provide a unique application name to be used as [STREAMING APP NAME] below. Leave all other inputs as the defaults.

      Deploy

    2. Create a Heroku Postgres database and attach it to the application

      $ heroku addons:create heroku-postgresql:mini --app=[STREAMING APP NAME] --wait

    3. Provision the Heroku Postgres database

      $ heroku run 'cd packages/ecars-db && npx sequelize db:migrate' --app=[STREAMING APP NAME]

    4. Scale the application's dynos

      $ heroku ps:scale web=1:eco sensor-simulator=1:eco sensor-persistence=0:eco --app=[STREAMING APP NAME]

    5. Link with the Heroku MQTT app

      $ heroku config:set MQTT_BROKER_URL=[MQTT APP URL] --app=[STREAMING APP NAME]

      Note: Make sure this URL has the Secure WebSockets Protocol wss:// instead of https://. eg: wss://example.herokuapp.com

  8. Deploy and configure the Heroku Progressive Web Application (PWA)

    1. Click the Heroku Deploy Button to deploy the progressive web application to Heroku. Provide a unique application name to be used as [PWA NAME] below. Leave all other inputs as the defaults.

      Deploy

    2. Create a Heroku Postgres database and attach it to the application

      $ heroku addons:create heroku-postgresql:mini --app=[PWA APP NAME] --wait

    3. Initialize database tables

      $ heroku run node scripts/createPostgresTable.js --app=[PWA APP NAME]

    4. Generate VAPID public and private keys for web push notifications. Save them for the next command and also the next Heroku application deploy.

      $ npx web-push generate-vapid-keys

    5. Set config vars

      $ heroku config:set VAPID_PUBLIC_KEY=[VAPID PUBLIC KEY] VAPID_PRIVATE_KEY=[VAPID PRIVATE KEY] SF_USERNAME=[ORG USERNAME] SF_PASSWORD=[ORG USER'S PASSWORD] SF_LOGIN_URL=[ORG LOGIN URL] SF_TOKEN=[ORG USER'S TOKEN] --app=[PWA NAME]

  9. Deploy and configure the Heroku Microservices Application

    1. Click the Heroku Deploy Button to deploy the microservices application to Heroku. Provide a unique application name to be used as [MICROSERVICES APP NAME] below. Leave all other inputs as the defaults.

      Deploy

    2. Attach [STREAMING APP NAME]'s Heroku Postgres database to the Microservices application.

      $ heroku addons:attach [STREAMING APP NAME]::DATABASE --as=DATABASE --app=[MICROSERVICES APP NAME]

    3. Set config vars

      $ heroku config:set VAPID_PUBLIC_KEY=[VAPID PUBLIC KEY] VAPID_PRIVATE_KEY=[VAPID PRIVATE KEY] SF_USERNAME=[ORG USERNAME] SF_PASSWORD=[ORG USER'S PASSWORD] SF_TOKEN=[ORG USER'S TOKEN] SF_LOGIN_URL=[ORG LOGIN URL] --app=[MICROSERVICES APP NAME]

  10. Deploy source to the Saleforce scratch org

    1. Update the Salesforce source in the following files, replacing example.herokuapp.com with the domain of the Heroku apps you created in the previous steps.

      1. Update with streaming application domain: force-app/main/default/cspTrustedSites/WebSockets.cspTrustedSite-meta.xml
      2. Update with streaming application domain: force-app/main/default/lwc/liveData/liveData.js
      3. Update with microservices application domain: force-app/main/default/namedCredentials/Heroku_App.namedCredential-meta.xml

    2. From the ecars root directory, push the source to the scratch org

      $ sf project deploy start

    3. Assign permissionsets to the scratch org user

      $ sf org assign permset -n ecars
$ sf org assign permset -n Walkthroughs

    4. Load sample data into the scratch org

      $ sf data tree import -p ./data/data-plan.json

  11. Now go to Demo Highlights to learn about what you just deployed and why it's interesting!

Teardown

To delete everything created by the automated script or manual deploy instructions, run the following commands.

$ sf org delete scratch -p -o ecars
$ heroku apps:destroy --app=[MQTT APP NAME]
$ heroku apps:destroy --app=[STREAMING APP NAME]
$ heroku apps:destroy --app=[PWA NAME]
$ heroku apps:destroy --app=[MICROSERVICES APP NAME]

Demo Highlights

  • The Car Configurator component, built using Lightning Web Components and Lightning Data Service, enables a Pulsar salesperson to configure a car for onsite customers and to generate a PDF using a custom built Heroku Service showing the customer’s selected car configuration options.
  • Within Service Cloud, a Pulsar service technician can view live diagnostic car data such as current MPGe, % battery remaining, and range remaining to diagnose an issue with a customer's car. Data is sent from the car using MQTT and streamed to Salesforce over WebSockets.
  • The Progressive Web App can run in the browser, or as a native app on desktop client (as above). By leveraging Lightning Web Components and Lightning Base Components on npm, Pulsar quickly reused components from the employee app to create this customer-facing app. To upload data from the customer-facing app into Salesforce, the new Composite Graph API is used to map out complex data models, and commit changes within a single transaction.
  • An event-driven architecture using Change Data Capture allows Pulsar to synchronize data with other systems in real time. The empApi Lightning web component is used to receive change events for Vehicle__c record changes. Pulsar can also leverage the same technology to support their sales reps with real-time data updates across devices.
  • Pulsar maintains a single source of truth, from customer lead to car configuration options, by securely storing data for all aspects of its business in Salesforce.

Additional Resources

Archive IoT Car Diagnostic Data with Postgres

Looking at real-time car diagnostic data is useful, but often it's useful to be able to look at historical data. You can persist this data to a Postgres database by enabling the sensor-persistence process type.

Note that we have not enabled this by default because it will quickly consume the maximum 10,000 rows allowed in the mini Heroku Postgres plan. If you enable the sensor-persistence process type for more than a few hours, you should use a larger Heroku Postgres plan.

Development

Please see CONTRIBUTION.md