INTRODUCTION TO EXTERNAL SERVICES – PART 1 – Shruti Sridharan

If you are a Salesforce Developer, at one point in time you would have been part of an API Integration and all the hassles involved in it. You have to create a Custom Setting to store the Endpoints, a Remote Site Setting to white list the domain, setting up the Authentication and last but not the least the Apex Code to make the requests and the tedious Unit Tests.

Do you want to get rid of all this mess? So let’s see how we can integrate Bit.ly (A Url Shortening service) and Salesforce without writing a single line of code – No code, Only clicks!

External Services (BETA) or Integrations

This new feature in Salesforce helps us to make callout to external APIs with just clicks and no code. The only requirement that we need to get this up and running is – a Swagger Specification or Open API Specification for the API that needs to be integrated with Salesforce. In case if your API doesn’t have a Swagger Specification, don’t worry, you can easily write one by yourself. Guess how?!? You just have to continue reading this blog post 😛

Note: Integrations (Beta) is only available in Lightning Experience.

Exploring Bit.ly API

Don’t tell me you haven’t heard about Bit.ly. Well, if not, here is what it is – it’s a url shortening service. Now what on earth is url shortening? Url shortening is the process of converting long urls to short urls so that they can be shared easily. That’s not it. If you shorten urls using Bit.ly, you get a whole lot of statistics such as number of clicks, number of shares, clicks by region etc.

Now we need to understand what APIs does Bit.ly expose that we developers can consume. Well, let’s take a stab at their developer documentation. Here is the link to the developer documentation – https://dev.bitly.com/api.html. Alright, now you don’t have to take the pain to find the APIs instead let me do that for you.

Bit.ly exposes a GET endpoint that we can use to shorten long urls. It takes three arguments:

  1. Access Token
  2. Long Url (Of course)
  3. Format

I don’t think we will need explanation for the second parameter 😉 Now what about the first and the third? The third parameter defines what should be the response type. Should it be a text, or should it be a JSON. Wow, that’s easy. Alright, now what about the first? That’s going to be a little tricky. To make things simpler, let’s not go down the route of OAuth for Authentication and instead let’s figure out if there is an easier way.

Luckily, we do have an easier way. Bit.ly allows us to create a Generic Access Token which can be used to authenticate our requests to Bit.ly. This means that you don’t have to use a username/password based authentication to generate an access token nor do you need to use OAuth. All you have to do is to generate a Generic Access Token and you are done.

The following screenshots explains how you can obtain the Generic Access Token.

Step 1: At first, click on this link – https://Bit.ly.com/a/oauth_apps. Now follow the screenshots below to create a Generic Access Token.

Bitly_Generic_Token

Click on ‘Generic Access Token’

Step 2:

Bitly_GenToken

Simply type your Account password to generate the Generic Access Token.

Next thing is to figure out what is the API Endpoint that we need to use in order to shorten the long urls. Bit.ly developer documentation to the rescue! The endpoint that we need to use to shorten the long url is as shown below:

GET https://api-ssl.Bit.ly.com/v3/shorten?access_token=ACCESS_TOKEN&longUrl=http%3A%2F%2Fgoogle.com%2F&format=txt

Let me explain the query string parameters:

  1. access_token: The Generic Access Token that we just created.
  2. longUrl: The long url that needs to be shortened.
  3. format: Value of txt means that we need the output in simple plain text.

Well, that’s it with the Bit.ly APIs.

Writing Swagger Schema for Bit.ly

Like as I mentioned before, the only hurdle to get External Services up and running is – a Swagger Specification or an Open API Specification for the API that needs to be integrated with Salesforce. Think of Swagger Spec as the “WSDL for REST” 😉 Let’s see how the Swagger Specification for the above shorten url endpoint of Bit.ly would look like:

{
“swagger”:”2.0″,
“info”:{
“description”:”Shorten URL API”,
“version”:”1.0.0″,
“title”:”Bit.ly”
},
“host”:”api-ssl.bitly.com”,
“schemes”:[
“https”
],
“paths”:{
“/v3/shorten”:{
“get”:{
“summary”:”Convert long URL into short URL”,
“produces”:[
“application/text”
],
“parameters”:[
{
“in”:”query”,
“name”:”access_token”,
“description”:”Access Token”,
“required”:true,
“type”:”string”
},
{
“in”:”query”,
“name”:”format”,
“description”:”Output Format”,
“required”:true,
“type”:”string”
},
{
“in”:”query”,
“name”:”longUrl”,
“description”:”Long URL”,
“required”:true,
“type”:”string”
}
],
“responses”:{
“200”:{
“description”:”Result of the conversion”,
“schema”:{
“type”:”string”
}
}
}
}
}
}
}

  1. info node – This is self-explanatory.
  2. host node – The domain or the host of the API that needs to be integrated.
  3. scheme node – The protocol supported by the API. This is an array of values and could be http, https or both.
  4. paths node – Different paths or routes to the API.
    1. /v3/shorten – The API endpoint exposed by Bit.ly to shorten links.
    2. GET node – Type of the verb.
      1. produces node – Return type of the API endpoint. This could be values like ‘text/plain’, ‘application/json’ etc.
      2. parameters node – Different parameters that the GET verb supports.
        1. access_token parameter –
          1. in node – Defines how the parameter is sent to the API. In our example it is a query string parameter.
          2. name node – Name of the query string parameter.
          3. type node – Data type of the parameter. This can take values like string, number etc.
        2. … (I guess you get the idea for the remaining)
      3. responses node –
        1. 200 node – Defines what will be returned when the API call is successful.

Didn’t I make it easy now? 😉

Setting up the Named Credential

Trust me this is super simple and easy – no rocket science. What exactly is a Named Credential? It is simply the authentication mechanism used by the API. Now you might be wondering, we would be configuring the Generic Access Token in the Named Credential. Well, not exactly. We will be supplying the Generic Access Token as the query string parameter storing it elsewhere in Salesforce and consider the Bit.ly API as an anonymous or an open API. Let me guide you through the steps to create the Named Credential.

NamedCred

Don’t forget to set the Identity Type and Authentication Protocol exactly as shown above.

Setting up External Services

Now we pretty much have everything that we need to setup the External Services for Bit.ly in Salesforce. Let me guide you through the step by step process detailing how to accomplish this in Salesforce.

Step 1: Navigate to Interations (BETA) in Lightning Setup menu.

Step 2: Click on Add New External Service.

Step 3: Supply a name.

Step 4: Copy the Swagger Schema and paste it like as shown below:

New External Serv

Step 5: Click Next and select the Named Credential that you just created.

Step 6: Hit Next.

Step 7: You should now be able to see the Apex Actions identified by the External Services wizard.

That is, it. Now let me explain how this works behind the scenes. When you successfully set up an External Service in Salesforce, behind the scenes Salesforce creates an Apex Class with all the methods that is required to make an API call to the External Application as defined in the Swagger Specification. Now the key thing to understand here is that, this auto generated Apex Class will not be visible to us customers and best of all we don’t have to worry about Unit Tests either. Isn’t the pretty darn awesome?

Creating a Visual Workflow for Url Shortening

This is going to be the fun part. Let’s now build a Visual Workflow that can accept a long url from the user and shorten it. It’s very important to understand that if you have successfully registered the External Service you should start seeing an Apex Action within your Flow’s Palette tab. If you do not see an Apex Action corresponding to your registered External Service, then it means that the External Service registration has failed.

Note: The External Service being a BETA feature doesn’t really throw errors even if you have an improper Swagger Specification. So watch out!

Alright, let me now guide you through the steps to create a Visual Workflow.

Step 1: Drag in a Screen to the Visual Workflow canvas and add a Text Field called ‘Long Url’.

Step1

Step 2: From the palette, drag the Apex Action (created as a result of the External Service registration) on to the canvas. Configure the Input and Output tabs as shown below:

Step2

If you are wondering what the EncodedLongUrl is, then here you go:

EncodedUrl

Step2B

Step 3: Now drag in another Screen element to display the shortened url. Add a Display Text Field to display the shortened url.

Step3

That’s how your flow would look like:

FinalFlow

Now what are you waiting for? Set the Start Element, hit Save and Run.

Adding Flow to a Lead Record Page in Lightning

So how do I use my Flow? Why not add it as a little component for my Lightning Record Page of my Lead object?

Step 1: Navigate to a Lead record and click ‘Edit Page’ on the Settings as shown below:

LeadEditPage

Step 2: Drag the Flow to the Lead Lightning Page.

FlowLightningPage

Hit Save and Activate it.

Well, I know that was long 😛 . If you have reached till here, you should be proud and trust me you have learned another powerful automation tool in Salesforce 😉

Url Shortening in Action

Alright, now let’s see this in action. Have a peek at the video below –

My Few Cents to Remember

External Services is certainly a very powerful tool and I have already become its die-hard fan. That being said, we should not forget it’s still in BETA. Over my experiences, I have noticed that it has shortcomings which could be a potential show stopper but nevertheless it indeed is a great start. Some of the limitations are as below:

  1. External Services does not support APIs which has complex schemas as output. The API needs to return a primitive datatype as its output.
  2. External Services does not support GET verbs without parameters. This is a bug that needs to be addressed.
  3. Make sure that in your Swagger Specification you do not use query string parameters whose name happens to be a keyword in Apex.

This is just a part 1 of my 2 or 3 or … series blog posts on External Services. So keep an eye for more #ExternalServices fun!

Adios Amigos!

Source

Leave a comment

Your email address will not be published. Required fields are marked *