Day 2 – Configure Salesforce for Github Communication and Vice Versa

Checkpoint – Credentials for Salesforce and Github

Alright,  now we have the credentials that we need after previous instructions had us signup.. but to reiterate make sure you have:

• A working Salesforce Account
• A working Github account 

All good?

Use Cases for this Integration

It isn’t everyday we get to use some under-appreciated features in SF like Named Credentials, and custom APEX REST endpoints, to facilitate both outbound and inbound data.

I will admit I get a little gitty about making systems talk to each other, but you want to always have a purpose I suppose.  Here are some real reasons you may want to connect these 2 systems..

• Backup code to a source control repository for change control
• Auditing changes made in the org via analyzing metadata
• Using Github Pages as a free host for a Wiki or Documentation portal

Also keep in mind that an API can be thought of as the interface into an Application (hence the name), and typically is a documented service with a definition of how you can send data to it, and most every system now a days provides these types of interfaces.

Data Structures Exchanged via Endpoints

There are standards that exist such as REST which gives a best practices approach and guidelines of how to send the data which makes this communication streamlined enough to agree on a common data contract.  JSON is the common data format now a days, with XML being the now outdated tougher format to manage.  REST API in Salesforce [JSON] vs. SOAP API [XML] is not really relevant unless you HAVE to use the SOAP API for any reason, and all our integration magic will be done via JSON.

What is JSON?

I’m sure you’ve seen something that looks similar to this block of JSON (Java Script Object Notation)

{“key”:”value”}

With this format of data which has strict rules that define what is “Valid” JSON,  you start to realize that it is much more than a string with curly brackets.   What do you we do about repeatable shapes of these strings that fit this JSON format standard?  We can define Types.

Types overall in OOP are extremely important but not in scope for this tutorial.  The important part was that JSON type data which is sent between systems via APIs and data contracts is the most common approach to these connections now a days.  You may deal with XML but JSON via REST http is the industry standard… for now.

JSON and Javascript in a Salesforce Developers Toolbox

I can’t stress enough how much understanding JSON benefitted me as a developer.  I will project a lot of details related to the anxiety caused by not understanding or trying to understand it for the first few development projects,  but there is no downside to overemphasizing it.  Specifically in Salesforce, until LWC came around you didn’t have a reason to be a fluent javascript developer, so things like this were not front and center in my hands on training I got at my junior level roles.

It was so mysterious to me for a while and I didn’t understand data structures fully (still probably don’t but feel better).  Knowing the basics of data though and how a SF SObject is shown in logs and is a JSON string or something close to it, and how an object is a Map (key:value or field:value as expressed with data), and an array of objects is a list of maps and what is acceptable and what isn’t, it was such an epiphany.   

To read more about JSON check this out: W3 Schools JSON

More Specific Examples of my JSON Enlightenment?

It’s hard to be honest about this and still somehow sound informed, but a good example is the usage of Types in Salesforce like List, and Map, and the key/value pairs that go into building the maps.

If you aren’t used to the spacial or whatever term of thinking through layers of connected data in your head, when you see something like Map<String, Map<List<String>,Map<String,String>> and you start feeling dizzy.  

But if we break it down to its simplest form, with a list being comma separated values, and the map being keys, with values for the keys,  JSON is a great visual to match to these “Map” and “List” terms.   Salesforce in logs also will typically be made up of JSON strings or something that resembles a non officially validated JSON value but something similar looking.   If you utilize the JSON class and Serialize and Deserialize options though, you can enforce that data meets JSON standards and start to get some assurances in your brain that things are conforming to certain things, and will therefore WORK!

But with that being said, it allowed me to start viewing things more clearly as key value pairs, and realize things like an object is potentially just a List of Maps (key/value pairs),  like {field:field_value, field2:field_value2}.  I know this is still kind of a convoluted example, but hey, once that clicked, those complex maps of lists and maps weren’t so daunting.

Final Thoughts on JSON before Integration Examples

So now we know that we are sending JSON data between these systems we need to talk to the front desk agent AKA an “App” or “Connected App”.   It is not required to be familiar with all of these topics to get through this example, but I want to unequivocally state that there is so much more to the topics that they could each have their own posts:

• Connected Apps in Salesforce
• OAUTH for authentication
• Named Credentials in Salesforce

All of these are things that we will utilize that are core to Integrations in Salesforce.  OAUTH is a broader term than just Salesforce, but Named Credentials and Connected Apps are Salesforce concepts.  Other platforms may allow for Apps to act as a gatekeeper to the data you are providing, but Connected Apps in Salesforce have their own Salesforce Specific characteristics.

Overall in our example, this interface is a gateway into the system you want to talk to, where you can further hash out your connection agreement details, and the Github user who is making use of the App can have some better control over connections made into their stuff.  Maybe you could visualize it like pong where you have the 2 APIs talking to each others connected apps.  Often you can still utilize a key or credentials to get into data without having to create these gateway apps, but it is usually to your benefit to do this when in a Production environment to have control over the permissions behind the Token you are given for access.

Typically when you want to connect into a system, you will have to acquire a token.  A token can be acquired in a variety of ways, but ours is going to be via O-Auth 2.0, facilitated by Salesforce and Named Credentials for the Outbound specifics, and a Github App for the inbound to Github specifics.

Integration Examples

Connection: (Outbound to Inbound) Salesforce to Github

Use case: Trigger Github Workflows via the Github API, to unlock the righteousness of SFDX and shell scripts
I know we are at the beginning of the tutorial so to break some of those terms down a bit…

• Github Workflow – Github allows the triggering of scripts to do Deployment related automation.  This can be used with SFDX to create some cool shit.
• Github API – Github has an extensive REST API to communicate with , as well as a nice suite of web-hooks to subscribe to, meaning endless customization options.
  • Web-hook – Arbitrary payload sent after specific events from a system usually containing details about that event.
• SFDX – Salesforce has a Command Line Interface (CLI) tool that is used with VSCode and other tools to communicate with the SF APIs and do Development related things.
• Shell Scripts – The scripts that run on the triggered events mentioned before are bash/shell scripts, which is what is used on a lot of terminals and systems that can have a zillion different configurations.  It’s not the best to develop in terms of friendliness but the things it enables are too many to be named.

Connection: (Outbound to Inbound) Github to Salesforce

Use Case: Web-hook data into your org for DevOps tracking purposes

Web-hook as mentioned previously can be thought of as a payload of data that we want to subscribe to when things happen in a system, usually so that we can act on them and trigger some type of automation or store them in a database for reports et al.  It’s up to the platform/system and whether or not they want or can support you getting these updates but all it will want from you is a URL. If you feed the payloads from the web-hook update into an API (or in this case a custom APEX REST Class) you can do things with the data and take advantage of Salesforces ability to give you a chance to stand up an endpoint that will accept data as you define it, tailored if needed.

Named Credentials