Luware Knowledge

Nimbus Portal Nimbus Admin Release Notes Service Status
Home Nimbus Use Cases Administration Use Cases

Use Case - Exposing an API via Microsoft Entra ID

Communicate with Assistant using a custom API accessible via custom scopes.

In this use case, we handle the scenario where you want to communicate with Assistant using a custom API, which is reachable via custom scopes.

Below you can find an example of how such scenario can be covered and what additional steps are required for having a Service Call template assigned to a service.

PRECONDITIONS

You require tenant administrator rights to to create, update and delete Action Templates

 

💡 Tip: You can apply the concepts shown here to both Direct Call Templates and Service Call Templates.

Show Icon Legend

💡 = A hint to signal learnings, improvements or useful information in context. 🔍 = Info points out essential notes or related page in context.
☝ = Notifies you about fallacies and tricky parts that help avoid problems. 🤔 = Asks and answers common questions and troubleshooting points.
❌ = Warns you of actions with irreversible / data-destructive consequence. ✅ = Intructs you to perform a certain (prerequired) action to complete a related step.
 
 

Expose an API

✅ To get started, create an App registration in your 1 or update an existing one. 💡 Leave all application options as they are.

Now to get started with the API Steps:

  1. Select Expose an API2 (located in the "Manage" section).
  2. Set the URI ID (your App ID)
  3. Add a scope :
    1. Scope name: 💡 we recommend a naming convention like "Crm.Read" 
    2. Admin Consent: Allow to read in CRM Xyz
    3. Description: As you want 
    4. State: Enabled

References: 

 

✅ After the Scope creation:

  1. Copy the Scope to clipboard (Save it for later usage)
  2. Click on "Add Client Application".

Now we make sure that the Assistant Client ID gets added under the section Authorized client applications. 
Enter the Client ID: 0ec02475-4b29-4cb5-8338-aa5623d301a2

This is the "Luware Nimbus ACS" client ID supplied by the Nimbus Customer Success team. 

💡 Note that you will only find this App in your Tenant when a preivous grantlink by Nimbus customer success was confirmed.

Under "Authorized Scopes" paste the Scope Link from your clipboard (step 1).
🌟 Tip: Keep this link available, you will need it again later.

✅ After the Client Application was added:

  1. Head to "API Permissions" (in the manage section).
  2. Click "Add a Permission" → Request API permissions.
  3. Click on "My APIs" tab.
  4. Select new "Crm.Read" entry (from the previous step).
  5. Check "Crm.Read" to Grant Admin Consent in the Permissions section

Usage of custom scopes within Assistant

✅ Ensure to have the "Scope Link" ready for this step. We will need it to create a Service Call Template with a Web Request action.

🔍 You can follow the steps of Use Case - Chaining of Assistant requests, however with the following differences to your first web request action:

  1. Within Nimbus Administration, head to Configuration > Service Call Templates
  2. Create a new Template. Configure your template name, OU and Description (e.g. "Retrieve data from CRM)"
  3. Within the template Add a new "Web Request" Trigger 

Define the URL to your CRM.

Note that this is a case-by-case topic. The API call and parameter to identify a caller is completely up to you. Refer to the System Fields and Parameters page for a list of available references within Nimbus.

 

 

💡 You can skip the "Headers" tab as optional. 

  1. Switch to the "Authorization" Tab
  2. Select Authentication type "Scopes".
  3. Create a new Scope item.
  4. Paste your "Scope Link" created and copied in Azure from 🌟 step 1 earlier above.
     

💡 In our example:

CODE
api://82ceec75-cdb5-4e75-ab7e-fdcae636efea/Crm.Read

☝ Please note that this link is completely unique to your Scope and Naming, Ensure that the spelling is done correctly on the name suffix after the /
  1. Switch to the "Response" Tab
  2. Enable "Wait for Response"
  3. Set the "Wait Timeout" sufficiently high for your CRM to respond.

 

Back in the "General" Tab

  1. Copy "Trigger ID" to clipboard
  2. "Save & Apply" this trigger, then create a new one

 

✅ Now we show your web results in the Browser of your Agents. Add another trigger action of type "Web Request" right after your previous.

  1. Enable "Open in default browser" → Only the "General" Tab will now be shown.

Create an URL as follows and paste the Trigger ID

CODE
https://internal-crm-url.com/{{f79470c3-c370-43ed-a8eb-edd9b2547e40.body.dossierId}}
Click on Save and Apply.
  1. Congratulations, you are done. Don't forget to assign your template to the Context Service Settings where you wish to trigger this context. → The browser will now open for all Agents in that Service whenever there is an incoming call.

 

Protect your own API (sample for a simulated backend API in c#)

In this step we show some possibilites how you can protect your backend and verify your custom scope.

💡 This is just a sample, your API can look completely different.

🔍 Your appsettings.json contains the necessary values (for the -application mentioned above in step 1)

Property Value
Instance https://login.microsoftonline.com/
Domain Your domain either with .onmicrosoft or your owned domain
TenantId Your TenantId
ClientId The Id of the client application
Audience ☝ The audience needs to match the Application ID URI
Scopes Your scopes you want to verify. E.g. "crm.read"
CallbackPath /signin-oidc or what ever you have configured as redirectUri
ClientSecret via Azure Key Vault
ClientCertificates via Azure Key Vault
  • Add your service for the Authentication to your builder during startup based on the configuration above
  • Use the correct controller attributes to secure your API controller
    • [Authorize] - for regular Authorization
    • [RequiredScope(RequiredScopesConfigurationKey = "AzureAd:Scopes")] - the verify the correct scope from the configuration
Assistant Configuration

The Assistant configuration allows to define direct- or service call templates. T...

Address Books

Address books extend the Nimbus search beyond what is within your internal O365 u...

Interact Domain Templates (CORS)

A domain template define and restrict where the source code of the Interact conta...

Not Available Reasons

Not Available Reasons (or N/A Reasons, NAR) are reasons that a user must specify ...

Table of Contents