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]
[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]
[php]
"paths": {
"/me/sendMail": {
"post": {
"summary": "Send a Mail",
"parameters": [
{
"in": "body",
"name": "email",
"schema": {
"$ref": "#/definitions/Email"
}
}
[/php]
- 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]
[php]"Message": {
"type": "object",
"properties": {
"subject": {
"type": "string"
},
"body": {
"$ref": "#/definitions/Body"
},[/php]
[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.
References :
- Open API Schema Examples – Salesforce Help Documentation
- MS Graph API Send Email () – Microsoft Documentation
- Swagger Editor – Swagger Open Source Documentation
- Exploring Graph API by connecting Microsoft Azure and Salesforce
- Exploring Open API 2.0 and Swagger Tools
- Register an External Service in Salesforce – Trailhead