How to contribute to a Non-profit using Salesforce

An example of a document for volunteers of technical talent

Overview

A) Understand the mission
- Process/Procedures
B) Understand the technical architecture
C) Pick a project
D) Setup Collaboration
E) Copy the public-facing website
F) Create a copy of the Salesforce database
G) Plan changes, update test scripts
H) Run tests, make changes, and deploy
Other CONTRIBUTE.md files on the internet
More about Salesforce

This is an example of a hands-on tutorial that volunteer software developers reference to get setup in order to make contributions in a collaborative way. This was written to ensure that you (a developer/graphic artist, etc.) get trained on a professional approach to software development while improving the non-profit’s digital assets. The sections here are:

A. Understand the mission (the organization and yours)
B. Understand the technical architecture
C. Pick a project
D. Setup collaboration tools and techniques
E. Copy the public-facing website
F. Create a copy of the Salesforce org
G. Plan changes, update test scripts
H. Run tests, make changes, and deploy

NOTE: Content here are my personal opinions, and not intended to represent any employer (past or present). “PROTIP:” here highlight information I haven’t seen elsewhere on the internet because it is hard-won, little-know but significant facts based on my personal research and experience.

A) Understand the mission

For this non-profit, the persona are: interns, hosts, mentors, donors. Each person goes through different status over time: prospective, active, inactive, alum.

Click this link to register for training on the Blackboard system
Access the YWAM Converge training content at https://blackboard.coursesites.com/ultra/courses/_190749_1/cl/outline
Click “YWAM Values” on the left menu to read it.
Click “Start Here” on the left menu to read “Welcome to Converge”.
Scroll down to watch the “What is YWAM” video. Click the volume icon to unmute.

When did YWAM (the parent organization) start? See https://youtu.be/Uz0EesM-G04
Scroll down the page to see the diagram summarizing the activities by phase:
Open a browser tab to the FAQ (Frequently Asked Questions) to see if you can answer the questions before revealing the answer. Kinda like a quiz.

Process/Procedures
Watch demo video of How to apply for a Converge intership [2:20] No sound. The Ruby system is not mobile-friendly (progressive).
Watch demo video of host app. No sound.

https://www.youtube.com/watch?v=hSqbotfxZAA Dec 23, 2015

B) Understand the technical architecture

The system consists of several components, described by this system flow chart on Google (created using Lucid Chart) ywan-architecutre-2019a-200x183-7427

A training management website used by interns to learn about being an intern. Videos on it are stored (as Public) on the YouTube channel
A public-facing website that exchanges information dynamically with
A Salesforce org database used internally for administration.
Audio podcasts from 2018 are also stored on YouTube.
Apple podcasts?
Facebook
Instagram?

C) Pick a project

Some volunteer opportunities are listed in CatchAFire.org managed by admins using the dahboard.

a. Team: How to get more people to be aware of this (advanced training to make a difference)? What are the outlets?

b. John: Create videos for display in emails (instead of text) about next steps, etc. within a drip email sequence.

c. Create automated test scripts (based on documented procedures) to verify whether the system works “end-to-end” (for different personas), to identify whether the sytem still works after changes. Kinda like auto-fill on steroids.

d. Dan: Upgrade front-end server version upgrade (to Ruby, Postgres, TLS 1.2 for Braintree, etc.).

e. Wilson: Create instructions (this page) to enable volunteers to create a dev environment and contribute changes.

f. Wilson/Dan: Convert bash scripts and instructions to create a dev instance of Ruby server running on Ubuntu.

g. Kermit: To troubleshoot without worry, define manual procedures and scripts to create a stand-alone Saleforce Dev. instance (a “crash dummy”) containing metadata and filtered/cleansed data from production org sandbox:

### Administrator:

Configure templates and generate a Dev. sandbox from prod instance.
Create test scripts on sandbox so running it doesn’t corrupt or degrade the production instance.
Export metadata (coding) from Sandbox.
Create data extract from Sandbox.
Cleanse data
generate additional test/mock data using mockaroo.com (generates up to 1,000 rows free).
Copy cleansed data into a location available to developers.

### Developer (volunteer):

Import metadata (coding) into Dev. instance.
Import cleansed data into Dev using DataLoader.
Modify test scripts to run on imported Dev. instance.

h. Enable and test disaster recovery.

i. PROJECT: To best communicate with student/interns, we need someone to research, propose, and then develop the best option for texting internationally to students, hosts, mentors, donors. Wilson said he and Kermit saw a company offering a good texting solution at Dreamforce. Texts can replace emails if they include links to static web pages or links with reminders to log in to dashboard to complete an activity.

j. Make introduction videos to each of the persona for display on the website and to make emails more “alive”.

k. Create training for mentors ?

l. Translations of the site into various languages. We have a team currently translating the site into Spanish. A LOT of their work is already done. At some point, I want to get a Volunteer Project posted to insert the “es:” text into the code. (BTW, all the training videos are also being translated to Spanish to be inserted into the videos too. That will be another project. The team in Colombia is translating those SRT files now.)

m. Architect a more secure way to maintain passwords and other secrets for team (HashiCorp Vault, etc.)

n. Propose one of your own.

D) Setup Collaboration

If you haven’t used the tools mentioned here, we will train you so that you can contribute confidently.

Make an appointment with John at
https://www.ywamocnj.org/make-an-appointment or https://ywamocnj.doodle.com/jthenry

John makes use of Zoom for group video conferencing than can be recorded.
From John, get an email invite to the Slack channel used by developers (join the channels):

http://ywamconverge.slack.com

Click the “Channels” heading on the left pane. Click on a channel name. Click on “Join Channel”.
Use your email to get a free GitHub account and let us know what your GitHub account name is. Then you can fork our GitHub to your own account. Create a branch under your account to make changes, then create a Pull/Merge Request.
We share sensitive info like passwords only on WhatsApp chat.
Saleforce Chatter real-time text message we use to make announcements that get sent out as emails.
WhatsApp group.

E) Copy the public-facing website

Open an internet browser to visit the production webpage for the non-profit at:

https://www.ywamocnj.org/
Youth With A Mission - Ocean City New Jersey

The tech behind the website consists of several components (all free open-source):
- Ubuntu 18 operating system (contains ssh and yum package manager)
- Utility Git (needed by Capistrano)
- PostgreSQL database
- Ruby (programming language interpreter)
- Rails engine Refinery CMS which support for Amazon S3 cloud storage and makes use of
- ElasticSearch to do indexing and
- Dragonfly for image editing
- Redis database to manage queues to Salesforce
- Sidekiq to proxy and manage Redis
- NGINX ?
- TODO: Utility to backup database
- TODO: Utility to cleanse data
Code and documentation about the website is at this GitHub repository:

https://github.com/ipoconnection/ipo-web

BTW The name “IPO” is a carry-over of previous branding, and kinda stuck. We should rename it someday.

Optionally, if you want to examine the repo off-line, on your machine, create a folder and clone the repo onto your local laptop.
Click the “Branch: master” and select the branch Dan is current using: upgrade-rails-4.0

That branch name will be different in the future.

README.md describes each component and installation process in more detail.

README.rdoc contains instructions for running on an Appl MacOS laptop. But since the system runs under Ubuntu in production, we are converting scripts and instructions to that OS, and assume that you are using a Docker or cloud image (running on Amazon Lightsail</a>, etc.).
Create a VPC instance within Amazon Lightsail or other bare-bones VPS (Virtual Private Server).

PROTP: Begin with the 512 MB RAM to practice loading, then move up as necessary.

TODO: In the future we will define files to use Docker with Kubernetes.
Open an SSH session to your machine and login using the default user (“ubuntu”).
Create another user, deployer.
```
sudo adduser deployer --ingroup admin
 
```

Type in password when prompted with “Enter new UNIX password:”.

passwd: password updated successfully
Changing the user information for deployer
Enter the new value, or press ENTER for the default
Full Name []: 
Room Number []: 
Work Phone []: 
Home Phone []: 
Other []: 
Is the information correct? [Y/n]

Reboot and login as deployer to run the Bash script which installs software, configure it, and populate the database, and runs a smoke test to verify viability.
Copy the command to invoke the install script to your Clipboard (by triple-clicking this line before pressing command+C) this string:
```
bash -c "$(curl -fsSL https://raw.githubusercontent.com/wilsonmar/DevSecOps/master/Ruby/ywam-setup-all.sh)"
```
Get on your VPC command line interface and press command+V to paste the command.

On Amazon Lightsail, you would need to first click on the orange clipboard icon, then paste in its form, then click on the CLI (black screen), then right-click to paste (on a Mac, press two fingers at once on the touchpad). Press Enter to run the command.

BTW The script is supposed to be idempotent because it erases resident folders from the previous run.

F) Create a copy of the Salesforce database

Salesforce provides weekly production backup zip. It’s triggered by a scheduled job from a service account which receives emails when done. Currently, each backup consists of 330 csv files take 8.3 MB zipped. Unzipped its 107 MB. The output zip file is copied to an alternative cloud provider (Google Drive) because Salesforce only stores backup files 48 hours, with file name (from a default name such as “WE_00DG0000000ggbAMAQ_1.ZIP”) to this example:

ywam-prod-data-2019-06-03-3amET.zip

Metadata (custom fields, reports, list views, workflows, etc.) is extracted to a name such as:

ywam-prod-meta-2019-06-03-3amET.zip

TODO: Use UTC.

Due to active changes, daily backups are maintained for 13 months (370 zip files). The assumption is that there is a lot of financial info in the backups.

TODO: Add to the name the number of days since Jan 1 of the year.

3rd party offerings:

https://skyvia.com/data-integration/salesforce-data-loader
https://spanning.com/resources/whitepapers/3-ways-to-restore-salesforce-data/
https://www.cloudally.com/how-to-recover-salesforce-data/
https://pages.ownbackup.com/salesforce-weekly-export
https://www.backupify.com/salesforce-backup

Production security

The production Salesforce instance is https://studentmobilizationcentre.my.salesforce.com, but to avoid additional charges we are trying to keep the number of people accessing it. Named users in SF are first initial and last name with no space.

John Henry, as the CEO, owns the all-powerful System Administrator permissions for the production org.
Mary Henry has the Standard “Executive Director” role.
support@ywamconverge.org is only emails.
API IDM is the user for API calls (does not use the UI).
Daniel Bryan is the root System Administrator.
James Strong “System Administrator” ?
jessica.kalisa@gmail.com “Program Volunteer”.
kermit Vestal kermitv@ywamocnj.org
wilsonmar@uofn.edu
?

There is a secret repository holding passwords to the production site.

PROPOSAL: Volunteers use generic accounts rather than named ones. For example:

admin@ywamconverge.org has the SF Standard “Executive Assistant” role.
“tester.312” has permissions to conduct tests and view security settings.
“user.415” has permissions to view reports and add opportunities.
TODO: Map out users, their roles, and permissions.

Dataflow diagram

The diagram here illustrates, on one page, how the various pieces talk to each other.

Your first exposure to Salesforce is likely the Salesforce Trailhead website https://trailhead.salesforce.com which provides anyone a free Trailhead account with up to 5 “hands-on org” in a “playground” to use while taking learning modules. The sample gallery developed by Salesforce Developer Evangelists can be loaded as Dev orgs through the App Exchange. Sample packages are “unmanaged” and can be altered when installed. There are also managed packages (such as the Non-Profit Success Pack) from Salesforce partners.

Each org (database) contains two types of information: master data values such as customer names and metadata (Apex coding, form layouts, and other configurations).

Those who have bought one of the various levels of licenses for production usage have a single PROD org instance. Administrators go into Setup’s Sandbox function to create copies of metadata in various types of Sandboxes (abbreviated SBX). Different levels of licenses come with different numbers of each type of sandbox. Dev (Development) Sandboxes are created so developers can add a few records specific to test what they are changing. Other types of Sandboxes contain data copied in. Dev Pro Sandboxes have up to 200 MB of test data. Partial Sandboxes hold a sampling of data for integration testing. Full Sandboxes contain a complete copy of production records and metadata.

Since it can take awhile to copy, an email is sent when it’s done. To get data records into Sandboxes, we export based on filters in templates define within the Salesforce website. The export process also sends an email.

The DataLoader utility is used to put data in Sandboxes. Because we are dealing with private production data, cleansing for duplicates and/or masking for privacy after export needs to done. Doing that directly in production provides for validation before committing.

Trraditionally, developers create Change Sets to patch metadata, and run Salesforce Apex tests and UI tests using Selenium or TOSCA/Flood.io</a> before pushing changes through various environments.

In 2018, Salesforce made available DX (Developer Experience) that manages temporary Scratch orgs updated by metadata stored in a Git version control repository. Temporary means 7-30 days before they disappear automatically.

To provide testing scripts the test data they need, custom scripts are written to load the test data into Scratch orgs and Playground org. QUESTION: Can the DataLoader put custom external test data into the Dev Sandbox?
QUESTION: Can the DataLoader put data into Playground orgs?
QUESTION: Can a custom package be created from a Sandbox?

Procedures

Each developer makes use of their own Salesforce org to work. This can be a Developer Sandbox provided from the Administrator or a copy of the production Salesforce org. in a Salesforce Trailhead Playground org.

At Salesforce Trailhead website https://trailhead.salesforce.com, sign up for a free Developer org. and sign into it. You may need to first open an incognito window to avoid cookies from other Salesforce sessions.
Load the metadata into your own org.
Ask for .csv files containing masked data that has also been cleansed and reduced in size.
Import the test data into your org.
Configure the API connection between the website and Salesforce API.

Load metadata into your own org.

@Kermit?

https://developer.salesforce.com/docs/atlas.en-us.216.0.sfdx_dev.meta/sfdx_dev/sfdx_dev_test_data_example.htm

Configure the API connection between the website and Salesforce

@Dan?

G) Plan changes, update test scripts

Draft a description of what the system will look like when you’re done. This can be a picture of an altered form or report.
Define commit messages for the sequence of changes. This can provide a roadmap for estimating effort and timelines.
Define the tests for each feature added or changed.
We believe in the advantages of a “test first” approach. Create test scripts to validate new fields that have not yet been created. If the change is removal of a field, write a “negative” test to verify the absence of the field among a list. Then code changes that cause the test to pass.

H) Run tests, make changes, and deploy

Run a test of the existing test suite to ensure that everything works.
Define what changes you would like to make, in small increments of commit
- If it’s a form, take a picture of the form, paste it in PowerPoint or Google GSuite and add the field.
- Plan out the commits that you’ll be making to get to done.
- Review with others regularly. Here is an opportunity for all sides to learn something new, and be better friends.
Create a branch, named beginning with your assigned user name followed by a dash and number.
Make changes to the test suite, and make commits.
Create a Pull (Merge) Request:

Please send a GitHub Pull Request to opengovernment with a clear list of what you’ve done (read more about pull requests). When you send a pull request, we will love you forever if you include test code. We can always use more test coverage. Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).

Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should contain a paragraph describing what changed and its impact:
```
git commit -m "A brief summary of the commit"
```
Change the test suite and make sure it runs to success.

Please consider the people who will read your code, and make code reable for them. We optimize for readability:
- Indent Bash shell files using three spaces (soft tabs).
- Use HAML for all views.
- Avoid logic in views, putting HTML generators into helpers.
- Put spaces after list items and method parameters ([1, 2, 3], not [1,2,3]), around operators (x += 1, not x+=1), and around hash arrows.
Visually review with others while it’s in your unit test environment.
Check the new branch into GitHub (or whatever version control repository your team uses).
Others make comments on the code.
One of the leads moves the branch into a test org and run more tests.

https://github.com/ipoconnection/ipo-web/blob/master/TESTS_README.md
One of the leads deploys the change into production, then run post-deploy tests.

Other CONTRIBUTE.md files on the internet

https://www.firsttimersonly.com/
https://kbroman.org/github_tutorial/pages/fork.html
https://github.com/firstcontributions/first-contributions
https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project
https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/
https://gist.github.com/MarcDiethelm/7303312

More about Salesforce

This is one of a series about Salesforce

Wilson Mar