In this blog, I am going to demonstrate about Writing an Open API 2.0 Schema For Salesforce Enhanced External Service using Microsoft Graph API.

We are going to cover the below topics :

Writing Open API 2.0 Schema for Graph API’s Send Mail ().
Using Open API 2.0 Schema in the Enhanced External Services in Salesforce.

Pre Requisite :

Read the blog and learn concepts of Open API 2.0 Schema, it’s structure and the tools that are used to define it – Explore Open API 2.0 and Swagger Tools
For Step 2, Make sure you have covered and have set up configuration from my previous blog – Explore Graph APIs by connecting Microsoft Azure & Salesforce.

Writing Open API 2.0 Schema for Graph API’s Send Mail ()

There are few platforms that don’t provide an Open API Schema on their own. Microsoft Graph API is one among them so We are going to build Open API from MS Graph API for Send Mail () that can be used in Salesforce Enhanced External services.

Before we start building, Please make sure you go through the Schema Examples for Enhanced External Service. So to begin with we are going to refer the first code from the above link :

[code lang=”js”]
{
"swagger": "2.0",
"info": {
"title": "bankService",
"description": "API description in Markdown.",
"version": "1.0.0"
},
"host": "api.example.com",
"basePath": "/v1",
"schemes": [
"https"
],
"definitions": {
"User": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones":{
"type":"array",
"items":{
"type": "object",
"$ref": "#/definitions/Phone"
}
}
}
},
"Phone":{
"properties":{
"typeofphone":{
"type":"string"
},
"phone":{
"type":"string"
}
}
}
},
"paths": {
"/users/{userId}": {
"get": {
"summary": "Returns a user by ID.",
"parameters": [
{
"in": "path",
"name": "userId",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/User"
}
}
}
}
},
"/users": {
"post": {
"summary": "Creates a new user.",
"parameters": [
{
"in": "body",
"name": "user",
"schema": {
"$ref": "#/definitions/User"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
[/code]

Now let’s look at the HTTP Request of Send Mail Graph API that is being referred from Graph API Docs :

[php]

POST https://graph.microsoft.com/v1.0/me/sendMail
Content-type: application/json

{
"message": {
"subject": "Meet for lunch?",
"body": {
"contentType": "Text",
"content": "The new cafeteria is open."
},
"toRecipients": [
{
"emailAddress": {
"address": "fannyd@contoso.onmicrosoft.com"
}
}
],
"ccRecipients": [
{
"emailAddress": {
"address": "danas@contoso.onmicrosoft.com"
}
}
]
},
"saveToSentItems": "false"
}

[/php]

Now we are going to update the sample Open API with the details from the above Send Mail () graph API.Let’s work on the sample Open API code and update lines 1 to 12 to below code snippet Refer Host, Basepath from line 1 of the Graph API code and enter title and description as per the name you wish..

[php]
{
"swagger": "2.0",
"info": {
"title": "Outlook API",
"description": "Outlook API",
"version": "1.0.0"
},
"host": "graph.microsoft.com",
"basePath": "/v1.0",
"schemes": [
"https"
],
[/php]

We will deal with the Definition part from line 13 to 41 in the later section of the blog.

Now let’s look at the ‘Paths‘ Section and update line 41 to 63 to below code snippet:

[php]

"paths": {
"/me/sendMail": {
"post": {
"summary": "Send a Mail",
"parameters": [
{
"in": "body",
"name": "email",
"schema": {
"$ref": "#/definitions/Email"
}
}

[/php]

Below is the explanation forthe above code snippet –

Add Parameters – ”In – Body”,”Name- email”,Schema – ‘” $ref”: “#/definitions/Email “
We have placed ‘Body ‘ for ‘In‘ parameter as code is for the POST request and not GET request
$ref – referring to the definitions section, we have named ‘Email‘ for the entire body section for HTTP request

In the entire process of schema creation, the body is the only challenge as the body itself is a complex JSON and has its own Schema. To define the body section, We need to start from the outermost brace of the body and then continue inside.

I will be explaining how to write a definition for the outer section:

[php]

Email": {
"type": "object",
"properties": {
"message": {
"$ref": "#/definitions/Message"
}

[/php]

In the above code, Type is Object and $ref – a reference to another definition. As I mentioned earlier, We need to work on from outer braces to inner braces, here is the definition for the message –

[php]"Message": {
"type": "object",
"properties": {
"subject": {
"type": "string"
},
"body": {
"$ref": "#/definitions/Body"
},[/php]

Similarly, repeat the process to the innermost curly braces and then merge the entire code. Once you merge the code, make sure you check for any syntax error by copy-pasting the code to Swagger Editor.

Your merged Open API Schema should look like below :

[php]
{
"swagger": "2.0",
"info": {
"title": "Outlook API",
"description": "Outlook API",
"version": "1.0.0"
},
"host": "graph.microsoft.com",
"basePath": "/v1.0",
"schemes": [
"https"
],
"definitions": {
"Email": {
"type": "object",
"properties": {
"message": {
"$ref": "#/definitions/Message"
}
}
},
"Message": {
"type": "object",
"properties": {
"subject": {
"type": "string"
},
"body": {
"$ref": "#/definitions/Body"
},
"toRecipients": {
"type": "array",
"items": {
"$ref": "#/definitions/Recipient"
}
}
}
},
"Body": {
"type": "object",
"properties": {
"contentType": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
"Recipient": {
"type": "object",
"properties": {
"emailAddress": {
"$ref": "#/definitions/EmailAddress"
}
}
},
"EmailAddress": {
"type": "object",
"properties": {
"address": {
"type": "string"
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"paths": {
"/me/sendMail": {
"post": {
"summary": "Send a Mail",
"parameters": [
{
"in": "body",
"name": "email",
"schema": {
"$ref": "#/definitions/Email"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Error",
}
}
}
}
}
}
[/php]

I hope you have understood now how we can create an Open API 2.0 Schema.

Using Open API 2.0 Schema in the Enhanced External Services in Salesforce

Now we can just go ahead and register an enhanced External Service by using this Schema.

Go to Set Up – > External Service and Set it up as instructed in the below screenshot :

Enter Name – Outlook
Select the Name Credentials Set up from the previous blog – Explore Graph API by connecting Microsoft Azure and Salesforce.
Copy Paste the created Open API Schema
Hit Save

I hope you now know how to register an Open API Schema on your own. In the next blog, I would demonstrate how you can use this External Service created via Flow.