DEV Community: kashyap

Retrieve Voice transcripts programmatically.

kashyap — Thu, 28 Apr 2022 05:04:52 +0000

Usecase

You have a functioning service cloud voice product configured in your org and you would like to retrieve the transcripts programmatically to further use them with Einstein API (or) Providing Recommendations via NBA . (here , I am consuming this in a LWC component)

Details

While there are many options on how to use the transcripts fetched, We will focus on the "fetching" part of transcriptions. i.e. We will focus on how to retrieve these transcriptions programmatically and what is needed for that.
The retrieved data then can be consumed by LWC / Aura or Visualforce page as per your requirements.

Pre-requisites

Service Cloud Voice enabled org.
(Here I am using Service Cloud voice with Amazon Telephony model where Amazon connect comes bundled with SCV product)
Rest API (Enabled by default) end point for Transcription
Documentation for reference [ ConnectAPI's ConversationEntries]
Apex Programming (Basics,Making callouts, Understanding of a JWT token)

Steps Outline

JWT Token
Callout to ConversationEntry endpoint by passing ConversationIdentifier (VendorCallKey)

Let's get Started !

Why JWT Token ?

Since we cannot query the Entries directly via SOQL, we are using REST API to retrieve those. To do this, we would need to authenticate ourselves to access the data.
We have to use one of the auth flows to get access token for that. And, JWT is the opted approach.

Wait, I am making a callout from Apex (Used by a Lightning Web Component) to the REST API endpoint of the same org. Do I still need to authenticate again?
Answer is Yes, Also, We cannot use Lightning sessions to access REST APIs. You would see an INVALID_SESSION error.

Now there is a Hack , I have tried creating a visualforce page and adding Api Global Variable to get the session Id like this

<apex:page>
##{!$Api.Session_ID}##
</apex:page>

and then, and then call getContent(thatvfpage) from Apex to get a page that contains an API-capable session ID, which we should be able to use (parsing out ##..##).

However, this doesn't seem to work. So, my next best option was to perform JWT authentication , retrieve the token and use it as this doesn't need user interaction to authenticate the user.

Step-1 JWT Token

Step-1A : Create a Signed Certificate and Key

The OAuth 2.0 JWTbearer authorization flow requires a digital certificate and the private key used to sign the certificate.
This is pretty straight forward and can be done following this doc [Create a Private Key and Self-Signed Digital Certificate]
--> We only need the certificate and key file

Step-1B : Upload this certificate in Files

Go to App Launcher > Files > Upload files > (upload the certificate generated). Assuming the name of file is Server

Step-1C : Create a Connected App and upload the certificate create in Step-1B

This is required as you would be using the certificate for authenticating via this connected app. Provide proper scopes and call back URL can be anything (eg: http://localhost:1717/OauthRedirect)

Step-1D: Write an apex class to handle JWT authentication.

Refer the Documentation here if you want to try this out.

If you are not aware of the entire logic, No worries ! - You can refer this git repo code
which I have written for a visualforce page. The Logic will be still the same.

Quick Explanation of the code:

retrievePKContent -> Is responsible to fetch the content of the certificate we uploaded in Step-1B and stripping off the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- strings.
createHeader -> Just creates JWT header with algorithm name
base64URLencode -> This is to encoding blob input to base64
generateJsonBody -> This generates JSON body for the claimsset.
combineJWTHeader_Claimset ->Combines the header and claimsset.
signPkey-> Signs the Private key and returns the assertion
fetchToken-> basically fetches the token with all the above info passed as JWT assertion.
doInit-> calls all of the methods and performs callout by calling fetchToken.

Step-1E: Test the apex code.

You can try calling doInit() method from execute anonymous to check and verify if the token is being obtained(or not)
Once you are seeing the token properly, You can quickly use postman by making a simple call to any salesforce REST API endpoint of that org to cross check if that token's working.

Step-2: . Callout to ConversationEntry endpoint by passing ConversationIdentifier (VendorCallKey).

Step-2A: The LWC Component

I am trying to fetch the conversations on a button click. So this is the UI part of my LWC.

    <article class="slds-card">
        <div class="slds-card__body slds-card__body_inner">                
            <lightning-button variant="brand-outline" label="Fetch Conversations" title="Fetch Conversations" onclick={onclickhandler} class="slds-m-left_x-small"></lightning-button>
        </div>
        <footer class="slds-card__footer">
                 <template for:each={conversationEntryList} for:item="conversationEntryObject">
                    <p key={conversationEntryObject.serverReceivedTimestamp}>{conversationEntryObject.sender.role} said ---> "{conversationEntryObject.messageText}"</p>
                </template>
         </footer>
        </article>
</template>

Exposing this to Record Page, home page and App page (this can be modified as per the requirement)

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>54.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Connect API Utility Component</masterLabel>
    <description>This is a demo component used to get conversation payload.</description>
    <targets>
        <target>lightning__RecordPage</target>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__RecordPage">
            <objects>
                <object>VoiceCall</object>
                <object>Case</object>
            </objects>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

*Step-2B: Javascript part of the LWC. *

We are fetching the VendorCallKey field value from the current VoiceCall record page

import { LightningElement,api,wire } from 'lwc';
import { getRecord, getFieldValue } from "lightning/uiRecordApi";
import CALLSTATUS_FIELD from "@salesforce/schema/VoiceCall.CallDisposition";
import VENDORCALLKEY_FIELD from "@salesforce/schema/VoiceCall.VendorCallKey";
import fetchConversations from "@salesforce/apex/JWTUtils.fetchConversations";
import MailingPostalCode from '@salesforce/schema/Contact.MailingPostalCode';

const fields = [CALLSTATUS_FIELD,VENDORCALLKEY_FIELD];

export default class EinsteinConversationSentiment extends LightningElement {

    isCallCompleted = false;   
    conversationEntriesResponse={};
    conversationEntryList=[];
    currentCE;
    conversationEntryObjectList=[{
        role:"NA",
        message:"NA",
        servertimestamp:"NA"
    }];
    error;
    conversationMap;

    @api
  recordId;

    @wire(getRecord, {
        recordId: "$recordId",
        fields
      })
      voicecall;



      onclickhandler(e)
      {
            console.log("Vendor Call Key for this record - "+this.voicecall.data.fields.VendorCallKey.value );
        fetchConversations({ vcKey: this.voicecall.data.fields.VendorCallKey.value })
            .then(result => {
                this.conversationEntriesResponse = JSON.parse(result);
                console.log(this.conversationEntriesResponse.conversationEntries);
                this.conversationEntryList = this.conversationEntriesResponse.conversationEntries;
            })
            .catch(error => {
                this.error = error;
            });
      }

}

*Step-2C: Calling the Connect Conversation Entries Endpoint. *

Now, the Logic to fetch the entries.

NOTE- I have added this in the same class where I am fetching JWT token.
Refer Step-1D git repo class.

@AuraEnabled
    public static String fetchConversations(String cid){
        // this method is responsible to fetch the JWT token. 
// stores the access token in access_token variable
        JWTUtils.doInit();
// replace your mydomain here.
        String url = String url = 'https://<mydomain>.my.salesforce.com/services/data/v53.0/connect/conversation/'+cid+'/entries';

        try {
            // Instantiate a new http object
            Http h = new Http();
            // Instantiate a new HTTP request, specify the method (GET) as well as the endpoint
            HttpRequest req = new HttpRequest();
            req.setEndpoint(url);
            req.setMethod('GET');
            req.setHeader('Authorization','Bearer '+access_token);
            // Send the request, and return a response
            HttpResponse res = h.send(req);
            System.debug(res.getBody());
            return res.getBody();
        } catch (Exception e) {
            throw new AuraHandledException(e.getMessage());
        }
    }

You would receive the list of ConversationEntries as a response from the conversation entries endpoint. The below object shows one of the ConversationEntry from the List returned.

In Step-2B you are parsing the response, and storing the list of conversationentries in "conversationEntryList" and if you compare this with Step-2A , you can see we are iterating over "conversationEntryList"

this.conversationEntryList = this.conversationEntriesResponse.conversationEntries;

<template for:each={conversationEntryList} for:item="conversationEntryObject">
 <p key={conversationEntryObject.serverReceivedTimestamp}>{conversationEntryObject.sender.role} said ---> "{conversationEntryObject.messageText}"</p>
 </template>

Each conversation Entry is stored in "conversationEntryObject" variable and that object consists of below information.

{
    "clientDuration": 4695,
    "clientTimestamp": 1649938471000,
    "identifier": "f7e30ac2-6666-3333-oooo-0c0811wsfb304",
    "messageText": "12, okay?",
    "relatedRecords": [
        "0LQ5j000000PuK1"
    ],
    "sender": {
        "appType": "telephony_integration",
        "role": "Agent",
        "subject": "VIRTUAL_AGENT"
    },
    "serverReceivedTimestamp": 1649938501255
}

Now, (for this project) what we are looking here is for 2 things:

-> Who said it ? (Is the conversation message from Agent Or End user?)-> "sender.role"
-> What did they say ? (The actual Message) -->"messageText"

We are obtaining those in below way

{conversationEntryObject.sender.role}
{conversationEntryObject.messageText}

Once All of these pieces are in place, You should see something like this

Now we are able to see the transcripts (the conversation of the voice call) obtained programmatically.

OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration

kashyap — Wed, 31 Mar 2021 06:01:50 +0000

Isn't Salesforce a CRM ? Why are talking about JWT with Salesforce ?

Exactly, Salesforce is a CRM and also a solid developer friendly and completely flexible platform which supports integration with almost any of 3rd party systems , database, applications.

Hmmmm ok .. Why JWT ? There are other authorization flows which can be used.

For other types of mainstream authorization flows such as Webserver flow, you need a user presence to authenticate.

Sometimes you want to authorize servers to access data without interactively logging in each time the servers exchange information.

For these cases, you can use the OAuth 2.0 JSON Web Token (JWT) bearer flow.

But How ?

Well, This flow uses a certificate to sign the JWT request and doesn’t require explicit user interaction.
However, this flow does require prior approval of the client app.

How does this work in a nutshell ?

The client(who ever is trying to access salesforce data) posts a JWT to the Salesforce OAuth token endpoint.
Salesforce then processes the JWT, which includes a digital signature, and issues the access token(As per prior approval of app).

OK! Lets look into a simple example between 2 Salesforce Orgs

OrgA with a Visualforce tab acting as Client App.

OrgB acting as target salesforce server from where we need to get authorized and fetch data.

I will refer these as OrgA and OrgB through out the post.

Lets take a look into our client application (which is a visualforce page tab)

When you hit Fetch JWT Token button on that page, You should expect an access token along with other parameters issued by a our salesforce OrgB (or) as highlighted "https://oceans11-dev-ed.my.salesforce.com"

Lets talk code now.

I will split the flow into 6 steps for simplicity.

Create a JWT
Create a Certificate and private key.
Upload the Certificate in connected app of your target OrgB
Upload the private key in Files of your Client OrgA
Request for access token
Salesforce Grants Access Token

1. Create a JWT

JWT is JSON Web Token. It consists of header and claims.
JWT header should look like this

{"alg":"RS256"}

alg - algorithm you are using

It firstly consists of claims, it should be of this format.

{
"iss": "3MVG99OxTyEMCQ3gNp2PjkqeZKxnmAiG1xV4oHh9AKL_rSK.BoSVPGZHQ
ukXnVjzRgSuQqGn75NL7yfkQcyy7", 
"sub": "my@email.com", 
"aud": "https://login.salesforce.com", 
"exp": "1333685628"
}

lets see what do we have here... These are called JWT Claims.

iss - OAuth client_id
sub - username of the target org you are connecting to
aud - url you would want to connect. if thats a sandbox then use test instead of login.
exp - time to expire the token.

You have to Base64url encode the JWT Header and the encoded JWT Claims Set separately without any line breaks.

Next, Create a string for the encoded JWT Header and the encoded JWT Claims Set in this format

Encoded JWT Header+ "." + Encoded JWT Claims

It would look something like this (before the dot(.) we have the header in encoded format )

eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiM01WRzk5T3hUeUVNQ1EzZ05wMlBqa3FlWkt4bm1BaUcxeFY0b0hoOUFLTF9yU0su
Qm9TVlBHWkhRdWtYblZqelJnU3VRcUduNzVOTDd5ZmtRY3l5NyIsICJwcm4iOiAibXlAZ1NjI4In0=

Please refer to generateJsonBody and combineJWTHeader_Claimset method for the logic using apex code provided in the Git Repo link at the end of this post.

Now we have the JWT claims & header , lets see step 2

2. Create a Certificate and private key.

This flow requires a digital certificate and the private key used to sign the certificate.

Please feel free to use your own private key and certificate issued by a certification authority.

Alternatively, you can use OpenSSL to create a key and a self-signed digital certificate.

Refer this on How to create a Digital Certificate

Once you have completed this step,

3. Upload the Certificate in connected app of your target OrgB

We would need to upload this digital certificate to the connected app in OrgB that is also required for the JWT bearer authorization flow.

4. Upload the private key in Files of your Client OrgA

and create the payload to access the token

As You already have the private key file which you obtained while creating the self signed open ssl certificate, we use it to sign the request

Since this is a salesforce org, I have uploaded it in a File and retrieved it using the ContentVersion object.

Sign the resulting string using RSA SHA256.
Create a string of the string from this step in the following format.

the combined JWT string + "." + base64_encoded_signature

See retrievePKContent and signPkey method from the Git repo link which

the base64 encoded signature should be something like this (I have clipped the content for keeping it small).

eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiAiM01WRzk5T3hUeUVNQ1EzZ05wMlBqa3FlWkt4bm1BaUcxeFY0b0hoOUFLTF9yU0su
Qm9TVlBHWkhRdWtYblZqelJnU3VRcUduNzVOTDd5ZmtRY3l5NyIsICJwcm4iOiAibXlAZ1NjI4In0=.iYCthqWCQucwi35yFs-nWNgpF5NA_a46fXDTNIY8ACko6BaEtQ9E6h4Hn1l_pcwcK
I_GlmfUO2dJDg1A610t09TeoPagJsZDm_H83bsoZUoI8LpAA1s-2a
36y2L2Bh7M8TNWiKa_BNM6s1FNKDAwHEWQrNtAeReXgRy0MZgQY2rZtqT2FcDyjY3JVQb
En_CSjH2WV7ZlUwsKHqGfI7hzeEvVdfOjH9NuaJozxvhPF489IgW6cntPuT2V647JWi7ng

5. Request for Access Token.

Next, Once you have the entire base64encoded string , make a callout to the token endpoint of the target org ORGB in this case.

the endpoint should look like this

https://login.salesforce.com/services/oauth2/token?grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion='+YOUR-ENTIRE-JWT-VALUE STRING YOU PREPARED '

This should be a POST call.

6. Salesforce grants access token.

once done, if everything is place correctly, You should see a response with access token.

If we see the Visualforce page above, that gives you the below result.

If you observe the image, I got the access token, I can see all the scopes and the id corresponds to the user id and org id
and the token type which is bearer.

Using this token you can easily access the data of the Target OrgB

Please find the complete code in GIT Link HERE
Please do not commit any changes to main

Hope this post helps someone who is trying to understand the JWT with salesforce or is trying to implement it.

See you again with a new post.

Password Manager using LWC

kashyap — Mon, 29 Mar 2021 07:50:36 +0000

Total time taken - 28 hours (including intermittent breaks :P )

This is Password manager application which can be used for internal teams to store their credentials as a Lightning App.

This application performs basic functionalities of a password manager Create password records, Update them, store and delete them along with generation of random passwords and exporting them to CSV (send to current user via Email attachment).

This uses Lightning message service to relay the selections made on the list to other components.

Link to Git repo:
https://lnkd.in/g2YpiGm

The whole purpose of this application is to showcase flexibility of using LWC for various functionalities.