Modern Work App Consult Blog articles

How to Export an Agent Developed in Copilot Studio

luisdem — Mon, 10 Mar 2025 17:20:10 GMT

If you've developed an agent in Copilot Studio and need to export it, follow these steps:

Open Copilot Studio: Navigate to https://copilotstudio.microsoft.com
Access Solutions: On the left-hand side menu, click on the three dots (...) and then select Solutions.

3. Create a New Solution:

In the top menu bar, click on + New solution.
Fill in the details for the new solution, including the display name, name, selecting or creating a new publisher, defining the version, and then click Create.

4. Navigate to the Solution List:

Return to the list of solutions.
Find and click on the name of the solution you want to export, which is usually located within default solutions.

5. Select the Agent:

Click on Agents and select the agent you wish to export.
In the top menu or by clicking on the three dots (...), select Advanced and then + Add to solution.

6. Add Agent to Solution:

hoose the solution you created earlier and click Save.
Return to the list of solutions.

7. Export the solution:

Click on the solution that you have exported the agent to and click on Export Solution.
Click on Next:
You have the option to enable the solution checker during the export process. Once you've made your selection, click on Export.
Once the export process is complete, the download button will become available. Click on the Download button to save the .zip file with your agent.

By following these steps, you can successfully export your agent from Copilot Studio.

How to Import an Agent Developed in Copilot Studio

If you need to import an agent into Copilot Studio, follow these steps:

Open Copilot Studio: Navigate to https://copilotstudio.microsoft.com
Access Solutions: On the left-hand side menu, click on the three dots (...) and then select Solutions.

3. Import the Solution:

In the top menu bar, click on Import solution.
Click on the Browse button to open the file selection dialog. Navigate to the location where your solution file with the agent is stored, select the file, and then click Open. After selecting the file, click on Next to proceed with the import process.
Carefully review all the information to ensure it is correct. Once you have double-checked the details, click on Next to proceed.
Click on Import to finish.

4. Verify the Import:

Make sure that the solution was imported successfully.
After the import is complete, go back to the Copilot Studio home page and check for your agent.

In this post, you learned how to export and import an agent in Copilot Studio. If you have any questions or run into issues, feel free to reach out for support. Happy exporting and importing!

ServiceNow Declarative Agent for M365 Copilot (non-official)

luisdem — Wed, 30 Oct 2024 13:28:53 GMT

This project showcases the use of a Declarative Agent for Microsoft 365 Copilot, designed to create personalized experiences through specific instructions, actions, and knowledge. Specializing in ServiceNow, this declarative agent leverages the following capabilities and actions:

SharePoint Integration: Enables users to retrieve information from files, which can be useful for providing context to ServiceNow tickets and for creating new tickets.
Graph Connectors: Utilizes the Knowledge Base and Services Catalog connectors from ServiceNow to enhance functionality.
Plugins: Incorporates a ServiceNow Scripted REST API that allows users to list their incidents and create new ones.

Note: This sample code is intended for illustrative purposes only and should not be deployed in a production environment without thorough review. It demonstrates how to build a simple Declarative Copilot using Visual Studio Code and the Teams Toolkit. Please note, I do not have the rights or permission from ServiceNow and Adventure Time (Ice King logo).

Prompt Samples

1. ServiceNow Knowledge Graph Connector:

List the articles regarding Outlook 2010. Place the results in a table with the article title in one column and a brief summary in the other

ServiceNow Service Catalog Graph Connector

How do I request a new laptop?

SharePoint Capability

List the items from the snow spreadsheet and format as a table. Also, please add an integer column as the first column, listing the item numbers.

Plugin: List my incidents

List my incidents

Plugin: Create a new incidents

The following prompt uses the list of incidents returned from the previously executed snow spreadsheet file. I’m asking Copilot to create a new incident based on the sixth item in that list.

Create a new incident for the item 6

Build a basic declarative agent with API plugin

Declarative agents are customized versions of Microsoft 365 Copilot that help you to create personalized experiences by declaring specific instructions, actions, and knowledge.

With the declarative agent, you can build a custom version of Copilot that can be used for specific scenarios, such as for specialized knowledge, implementing specific processes, or simply to save time by reusing a set of AI prompts. For example, a grocery shopping Copilot declarative agent can be used to create a grocery list based on a meal plan that you send to Copilot.

You can extend declarative agents using plugins to retrieve data and execute tasks on external systems. A declarative agent can utilize multiple plugins at the same time.

Get started

Prerequisites

To run this app template in your local dev machine, you will need:

Node.js, supported versions: 16, 18

A Microsoft 365 account for development.

Teams Toolkit Visual Studio Code Extension version 5.0.0 and higher or Teams Toolkit CLI

Microsoft 365 Copilot license

ServiceNow Developer Instance

First, select the Teams Toolkit icon on the left in the VS Code toolbar.
In the Account section, sign in with your Microsoft 365 account if you haven't already.
Create Teams app by clicking Provision in "Lifecycle" section.
Select Preview in Copilot (Edge) or Preview in Copilot (Chrome) from the launch configuration dropdown.
Select your declarative agent from the Copilot app.
Send a prompt.

What's included in the project

Folder	Contents
`.vscode`	VSCode files for debugging
`appPackage`	Templates for the Teams application manifest, the plugin manifest and the API specification
`env`	Environment files

The following files can be customized and demonstrate an example implementation to get you started.

File	Contents
`appPackage/declarativeCopilot.json`	Define the behaviour and configurations of the declarative agent.
`appPackage/manifest.json`	Teams application manifest that defines metadata for your declarative agent.
`appPackage/instructions.txt`	Define how the agent should communicate. An agent might be concise, detailed, interactive, or suggestive. Also include any restrictions that should be applied.
`appPackage/ai-plugin.json`	It contains everything Copilot needs to know about the API that isn’t in the Swagger file. It breaks the API down into “functions” that share a common URL path and result set.
`appPackage/apiSpecificationFile/openapi.json`	It is the Swagger file for the API.

The following are Teams Toolkit specific project files. You can visit a complete guide on Github to understand how Teams Toolkit works.

File	Contents
`teamsapp.yml`	This is the main Teams Toolkit project file. The project file defines two primary things: Properties and configuration Stage definitions.

Addition information and references

ServiceNow Plugin

This project consumes two ServiceNow Scripted REST APIs to integrate with ServiceNow's platform, enabling seamless data exchange and automation of specific workflows.

ServiceNow Scripted REST APIs

Scripted REST APIs in ServiceNow allow developers to create custom web service APIs that can interact with ServiceNow data and services. These APIs can be configured to support various HTTP methods (GET, POST, PUT, DELETE) and can be used to perform operations like querying data, creating records, updating records, and deleting records.

Creating Scripted REST APIs

This section includes the code for the Scripted REST API designed to list the incidents associated with a user.

Navigate to System Web Services: Go to System Web Services > Scripted Web Services > Scripted REST APIs.
Create a New API: Click on New and provide a name and namespace for your API.
Define Resources: Create resources by specifying the HTTP method, relative path, and any path parameters.
Write Scripts: In the scripting window, write the necessary scripts to handle the request and response objects.
Test the API: Use the REST API Explorer to test your API and ensure it works as expected.

List my Incidents REST API

The API is built on ServiceNow's platform, utilizing its robust scripting capabilities to fetch and return incident data.

This API supports the GET method and responds with a JSON object containing the relevant incident details.

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {

 
	var username = request.pathParams.username;
    //var username = request.queryParams.username;
	
	// Get the ServiceNow instance name
    var instanceName = gs.getProperty('instance_name', 'default_instance');

	// Replace '+' with ' ' (space)
    username = username.replace(/\+/g, ' ');

    // Query the Incident table for incidents associated with the email
    var gr = new GlideRecord('incident');
    gr.addQuery('caller_id.name', username);
    gr.query();

    // Prepare the result
    var result = [];
    while (gr.next()) {
        result.push({
            number: gr.getValue('number'),
            short_description: gr.getValue('short_description'),
            state: gr.getValue('state')
        });
    }

    // Check if incidents were found
    if (result.length === 0) {
        response.setStatus(404);
        response.setBody({error: 'No incidents found for the user name'});
    } else {
        // Set the result as the response body
        response.setStatus(200);
        response.setBody(result);
    }

})(request, response);

Create a new incident

This section includes the code for the Scripted REST API designed to create new incidents on ServiceNow.

This API leverages ServiceNow’s capabilities to accept incident details through a POST request and create a corresponding incident record in the ServiceNow system. The request body should contain the necessary incident data, and upon successful creation, the API responds with the details of the newly created incident.

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {

    // Parse the request body to get incident details
    var requestBody = request.body.data;

    // Check required fields in the request body
    if (!requestBody || !requestBody.short_description || !requestBody.username) {
        response.setStatus(400); // Bad Request
        response.setBody({error: "Missing required fields: short_description or username"});
        return;
    }

    // Lookup caller_id based on the username
    var userGr = new GlideRecord('sys_user');
    userGr.addQuery('name', requestBody.username);
    userGr.query();

    if (!userGr.next()) {
        response.setStatus(404); // Not Found
        response.setBody({error: "User not found with username: " + requestBody.username});
        return;
    }

    var callerId = userGr.sys_id;

    // Create a new incident record in ServiceNow
    var gr = new GlideRecord('incident');
    gr.initialize();
    gr.short_description = requestBody.short_description;
	gr.description = requestBody.description;
    gr.caller_id = callerId; // Assign the found caller's sys_id
    gr.category = requestBody.category || 'inquiry'; // Optional: Default category
    gr.impact = requestBody.impact || 3; // Optional: Default to low impact
    gr.urgency = requestBody.urgency || 3; // Optional: Default to low urgency

    var incidentNumber;
    try {
        // Insert the incident record
        var sysId = gr.insert();
        incidentNumber = gr.number;

        // Set success response
        response.setStatus(201); // Created
        response.setBody({
            result: 'Incident created successfully',
            sys_id: sysId,
            number: incidentNumber
        });
    } catch (e) {
        // Handle error during record insertion
        gs.error("Error creating incident: " + e.message);
        response.setStatus(500); // Internal Server Error
        response.setBody({error: "Error creating incident: " + e.message});
    }

})(request, response);

There are two versions.

The official one, shared at Microsoft repo, uses a REST API developed by Cristiano to connect to ServiceNow:

copilot-pro-dev-samples/samples/da-SnowWizard at main · pnp/copilot-pro-dev-samples · GitHub

My version, uses the Scripted REST API from ServiceNow and uses two ServiceNow Graph Connectors:

GitHub - luishdemetrio/SnowKing

THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.

Step by Step: Integrate Advanced RAG Service with Your Own Data into Copilot Studio

freistli — Fri, 06 Sep 2024 03:56:31 GMT

This post is going to explain how to use Advanced RAG Service easily verify proper RAG tech performance for your own data, and integrate it as a service endpoint into Copilot Studio.

This time we use CSV as a sample. CSV is text structure data, when we use basic RAG to process a multiple pages CSV file as Vector Index and perform similarity search using Nature Language on it, the grounded data is always chunked and hardly make LLM to understand the whole data picture.

For example, if we have 10,000 rows in a CSV file, when we ask "how many rows does the data contain and what's the mean value of the visits column", usually general semantic search service cannot give exact right answers if it just handles the data as unstructured. We need to use different advanced RAG method to handle the CSV data here.

Thanks to LLamaIndex Pandas Query Engine, which provides a good idea of understanding data frame data through natural language way. However to verify its performance among others and integrate to existing Enterprise environment, such as Copilot Studio or other user facing services, it definitely needs AI service developing experience and takes certain learning curve and time efforts from POC to Production.

Advanced RAG Service supports 6 latest advanced indexing techs including CSV Query Eninge, with it developers can leverage it to shorten development POC stage, and achieve Production purpose. Here is detail step to step guideline:

POC Stage

Prerequisite

a. Deploy below models in [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/multi-service-resource?pivots=azportal), get its Service URL and Key:

gpt-4o mini or gpt-4o

text-embedding-3-small

b. Create [Azure Document Intelligent](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/create-document-intelligence-resource?view=doc-intel-4.0.0) Service, get its Service URL and Key.

c. One Docker Environment:

Windows Docker, WSL2, Debian or Ubuntu

Setup

a. In Docker environment, run this command to clone the dockerfile and related config sample:

git clone https://github.com/freistli/AdvancedRAG.git

b. In the AdvancedRAG folder, rename .env.sample to .env

cd AdvancedRAG
mv .env.sample .env

c. In the .env file, configure necessary environment variables. In this tutorial, let's configure:

#Azure OpenAI Setting
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_Deployment=gpt-4o-mini
AZURE_OPENAI_EMBEDDING_Deployment=text-embedding-3-small
AZURE_OPENAI_ENDPOINT=https://[name].openai.azure.com/

# Azure Document Intellenigence
DOC_AI_BASE=https://[name].cognitiveservices.azure.com/
DOC_AI_KEY=

NOTE:

Azure AI Search is not required here because the CSV Query Engine doesn't need it. If you want to try Azure AI Search Index, then configure it.

d. Build your own docker image:

docker build -t dockerimage:tag .

e. Run this docker:

docker run -p 8000:8000 dockerimage:tag

f. Access http://localhost:8000/

Now we can see this service UI

Evaluate Response Quality & Performance

a. Click the CSV Query Engine tab, upload a test CSV file, click Submit

b. Click the Chat Mode tab, now we can use Natural Language to test how good the CSV Query Engine at understanding CSV content:

Expose it as a REST API Endpoint

The Advanced RAG Service is built with Gradio and FAST API. It opens necessary API Endpoints by default. We can turn off any of them in the .env settings.

The Chat endpoint can be used for different index types query/search. Since we are using "CSV Query Engine", now it is:

POST {{LocalURL}}/advchatbot/run/chat
content-type: application/json

{
"data": [
    "how many records does it have",   
    "", 
    "CSV Query Engine",   
    "/tmp/gradio/86262b8036b56db1a2ed40087bbc772f619d0df4/titanic_train.csv",    
    "You are a friendly AI Assistant" ,
    false   
]
}

The response is:

{
"data": [
    "The dataset contains a total of 891 records. If you have any more questions about the data, feel free to ask!",
    null
],
"is_generating": true,
"duration": 3.148253917694092,
"average_duration": 3.148253917694092,
"render_config": null,
"changed_state_ids": []
}

Using this method, we can easily integrate the specific RAG capability to our own service, such as Copilot Studio. Before that, let's publish the service first.

Publish to Azure

We have different methods to release docker as an app service. Here are the generate steps when we use Azure Contain Registry and Azure Container App.

a. Create Azure Container Registry resource [ACRNAME], upload your tested docker image to it. The command is:

az login
az account set -s [your subscription]
az acr login -n [ACRNAME]
docker push [ACRNAME].azurecr.io/dockerimage:tag

b. Create an Azure Container App, deploy this docker image, and deploy it. Don't forget enable Session Affinity for the Container App.

To automate the Azure Container App deployment, I provided deploy_acr_app.sh in the repo.

#!/bin/bash
set -e

if [ $# -eq 0 ]
then
echo "No SUF_FIX supplied, it should be an integer or a short string"
docker image list
exit 1
fi

SUF_FIX=$1
RESOURCE_GROUP="rg-demo-${SUF_FIX}"
LOCATION="eastus"
ENVIRONMENT="env-demo-containerapps"
API_NAME="advrag-demo-${SUF_FIX}"
FRONTEND_NAME="advrag-ui-${SUF_FIX}"
TARGET_PORT=8000
ACR_NAME="advragdemo${SUF_FIX}"

az group create --name $RESOURCE_GROUP --location "$LOCATION"

az acr create --resource-group $RESOURCE_GROUP --name $ACR_NAME --sku Basic --admin-enabled true

az acr build --registry $ACR_NAME --image $API_NAME .

az containerapp env create --name $ENVIRONMENT --resource-group $RESOURCE_GROUP --location "$LOCATION"

az containerapp create --name $API_NAME --resource-group $RESOURCE_GROUP --environment $ENVIRONMENT --image $ACR_NAME.azurecr.io/$API_NAME --target-port $TARGET_PORT --ingress external --registry-server $ACR_NAME.azurecr.io --query properties.configuration.ingress.fqdn

az containerapp ingress sticky-sessions set -n $API_NAME -g $RESOURCE_GROUP --affinity sticky

To use it:

chmod a+x deploy_acr_azure.sh
az login
az account set -s [your subscription]
./deploy_acr_azure.sh [suffix number]

Note: for more details about this sh, can refer to this guideline.

After around 7~8 minutes, the Azure Container App will be ready. You can check the output and access it directly:

To protect your container app, can follow this guide to enable authentication on it.

Enable authentication and authorization in Azure Container Apps with Microsoft Entra ID

Integrate into Copilot Studio

By default, we need to upload a CSV to the AdvRAG service before analysis. The service always saves the uploaded file to its local temp folder on server side. And then we can use temp file path to start the analysis query.

To skip this step, we can save common files in subfolder rules of the AdvancedRAG folder, and then build your docker image. The files will be copy to the docker itself. As a demo, I can put a CSV file in AdvancedRAG/rules/files, and then pubish the docker to Azure.

a. Open Copilot Studio, create a new Topic, use "CSV Query" to trigger it.

b. For demo purpose, I upload a test CSV file and got its path, then put it into a variable:

c. Now let's add a Question step to ask what question the user want to ask:

d. Click "+", "Add an Action", "Create a flow". We will use this new flow to call AdvancedRAG service endpoint.

e. We need Query, File_Path, System_Message as input variables.

e. In the flow Editor, let's add an HTTP step. In the step, post the request to the AdvancedRAG endpoint as below:

Save the flow as ADVRAGSVC_CSV, and publish it.

f. Back to Copilot Studio topic, we will add the action as below, and set input variables as need:

g. Publish and open this Custom Copilot in Teams Channel based on this guide.

h. Now we can test this topic lit this, as we see, even I used gpt-4o-mini here, the response accuracy is very good:

From above, it shows how to quickly verify potential useful RAG techs (Pandas Query Engine) in the AdvancedRAG service studio, expose and publish it as REST API endpoint which can be used by other service, such as Copilot Studio.

The overall process can be applied to Knowledge Graph, GraphRAG, Tree Mode Summary and other type indexes with this AdvnacedRAG service. The main difference is for CSV, we can use its file path as the index name directly, for other indexes, we need to build index firstly, and then use index folder path as Index name. In this way developers can efficiently move from proof of concept to production, leveraging advanced RAG capabilities in their own services.

More Information

How to improve

The AdvancedRAG service focuses on key logic and stability of different important index types, the efficiency to be landed into M365 AI use cases. For any feature improvement ideas, feel free to visit below repos to create issues, fork projects and create PRs.

Docker Deploy Repo: https://github.com/freistli/AdvancedRAG

General Introduction

Exploring the Advanced RAG (Retrieval Augmented Generation) Service

freistli — Fri, 06 Sep 2024 03:55:55 GMT

In the ever-evolving landscape of AI, LLM + RAG (Retrieval Augmented Generation) is a typical use scenario. Retrieving accurate related chunked data from complicated docs and then improving LLM response quality becomes challenge. There is no a silver bullet RAG can address all requirements so far. Developers need to verify different advanced RAG techs to find out which is a proper one for their scenarios considering accuracy, response speed, costs, etc. In order to solve this, with Azure Intelligent Document, Azure OpenAI, LlamaIndex, LangChain, Gradio..., I developed this AdvancedRAG service. This service is encapsulated in a Docker container, offers a streamlined way to experiment with different indexing techniques, evaluate their accuracy, and optimize performance for various RAG use cases. Whether you're building a quick MVP, a proof of concept, or simply exploring different indexing strategies, this service provides a versatile playground.

Introduction

The Advanced RAG AI Service enables developers to quickly verify different RAG indexing techniques, assessing both accuracy and performance. From index generation to output verification through chat mode and proofreading mode, this service offers comprehensive support. It can run locally in a Docker container or be deployed to Azure Container Apps, providing flexibility for various deployment scenarios.

Docker Deploy Repo: https://github.com/freistli/AdvancedRAG

Key Features

Knowledge Graph - LlamaIndex
Recursive Retriever Query - LlamaIndex
Tree Mode Summarization - LlamaIndex
CSV Query Engine - LlamaIndex
Semantic Hybrid Search + Sub Query Engine - Azure AI Search
Microsoft GraphRAG (Local Search + Global Search)

Quick Start Guide

To get started with the Advanced RAG service, follow these steps:

Cloning the Repository

git clone https://github.com/freistli/AdvancedRAG.git

Setting Up Environment Variables

Rename .env_4_SC.sample to .env_4_SC and input the necessary environment variables. Note that an Azure OpenAI resource and an Azure Document Intelligence resource are required. Azure AI Search is optional unless you plan to build or use an Azure AI Search index.

Building and Running the Docker Image

Build the Docker image:

docker build -t docaidemo .

Run the image locally:

docker run -p 8000:8000 docaidemo

Access the service at http://localhost:8000.

Running on Azure Container App

Publish your Docker image to Azure Container Registry or Docker Hub.
Create an Azure Container App, select the published Docker image, and deploy the revision pod without any extra commands.
Set environment variables in the Azure Container App if you didn't include .env_4_SC in the image.

Building an Index

Click the "Index Build" tab.
Upload a file to the file section. (PDF format is recommended for complex content.)
Click "Submit" and wait for the index building to complete. Status updates will appear in real-time on the right pane.

4. Once you see the completion message, you can download the index for local use.

2024-06-13T10:04:54.120027: Index is persisted in /tmp/index_cache/yourfilename
/tmp/index_cache/yourfilename can be used as your Index name.

Setup Your Own Index in the Docker Image

"rules" Index Name is predefined for Knowledge Graph Index of Japanese proofread demo in this solution. Developers can use their own indexes in other folders for the docker:

To make it work:

Move to the folder which contains the AdvancedRAG dockerfile
Create a folder to keep the index, for example, index123
Extract the index zip file you get from the step 6 in the "Build Index" section, save index files you downloaded into ./index123
Build the docker image again.

After this, you can use index123 as index name in the Chat mode.

Using the Advanced RAG Service

Calling the Service through REST API

Endpoint: https://{BASEURL}/proofreadaddin/run/predict
- "rules" Index Name is predefined for Knowledge Graph Index of proofread addin. Please save Default knowledge graph index into ./rules/storage/rules_original
Method: POST
Header: Content-Type: application/json
Sample Data:

{
"data": [ 

"今回は半導体製造装置セクターの最近の動きを分析します。",  

false <--- Streaming

]
}

Endpoint: https://{BASEURL}/advchatbot/run/chat
Method: POST
Header: Content-Type: application/json
Sample Data:

{
  "data": [
    "When did the Author convince his farther",  <----- Prompt
    "", <--- History Object, don't change it
    "Azure AI Search",  <------ Index Type
    "azuresearch_0",   <------- Index Name or Folder
    "You are a friendly AI Assistant",    <----- System Message
    false <----- Streaming
  ]
}

Consuming the Service REST API in Copilot Studio Power Autoflow Action

Consuming the Service in Office Add-In

For the Proofread Addin use case, refer to: Proofread Addin.

Chat Mode

Click "Chat Mode."
Choose the index type.
Enter the index path or Azure AI Search Index name in the "Index Name" text field.
Interact with the document using various system messages if needed.

Proofread Mode

Proofread mode is tailored for non-English languages and requires a Knowledge Graph Index. Steps to generate this index are the same as for other indices.

Viewing the Knowledge Graph Index

Click the "View Knowledge Graph Index" tab.
Enter your Knowledge Graph Index name and click "Submit."
After a short wait, click "Download Knowledge Graph View" to see the result.

More Information

Step by Step: Integrate Advanced CSV RAG Service with your own data into Copilot Studio (microsoft.com)

Conclusion

The Advanced RAG Service is a convenient solution for developers looking to explore and optimize retrieval augmented generation techniques. By providing a flexible, Docker-based environment, it enables rapid experimentation and deployment, making it easier to find the best indexing strategies for specific use cases, and provide REST API Endpoints. Whether you're working locally or deploying to the cloud, this service streamlines the process of developing and testing advanced AI solutions.

Create a Jenkins pipeline to deploy Desktop Apps as MSIX - Part 2: Packaging a Visual Studio solutio

luisdem — Fri, 31 May 2024 18:49:49 GMT

Parts:

Setup the Jenkins environment: install Jenkins and the required tools.

Packaging a Visual Studio solution: for applications that use Visual Studio IDE, like Windows Forms and WPF.

Packaging a solution developed outside Visual Studio: for applications developed outside VS, i.e., in others IDEs like Eclipse or Visual Studio Code, for Java GUI application.

Packaging using the VB6RegistryTool: despite of the name, the tool can be used by any technology.

1. Visual Studio Solution

In this section it will be demonstrated how to create the Visual Studio solution with a Windows Forms application and the Windows Application Packaging Project project used to generate the MSIX file.

In case you prefer, you can skip this step, since the solution is already available on jenkins_msix repo.

Create the Windows Form application

On Visual Studio 2019, select Create a new project, select the Windows Forms app project template and click Next:

Provide the project name WinForms.App and click Next:

I am choosing the .NET 6.0 framework, but feel free to use any other version. Click on Create:

This is the WinForms project structure. I am using only a PictureBox and a button, but it could be an empty project, as the idea is just to show how to package a WinForm application:

Follows the code-behind:

namespace WinForms.App { public partial class Form1 : Form { public Form1() { InitializeComponent(); } private void button1_Click(object sender, EventArgs e) { Close(); } } }

So far, the WinForm project is a .NET 6.0 application that depends of the .NET runtime available in the client machine. To remove this dependency, it is possible to publish the project as self-contained where the .NET runtime and runtime libraries are bundled together with the application and third-party assemblies.

Add the following lines to the SelfContained and RuntimeIdentifier to the WinForms.App project file:

<PropertyGroup> <OutputType>WinExe</OutputType> <TargetFramework>net6.0-windows</TargetFramework> <Nullable>enable</Nullable> <UseWindowsForms>true</UseWindowsForms> <ImplicitUsings>enable</ImplicitUsings> <SelfContained>true</SelfContained> <RuntimeIdentifier>win-x64</RuntimeIdentifier> </PropertyGroup>

More details at: Trim self-contained deployments and executables

Build the application to ensure that no errors appear.

Create the the Windows Application Packaging project

The next step is adding the Windows Application Packaging Project to the solution.

Right-click on the solution, select Add and click on New Project...:

Select the Windows Application Packaging Project and click Next:

Provide the project name WinForms.Packaging and click Create:

The next step is to provide the target and minimum platform version supported by your application. I am selecting both versions to 19041 to keep it simple, as I need to install the same SDKs on my Jenkins server environment:

In the WinForms.Packaging project, right-click on Dependencies node and click Add Project Reference...:

Select the Windows Application Packaging Project and click Next:

Observe that the WinForms.App project was added to the WinForms.Packaging project:

The Windows Application Packaging Project don't accept the target Any CPU. Therefore, we need to change the processor target to x86 or x64 for both projects.

Open Configuration Manager, change the Active solution platform to x86, change the WinForms.App and WinForms.Packaging projects to x86:

Build the application to ensure that no errors appear.

Build the application using MSBuild command line

Before creating a Jenkins pipeline, let's make sure that the MSBuild command line that will be used to build our application is working.

Open the Package Manager Console (you can press CTRL+Q and type package manager console):

Before running the following command, make sure to provide the MSBuild.exe PATH available in your environment:

&"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" /p:AppxBundlePlatforms=X86 /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageSigningEnabled=false

In my case, the msix package file was generated on:

C:\github\msixdemos\01_VisualStudio\WinForms.App\WinForms.Packaging\AppPackages\WinForms.Packaging_1.0.0.0_AnyCPU_Debug_Test

In the next section, it will demonstrate how to build a Jenkins Pipeline for this project.

2. Jenkins Pipeline

Pipeline is a series of tasks required to build, test, and deploy an application.

Create a new job

In the Jenkins Dashboard, click on the Create a job option:

Provide a name for the job, check the Pipeline type of job and click on OK to proceed.

In the pipeline configuration page, check the GitHub Project to specify that this is a GitHub project and provide a GitHub URL:

Scroll down under the Pipeline section and change the definition to Pipeline script from SCM

Provide the Repository URL as well. Because this is a public project, we can skip the credentials:

Scroll-down to the Branches to build section, change the branch name to */main, the Jenkins script path to Jenkinsfile01 and click on Save:

Those actions were needed as we want to use the Jenkins pipeline file available in the main branch of the following repo:

Jenkins Pipeline File

In the previous section it was demonstrated how to setup the Jenkins pipeline to use a Jenkins script file available on our GitHub repository.

Follows the Jenkinsfile01 content:

pipeline { agent any environment { MSBUILD = "C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Msbuild\\Current\\Bin\\MSBuild.exe" CONFIG = 'Release' PLATFORM = 'x86' } stages { stage('Update manifest version') { steps { powershell ''' $manifest = "01_VisualStudio\\WinForms.App\\WinForms.Packaging\\Package.appxmanifest" [xml]$xmlDoc = Get-Content $manifest $version = $xmlDoc.Package.Identity.Version $trimmedVersion = $version -replace '.[0-9]+$', '.' $xmlDoc.Package.Identity.Version = $trimmedVersion + ${env:BUILD_NUMBER} $xmlDoc.Save($manifest) ''' } } stage('Build') { steps { bat "dotnet restore 01_VisualStudio\\WinForms.App\\WinForms.App\\WinForms.App.csproj" bat "\"${MSBUILD}\" 01_VisualStudio\\WinForms.App\\WinForms.app.sln /p:Configuration=${env.CONFIG} /p:AppxBundlePlatforms=${env.PLATFORM} /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageSigningEnabled=false" } post{ always { archiveArtifacts artifacts: '**/*.msix', followSymlinks: false } } } } }

The pipeline directive is the complete script from beginning to end.

The agent directive instructs Jenkins to allocate an executor and workspace for the entire Pipeline. In our case, we are justing saying it can run on any agent. For example, it could be specified that it could run in a Docker container or run on a specific node.

The environment directive specifies a sequence of key-value pairs which will be defined as environment variables for all steps, or stage-specific steps, depending on where the environment directive is located within the Pipeline.

In our case, it is defined the variables MSBUILD that contains the MSBUILD path, the CONFIG with the value Release and PLATFORM with the value x86. Those variables will be used in the command line used to build our application.

The stages block contains on or more stage block, and each stage is going to have one or more steps. In our case, we have only one stage named Build, that has two steps to restore the dotnet WinForms.App project and to build the solution.

The post section defines the additional step needed to keep the msix file artifact available in our build, as workspace is a temporary directory.

You can find more details about the Jenkins pipeline syntax in the post Getting started with Pipeline.

In addition, there is a great post about how to Creating a Jenkins pipeline for a .NET Core application.

Switch back to Jenkins, click on Dashboard and click on the Visual Studio Solution pipeline:

Click on Build Now to start the build:

The job starts by checking out the source code to next restore and build our solution as defined in the Jenkinsfile01.

After the build is done, the build icon will be green and the msix artifact will be available:

The next post demonstrate how to package an application that not uses the Visual Studio IDE, but that uses the Windows Application Packaging Project to generate the MSIX file.

How Copilot and Intelligent Recap are Aggregating Value for Microsoft Teams’ Users

luisdem — Mon, 22 Jan 2024 17:13:19 GMT

A comparison of two AI-powered features that help you get the most out of your meetings

Meetings are an essential part of our work, where we share ideas, make decisions, and collaborate with others. However, meetings can also be challenging, especially when we have to deal with multiple agendas, diverse perspectives, and complex topics. How can we make our meetings more productive, engaging, and accessible? How can we capture the key insights and outcomes of our meetings, and act on them effectively? How can we leverage the power of artificial intelligence (AI) to enhance our meeting experience and productivity?

In this blog post, we will introduce you to two new AI-powered features in Microsoft Teams that aim to answer these questions: Intelligent Recap and Microsoft M365 Copilot. These are two innovative tools that help you get the most out of your meetings, by providing you with relevant and personalized information and insights based on your needs and preferences. We will explain what these features are, how they work, and how they differ from each other. We will also show you how to use them together to improve your meeting experience and productivity.

What are Intelligent Recap and Copilot?

Intelligent Recap and Microsoft M365 Copilot are two different AI-powered features in Microsoft Teams that help you get the most out of your meetings. They both use artificial intelligence to analyze the meeting content and context and provide you with relevant and personalized information. However, they have different purposes and functionalities, as we will explain below.

How does Intelligent Recap work?

Intelligent Recap in Teams Premium uses AI (artificial intelligence) to deliver a personalized and intelligent overview of each meeting, helping you discover the information that matters to you most, whether you attended the meeting or missed it. It is available in Teams, on a new tab called 'Recap', where you can watch a meeting recording directly within this Teams recap page, and many of its components will also be available when you watch a meeting recording in Stream.

Intelligent Recap automatically generates a summary of the key points and action items discussed in the meeting, using natural language processing and understanding. You can edit, add, or delete any notes as you wish, and share them with your colleagues or other stakeholders. You can also search for specific keywords or phrases in the notes, and jump to the corresponding part of the recording where they were mentioned.

Intelligent Recap also identifies potential tasks or follow-ups that emerged from the meeting, and suggests them to you as recommendations. You can review these recommendations, assign them to yourself or others, set deadlines, and track their progress. You can also create new tasks from scratch, or link existing ones from other apps like Planner or To Do.

Intelligent Recap creates a customized set of highlights for each meeting participant, based on their role, interests, and interactions in the meeting. For example, you might see highlights such as when your name was mentioned, when someone asked you a question, when you shared your screen, when you gave feedback, or when someone praised your work. These highlights help you catch up on what you might have missed, or revisit what you contributed to the meeting. You can also see other people's highlights by clicking on their profile pictures in the recap page.

Some of the components of Intelligent Recap are:

A summary of the meeting highlights, such as key topics, decisions, actions, and follow-ups.
A transcript of the meeting conversation, with speaker attribution and time stamps.
A list of the meeting participants, with their roles and attendance status.
A collection of the meeting attachments, such as files, links, polls, and whiteboards.
A word cloud of the most frequently used words in the meeting.
A timeline of the meeting events, such as when someone joined, left, or shared their screen.

Intelligent Recap helps you stay on top of your meetings, review the important information, and take action on the next steps.

Learn more about Microsoft Teams Premium: Microsoft Teams Premium | Microsoft Teams

How does Copilot work?

Microsoft 365 Copilot is a dynamic and interactive feature that leverages advanced language query to deliver real-time responses to your requests. It builds on the Intelligent Recap insights by applying conversational AI (powered by GPT), and returning insights tailored to your unique prompts. While Intelligent Recap proactively offers these insights, Copilot responds to your questions and prompts, ready to help you dig deeper into the meeting context.

Copilot uses a natural language interface that allows you to ask questions or make requests using your own words. It understands the meeting context and the intent of your queries and provides relevant and accurate answers. For example, you can ask Copilot questions like "What did John say about the budget?" or "What are the next steps for the project?" and Copilot will search for the information in the meeting transcript, notes, tasks, and attachments, and provide you with concise and helpful answers.

Copilot is also a collaborative tool that enables you to share your Copilot insights with other meeting participants or save them for later reference. You can send Copilot answers to the meeting chat, or export them to other apps like Word, PowerPoint, or OneNote.

Copilot also has a feedback mechanism that allows you to rate the quality of the Copilot responses and help improve the system over time. You can give Copilot a thumbs up or a thumbs down, or provide more detailed feedback on how Copilot can improve its answers. Copilot will learn from your feedback and provide better answers in the future.

Copilot helps you get more value out of your meetings, by providing you with real-time information and insights that enhance your understanding and decision making.

Learn more about Microsoft 365 Copilot: The Copilot System: Explained by Microsoft and How Microsoft 365 Copilot works.

What are the differences and similarities between Intelligent Recap and Copilot?

Intelligent Recap and Copilot are both AI-powered features that help you get the most out of your meetings in Microsoft Teams. They both use artificial intelligence to analyze the meeting content and context and provide you with relevant and personalized information. However, they have different purposes and functionalities, as summarized in the table below.

	What	Current Way	New Way
Intelligent recap in Teams Premium	Capture key meeting ideas and follow up actions	Attendees have to manually take notes and action items during the meeting	Automatically get consistent meeting notes and action items for attendees
	Listen to or watch what happened during a meeting	Spend hours after the workday watching meeting recordings and jumping around trying to find specific points of conversation	Save time with an auto-generated, immersive recap of a specific meeting or series, all in one place. Skim chapters and meeting topics that are automatically created and focus on the most relevant places for you to listen in
	Find times in the meeting relevant for you	Spend time sifting through for specific, relevant points just for you	Quickly find and jump to when your name was mentioned, when a screen was shared, when you joined/left the meeting, when your colleagues spoke, and by different topics throughout the discussion
Copilot in Teams	Stay on topic during a meeting	Spend valuable meeting minutes summarizing progress, discussing agenda, handling conflict and compiling feedback	Ask Copilot to automatically recap discussion and decisions made; proactively suggest agenda items and points to stay on topic, suggest questions, and even identify project and timeline conflicts.
	Author or generate content from discussions	Time and effort to brainstorm ideas, draft new content, and format concepts into diagrams	Get more done and save time by leveraging Copilot to brainstorm ideas on top of your own, synthesize and format information, build tables and diagrams, and organize text.
	Gain deeper insights from meeting, chat, and channel conversations	Spend hours watching meeting recordings, asking colleagues for input, or scrolling through chats to understand what happened	Quickly understand why a decision was made, different perspectives from the group, unresolved questions, and more with specific, context-baed questions to Copilot.

How to use Intelligent Recap and Copilot together

To get the best results from Intelligent Recap and Copilot, you need to enable them in your Microsoft Teams settings. You also need to have a Microsoft Teams Premium subscription and Copilot license to access Intelligent Recap. Once you have enabled these features, you can use them in the following ways:

- Before the meeting, you can use Copilot to prepare for the meeting by asking it questions about the meeting agenda, participants, goals, and background information. Copilot will search for relevant documents, emails, chats, and other sources of information and provide you with concise and helpful answers. You can also use Copilot to create a meeting outline with key points and questions to guide the discussion.

- During the meeting, you can use Copilot to keep track of the conversation and capture important information. Copilot will listen to the meeting audio and transcribe it in real time. It will also identify areas of agreement, disagreement, options, decisions, actions, and follow-ups. You can ask Copilot questions or give it commands using natural language, such as "What are the pros and cons of option A?" or "Remind me to send an email to John after the meeting". Copilot will respond with relevant insights and suggestions on how to move forward.

- After the meeting, you can use Intelligent Recap to review the meeting summary and highlights. Intelligent Recap will provide you with a comprehensive report that includes a transcript of the meeting audio, a list of attendees and their engagement level, a timeline of key moments and topics discussed, a summary of decisions made and actions assigned, a collection of files shared during the meeting, and a feedback survey for participants. You can also use Intelligent Recap to search for specific information or keywords within the report.

Conclusion

Intelligent Recap and Copilot are two AI-powered features that enhance your meetings in Microsoft Teams. They both use artificial intelligence to analyze the meeting content and context and provide you with relevant and personalized information. However, they have different purposes and functionalities, as Intelligent Recap provides insights after the meeting has concluded, while Copilot provides real-time value during the meeting. By using these features, you can improve your meeting experience and productivity, and get more out of your collaboration.

Upskilling: ChatGPT Prompt Engineering for Developers now in C#

MikeFrancis — Fri, 26 May 2023 15:33:38 GMT

Like most developers today, I'm upskilling on the new Generative AI technologies like OpenAI's ChatGPT, Microsoft Bing Chat, GitHub Copilot, and the Azure OpenAI Service. The key to effectively using these technologies lies in crafting the right prompts. A prompt includes instructions that describe the desired output and provide context to the AI service.

Writing effective prompts is a valuable skill, and it has even given rise to the role of a "Prompt Engineer." While you don't need to be a Prompt Engineer to use these technologies efficiently, understanding the different types of prompts is essential to unlock their full potential. To help with this, DeepLearning.AI offers a free course called ChatGPT Prompt Engineering for Developers. This course is highly recommended as it provides excellent descriptions and hands-on walkthroughs of various prompt types. The interactive samples in the course are implemented in Python using Jupyter Notebooks, which is a popular language in the AI space.

For those who want to use the samples with the Azure OpenAI service and the Azure OpenAI client library for .NET, I have ported the Python samples to C#. I am using the Polyglot Notebooks extension for Visual Studio Code to run the notebooks. The Polyglot Notebooks extension includes the .NET Interactive runtime, providing support for C# and .NET.

The notebooks are available on GitHub here: Azure OpenAI C# Prompt Engineering Samples.

A better way to identify external users in an Outlook mail

Matteo Pagani — Wed, 12 Apr 2023 13:00:00 GMT

Many companies are working in a context where content sensitivity is very important. You should be very careful on what information you are sharing and with whom, especially if one or more recipients don't belong to your organization. To help employees being more diligent, the Outlook team developed a while ago a feature called MailTips, which is a way to provide contextual information to a user when a specific condition happens. One of the conditions that IT admins can turn on is external users checking. The image below shows an example of what happens in my Outlook client when I try to send a mail that includes a recipient who is outside Microsoft:

You can notice that, as soon as I add my personal mail address, the recipient is highlighted in yellow and I get a message at the top of the mail notifying me that there's one external recipient, with the option to quickly remove it. The MailTip, however, is just a warning. If I try to send this mail, I don't get further notifications and the mail is simply sent.

For some companies who are very sensitive to the confidentiality topic, this isn't enough. They need a more direct way to alert an employee when they're sharing a mail with an external user, to make sure that they aren't sharing any confidential information.

In this blog post, we're going to build an Outlook add-in that we can use to achieve this goal. The add-in is going to intercept the click on the Send button and, in case one or more recipients are outside the organization, will display a warning pop-up. The user will need to confirm a second time before actually sending the mail:

Setup the project

To set up the project, we will need to use the Yeoman generator to create an Office add-in using the web development model. Once you have installed all the required tools highlighted in the documentation, open a terminal, and create a folder where you want to store your project:

mkdir outlook-external-users

Then start Yeoman with the following command:

yo office

You're going to start a wizard to scaffold the starting project:

Choose a project type: choose one of the available options for the category Office add-ins Task Pane project. There are multiple options based on your favorite web framework. In my case, I picked up the React based one.
Choose a script type: also in this case, it's a matter of preference, but I highly suggest using TypeScript rather than plain JavaScript.
What do you want to name your add-in? Give it a meaningful name, like Outlook external users.
Which Office client application would you like to support? Choose Outlook.

Now let Yeoman generate the project and restore all the required dependencies from NPM, the Node Package Manager.

Configure the project to intercept events

The default template generated by Yeoman supports the two standard scenarios: task pane (the sidebar that is displayed on the left) and command (an operation that is directly executed on the current context, like a selected portion of the mail text). In our scenario, instead, we must support a third use case: event-based activation. Our add-in must stay "silent" in background and come alive when a specific action happens, in our case the user pressing the Send button on a mail compose window. The official documentation lists all the supported events that we can intercept. The one we are interested in is called OnMessageSend.

The first change we must make is in the manifest file, called manifest.xml and included in the root of the project. Inside the file, you will find a section called ExtensionPoint, which sits under the DesktopFormFactor section, with, as type, MessageReadCommandSurface. This is the default extension point of the template, which means that the add-in buttons will be visible when you're reading an e-mail. We can ignore it for our scenario. Let's add, below this extension, another one with the following syntax:

<ExtensionPoint xsi:type="LaunchEvent">
  <LaunchEvents>
    <LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="PromptUser" />
  </LaunchEvents>
  <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
  <SourceLocation resid="WebViewRuntime.Url"/>
</ExtensionPoint>

We are creating a new ExtensionPoint entry with type LaunchEvent, which is our event-based activation scenario. Inside, we must specify a collection of LaunchEvent entries, one for each event we want to listen to. In our scenario, it's only one event: OnMessageSend.

The second parameter is equally important: FunctionName is the name of the TypeScript function we're going to create to handle the event. The final property is called SendMode and it's applied only to events which are related to a Send event, like in this case (another example is SendAppointment). The PromptUser value means that in case the condition we have defined is not met, the user will see a prompt that will give them the option to cancel the operation or send the mail anyway.

This is the correct behavior for our add-in, thus it's important to specify it, otherwise Outlook will switch to the default behavior, which is SoftBlock. In this case, the pop-up will be displayed without any option to send the mail anyway, the user will be blocked until the condition is fixed. This isn't the behavior we want: the pop-up should be an extra layer of warning that external users are included, but we shouldn't completely prevent users from sending mails to people outside the organization!

The next step is to create a file that will host our event management code. The basic project already contains two folders for the two default scenarios (taskpane and commands), let's add a new one called launchevent and, inside it, let's create a file called launchevent.js.

Since this is a new JavaScript file which isn't included in the default template, we must manually reference it. Open the commands.html file inside the commands folder and, inside the <head> section, add the following entry:

<script type="text/javascript" src="../launchevent/launchevent.js"></script>

The last step is to change the Webpack configuration. When you test or publish your add-in, Webpack takes care of bundling all the required assets together. Since now we have a new JavaScript file in our project, we must make sure it's properly included. Open the webpack.config.js file in the root of the project and, inside the plugins section, add the following entry:

new CopyWebpackPlugin({
        patterns: [
          {
            from: "./src/launchevent/launchevent.js",
            to: "launchevent.js",
          },
        ],
      }),

That's it. Now we have all the building blocks which are needed to intercept the mail send. We just need the code to do it 😃

Implement the event handler

Let's look at the code that we need to include in the launchevent.js file:

const customerDomain = "@contoso.com";

function onMessageSendHandler(event) {
  let externalRecipients = [];
  Office.context.mailbox.item.to.getAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      var recipients = asyncResult.value;
      recipients.forEach((recipient) => {
        if (!recipient.emailAddress.includes(customerDomain)) {
          externalRecipients.push(recipient.emailAddress);
        }

        if (externalRecipients.length > 0) {
          event.completed({
            allowEvent: false,
            errorMessage:
              "The mail includes some external recipients, are you sure you want to send it?\n\n" +
              externalRecipients.join("\n") +
              "\n\nClick Send to send the mail anyway.",
          });
        } else {
          event.completed({ allowEvent: true });
        }
      });
    } else {
      event.completed({ allowEvent: true });
    }
  });
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to map the event handler name specified in the manifest's LaunchEvent element to its JavaScript counterpart.
// 1st parameter: FunctionName of LaunchEvent in the manifest; 2nd parameter: Its implementation in this .js file.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onMessageSendHandler", onMessageSendHandler);
}

The core of the file is the onMessagesendHandler function, which is registered as handler every time the Send button of the mail compose window is clicked. Let's see, step by step, the operations performed inside the handler:

First, we use the Office APIs to retrieve the list of recipients of the mail, by calling Office.context.mailbox.item.to.getAsync(). This is an asynchronous API, so we need to manage the result inside a callback.
Inside the status property of the result, we get the information if the operation has succeeded. If that's the case (Office.AsyncResultStatus.Succeeded), we use the value property, which is a collection of recipients.
We use the forEach() statement to iterate through all the recipients.
For each recipient, we check the value of the emailAddress property, and we test if it includes the domain we consider internal (in this example, we check if it's a Contoso.com mail address).
Every recipient that doesn't qualify is added to a collection, called externalRecipients.
In case the collection contains more than one item, it means that there are external users as recipients. We call event.completed(), to notify Outlook that we have completed our checks, but we set the allowEvent property to false, which means that our condition isn't satisfied, thus we must display the pop-up. In this case, we populate also the errorMessage parameter with the text that we want to display to the user, which includes the list of external recipients we have identified.
In case the collection doesn't contain any item, instead, it means there are no external recipients. We call event.completed() as well but, in this case, we set the allowEvent property to true. The event can be executed, so we allow Outlook to send the mail without showing any prompt.

This is the code implementation. We're ready to debug our add-in!

Debug the Outlook add-in

From the debug point of view, there's no difference between an event-based activation add-in and a traditional Outlook add-in. The easiest way to test it is by using Visual Studio Code. When you open your project and you move to the Debug tab, you will find multiple debug profiles, including one called Outlook Desktop (Edge Chromium):

Select it and press F5 (or click on the Play icon). Visual Studio Code will launch Outlook desktop and will sideload the add-in. Now compose a new e-mail and add, in the To field, at least one e-mail address which domain doesn't match with the one you have specified in the customerDomain property. If you did everything correctly, you should see the same experience I've shared at the beginning of the post:

When you click on Send anyway, the compose window will be closed and the mail will be sent; if you click on Don't send, instead, the user will go back to the Compose window and they will be able to change the content of the mail or the list of recipients.

Wrapping up

In this post, we have learned how to build an Outlook add-in which uses the event-based activation model to provide a more restrictive external recipients experience to users. Thanks to this add-in, we can add an extra layer of security to make sure that employees aren't sending confidential information to external users.

You can find the complete project on GitHub. Remember that this add-in uses the web model so, if you want to use it in your environment, you will have to host it on your own. For example, you can leverage Azure Storage by following the guidance on the official documentation.

Happy coding!

Microsoft Teams: Capture Chat Messages and Replies

MikeFrancis — Fri, 19 May 2023 21:03:47 GMT

You may have the need to archive chat messages or capture chat sessions for further processing. Activities like summarizing the conversation, extract action items, or suggesting meeting times can be done by analyzing the chat conversation. This starts with extracting the conversation using the Microsoft Graph APIs. In Microsoft Teams, a chat conversation is made up of messages and replies. A 'message' is the initiating text. Responses to the initial prompt by recipients of the message and the message initiator are 'replies'. For example:

In this case the 'message' is 'Where did you want to meet for lunch?'. The remainder of the conversation are 'replies'. The Microsoft Teams Connector, provides methods we need to extract the messages. However, no method is provided for collecting the message replies. For this, we will call the Microsoft Graph using a custom connector.

An exported solution with the following implemented can be downloaded here.

Requirements Scope

The solution must only capture messages for Teams that a specified user (Service Account) is a member.
The solution must capture both messages and replies for that message.
The solution must capture messages in both public and private channels.

Tools

The Postman Graph API collection is very useful for experimenting with the Graph APIs. See here: Use Postman with the Microsoft Graph API - Microsoft Graph | Microsoft Learn This useful for getting the Team, Channel and Message ids you'll need for testing the custom connector.

Implementation

In Azure Active Directory (AAD) - For the global admin - Create a Service account and app registration

Create a Service Account (A user account not associated with an actual user) with the default 'User' role.
Create an App registration with the following delegated permissions:

These permissions require consent by the Global admin for the organization.
In 'Authentication' Add the 'Web' platform and specify the following Redirect URI: https://global.consent.azure-apim.net/redirect.
Create a secret. Note the secret, Client Id, and Tenant Id, of the app registration. You'll need these when creating the custom connector.
Assign the Power Apps, and Microsoft 365 licenses as you normally do when onboarding users.

Power Automate - For app makers - Create the Custom Connector for calling the MS Graph

In this step we'll create a custom connector that will call the MS Graph API:

GET /teams/{team-id}/channels/{channel-id}/messages/{message-id}/replies

Connector Name: GetMessageReplies Key Fields: General:

Host: graph.microsoft.com
Security:
Authentication Type: OAuth 2.0
Identity Provider: Azure Active Directory
Client ID: <client id from AAD section above>
Authorization URL: https://login.microsoftonline.com
Tenant ID: common
Resource URL: https://graph.microsoft.com
Redirect URL: https://global.consent.azure-apim.net/redirect

Definition:

General:
    Summary: Get message replies
    Description: Get message replies
    Operation ID: Get-message-replies
    Visibility: Important
Request:
    Import from sample:
        GET
        URL: https://graph.microsoft.com/beta/teams/{TeamId}/channels/{ChannelId}/messages/{MessageId}/replies

// Response:
// Import from sample:
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('eb825a11-3b12-4c5f-8258-fd405b1395c8')/channels('19%3Aq0-BRQ6TDgcZczl9O7V2Ye078k1eOIzgghUkpRzTlW41%40thread.tacv2')/messages('1677699468267')/replies",
    "@odata.count": 0,
    "value": []
}

Test:

Click Update connector to save.
Create a connection using the Service Account created in the AAD section above.
Provide a TeamId, ChannelId, and Message Id, acquired from the PostMan Graph API helper. (See Tools section.)
Click 'Test operation'. A successful test will return a 200 status code. See screenshot below.

Power Automate - For app maker - Create Scheduled and Power App Flows

In the following steps, we'll create a flow that will collect chat messages and replies for every Team the service account is a member. The idea here is that an admin would add this user account to each Team where they want to extract the chat messages.

In this step we'll create a scheduled flow that calls a child flow that will capture the messages and replies and pass them back to the calling flow. This is required to have the flow run in the context of the 'run-only' user, which will be the Service Account created in the AAD section above.

Create Child Flow

Let create the child flow first. Create an Instant flow with a PowerApps V2 trigger. Call this flow GetChatMessages.
Initialize an array variable called 'result'.
Use the Microsoft Teams Connector to call the following. The channels, message, and replies should be in nested 'Apply to each' controls:
1. List Teams - Specify the Service Account for the connection reference.
2. List Channels
3. Get Messages
4. Get replies for message - here you will call the custom connector.

Append the current team, channel, message and replies to the 'result' array.

Covert the array to a string and return to calling flow.

Save the Flow
On the Flow's detail page, edit the 'Run only users' and set the 'Connections Used' for Microsoft Teams and GetAllTeams (Custom Connector) to be the Service Account.

Share the flow with the Service Account.
Optionally specify the Service Account as an owner of the flow.

Create Main Flow

Create a Scheduled flow. Name this GetTeamsChannelsMessages. By default, the flow will run every minute, you may want to change this to a longer interval (weekly) while you are developing the flow. You can always trigger this manually during development.
Add the action to call a Child Flow. Specify GetChatMessages created above.
Save the Flow
Share the flow with the Service Account.
Optionally specify the Service Account as an owner of the flow.
When your testing is complete, update the schedule to the interval you need. You should run a few tests to determine the maximum runtime for the flow and adjust the schedule accordingly.

Results

Here is an example of the output of the chat in the first screenshot:

{
  "Team": "Demo Team",
  "Channel": "Project Silver",
  "MessageId": "1677098428650",
  "MessageText": "Where did you want to meet for lunch?",
  "ReplyId": "1677098885814",
  "ReplyText": "I'd don't want to go all the way out to Dunmore."
},
{
  "Team": "Demo Team",
  "Channel": "Project Silver",
  "MessageId": "1677098428650",
  "MessageText": "Where did you want to meet for lunch?",
  "ReplyId": "1677098838074",
  "ReplyText": "No seafood. How about Cugino's?"
},
{
  "Team": "Demo Team",
  "Channel": "Project Silver",
  "MessageId": "1677098428650",
  "MessageText": "Where did you want to meet for lunch?",
  "ReplyId": "1677098447360",
  "ReplyText": "How about Cooper's?"
}

Using Adaptive Cards to Collect Feedback on ServiceNow Tickets in Teams.

luisdem — Mon, 17 Apr 2023 14:05:46 GMT

In any organization, gathering feedback from customers and employees is essential to improve products and services, as well as to enhance the overall experience. However, obtaining that feedback can be a challenging task, especially when you need to reach out to a large number of people.

Fortunately, with the rise of digital communication tools and collaborative apps, it's becoming easier than ever to gather feedback efficiently and in a timely manner. Among these apps, Microsoft Teams stands out as one of the most popular and versatile options, providing a unified platform for team communication and collaboration.

In this post, we'll explore how you can leverage Microsoft Teams to gather feedback from your customers or employees via surveys sent as Adaptive Cards, using ServiceNow as the source of information. Specifically, we'll discuss how to set up an automated process that sends Adaptive Cards to Microsoft Teams after a ticket is closed on ServiceNow, making it easy for respondents to provide feedback directly from Teams. By doing so, you'll not only save time and effort but also increase the response rate and improve the quality of the feedback you receive.

Prerequisites

ServiceNow Environment

ServiceNow provides a free development environment called the Now Platform (https://developer.servicenow.com/dev.do), which enables developers to quickly build, test, and deploy applications to improve workflows and productivity within their organizations. With a free account on the Now Platform, you can start building powerful applications that leverage ServiceNow's advanced capabilities for workflow management, incident management, and service requests. Whether you're an experienced developer or just getting started, the Now Platform offers a flexible and easy-to-use environment for creating custom solutions tailored to your organization's unique needs.

Microsoft Teams

Go to the Microsoft Teams website (https://www.microsoft.com/en-us/microsoft-teams/group-chat-software) and click on the "Sign up for free" button.
Enter your email address and click on "Next". If you already have a Microsoft account, you can sign in with that account.
Create a new password and click on "Sign up".
Follow the prompts to complete the setup process, such as entering your name and company information.
Once your account is set up, you can download the Microsoft Teams app on your desktop or mobile device and start collaborating with your team.

With a free Microsoft Teams account, you can chat with colleagues, make voice and video calls, share files, and collaborate on projects from anywhere. Plus, with its seamless integration with other Microsoft products, such as Office 365 and SharePoint, Microsoft Teams can help streamline your organization's workflows and improve productivity.

Power Automate Environment

Microsoft provides a free Power Automate environment (https://powerautomate.microsoft.com/en-us/#home-signup), which enables users to automate workflows across multiple applications and services. With Power Automate, you can create automated processes, such as approvals, notifications, and data synchronization, to save time and increase efficiency. Whether you're a business user or a developer, the Power Automate environment provides an intuitive and easy-to-use interface for creating and managing workflows. Plus, with its seamless integration with other Microsoft products, such as Teams and SharePoint, Power Automate can help streamline your organization's workflows and improve collaboration.

Power Automate or Azure Logic Apps Part

To automate the process of sending Adaptive Cards to Microsoft Teams after a ServiceNow ticket is closed, you can use either Power Automate or Azure Logic Apps. With these tools, you can create a flow that retrieves the necessary information from ServiceNow and then prepares and sends the Adaptive Card to Teams.

In this post, I am demonstrating how to use Power Automate to automate the process of sending Adaptive Cards to Microsoft Teams after closing a ServiceNow ticket. However, the process is similar if you decide to use Azure Logic Apps instead, so feel free to choose the tool that best suits your needs and preferences.

It's worth noting that this solution utilizes Microsoft 365 seeded licenses and standard connectors, which makes it a cost-effective option for organizations looking to streamline their feedback process. Power Automate and Azure Logic Apps provide a range of pre-built connectors and templates that allow you to easily connect different apps and automate workflows, without the need for extensive coding or development work.

By leveraging these tools, you can reduce manual effort and errors, improve collaboration and communication across teams, and gain valuable insights into the needs and preferences of your users. And with the use of seeded licenses and standard connectors, you can achieve all of this at a minimal cost, making it an ideal option for small and medium-sized businesses.

Steps:

Open a web browser and go to the Power Automate portal.
Sign into Power Automate using your Microsoft account or organizational account.
Once you're signed in, you should see the Power Automate portal dashboard. On the left-hand menu, click on "Create" to create a new flow.
Choose a template from the available options or start from scratch by selecting "Instant - from blank".

Give your flow a name, such as Closed Ticket Survey via ServiceNow. Choose the When an HTTP request is received as the trigger, and click on Create.

HTTP triggers are a powerful feature in Power Automate that allows us to create custom APIs and automate processes with external systems. By creating a custom HTTP trigger, we can make the approval process more flexible and scalable, and enable other systems to interact with Microsoft Teams Approvals without having to go through ServiceNow.

To set up the "When a HTTP request is received" trigger, we need to define the input parameters that will be sent via a rule from ServiceNow (we will create this rule later).

Click on the "When a HTTP request is received" trigger to select it. Paste the following Request Body JSON Schema that will be sent by ServiceNow into the text box:

Click here to visualize the JSON

{ "type": "object", "properties": { "number": { "type": "string" }, "short_description": { "type": "string" }, "description": { "type": "string" }, "resolved_by_name": { "type": "string" }, "resolved_by_email": { "type": "string" }, "state": { "type": "string" }, "closed_at": { "type": "string" }, "opened_by_name": { "type": "string" }, "opened_by_email": { "type": "string" }, "closed_by_name": { "type": "string" }, "closed_by_email": { "type": "string" }, "opened_at": { "type": "string" }, "resolved_at": { "type": "string" } } }

The next step is sending the adaptive card to Teams.

Add a new action after the "When a HTTP request is received" step. In the search box, type "Teams" and select the Post adaptive card and wait for a response:

Select Chat with Flow bot for the Post in type field.
Copy and paste the following JSON code into the message field to create the Adaptive Card:

Click here to visualize the JSON

{ "type": "AdaptiveCard", "body": [ { "type": "ColumnSet", "horizontalAlignment": "Center", "columns": [ { "type": "Column", "items": [ { "type": "TextBlock", "text": "@{triggerBody()?['number']}", "wrap": true, "horizontalAlignment": "Left", "weight": "Bolder", "size": "Large" }, { "type": "TextBlock", "spacing": "None", "text": "@{triggerBody()?['short_description']}", "wrap": true, "size": "Large", "horizontalAlignment": "Left" }, { "type": "TextBlock", "text": "@{triggerBody()?['description']}", "wrap": true, "spacing": "Medium", "horizontalAlignment": "Left" } ], "width": "stretch" } ], "width": 1 }, { "type": "ColumnSet", "horizontalAlignment": "Center", "columns": [ { "type": "Column", "items": [ { "type": "ColumnSet", "horizontalAlignment": "Center", "columns": [ { "type": "Column", "items": [ { "type": "Image", "url": "https://adaptivecards.io/content/LocationGreen_A.png", "altText": "Location A" } ], "width": "auto" }, { "type": "Column", "items": [ { "type": "TextBlock", "text": "**Opened at**", "wrap": true }, { "type": "TextBlock", "spacing": "None", "text": "@{formatDateTime(triggerBody()?['opened_at'], 'yyyy-MM-dd')}", "wrap": true, "horizontalAlignment": "Center" } ], "width": "auto" } ] } ], "width": 1 }, { "type": "Column", "spacing": "Large", "separator": true, "items": [ { "type": "ColumnSet", "horizontalAlignment": "Center", "columns": [ { "type": "Column", "items": [ { "type": "Image", "url": "https://messagecardplayground.azurewebsites.net/assets/LocationBlue_B.png", "altText": "Location B" } ], "width": "auto" }, { "type": "Column", "items": [ { "type": "TextBlock", "text": "**Resolved at**", "wrap": true }, { "type": "TextBlock", "spacing": "None", "text": "@{formatDateTime(triggerBody()?['resolved_at'], 'yyyy-MM-dd')}", "wrap": true, "horizontalAlignment": "Center" } ], "width": "auto" } ] } ], "width": 1 }, { "type": "Column", "spacing": "Large", "separator": true, "items": [ { "type": "ColumnSet", "horizontalAlignment": "Center", "columns": [ { "type": "Column", "items": [ { "type": "Image", "url": "https://messagecardplayground.azurewebsites.net/assets/LocationRed_C.png", "altText": "Location C" } ], "width": "auto" }, { "type": "Column", "items": [ { "type": "TextBlock", "text": "**Closed at**", "wrap": true }, { "type": "TextBlock", "spacing": "None", "text": "@{formatDateTime(triggerBody()?['closed_at'], 'yyyy-MM-dd')}", "wrap": true } ], "width": "auto" } ] } ], "width": 1 } ], "spacing": "Medium" }, { "type": "ColumnSet", "columns": [ { "type": "Column", "items": [ { "type": "ColumnSet", "columns": [ { "type": "Column", "items": [ { "type": "Image", "horizontalAlignment": "Left", "url": "https://messagecardplayground.azurewebsites.net/assets/clock.png", "altText": "Calendar conflict", "width": "15px", "height": "15px" } ], "width": "auto" }, { "type": "Column", "spacing": "None", "items": [ { "type": "TextBlock", "text": "@{formatDateTime(triggerBody()?['opened_at'], 'HH:MM')}", "wrap": true, "spacing": "None", "horizontalAlignment": "Center" } ], "width": "stretch" } ] } ], "width": "80px", "verticalContentAlignment": "Center" }, { "type": "Column", "backgroundImage": { "url": "https://messagecardplayground.azurewebsites.net/assets/SmallVerticalLineGray.png", "fillMode": "RepeatVertically", "horizontalAlignment": "Center" }, "items": [ { "type": "Image", "horizontalAlignment": "Center", "url": "https://adaptivecards.io/content/LocationGreen_A.png", "altText": "Opened by" } ], "width": "auto", "spacing": "None" }, { "type": "Column", "items": [ { "type": "TextBlock", "text": "**@{triggerBody()?['opened_by_name']}**", "wrap": true }, { "type": "ColumnSet", "spacing": "None", "columns": [ { "type": "Column", "items": [ { "type": "TextBlock", "text": "@{triggerBody()?['opened_by_email']}", "wrap": true, "spacing": "None" } ], "width": "stretch" } ] } ], "width": 40 } ], "separator": true, "spacing": "Medium" }, { "type": "ColumnSet", "spacing": "None", "columns": [ { "type": "Column", "items": [ { "type": "ColumnSet", "columns": [ { "type": "Column", "items": [ { "type": "Image", "horizontalAlignment": "Left", "url": "https://messagecardplayground.azurewebsites.net/assets/clock.png", "altText": "Calendar conflict", "width": "15px", "height": "15px" } ], "width": "auto" }, { "type": "Column", "spacing": "None", "items": [ { "type": "TextBlock", "text": "@{formatDateTime(triggerBody()?['resolved_at'], 'HH:MM')}", "wrap": true, "spacing": "None", "horizontalAlignment": "Center" } ], "width": "stretch" } ] } ], "width": "80px", "verticalContentAlignment": "Center" }, { "type": "Column", "backgroundImage": { "url": "https://messagecardplayground.azurewebsites.net/assets/SmallVerticalLineGray.png", "fillMode": "RepeatVertically", "horizontalAlignment": "Center" }, "items": [ { "type": "Image", "horizontalAlignment": "Center", "url": "https://messagecardplayground.azurewebsites.net/assets/LocationBlue_B.png", "altText": "Location B: Flight" } ], "width": "auto", "spacing": "None" }, { "type": "Column", "items": [ { "type": "TextBlock", "text": "**@{triggerBody()?['resolved_by_name']}**", "wrap": true }, { "type": "ColumnSet", "spacing": "None", "columns": [ { "type": "Column", "items": [ { "type": "TextBlock", "text": "@{triggerBody()?['resolved_by_email']}", "wrap": true } ], "width": "stretch" } ] } ], "width": 40 } ] }, { "type": "ColumnSet", "spacing": "None", "columns": [ { "type": "Column", "items": [ { "type": "ColumnSet", "columns": [ { "type": "Column", "items": [ { "type": "Image", "horizontalAlignment": "Left", "url": "https://messagecardplayground.azurewebsites.net/assets/clock.png", "altText": "Calendar conflict", "width": "15px", "height": "15px" } ], "width": "auto" }, { "type": "Column", "spacing": "None", "items": [ { "type": "TextBlock", "text": "@{formatDateTime(triggerBody()?['closed_at'], 'HH:MM')}", "wrap": true, "spacing": "None", "horizontalAlignment": "Center" } ], "width": "stretch" } ] } ], "width": "80px", "verticalContentAlignment": "Center" }, { "type": "Column", "backgroundImage": { "url": "https://messagecardplayground.azurewebsites.net/assets/SmallVerticalLineGray.png", "fillMode": "RepeatVertically", "horizontalAlignment": "Center" }, "items": [ { "type": "Image", "horizontalAlignment": "Center", "url": "https://messagecardplayground.azurewebsites.net/assets/LocationRed_C.png", "altText": "Location B: Flight" } ], "width": "auto", "spacing": "None" }, { "type": "Column", "items": [ { "type": "TextBlock", "text": "**@{triggerBody()?['closed_by_name']}**", "wrap": true }, { "type": "ColumnSet", "spacing": "None", "columns": [ { "type": "Column", "items": [ { "type": "TextBlock", "text": "@{triggerBody()?['closed_by_email']}", "wrap": true } ], "width": "stretch" } ] } ], "width": 40 } ] }, { "type": "TextBlock", "text": "Rate your experience!", "weight": "Bolder", "color": "Accent", "size": "Medium", "spacing": "Medium" }, { "type": "TextBlock", "text": "Please rate your experience! Your feedback is very appreciated and will help improve your experience in the future. ", "wrap": true }, { "type": "Input.Text", "placeholder": "Add a comment", "isMultiline": true, "id": "comment" }, { "type": "Input.ChoiceSet", "choices": [ { "title": "Terrible", "value": "Terrible" }, { "title": "Poor", "value": "Poor" }, { "title": "Fair", "value": "Fair" }, { "title": "Good", "value": "Good" }, { "title": "Excellent", "value": "Excellent" } ], "placeholder": "Placeholder text", "isRequired": true, "id": "rating" }, { "type": "ActionSet", "actions": [ { "type": "Action.Submit", "title": "Submit" } ] } ], "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "version": "1.4", "msTeams": { "width": "full" } }

The above Adaptive Card was generated using the Adaptive Cards Designer tool (https://adaptivecards.io/designer), which allows you to create visually appealing and functional cards without the need for coding. The card was designed using the following sample data JSON.

Click here to visualize the JSON

"number": "INC0000060", "short_description": "Unable to connect to email", "description": "I am unable to connect to the email server. It appears to be down.", "resolved_by_name": "user 1", "resolved_by_email": "user@sample.com", "state": "", "closed_at": "2016-12-14 02:46:44", "opened_by_name": "user 2", "opened_by_email": "user2@sample.com", "opened_at": "2016-12-12 15:19:57", "resolved_at":"2016-12-13 21:43:14", "closed_by_name": "user 3", "closed_by_email": "user3@sample.com" }

Click on the Recipient text field, and add the dynamic value opened_by_email. This value will be replaced with the email address of the person who opened the ServiceNow ticket, allowing you to send the Adaptive Card directly to them in Microsoft Teams.

Add a new action after the "Post adaptive card and wait for a response" step. In the search box, type "Data Operation" and select the Parse JSON:

Next, click on the Content text field and enter the expression body('Post adaptive card and wait for a response'). This expression will allow the flow to retrieve the JSON payload generated by the Adaptive Card and send it as the content of the message to Microsoft Teams. Finally, click on the Save button to save your changes.

Copy and paste the following JSON code into the Schema field to get the response of the survey:

Click here to visualize the JSON

{ "type": "object", "properties": { "data": { "type": "object", "properties": { "comment": { "type": "string" }, "rating": { "type": "string" } } } } }

Next, you'll want to save the survey results returned from Microsoft Teams in a SharePoint List for further analysis and processing. To do so, follow the steps outlined below.

If you're interested in taking the feedback process to the next level, you might want to check out the post How to track the user experience of your Bot with Azure, Power BI and Microsoft Teams, that was written by Alexis Kinzelin (Cloud Solution Architect at Microsoft). In this post, Alexis shows you how to create a Power BI dashboard from the data stored on the SharePoint List, allowing you to easily visualize and analyze the feedback data and gain valuable insights into the performance and user experience of your Bot.

By integrating Power BI with Azure and Microsoft Teams, you can create a seamless end-to-end feedback process that allows you to collect, analyze, and act on feedback from your users in a timely and efficient manner. So be sure to check out our post and take your feedback process to the next level!

After completing the "Parse JSON" step, you'll need to add a new action to create a new item in your SharePoint List. To do so, follow the steps below:

Click on the "Add an action" button.

In the search box, type "SharePoint" and select the Create item action.
Select the appropriate SharePoint Site, List, and Folder where you want to create the new item.

Fill in the fields for each column in your SharePoint List, using the dynamic values generated by the Adaptive Card survey response. This will allow you to capture and store the survey responses in your SharePoint List for further analysis and reporting.

Save the flow.

Note that when you save your trigger, you will be given a URL that you can use to invoke the trigger from external systems.

Set up ServiceNow Business Rule

Business Rules are server-side logic that execute when database records are queried, updated, inserted, or deleted. For more details, please check the Service Now Business Rules documentation.

To configure a ServiceNow Business Rule that triggers a request to Microsoft Power Automate when an incident is closed, follow the steps outlined below:

Navigate to the Business Rules module in ServiceNow. This can be done by typing "Business Rules" in the navigation bar and selecting the appropriate option.

Click the "New" button to create a new business rule:

Give the business rule a name and description that accurately describes its purpose. For example, Incident Closed Survey.
Choose the table to which the business rule applies. This can be done by selecting the table from the drop-down menu in the "Applies to" field. For example, Incident [incident].
Specify the conditions that must be met for the business rule to run. This is done by adding conditions to the "When to run" section of the business rule. For example, you could specify that the rule should run after a new record is created or updated.
Add a filter condition to consider only closed tickets (state is closed).

Click on the Advanced tab to define the actions that the business rule should take when it runs. This is done by adding script to the "Script" section of the business rule. The script can be written in JavaScript and can perform a variety of actions, such as updating a field, sending an email notification, or creating a related record.

It's important to note that creating a business rule in ServiceNow requires some knowledge of JavaScript and the ServiceNow platform. If you're not familiar with these concepts, it may be helpful to seek assistance from a ServiceNow administrator or developer.

Add the following code:

Click here to visualize the JSON

(function executeRule(current, previous /*null when async*/) { gs.info("Incident Survey rule is running"); var snowURL = "https://dev78230.service-now.com/"; var number = current.getValue("number"); var shortDescription = current.getValue("short_description"); var description = current.getValue("description"); var stateId = current.getValue("state"); var openedAt = current.getValue("opened_at"); var resolvedAt = current.getValue("resolved_at"); var closedAt = current.getValue("closed_at"); var statusDescription; var openedById = current.getValue("caller_id"); var openedByName; var openedByEmail; var resolvedById = current.getValue("resolved_by"); var resolvedByName; var resolvedByEmail; var closedById = current.getValue("closed_by"); var closedByName; var closedByEmail; //this isnt the best practice. Consider change it to oauth2 authentication var user = 'admin'; var password = 'CHANGE HERE'; //GET THE NAME OF WHO RESOLVED THE CASE var resolvedByRequest = new sn_ws.RESTMessageV2(); resolvedByRequest.setBasicAuth(user,password); resolvedByRequest.setRequestHeader("Accept","application/json"); resolvedByRequest.setRequestHeader('Content-Type','application/json'); resolvedByRequest.setEndpoint(snowURL + "api/now/table/sys_user?sysparm_query=sys_idIN"+ resolvedById +"&sysparm_fields=sys_id,name,email"); resolvedByRequest.setHttpMethod("GET"); var resolvedByResponse = resolvedByRequest.execute(); var resolvedByBody = resolvedByResponse.getBody(); var resolvedByJson = new JSONParser().parse(resolvedByBody); resolvedByName = resolvedByJson.result[0].name; resolvedByEmail = resolvedByJson.result[0].email; gs.info("Incident Survey: name: " + resolvedByName + ", email: " + resolvedByEmail); //GET THE NAME OF WHO OPENED THE CASE var openedByRequest = new sn_ws.RESTMessageV2(); openedByRequest.setBasicAuth(user,password); openedByRequest.setRequestHeader("Accept","application/json"); openedByRequest.setRequestHeader('Content-Type','application/json'); openedByRequest.setEndpoint(snowURL + "api/now/table/sys_user?sysparm_query=sys_idIN"+ openedById +"&sysparm_fields=sys_id,name,email"); openedByRequest.setHttpMethod("GET"); var openedByResponse = openedByRequest.execute(); var openedByBody = openedByResponse.getBody(); var openedByJson = new JSONParser().parse(openedByBody); openedByName = openedByJson.result[0].name; openedByEmail = openedByJson.result[0].email; //GET THE NAME OF WHO CLOSED THE CASE var closedByRequest = new sn_ws.RESTMessageV2(); closedByRequest.setBasicAuth(user,password); closedByRequest.setRequestHeader("Accept","application/json"); closedByRequest.setRequestHeader('Content-Type','application/json'); closedByRequest.setEndpoint(snowURL + "api/now/table/sys_user?sysparm_query=sys_idIN"+ closedById +"&sysparm_fields=sys_id,name,email"); closedByRequest.setHttpMethod("GET"); var closedByResponse = closedByRequest.execute(); var closedByBody = closedByResponse.getBody(); var closedByJson = new JSONParser().parse(closedByBody); closedByName = closedByJson.result[0].name; closedByEmail = closedByJson.result[0].email; //CALL POWER AUTOMATE TO SEND TO TEAMS APPROVALS try { var body = { "number": number, "short_description": shortDescription, "description": description, "resolved_by_name": resolvedByName, "resolved_by_email": resolvedByEmail, "state": stateId, "closed_at": closedAt, "opened_by_name": openedByName, "opened_by_email": openedByEmail, "closed_by_name": closedByName, "closed_by_email": closedByEmail, "opened_at": openedAt, "resolved_at": resolvedAt }; var r = new sn_ws.RESTMessageV2(); // Change the following URL by the one you have created as HTTP trigger on Power Automate r.setEndpoint("https://prod-96.westus.logic.azure.com:443/workflows/ee1cfb87108044f5affdeab515871234/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=xndVM5q0vLUdIK0GG6mrPb1-_5pjaqfE2oKj0RHHtJI"); r.setHttpMethod("POST"); r.setRequestBody(JSON.stringify(body)); r.setRequestHeader("Accept","application/json"); r.setRequestHeader('Content-Type','application/json'); var response = r.execute(); var httpStatus = response.getStatusCode(); } catch (ex) { var message = ex.message; gs.error("Error message: " + message); } gs.info("Webhook target HTTP status response: " + httpStatus); })(current, previous);

Click on Submit to save it.

The next step is to close an incident and verify if the notification is sent to Power Automate, and subsequently to Teams. This will allow you to ensure that the integration is working correctly and that the survey feedback process is functioning as expected.

To access the list of open incidents in ServiceNow, follow the steps below:

Click on "Service Desk" in the ServiceNow menu.

Select "Incidents" from the drop-down menu.

This will take you to the list of currently open incidents. Here, you can view the details of each incident and take appropriate action as needed.

Close an incident:

Switch back to Microsoft Teams and observe that your the survey was sent:

Once the user has responded to the survey, the flow will return to Power Automate, which will then save the survey results to the designated SharePoint List.

This allows you to easily collect and analyze feedback from your users, and track any changes or trends over time.

Conclusion

In this post, we've explored how to use Microsoft Teams and ServiceNow to collect and analyze user feedback using Adaptive Cards and SharePoint Lists. By integrating these tools, you can streamline the feedback process, improve collaboration across teams, and gain valuable insights into the needs and preferences of your users.

We've covered the steps involved in setting up the integration, from creating the Adaptive Card survey to configuring the Power Automate flow and SharePoint List. By following these steps, you can easily implement the feedback process in your organization and start collecting valuable insights from your users.

We hope you found this post useful and informative. If you have any feedback or suggestions on how to improve this integration, please share them in the comments below. We look forward to hearing from you!

Build a Viva Connections card to display stock prices - Part 3: deployment and security

Matteo Pagani — Wed, 22 Mar 2023 14:00:00 GMT

Welcome to the final post in the series about building a Viva Connections card to display stock prices! After building the backend in the first post and the card in the second post, now it's time to deploy our solution and to take a deeper look at the security of our API.

Let's start with the deployment of the backend!

Deploying the backend

Our backend is made by an Azure Function and an Azure Cache for Redis instance. The easiest way to deploy these components is to use a template, so that we don't have to manually create all the services and configure them. On the GitHub repository of the project, you can find a Bicep template. Bicep is a powerful language that you can use to deploy Azure resources and define dependencies, properties, etc.

The template defines the following resources:

A web app hosting plan, using the Y1 SKU, which hosts the Azure Function.
An Azure Function app, hosted on Linux and which runs the .NET runtime. The function already includes, in the application settings, the properties we have set in the first post to manage the cache, like CacheConnection and CacheExpirationInHours.
An Azure Storage instance, which is required by the Azure Function to work since it's where all the logs are stored.
An Azure Cache for Redis instance. Thanks to the Bicep syntax, we can specify that the Azure Function is dependent on the cache, so that it will be created first. This will enable the URL assigned to the instance to be automatically injected into the CacheConnection setting in the Azure Function.
An Azure Application Insights instance, which is used to collect analytics and errors on the Azure Function.

The easiest way to deploy the Bicep template is to use Visual Studio Code, by installing the dedicated extension. Once you have installed it, click on the Azure icon on the left sidebar and make sure to login with an account which has the permission to create resources on your Azure subscription.

Now open the main.bicep file with Visual Studio Code. Press CTRL-SHIFT-P and, from the command palette, choose Bicep: Deploy Bicep file. You will be asked for a series of information:

The name of the deployment (you can leave the default one).
The target subscription in which to deploy the resources.
The resource group where to include the resources (it’s suggested to create a new one dedicated to this project).
The Azure region where to deploy the resources.

Then you will be asked if you want to provide a parameter file with the settings of the resources. We won’t use one, but we’ll provide the information as part of the deployment. As such, pick None. This will trigger a series of additional questions:

The name to assign to the Azure Cache for Redis service. You can use the first option to automatically generate one or you can specify a custom one.
The name to assign to the Azure Function. You can use the first option to automatically generate one or you can specify a custom one.
The Azure region in which to deploy the resources. Use the default value (resourseGroup().location) to create the resources in the same region you have chosen to host the resource group.
The runtime used by the Azure Function. Leave the default value, which is dotnet.

As the last question, you will be asked if you want to create a parameters file with the values you have just specified. Choose Yes if you’re planning to repeat the process in the future, otherwise say No. At this point, the deployment process will start. In the Output window of Visual Studio Code, you will see a URL that you can open to check the status of the deployment:

When you open the URL, you will be redirected to the Azure portal to see the deployment in action:

Most of the resources will be deployed very quickly, while the Azure Cache for Redis service will require a while. Don’t worry, it’s expected. Once the deployment is completed, you will find in the resource group you have chosen all the resources which are required to host the solution.

Deploying the Azure Function

The previous step has created on Azure all the services which are required to host our solution, but it didn’t deploy the solution itself. Since we have built the Azure Function with Visual Studio 2022, we can use the built-in Publish feature to deploy it. Right click on the project and choose Publish. Click New to start the wizard to generate a publish profile:

Target: choose Azure.
Specific target: choose Azure Function App (Linux).
Functions instance: pick your Azure subscription and look for the Azure Function instance that you have just created with the Bicep template. - Deployment type: for this article, we'll choose Publish (generates pubxml file). However, if you want a better long-term solution, you can choose CI/CD using GitHub Actions, which will generate a workflow for GitHub Actions that can automatically build and deploy an updated version of the Azure Functions every time you commit changes to your code.

Once the process is completed, Visual Studio will display an overview of the deployment:

Click on Publish to start the deployment process. Once the operation is completed, you should be all set. To test it, try to use Postman or open your browser against the URL https://<your-function-url/api/stockPrices/MSFT and you should see the JSON with the latest snapshot about the Microsoft stock.

Before using the API in our card, there's an extra step we must follow. Do you remember that, in the previous post, we had to enable CORS in the local Azure Functions configuration file so that the Viva Connections dashboard would have been able to reach the API? We must do the same also now that we have published the function on Azure, since the domain which hosts it is different from SharePoint's domain. Go to the Azure portal, click on the Azure Function you have just deployed and look for the CORS option in the left panel, under the API section. Under the allowed origins section, add the URL of your SharePoint website, like in the following example, then hit Save:

Please note: if you have followed the first post step by step and you have already created an Azure Cache for Redis instance, you can skip using the Bicep template. In this case, however, you will have to:

In the Publish wizard in Visual Studio, instead of picking an existing Azure Functions instance, you must click on Create New and follow the wizard to create a new instance.

Once the Azure Function is up & running, you must open it in the Azure portal, click on Configuration and, under Application Settings, add two keys: CacheConnection, with the full connection string to the Azure Cache for Redis instance, and CacheExpirationInHours, with the amount of time in hours that must pass before the cache is invalidated.

Deploy the Viva Connections card

Viva Connections cards are considered SharePoint applications, so they are deployed through the SharePoint administrator center. The first step is to generate a package. Open Visual Studio Code on your card project, click on Terminal → New terminal and run the two following commands:

gulp bundle --ship

gulp package-solution --ship

The first command will package all the required JavaScript files into a single bundle. The second one will generate a file with .sspkg extension under the sharepoint folder of your project. This is the package we must upload to the SharePoint admin center. To access the admin center, you must open your browser on the URL https://<your-sharepoint-tenant>-admin.sharepoint.com/. For example, if your company is called Contoso, the URL will be https://contoso-admin.sharepoint.com/.

Please note: you must have administrator rights on SharePoint to be able to access the portal and perform the next steps.

From the panel on the left, choose More features and click the Open button under Apps:

Once you are in the App Catalog, click on Upload and look on your computer for the file with .sspkg extension that you have previously created. Once the file has been uploaded, you can choose to just enable the application or to also add it automatically to all the existing SharePoint sites. Pick up the option that makes more sense for your scenario. The second one makes your work easier, because the card will be already available when you start configuring your Viva Connections dashboard; otherwise, you will need to manually add it to the SharePoint site which hosts your dashboard.

That's it. Now if you head to the SharePoint website which hosts your Viva Connections Dashboard, click on Manage Viva Connections and enter editing mode, you will see your Stocks card among the available ones you can add to the dashboard:

You will also have the option, by clicking on the pencil icon, to open the property panel and customize the properties we have defined in the second post, like the Azure Functions URL and the stock symbol to track.

Secure our backend

If you followed the article so far, you will have a working card on your Viva Connections dashboard displaying the stock price of a company. However, as we anticipated in the previous post, the current implementation has a security flaw. The Azure Function URL is public, and it isn't protected in any way. Anyone with the full URL of our backend would be able to use the service we've built in their solutions and projects. From a security perspective, it might not be a big problem: in the end, we aren't returning any sensitive information; it might be, however, from a cost perspective, because we could get unexpected expensive bills from Azure or Alpha Vantage (in case we opted in for a paid plan) because someone else abused our API.

The best way to protect our API in our scenario is to use the Microsoft Identity platform. Since our card is hosted on SharePoint, which is a platform that requires the user to be authenticated with their work account, we can leverage single sign-on. We won't have to ask the user to login to use the API, since they are already authenticated. There are two changes we must make to support this scenario:

One in the backend, to protect the API. We won't have to change the code, since we'll leverage the built-in Authentication feature in Azure.
One in the card, to make authenticated calls against the protected API. The HTTP request must include the Authorization header with a valid token.

Let's see step by step the changes to make.

Secure the Azure Function

As mentioned, we won't have to change the code of our Azure Function, since we're going to use the built-in authentication support provided by Azure. Open the Azure portal, go to the Azure Function you have previously deployed and, in the left sidebar, click on Authentication:

In the page, choose Add identity provider and pick Microsoft from the list. This process will start a wizard that creates a new app registration on Azure Active Directory, which will be used to support SSO. Make sure to set the following options:

Under App registration type, choose Create new app registration.
Under Name, call it Stock Prices.
Under Supported account types, choose Current tenant – Single tenant. This will ensure that only our employees will be able to use the API.

Then configure the App Service authentication settings section with the following settings:

Under Restrict access, choose Require authentication.
Under Unauthenticated requests, choose HTTP 401 Unauthorized.

Click Add to complete the authentication process. Our Azure Function is now protected and, if you try to hit again the URL with Postman or your browser, you will get back a 401 Unauthorized error.

Please note: the previous guidance assumes that your Azure Active Directory tenant is hosted on the same domain as your SharePoint tenant. In case they are hosted on different domains, you must create the AAD app registration manually and supply the various information (application id, tenant id, client secret) to the Azure Functions configuration. You will also need to choose the option Any Azure AD directory - Multi tenant under Supported account types.

To use the AAD app we have just registered to protect our API, we must make a final change in the app configuration. Still in the Azure portal, go to the Azure Active Directory section and, from the sidebar, choose App registrations. Look for the application called Stock Prices that you have just created and go to the Expose an API section. Click on Add a scope and use the following settings:

Under Scope name, type access_as_user.
Under Who can consent?, choose Admins and users.
Under Admin content display name, type Access the API on behalf of a user.
Under Admin consent description, type Access the API on behalf of a user.
Make sure State is set to Enabled.

Click Save to complete the process. Now our API is protected, so we can move on and make the required changes to the card.

Secure the card

From a data manipulation perspective, the code of our card doesn't change. We still need to perform a HTTP GET to our API and parse the JSON we receive back with the stock data about the company we have chosen. The difference, however, is the way we perform the HTTP GET, since now we must include inside the request a valid token to authenticate ourselves. Luckily, the SharePoint Framework makes this operation easy: when employees are using Viva Connections (or visiting any SharePoint site), they're already logged in with their work identity, so SPFx includes a special HTTP client which is already authenticated through single sign-on. We just need to use it instead of the traditional fetch() API. First, let's add the following statement at the top of our StocksAdaptiveCardExtension.ts file:

import { AadHttpClient } from '@microsoft/sp-http';

Then, let's change the fetchData() function as following:

public async fetchData(): Promise<void> { 

    const url = this.properties.apiUrl + "/" + this.properties.stockSymbol;

    const aadClient = await this.context.aadHttpClientFactory.getClient("api://c94af769-ef30-4d37-a660-b602aab24d5b");
    let response = await aadClient.get(url, AadHttpClient.configurations.v1);

    const json = await response.text();
    const parsedJson: IStockPrice = JSON.parse(json) as IStockPrice;

    this.setState({stock: parsedJson});
}

We use the getClient() function, exposed by this.context.aadHttpClientFactory, to get an authenticated client. As parameter, we must pass the special URL api:// followed by the app id of the AAD app that we have previously registered. We can find this URL under the Expose an API section of our AAD app:

Once we have an authenticated client, we perform the HTTP GET request by calling the get() method and passing, as parameters, the URL of our Azure Function (which is stored in the properties) and the version to use, through the constant AadHttpClient.configurations.v1.

This is the only change we must make. The rest of the code is the same: we take the response, turn it into a string and then parse it as an IStockPrice object.

The final change we must make is in the manifest that is generated when we create the package to upload on the SharePoint admin portal. We must declare, in fact, that our card is using an external API. You can find this configuration in the package-solution.json file under the config folder. Make sure to add, under the solution property, the following entry:

json

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "webApiPermissionRequests": [
      {
        "resource": "Stock Prices",
        "scope": "access_as_user"
      }
    ]
  }
}

The value of the resource property must match the name we have assigned to the app registration we have created in our AAD tenant.

The last step is to repeat the two gulp based commands we have previously seen to generate a new .sspkg package and upload it on the Apps section of the SharePoint admin portal. This time, after having chosen if we want to only enable the app or to automatically add it to all the sites, we will see a new prompt:

We must approve API access for our card, otherwise it won't be able to perform authenticated requests. Click on Go to API Access page, in which you will find a pending request:

Click on Approve to complete the process.

That's it. Now if you add the card again to your Viva Connections dashboard, everything should continue to work as before. The difference, however, is that the API is now protected and only your card will be able to retrieve the stock data. Any user outside the company, even if they know the URL of your Azure Function, won't be able to access the data: they will just get a 401 Unauthorized response.

Please note: the project that you will find on the GitHub repository supports both authenticated and unauthenticated requests, through a new property added to the panel called AAD App Id. When you add the card to the dashboard, you can use this property to specify the App ID of the AAD application you have created to support single sign-on. If the property is set, the fetchData() function will use the AadHttpClient to perform the authenticated request; if the property is left empty, instead, it will use the standard unauthenticated fetch() API.

Wrapping up

In this final post of the series, we have learned how to take our stock card for Viva Connections in production, by deploying the backend on Azure and by uploading the card as a SharePoint app in the administrator portal. We have also learned how to protect our API, which is optional but highly suggested to avoid unauthorized users abusing our backend.

Everything we have learned so far is available on GitHub. The repository includes the Azure Function (in the function folder), the card (in the card folder) and the Bicep template to deploy the Azure resources (again, in the function folder).

Happy coding!

Build a Viva Connections card to display stock prices - Part 2: the card

Matteo Pagani — Tue, 21 Mar 2023 12:54:30 GMT

Welcome back to our series of posts about building a Viva Connections card to display the stock price of a company! In the previous post we built the backend which provides the data we need to display. The backend was built using an Azure Function, in companion with the Azure Cache for Redis service to improve performance and reduce the number of API calls against Alpha Vantage, the free service we have chosen to retrieve stock information.

In this post, we're going to build the actual Viva Connections card, using the SharePoint AdaptiveCard extension model. As a reminder, this is the look & feel of the actual card we're going to build:

SharePoint Adaptive Cards supports three types of templates. In our case, we're going to choose the one called Primary Text, which supports displaying a title, a primary text, and a description. As you can notice from the screenshot, the card doesn't offer too much space to display information. This is where the Quick View feature comes into play. When we click or tap on the See more button, we'll open a panel that will be rendered using an adaptive card and that we can use to display more information and more detailed content.

Now that we have understood what we're going to build, let's start to build it!

Setting up the project

Viva Connections is a Teams application, but it's part of the SharePoint ecosystem. The Viva Connections dashboard, in fact, is hosted on the same intranet SharePoint used by the company. As such, the developer story for Viva Connections is based on SharePoint and the same type of extensions you can build for SharePoint (like web parts) can be used also for Viva Connections. However, there's one type of extension that was recently added that is tailored specifically for Viva Connections, which is the SharePoint Adaptive Card. The name comes from the fact that parts of the layout of the card can be defined using Adaptive Cards, a popular technology in the Microsoft 365 ecosystem to render UI components starting from a JSON template.

On this blog, I already walked you through the steps required to create a SharePoint Adaptive Card extension on Windows, so you can head to the article to discover all the requirements you need.

In this blog post, we'll assume you have satisfied all the requirements, so just open a terminal, create a folder where to store your project and type the following command:

yo @microsoft/sharepoint

You will start a wizard that will guide you through the creation of the project. Make sure to choose the following values:

What is your solution name?: Choose the name you prefer, I used viva-connections-stocks
Which type of side client-component to create?: Adaptive Card Extension
Which template do you want to use?: Primary Text Card template
What is your Adaptive Card Extension name?: Viva Connections Stocks

Yeoman will generate a starting project for us. Let's explore it.

Building the SharePoint Adaptive Card

A SharePoint Adaptive Card project is made by multiple files, but there are four of them which are important (keep in mind that the name might change, since it's generated based on the name you have chosen for the project):

The StocksAdaptiveCardExtension.manifest.json file, which describes the card. It contains valuable information like the name, the version, and the properties.
StocksAdaptiveCardExtension.ts, which is the entry point of the card. This file includes a class that inherits from BaseAdaptiveCardExtension and it takes care of initializing the card. This is where we're going to load the stocks information from our Azure Function.
CardView.ts, which is the definition of the card. This file includes a class that inherits from BasePrimaryTextCardView (since we chose the Primary Text template; if we would have picked a different template, it would be a different base class) and it's where we supply the data that we want to display in the card (the stock information).
QuickView.ts, which is the definition of the adaptive card displayed when you click or tap on the card. This file includes a class that inherits from BaseAdaptiveCardView and, similarly to the CardView, it's where we supply the data that we want to display in the quick view.

You can use any type of editor to work on this project, but I highly suggest Visual Studio Code, since it offers a built-in debugging experience, which will come especially useful when it will be time to start testing our Viva Connections card.

Let's break down the development of the card in little steps, so that hopefully it will be easier for you to follow the process.

Loading the data

The entry point of the card, which is implemented by the StocksAdaptiveCardExtension.ts file, is the place where a Viva Connections card must load the data we want to display. This class, in fact, implements a function called onInit(), which is triggered when the card is loaded in the dashboard. This is the right place to load and initialize the data.

Before starting to fetch the data, however, we need a way to represent the stock information coming from the Azure Function. The default template is based on TypeScript, so why not leverage the strongly typed support that this language brings over JavaScript? Let's add a new file to our project and call it IStockPrice.ts, then copy the following definition:

export interface IStockPrice {
    openingPrice: number;
    closingPrice: number;
    highestPrice: number;
    lowestPrice: number;
    volume: number;
    time: Date;
    companyName: string;
    exchange: string;
    symbol: string;
}

This interface is the equivalent of the StockPrice class we have defined in our Azure Function, and it matches the JSON payload we're going to receive from our backend. Now that we have an interface, we must introduce the concept of state in a Viva Connections card. If you have experience with React, you'll find yourself at home, since it's the same concept and it's even implemented with the same APIs. State is the place where you store data that is persisted across the lifecycle of a card. It's the best place to store our data, since we can read its content from every file included in the project. This means that we can store the stock information in the onInit() function of the StocksAdaptiveCardExtension.ts file and then read it in the CardView.ts file.

The StocksAdaptiveCardExtension.ts file already includes a definition for the state which, however, is empty by default. We must add a new property to store the stock information, using the interface we have just created:

export interface IStocksAdaptiveCardExtensionState {
  stock: IStockPrice;
}

Now we can move on and define now a new function called fetchData(), which uses the fetch() API to retrieve the stock price from our Azure Function (we'll use the Microsoft one as a reference).

public async fetchData(): Promise<void> { 

    const url = "https://myfunction.azurewebsites.com/api/stockPrices/MSFT";

    let response = await fetch(url);

    const json = await response.text();
    const parsedJson: IStockPrice = JSON.parse(json) as IStockPrice;

    this.setState({stock: parsedJson});
}

The function is quite straightforward. First, we retrieve the JSON payload that contains all the information about the Microsoft stock; then we turn into a string, calling the text() function and we use JSON.parse() to convert the string into an IStockPrice object. Finally, we store it into the stock property of the state, by calling this.setState().

Now, we just need to call this function inside the onInit() method:

public async onInit(): Promise<void> {
  
  this.state = { 
    stock: null
  };

  
  await this.fetchData();
  

  this.cardNavigator.register(CARD_VIEW_REGISTRY_ID, () => new CardView());
  this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());

  return Promise.resolve();
}

The onInit() function takes care of two additional tasks: first, before working with the state, we must initialize it. In our scenario, we don't have a default value, so we just set the stock property in the state to null. Second, we must register the cards and the quick view we want to render. The card is registered into the cardNavigator collection, while the quick view is registered in the quickViewNavigator collection. The default template includes a single card and a single quick view. A more complex project might provide multiple cards (for example, one for the medium and one for the large size) and multiple quick views (for example, triggered by different actions).

Now that we have the stock data, we must display it. Let's head to the CardView.ts file: we'll find a function called data(), which implements an interface that changes based on the template we have chosen. In our case, it's called IPrimaryTextCardParameters and it offers three properties, one for each of the elements that we can customize in the card: the title, the primary text, and the description.

Thanks to the state, we can set some of these properties with the stock information we have previously downloaded:

public get data(): IPrimaryTextCardParameters {
  return {
    description: "MSFT",
    primaryText: this.state.stock.openingPrice.toString(),
    title: this.properties.title
  };
}

The description property has a fixed value, the MSFT symbol; title is taken from the card properties (we'll get back to it later); primaryText is taken from the state. Thanks to the this.state keyword, we can access the IStockPrice object we have previously stored. Specifically, we are displaying on the card the current price of the stock, which is stored in the openingPrice property.

That's all we need to implement the basic experience. We're ready to test this first step.

Testing the Viva Connections card

SharePoint offers a feature called SharePoint Workbench to test SharePoint extensions, including Adaptive Card ones. It's a special environment, hosted on our SharePoint tenant, which can connect to our local machine and load an extension hosted locally. This tool simplifies the testing experience; otherwise, we would need each time to create a new SharePoint package, upload it to the administrator portal, test the work, identify the issues, make changes, and repeat the process again.

Before getting to the SharePoint workbench, however, we must launch the Azure Functions which we built the last time. However, it isn't enough. We must also use a tool like Ngrok to expose our local machine to a public URL, so that the Azure Functions can be accessed also by the SharePoint workbench. Since it runs on our SharePoint website, in fact, it's not able to connect to an API exposed on localhost. Once you have ngrok setup on your machine, launch it with the following command:

ngrok http 7071

You will get back a URL like https://<random-value>.ngrok.io. Make sure to include it in the code, by assigning it to the url property of the fetchData() function.

Now you can go back to the Viva Connections card project. Inside the .vscode folder, you will find a file called launch.json, which defines the debugging profile. You will find a url property, with the following setting:

"url": "https://enter-your-SharePoint-site/_layouts/workbench.aspx",

Replace the first part of the URL with the real URL of your SharePoint domain. Now you must perform two operations in Visual Studio Code:

In the top menu, click on Terminal → New Terminal to open a terminal on the current folder. Run the following command:

powershell
```
gulp serve --nobrowser
```
This command will run a local server that will host the Adaptive Card extension and it will enable the Live Reload feature, so that you can make changes to the code without having to redeploy the project.
Move to the Debug tab from the left sidebar and press F5. Visual Studio Code will launch a browser on the SharePoint workbench, and you will have to login with a valid SharePoint account.

This is how the SharePoint Workbench looks like:

When you click on +, you will see a series of components that you can add to test them. You will see a special section called Local, with the name of your project. Click on it to add it to the workbench. If you have done everything correctly, you will see a card with the Microsoft stock price.

In case, instead, you get an error, you can leverage the developers' tools in the browser (press F12 in Edge or Chrome) to see what's going on. It's likely that the first time you will experience a CORS failure: since the SharePoint website is hosted on a different domain than your Azure Functions, the request is blocked by default. While you're in development, you can overcome this problem by adding the CORS entry under the Host section in the local.settings.json file of your Azure Function:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
  },
  "Host": {
    "CORS": "*"
  }
}

This configuration will open the usage of the API from any client app. You can also choose to restrict it, by adding the domain of your SharePoint website (like https://contoso.sharepoint.com).

Everything works, but the current implementation has a lot of limitations. We have hardcoded information, like the URL of our Azure Function or the stock price we want to track. This means that we would need to make changes to the code every time we want to track a stock different than Microsoft or the URL of our backend changes. Let's fix that by adding properties.

Adding properties

When you have added the Stocks card in the SharePoint Workbench, you have noticed that a panel opened on the right, which gave you the option to customize the title and to choose the size of the card. These are properties: the administrator who configures the Viva Connections dashboard can define them and, in code, you can read their value so that you can customize the behavior of the card. We have already seen an example of the property in action. Let's look again at the data() function implemented in the CardView.ts file:

public get data(): IPrimaryTextCardParameters {
  return {
    description: this.state.stock.symbol, 
    primaryText: this.state.stock.openingPrice.toString(),
    title: this.properties.title
  };
}

The title of the card is taken from the this.properties collection, which means that the administrator who configures the dashboard can customize the title without needing to ask the developer to make changes.

Let's use the same approach to add two other properties: one called stockSymbol, to store the company we want to track; one called apiUrl, to store the URL of our backend.

The first place where you must define properties is the manifest file. You will find a section called properties, where you can list them with their default value. This is how we must change it:

"properties": {
  "title": "Stocks",
  "stockSymbol": "",
  "apiUrl": ""
},

title was already included, with a default value of Stocks. We add stockSymbol and apiUrl and we use an empty string as default value, since we don't have a way to guess which will be the stock symbol to track or the backend URL.

The next step is to update the IStocksAdaptiveCardExtensionProps interface, included in the StocksAdaptiveCardExtension.ts file, which describes the properties, in a similar way to what we did before with the IStocksAdaptiveCardExtensionState interface for the state. This is how we must change it:

export interface IStocksAdaptiveCardExtensionProps {
  title: string;
  stockSymbol: string;
  apiUrl: string;
}

We are simply adding two new properties, stockSymbol and apiUrl, which type is string.

Now that we have our properties, we must change the fetchData() function we have previously created so that the API URL and the stock symbol are taken from the properties, instead of being hardcoded:

public async fetchData(): Promise<void> { 

    const url = this.properties.apiURL + "/api/stockPrices/" + this.properties.stockSymbol;

    let response = await fetch(url);

    const json = await response.text();
    const parsedJson: IStockPrice = JSON.parse(json) as IStockPrice;

    this.setState({stock: parsedJson});
}

There's one last step to complete the task. We have defined two new properties, but we haven't added a way to set them. The panel that is displayed when you add a card to the dashboard, in fact, isn't automatically generated by SharePoint, but it's managed by a file included in the project (the one called StocksPropertyPane.ts, in our case). Inside this file, you use TypeScript objects to define the various fields. Let's take a look:

import { IPropertyPaneConfiguration, PropertyPaneTextField } from '@microsoft/sp-property-pane';
import * as strings from 'StocksAdaptiveCardExtensionStrings';

export class StocksPropertyPane {
  public getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: { description: strings.PropertyPaneDescription },
          groups: [
            {
              groupFields: [
                PropertyPaneTextField('title', {
                  label: strings.TitleFieldLabel
                }),
                PropertyPaneTextField('stockSymbol', {
                  label: strings.StockCodeLabel
                }),
                PropertyPaneTextField('apiUrl', {
                  label: strings.ApiUrlLabel
                })
              ]
            }
          ]
        }
      ]
    };
  }
}

This class is very flexible, since you can define an arbitrary number of properties, group them into different sections, etc. For the sake of simplicity, in our case we are displaying all the properties into a unique group. Each property is mapped to a specific PropertyPane object. In our scenario, all the properties are strings, so they are rendered with a PropertyPaneTextField object, which generates a text input. The SharePoint Framework includes many other types of objects, like PropertyPaneDropdown or PropertyPaneCheckbox, to support several types of parameters, like boolean or numbers.

When we initialize the PropertyPaneTextField object, we must specify two information:

The name of the property we want to bind to the field.
The label we want to display as header of the field. By default, SharePoint Adaptive Card extensions are built with localization in mind, so labels aren't hardcoded, but they're taken from an interface included in the project called IStocksAdaptiveCardExtensionStrings and defined in the mystring.d.ts file. This interface loads the strings from a localization file: by default, the project includes only English as a language, so you'll find the strings in the en-us.js file.

The StocksPropertyPane.ts file already included a field to support the title property. As we have seen in the previous snippet, we just must add two new fields to support the stockSymbol and apiUrl properties.

This was the last required step to support properties. There's only one catch that we must keep in mind: properties, by default, are loaded only when the card is initialized. This means that, with the current implementation, when you drag the card into the dashboard and you start changing properties, you won't see the changes until you refresh the page. If you want to make the card more dynamic, you can use the onPropertyPaneFieldChanged event, which is available in the StocksAdaptiveCardExtension.ts file. Let's look at the implementation:

protected onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any): void {
  if (propertyPath === 'stockSymbol' || propertyPath === 'apiUrl' && newValue !== oldValue) {
    if (newValue) {
      void this.fetchData();
    } 
  }
}

Using the propertyPath parameter, we check which property was changed. In our case, we want to detect changes in the stockSymbol or apiUrl properties. If the administrator simply changes the title of the card, in fact, we don't need to retrieve new data from our backend. If one of these two properties has changed and there's indeed a new value, we call again the fetchData() function we have previously defined to query our backend, using the new API URL or the new stock symbol.

Now that we have completed the implementation, we can use the SharePoint Workbench again to test our project. This time, when you add the Stocks card to the dashboard, the property pane on the right should include two new fields other than the title one:

Now set the two fields with a valid stock symbol and with the URL generated by Ngrok: the card should automatically update with the data coming from our Azure Function.

Implementing the quick view

The last feature we're going to implement today is the quick view. We don't have to do much in code, since the default template already implements the quick view the way we need: when the user clicks on the button on the card, we want to open the quick view to display more details about the stock.

Let's open the CardView.ts file and let's look at how the button is implemented:

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [
    {
      title: strings.QuickViewButton,
      action: {
        type: 'QuickView',
        parameters: {
          view: QUICK_VIEW_REGISTRY_ID
        }
      }
    }
  ];
}

The file includes a function called cardButtons(), which can return zero, one or two ICardButton objects. A card, in fact, doesn't need to have a button (you can also manage the click on the card itself) but, if you want to have them, you can have only one when the card is displayed in medium size and two when the card is displayed in large size.

A card button supports various types of interactions. The Quick View panel is a built-in one, so you just need to supply a label for the button (using the title property) and, as action type, the fixed QuickView value. Then, as parameter, you must supply the view property with the identifier of the quick view you want to display, among the ones that have been registered inside the quickViewNavigator collection.

This is about triggering the quick view. But how is a quick view defined? Let's look at the QuickView.ts file. The basic structure is the same as the CardView one. It includes, in fact, a data() function which we must use to supply the information we want to display on the card. However, this time the function implements the IQuickViewData interface, which is generic. Unlike with the basic card (which supports only three templates, each of them with a limited number of parameters), we have lot of flexibility with an adaptive card, so we can supply an undefined number of parameters.

The core implementation of the QuickView file, however, is the template() function, in which we must supply the JSON that defines the Adaptive Card. In the default template, this JSON is defined in a dedicated file called QuickViewTemplate.json, so the function simply uses the require() JavaScript method to load the content of that file:

public get template(): ISPFxAdaptiveCard {
  return require('./template/QuickViewTemplate.json');
}

The default project contains a basic template, which isn't a good fit, however, for our scenario. The easiest way to generate a better template is to leverage the Adaptive Card Designer, a tool which you can use to visually design your card and get the corresponding JSON. Additionally, the template gallery includes a stock template, which is perfect for our needs. This is the definitive version of the template, modified for our needs:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
      {
          "type": "Container",
          "items": [
              {
                  "type": "TextBlock",
                  "text": "${companyName}",
                  "size": "Medium",
                  "wrap": true
              },
              {
                  "type": "TextBlock",
                  "text": "${primaryExchange}: ${symbol}",
                  "isSubtle": true,
                  "spacing": "None",
                  "wrap": true
              },
              {
                "type": "TextBlock",
                "text": "${time}",
                "wrap": true
            }
          ]
      },
      {
          "type": "Container",
          "spacing": "None",
          "items": [
              {
                  "type": "ColumnSet",
                  "columns": [
                      {
                          "type": "Column",
                          "width": "stretch",
                          "items": [
                              {
                                  "type": "TextBlock",
                                  "text": "${formatNumber(latestPrice, 2)} ",
                                  "size": "ExtraLarge",
                                  "wrap": true
                              }
                          ]
                      },
                      {
                          "type": "Column",
                          "width": "auto",
                          "items": [
                              {
                                  "type": "FactSet",
                                  "facts": [
                                      {
                                          "title": "High",
                                          "value": "${high} "
                                      },
                                      {
                                          "title": "Low",
                                          "value": "${low} "
                                      }
                                  ]
                              }
                          ]
                      }
                  ]
              }
          ]
      }
  ]
}

We won't go through the details of implementing an adaptive card, you can refer to the official documentation. One thing I want to highlight, however, is that you can notice how some values aren't hardcoded, but there's a special string that acts as a placeholder, like ${companyName} or ${symbol}. These are parameters, which are replaced at runtime with the parameters we supply to the data() function of the QuickView file. This is how our data() function looks like:

public get data(): IQuickViewData {
  return {
    subTitle: strings.SubTitle,
    title: strings.Title,
    companyName: this.state.stock.companyName,
    symbol: this.state.stock.symbol,
    latestPrice: this.state.stock.openingPrice,
    high: this.state.stock.highestPrice,
    low: this.state.stock.lowestPrice,
    primaryExchange: this.state.stock.exchange,
    time: this.state.stock.time
  };
}

Thanks to the this.state keyword, we can access the stock object we have previously stored and retrieve the various information we want to display, like the company name, the symbol, or the latest price. The properties names match the placeholders we have placed in the JSON template of the Adaptive Card.

We're good to test our code now. Press F5 again in Visual Studio Code to launch the SharePoint workbench, add the Stocks card to the dashboard and set up its properties. Now, if you click on the See more button on the card, you should see the adaptive card being rendered, which displays a bit more information about the stock than the one you see in the card:

Wrapping up

In this second part of the series we have built our Viva Connections card. We didn't just build a card to display stock prices but, in the process, we have learned the basics on how to build a Viva Connections card. Everything we have learned, in fact, can be easily reapplied to display any type of data, coming from any type of 3rd party service.

In the next and final post of the series, we'll talk about deployment and security. The current implementation, in fact, has a security flaw: anyone with the URL of our Azure Function will be able to call the API and get the stock data. We'll learn how to protect the API, so that only authorized users who are logged in into Teams and Viva Connections can use it.

In the meantime, remember that the full code of the final solution is available on GitHub.

Happy coding!

Build a Viva Connections card to display stock prices - Part 1: the backend

Matteo Pagani — Mon, 20 Mar 2023 19:08:20 GMT

Recently, a customer engaged with my team because they have started to adopt Viva Connections in their company. They are happy about the experience, but they miss one piece of information that they consider important: the stock price of the company. It is quite a common use case, but Viva Connections doesn't provide this feature as built in. So, I decided: "Why not take advantage of this engagement and build something that can be useful to every customer who is adopting Viva Connections?". In this series of posts, we're going to build a Viva Connections card to display the price of any stock on the market, powered by a set of Azure services like Azure Functions and Azure Cache for Redis. This post will be focused on the backend, while in the next one we're going to build the actual card.

This is the final look of the project we're going to build:

The card displays the basic information (stock name and current price). When you click on it, an Adaptive Card will display more details on the stock.

Building the backend

We're going to leverage a service called Alpha Vantage to get the stock prices. It's a powerful service that offers an API that can return either a JSON or a CSV file and it supports a lot of market data. The company offers a free tier with some limitations (5 API requests per minute and 500 requests per day), so you might want to consider purchasing a paid tier for a production scenario. However, our backend will include a cache based on Azure Cache for Redis, which will help us to reduce the number of calls we must perform against the API.

We're going to use two different APIs offered by Alpha Vantage:

The Intraday API, which gives an historical list of all the prices across the day. You can see an example here. We'll use it to get the stock prices.
The Overview API, which gives you detailed stock information about a company. You can see an example here. We'll use it to get some accessory information like the company name and the market.

The first step is to head to the official website and register. You will receive an API key: store it somewhere since we'll need to use it later.

As I mentioned in the introduction, we won't call this API directly from the Viva Connections card, but we're going to build a middleware API, which will help us to improve performance and reduce the number of API calls we must perform against the Alpha Vantage APIs. We're going to build this API using Azure Functions: thanks to the serverless model, we can focus only on the code we need to write, without worrying about the infrastructure and the configuration. Additionally, pricing is very low, with one million executions per month included in the free plan.

Since I'm a .NET developer, I'm going to build the Azure Function in C# using Visual Studio 2022. If you're a web developer, you can use Visual Studio Code to create a project based on Node.js as runtime, which enables you to write the function with JavaScript / TypeScript. Start by creating a new project in Visual Studio using the Azure Functions template (you will need the Azure workload enabled), pick .NET 6.0 as runtime and choose Http Trigger with Open API as function type. For testing purposes, choose Anonymous as authentication.

As a first step, it's not required but I suggest you give a more meaningful name to the file and the class name that is generated by Visual Studio. But, most of all, set a meaningful name inside the [FunctionName] attribute, since it will define the name of the API endpoint:

[FunctionName("StockPricesApi")]

The second change we must make is on the signature of the Azure Function. We need a way to get an input parameter from the caller, which is the stock symbol we want to track. There are multiple ways to do that: the one we're going to use is routing. The final segment of our API's URL will include the stock symbol. Let's change the signature of the Run() method like this:

public async Task<IActionResult> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "stockPrices/{stockSymbol}")] HttpRequest req, string stockSymbol)

Let's say we want to get the stock price of Microsoft. Thanks to this change, we can call the API with the following URL:

https://<azure-function-url>/api/stockPrices/MSFT

The Azure Functions runtime will automatically inject into the stockSymbol parameter of the function the final segment of the URL, which includes the stock symbol. Now we have all the information we need to call the Alpha Vantage APIs but, before doing it, let's make our life easier, by adding a NuGet package to our project that will help us to work with the Alpha Vantage APIs without having to manually perform HTTP requets or to parse JSON. Right click on the project, choose Manage NuGet packages, look and install a package called AlphaVantage.Net.Stocks. Now we have everything we need to start calling the Alpha Vantage APIs. However, as mentioned in the introduction, the information we want our Azure Function to return is the combination of two different Alpha Vantage APIs: Intraday and Overview. A such, let's create a new class that will combine the information we want to display in the Viva Connections card in a single entity:

public class StockPrice
{
    public decimal OpeningPrice { get; set; }

    public decimal ClosingPrice { get; set; }

    public decimal HighestPrice { get; set; }

    public decimal LowestPrice { get; set; }

    public long Volume { get; set; }

    public string CompanyName { get; set; }

    public string Exchange { get; set; }

    public string Symbol { get; set; }

    public DateTime Time { get; set; }
}

Now let's write some code using the AlphaVantage.Net.Stocks library which creates a new StockPrice object pulling data from the two APIs:

[FunctionName("StockPricesApi")]
public async Task<IActionResult> Run(
           [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "stockPrices/{stockSymbol}")] HttpRequest req, string stockSymbol)
{
   string apiKey = "your-api-key";
   var client = new AlphaVantageClient(apiKey);
   var stocksClient = client.Stocks();

   StockTimeSeries stock = await stocksClient.GetTimeSeriesAsync(stockSymbol, Interval.Min60, OutputSize.Compact, isAdjusted: true);

   var query = new Dictionary<string, string>()
   {
       {"symbol", stockSymbol }
   };

   JsonDocument company = await client.RequestParsedJsonAsync(ApiFunction.OVERVIEW, query);

   var stockQuote = new StockPrice {
       OpeningPrice = stock.DataPoints.FirstOrDefault().OpeningPrice,
       ClosingPrice = stock.DataPoints.FirstOrDefault().ClosingPrice,
       HighestPrice = stock.DataPoints.FirstOrDefault().HighestPrice,
       LowestPrice = stock.DataPoints.FirstOrDefault().LowestPrice,
       Time = stock.DataPoints.FirstOrDefault().Time,
       Volume = stock.DataPoints.FirstOrDefault().Volume,
       CompanyName = company.RootElement.GetProperty("Name").GetString(),
       Exchange = company.RootElement.GetProperty("Exchange").GetString(),
       Symbol = company.RootElement.GetProperty("Symbol").GetString()
   };

  
   return new OkObjectResult(stockQuote);

}

The first step is to create an AlphaVantageClient object, which requires the API key we got from the Alpha Vantage portal as initializer. Then, since we want to work with stock prices, we must get a specific client to call the Stocks() function. Getting the prices is quite easy: we use the GetTimeSeriesAsync() method, passing various parameters to customize the output (like the time interval or that we want the most recent prices instead of the whole history). Most importantly, as the first parameter we specify the stock symbol we want to track, which is coming from the URL of the API. In response, we get a StockTimeSeries object, with a collection of DataPoints objects. Each of them represents a stock value on a specific date and time, from the most recent to the oldest one. Our API needs to return the most recent one, so we pick the first item in the collection, and we use some of its properties to populate our StockPrice object.

Getting the information about the company is a bit different, since the AlphaVantage.Net library doesn't include a specific client (and, thus, specific objects) to deal with the Company entity like it does with stocks. As such, we must use the generic method RequestParsedJsonAsync(), to which we pass:

The Alpha Vantage API we want to call, using one of the values of the ApiFunction enumerator. In our case, it's OVERVIEW.
The input parameters for the API, through a Dictionary<string, string> collection. In our case, we must provide only one parameter called symbol with, as value, the stock symbol of the company (again, we're getting this from the API URL).

We get back a JsonDocument object, which isn't strongly typed. As such, we must use the GetProperty() method to get out the values from the JSON. The ones we are interested in are Name, Exchange and Symbol. All of them are strings, so we extract their values by calling GetString(). Thanks to this code, we can extract the information we need to complete our StockPrice object, which we can wrap into an OkObjectResult object and return it. This special ASP.NET object will automatically serialize our StockPrice object, returning an equivalent JSON to the caller.

We can test our work by pressing F5. Visual Studio will launch the local Azure Functions emulator and our API will be hosted locally. To see if it's working, we can use a tool like Postman (or just open your browser) and hit the URL http://localhost:7071/api/stockPrices/{stockSymbol}, replacing {stockSymbol} with the stock symbol of a company, like MSFT or AAPL. If you did everything correctly, you would see a JSON like the following one:

Protecting our API key

The previous code has a flaw: we're keeping the API key in code, which is anything but good practice. First, because if we're hosting our project on a source control repository, everyone who has access to it will be able to see our key. Second, because if at any point in time we must change the API key, we are forced to build and deploy an updated version of our function. Let's improve our code and move the API key into the application settings. However, we aren't going to use the default ones (the ones stored in the local.settings.json file) because also this file must be considered public, and it's typically committed as part of the project on a repository. We're going to use a .NET feature called Secret Manager. The way it works is like a regular settings file: it's a JSON file, in which we can store key / value pairs that are available to the web application. However, this file is stored in a location outside the project, so that it doesn't become part of the files that are included into the repository. What makes it powerful is that this file is completely transparent to us as developers since its content gets merged with the default application settings at runtime. As such, we can read settings from this file using the same exact code we use to read the other application settings.

To start, right click on your project and choose Add → Connected service. Under Service Dependencies, click on the + icon and look for a feature called Secrets.json (local).

Confirm the changes described in the next step and click Finish. This will install a NuGet package called Microsoft.Extensions.Configuration.UserSecrets. Now right click on the project and choose Manage user secrets. This step will do two operations:

A new property will be added to the .csproj file called UserSecretsId. It's a GUID that univocally identifies the secrets of your application.
It will open a file called secrets.json, which is stored in the path %APPDATA%\Microsoft\UserSecrets\<userSecretsId>\.

Let's add our API key in the secrets.json file:

{
  "AlphaVantageApiKey": "your-api-key"
}

Now we must change the code of our Azure Function so that the API key is read from the configuration. As mentioned, we don't have to make many changes, since the secrets are automatically merged into the Azure Functions configuration. All we need to do is to change the public constructor of our function to add a new parameter of type IConfiguration:

private readonly ILogger<StockPricesApi> _logger;
private readonly IConfiguration _configuration;

public StockPricesApi(ILogger<StockPricesApi> log, IConfiguration configuration)
{
    _logger = log;
    _configuration = configuration;
}

Thanks to dependency injection, the runtime will automatically inject into the IConfiguration object all the settings read from the secrets and the application settings. This means that, to get the API key, we just need to change the following line of code from:

string apiKey = "your-api-key";
var client = new AlphaVantageClient(apiKey);
var stocksClient = client.Stocks();

to:

string apiKey = _configuration.GetValue<string>("AlphaVantageApiKey");
var client = new AlphaVantageClient(apiKey);
var stocksClient = client.Stocks();

If you want to test that everything is still working, just press F5 and try to call again the endpoint http://localhost:7071/api/stockPrices/MSFT. You should get a JSON again with all the stock information about Microsoft.

Adding caching

The current implementation works fine, but it has a limit. Every time we invoke the Azure Function, we're calling the Alpha Vantage APIs. If we pause and think to the full context of our solution (displaying the stock price in a Viva Connections card), this means that potentially hundreds or thousands of employees might open the Viva Connections dashboard in a very short time and all of them will try to get a fresh copy of the stock data from the API. This introduces two problems:

One is about performance since we might overload the Alpha Vantage APIs with requests.
One is about API limitation. As we have learned in the beginning of the post, the Alpha Vantage APIs have some limitations (especially in the free tier) when it comes to the number of requests you can make hourly and daily.

To reduce the impact of these two problems, we're going to introduce caching, using the Azure Cache for Redis service, which is one of the most popular solutions to support caching scenarios in your applications. By using this service, we're going to store the most recent stock pricing information into a cache. When the Azure Function gets called, it will try to get the price first from the cache; only if it doesn't exist or if the value is too old, we're going to hit the real Alpha Vantage APIs. Redis is powerful because, other than being simple to use and very efficient, it also takes care automatically of many of the challenges that you must face when you implement a caching mechanism. For example, it automatically manages the cache expiration, by deleting an item once the expiration time you have set has passed.

The easiest way to add caching is to right click again on your project, choose Add → Connected service and, under Service Dependencies, click the + symbol. This time, we're going to pick Azure Cache for Redis.

For this project, we're going to leverage the real Azure Cache for Redis service, so that we can simplify the developer environment. However, if you prefer to work on a completely local and offline solution, you can choose the option Redis Cache on container (local), which will create the Redis cache on a local container. This option requires you to install Docker Desktop, since the container is based on a Docker image.

If you haven't already done it, you will be asked to login with an account which is connected to an Azure subscription. Then click on Create new to start the wizard to create a new instance of the service. Feel free to pick the region, resource group and name you prefer. In terms of SKU, a Basic C0 is good enough for our scenario, since we'll need to store only JSON data. Once you have created and selected the service, Visual Studio will help you to configure your application to connect to it. First, it will add a setting in your configuration called CacheConnection with, as value, the connection string. Since we have already set up the Secrets Manager support, make sure to select Local user secrets file: Secrets.json (local).

Once you complete the wizard, it's time to install a NuGet package that will help us to read and store data into the cache. Right click again on the project, choose Manage NuGet Packages, search for and install a package called StackExchange.Redis. Now we can leverage dependency injection so we can simplify the cache integration in our function. However, to do it, we must customize the initialization process of the Azure Function, which can be achieved by adding a new file to our project called Startup.cs. This is the implementation you must supply:

[assembly: FunctionsStartup(typeof(StockPricesApi.Startup))]

namespace StockPricesApi
{
    public class Startup: FunctionsStartup
    {
        public override void Configure(IFunctionsHostBuilder builder)
        {
           
        }
    }
}

The Startup class must implement a class called FunctionsStartup and, as header, we must use the assembly attribute to declare the definition of the current class as the one to use when the Azure Functions starts up. Inside the Configure() method we have access to the IFunctionsHostBuilder object, which we can use to customize the Azure Functions initialization. Among the various tasks we can perform, we can use it to register new objects in the dependency injection container other than the default ones we have already used (like ILogger and IConfiguration). We can use it to initialize the Redis connection as following:

using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using StackExchange.Redis;

[assembly: FunctionsStartup(typeof(StockPricesApi.Startup))]

namespace StockPricesApi
{
    public class Startup: FunctionsStartup
    {
        public override void Configure(IFunctionsHostBuilder builder)
        {
            var connection = builder.GetContext().Configuration["CacheConnection"];
            var muxer = ConnectionMultiplexer.Connect(connection);
            builder.Services.AddSingleton<IConnectionMultiplexer>(muxer);
        }
    }
}

First, we retrieve the connection string from the CacheConnection entry in the configuration. Then, we create a connection using the ConnectionMultiplexer.Connect() method, passing as parameter the connection string. Finally, we register the connection object in the dependency injection container, by passing it to the builder.Services.AddSingleton<IConnectionMultiplexer>() method.

Now, to access to the cache in our function, we just need to add a new IConnectionMultiplexer parameter to the the initializer of our Function class:

private readonly ILogger<StockPricesApi> _logger;
private readonly IConnectionMultiplexer _redisCache;
private readonly IConfiguration _configuration;

public StockPricesApi(ILogger<StockPricesApi> log, IConnectionMultiplexer redisCache, IConfiguration configuration)
{
    _logger = log;
    _redisCache = redisCache;
    _configuration = configuration;
}

Now we can use the _redisCache object to read and write data against the Azure Cache for Redis service we have just set up. Redis works similarly to the application settings, so using a key / value pair approach. In our case, the key will be dynamic: since the Viva Connections card can be used to display information about any stock, we need to create a different entry in the cache for each stock; the value will be the JSON returned by the Alpha Vantage API for that stock.

Let's see how our function code changes to use the cache:

public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "stockPrices/{stockSymbol}")] HttpRequest req, string stockSymbol)
{
    _logger.LogInformation("C# HTTP trigger function processed a request.");
    _logger.LogInformation($"Requested stock symbol: {stockSymbol}");

    var db = _redisCache.GetDatabase();
    var json = await db.StringGetAsync($"StockPrice-{stockSymbol}");

    StockPrice stockQuote;

    if (string.IsNullOrEmpty(json))
    {
        _logger.LogInformation($"Stock price for {stockSymbol} not available in cache, getting a fresh value");

        string apiKey = _configuration.GetValue<string>("AlphaVantageApiKey");
        var client = new AlphaVantageClient(apiKey);
        var stocksClient = client.Stocks();

        StockTimeSeries stock = await stocksClient.GetTimeSeriesAsync("MSFT", Interval.Min60, OutputSize.Compact, isAdjusted: true);

        var query = new Dictionary<string, string>()
        {
            {"symbol", stockSymbol }
        };

        JsonDocument company = await client.RequestParsedJsonAsync(ApiFunction.OVERVIEW, query);

        stockQuote = new StockPrice {
            OpeningPrice = stock.DataPoints.FirstOrDefault().OpeningPrice,
            ClosingPrice = stock.DataPoints.FirstOrDefault().ClosingPrice,
            HighestPrice = stock.DataPoints.FirstOrDefault().HighestPrice,
            LowestPrice = stock.DataPoints.FirstOrDefault().LowestPrice,
            Time = stock.DataPoints.FirstOrDefault().Time,
            Volume = stock.DataPoints.FirstOrDefault().Volume,
            CompanyName = company.RootElement.GetProperty("Name").GetString(),
            Exchange = company.RootElement.GetProperty("Exchange").GetString(),
            Symbol = company.RootElement.GetProperty("Symbol").GetString()
        };

        var stockQuoteJson = JsonConvert.SerializeObject(stockQuote);
        int cacheExpireInHours = 6;
        await db.StringSetAsync($"StockPrice-{stockSymbol}", stockQuoteJson, TimeSpan.FromHours(cacheExpireInHours));
        _logger.LogInformation($"Json saved into in Redis: {stockQuoteJson}");
    }
    else
    {
        stockQuote = JsonConvert.DeserializeObject<StockPrice>(json);
        _logger.LogInformation($"Stock price for {stockSymbol} retrieved from Redis cache");
        _logger.LogInformation($"Json read from Redis: {json}");
    }

    return stockQuote != null ? new OkObjectResult(stockQuote) : new NotFoundResult();

}

First, we get a reference to the Redis database by calling the GetDatabase() method. Then, from the database, we try to read a value identified by the key StockPrice-{StockSymbol}, where StockSymbol is the symbol of the stock that the user is trying to retrieve. For example, if the API has been called with the endpoint /api/stockPrices/MSFT, the function will look on Redis for an item with key StockPrice-MSFT. The value we're expecting is a JSON string, so we use the StringGetAsync() method. If the value is empty, it means that it hasn't cached before or that the value is expired.

In this case, we proceed with the original code we have previously written, which retrieves the data from the Alpha Vantage API to build a StockPrice object.

The only difference is that, before returning it to the caller, we convert the StockPrice object into a JSON string (using JsonConvert.SerializeObject()) and we store it into the Redis cache by calling StringSetAsync(). As parameters, we pass the key specific for this stock symbol, the JSON string, and the cache expiration. In this case, we're passing a fixed value (6 hours), but you can also turn this parameter into an application setting, so that you can change it at a later stage without redeploying the function. Cache expiration means that Redis will automatically invalidate the value after the time you have specified has passed. In this case, it means that the Azure Function will get a new one from Alpha Vantage the first time the API is called after 6 hours since the data for that stock symbol was originally acquired.

In case, instead, we have a valid value in the cache, we deserialize the JSON back into a StockPrice object and we return it to the caller, without interacting at all with the Alpha Vantage APIs.

That's it. Now if you press F5 and you try again to hit the URL http://localhost:7071/api/stockPrices/MSFT, the first time the JSON payload will come from the Alpha Vantage APIs, while every other call will get the value from the cache.

If you want to check that the Redis data is there (and eventually experiment with it), you can use a tool called Redis Insights, which gives you a UI to explore the content of a Redis cache. Once you have installed it, click on Add Redis database and use the Add Database manually option. Before adding it, however, you must temporarily disable SSL-only support for your Redis cache, otherwise the tool won't be able to connect. To do that, open the Azure portal and look for the Azure Cache for Redis you have previously created from Visual Studio. On the left blade, click on Advanced Settings and set to No the option Allow access only via SSL.

For security reasons, you should change the option back to Yes as soon as you have finished using Redis Insight.

Now you can go back to the Redis Insight and add the connection with the following parameters:

Host: it's the URL of your Redis service, you can get it from the Overview page on Azure.
Port: it's 6379.
Database alias: use the full URL of your Redis service followed by the port (for example, your-service.redis.cache.windows.net:6379).
Username: leave it empty.
Password: use the Primary password that you can find in the Access Keys section on Azure.

Then click Add Redis database. If all the information is correct, you will see your service listed in the main table and, clicking on it, you will see the available data. If you have implemented caching in your Azure Function correctly, you will see an entry with the name StockPrice- followed by the stock symbol you have chosen and, if you click on it, you will see the full JSON from your API:

The tool is helpful also to debug and diagnose the cache, since you can edit and delete the stored value. This way, for example, you can trigger a new Alpha Vantage API request from the Azure Function without having to wait for the cache to expire.

Wrapping up

In this post, we have focused on the backend of our Viva Connections solution to display stock prices. In the next one, we'll complete the project, and we'll build the actual card, which will use the backend we have just built to get the data to display.

You can find the project written so far on GitHub. The project also includes a Bicep template that you can use to deploy on Azure all the required resources (Azure Functions and Azure Cache for Redis) configured in the correct way. We'll talk more about this in the final post of this series.

Happy coding!

Bring the ChatGPT model into our applications

Matteo Pagani — Mon, 13 Mar 2023 15:13:36 GMT

In the first two posts of this series we have developed an Outlook add-in that, using the Open AI models, helps users to generate professional business mails starting from a simple sentence. In the first post, we achieved this goal by directly using the OpenAI APIs; in the second one, instead, we have leveraged the Azure OpenAI service. In both cases, however, we didn't use the model that powers up ChatGPT, because it wasn't available yet at the time of writing, but we leveraged a similar one called Davinci.

Since a few days, both OpenAI and Azure OpenAI have finally made available the ChatGPT model, so that developers can integrate it into their experiences. In the previous posts, we said that the when this would have happened, we wouldn't have needed to change much code, probably just the model's name. This turned out to be partially true: the overall architecture of the add-in is unchanged, but the way you provide the prompt to the ChatGPT model is slightly different than the way you do it with the Davinci one. The different approach comes from the fact that, while Davinci was created mainly for content generation scenarios, ChatGPT targets specifically conversational ones. As such, you must be able to send entire conversations to the API, so that it can gather the required context to handle a conversation without having to specify all the information at each prompt.

In this post, we're going to learn the changes we must make based on the service we're using.

Using ChatGPT with the OpenAI APIs

I've already anticipated this a few days ago, when I updated the original post, but I wanted to consolidate everything in a single article, so let's review the required changes when you want to directly use the OpenAI platform.

OpenAI released the ChatGPT model as gpt-3.5-turbo and the good news is that it's 10 times cheaper than the Davinci one. The model, in fact, is priced $0.002 / 1K tokens, while the Davinci one we have used in the original version of the project is priced $0.0200 / 1K tokens.

Before starting to make the changes which are required to use this model, we must open a terminal on the folder which contains our project and upgrade the OpenAI library with the following command:

npm update openai

This command will install version 3.1.0 of the library, which includes a new API to interact with the ChatGPT model. Now let's take a look at the updated generateText() function which uses this new API:

generateText = async () => {
  var current = this;
  const configuration = new Configuration({
    apiKey: "your-API-key",
  });
  const openai = new OpenAIApi(configuration);
  const response = await openai.createChatCompletion({
    model: "gpt-3.5-turbo",
    messages: [
      {
        role: "system",
        content: "You are a helpful assistant that can help users to create professional business content.",
      },
      { role: "user", content: "Turn the following text into a professional business mail: " + this.state.startText },
    ],
  });
  current.setState({ generatedText: response.data.choices[0].message.content });
};

There are three main differences compared to the previous implementation. The first one is that we have a new API to interact with ChatGPT, called createChatCompletion(), which we must use instead of createCompletion(). The second difference, even if it's a small one, is that we have to change the model name to gpt-3.5-turbo. The third difference is the most important one. To support the conversational scenario, the prompt you pass to the model to generate text isn't based any more on a single sentence, but on on a collection of messages object. Each of them has two properties:

role, which is used to define who generated the prompt. It could be the user, the system or the assistant itself.
content, which is the actual text.

In the code sample, you can see two types of messages: one with system as role, which we're using to instruct the model on the type of outcome we want to achieve (you are an assistant that can generate business content); one with user as role, which is instead the actual ask (turn the following text into a business mail).

This scenario might not be the best one to explain this approach, since we're using ChatGPT to generate content and not to handle a conversation. Let's see another example taken from the documentation, which should be more helpful to better understand how it works.

const response = await openai.createChatCompletion({
     model: "gpt-3.5-turbo",
     messages: [
       {"role": "system", "content": "You are a helpful assistant."},
       {"role": "user", "content": "Who won the world series in 2020?"},
       {"role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020."},
       {"role": "user", "content": "Where was it played?"}
     ],
   });

As we mentioned, ChatGPT is born to support conversational scenarios, however the conversation history isn't managed by OpenAI, but it must be managed by the developer. This means that we must use the messages collection to provide the whole history, including the messages generated by ChatGPT using assistant as a role. This way, the model is able to provide an answer to the last question (Where was it played?) even if it doesn't include the full context.

However, even if we aren't in a conversational scenario, ChatGPT is very powerful and works great for content creation. Additionally, the ChatGPT model is much cheaper than the Davinci one, so it's great fit for our Outlook add-in.

Using ChatGTP APIs with Azure Open AI

Since a few days Microsoft has announced the public preview of ChatGPT inside Azure Open AI. This means that, if you have been approved to use the Azure Open AI service (see my previous post for more details on the approval process), now you can head to the Model deployments section and, in the dropdown, you will see a new option called gpt-35-turbo.

Please note: make sure that your service instance is deployed in East US. At the time of writing, this is the only region where the ChatGPT model is available.

From a code perspective, working with Azure OpenAI requires less changes compared to the OpenAI APIs, since the format is the same. You must submit a HTTP POST request to the openai/deployments/{deploymentName}/completions?api-version=2022-12-01 URL, prefixed by the URL of your instance. Inside the HTTP request, you must provide the API key as header and the payload with the prompt you want to submit as body. The main difference is the way you create the prompt. Azure OpenAI follows the same conversational approach we have seen with OpenAI but, instead of using a collection of messages, it uses a single message with special placeholders to define the history. Let's look at the updated version of the generateText() function:

generateText = async () => {
  var current = this;

  const apiKey = "your-api-key";
  const endpoint = "your-url";
  const prompt =
    "<|im_start|>system\nThe system is an AI assistant that helps people to write professional business mails.\n<|im_end|>\n<|im_start|>user\nTurn the following text into a professional business mail: " +
    this.state.startText +
    "\n<|im_end|>\n<|im_start|>assistant";
  const deploymentName = "your-deployment-name";

  const url = endpoint + "openai/deployments/" + deploymentName + "/completions?api-version=2022-12-01";

  const payload = {
    prompt: prompt,
    max_tokens: 1000,
  };

  var response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "api-key": apiKey,
    },
    body: JSON.stringify(payload),
  });

  var data = await response.json();
  current.setState({ generatedText: data.choices[0].text });
};

As you can see, the code to perform the HTTP request is the same, including the way we handle the response. However, the prompt property of the payload combines multiple prompts, which are delimited by the <|im_start|> and <|im_end|> placeholders. After the <|im_start|> placeholder, before including the actual prompt, we specify who generated it, using keywords like system, user or assistant. The prompt ends with an open sentence: the <|im_start|> placeholder, followed by the assistant role. By not closing it, we tell Azure Open AI that we want the AI model to take the input we have provided and use it to generate something for us. If you want to know more details on how to work with this model, you can read this good article from the official documentation.

The downside of this approach is that it make slightly more complicated the prompt generation compared to Open AI. The good news, however, is that you won't have to change much your code to use the ChatGPT model, while Open AI requires more work on the code.

Wrapping up

The advent of ChatGPT is a game changer in the AI ecosystem, since it opens new and exciting scenarios to change the way we work, and we create content. Thanks to OpenAI and Azure OpenAI, now we can bring the power of this model right into our applications. And if we have already built experiences using the Davinci model, like our business mail generator, moving to ChatGPT is quite simple, as we have learned in this post.

As usual, you can find the source code of the project on GitHub.

ServiceNow with Microsoft Teams Approvals Part 2 - HTTP Trigger

luisdem — Mon, 17 Apr 2023 14:03:06 GMT

As more and more organizations move towards remote work, communication and collaboration tools have become essential for seamless and efficient workflows. Microsoft Teams is one such tool that allows teams to communicate, collaborate, and stay productive from anywhere. Teams Approvals is a feature within Microsoft Teams that enables users to create, manage, and track approvals directly within Teams. On the other hand, ServiceNow is a powerful platform for managing workflows, incidents, and service requests. Integrating Teams Approvals with ServiceNow can streamline approval processes and improve overall efficiency.

There are different ways to implement this integration, in the first part of the post, we saw how we could integrate ServiceNow with Microsoft Teams Approvals to simplify the approval process for ServiceNow change requests.

In this second part of the post, we will explore how we can create a custom HTTP trigger in Power Automate to allow ServiceNow to trigger the approval process in Microsoft Teams. This will enable us to automate the approval process even further and integrate it with other systems that may not be directly connected to ServiceNow.

By the end of this post, you'll have a better understanding of how to integrate Microsoft Teams Approvals with ServiceNow and the benefits it can bring to your organization.

Prerequisites

ServiceNow Environment

Microsoft Teams

Go to the Microsoft Teams website (https://www.microsoft.com/en-us/microsoft-teams/group-chat-software) and click on the "Sign up for free" button.
Enter your email address and click on "Next". If you already have a Microsoft account, you can sign in with that account.
Create a new password and click on "Sign up".
Follow the prompts to complete the setup process, such as entering your name and company information.
Once your account is set up, you can download the Microsoft Teams app on your desktop or mobile device and start collaborating with your team.

Power Automate Environment

Scenarios

First, ensure that you have a valid account for both Microsoft Teams and ServiceNow, as well as access to Power Automate.

1. Scheduled Trigger

This scenario is available in the first part of this post.

2. Http Trigger

HTTP triggers are a powerful feature in Power Automate that allows us to create custom APIs and automate processes with external systems. By creating a custom HTTP trigger, we can make the approval process more flexible and scalable, and enable other systems to interact with Microsoft Teams Approvals without having to go through ServiceNow.

Here's a scenario on how to integrate Microsoft Teams Approvals with ServiceNow using Power Automate's scheduled trigger:

Open a web browser and go to the Power Automate portal.
Sign in to Power Automate using your Microsoft account or organizational account.
Once you're signed in, you should see the Power Automate portal dashboard. On the left-hand menu, click on "Create" to create a new flow.
Choose a template from the available options, or start from scratch by selecting "Instant - from blank".

Give your flow a name, such as Pending Approvals via ServiceNow. Choose the When an HTTP request is received as the trigger, and click on Create.

To set up the "When a HTTP request is received" trigger, we need to define the input parameters that will be sent via a rule from ServiceNow (we will create this rule later).

Click on the "When a HTTP request is received" trigger to select it. Paste the following Request Body JSON Schema that will be sent by ServiceNow into the text box:

{
    "type": "object",
    "properties": {
        "sysapproval": {
            "type": "string"
        },
        "sys_id": {
            "type": "string"
        },
        "due_date": {
            "type": "string"
        },
        "sys_created_by": {
            "type": "string"
        },
        "approver": {
            "type": "string"
        },
        "short_description": {
            "type": "string"
        },
        "description": {
            "type": "string"
        },
        "opened_by": {
            "type": "string"
        },
        "approver_email": {
            "type": "string"
        },
        "requestor_email": {
            "type": "string"
        },
        "link_details": {
            "type": "string"
        }
    }
}

The next step is sending the approval request to Microsoft Teams Approvals app.

Add a new action after the "When a HTTP request is received" step. In the search box, type "Approvals" and select the Start and wait for an approval:

Select Approve/Reject - Everyone must approve for the Approval type field.
Set up the mapping between the ServiceNow data fields and the corresponding fields in the Power Automate action:

Field	Value
Title	short_description
Assigned to	approver_email
Details	description
Item link	link_details
Item link description	ServiceNow more detail

Add a new action after the "Start and wait for an approval" step. In the search box, type "Control" and select the Condition control:

Inform the value Outcome from the Start and wait for an approval step and the value Approve:

Add a new action for the If yes step. In the search box, type "ServiceNow" and select the Update Record control:

This action will update the corresponding approval records in ServiceNow with the latest information retrieved from Microsoft Teams.

In the Record Type field, make sure to select the second "Approval" item in the dropdown list, which corresponds to the "approval" table from production environment and not the first one which is for the staging environment.
In the System ID field, select the sys_id from the When a HTTP request is received step.

In the Comments field, select the Responses Comments from the Start and wait for an approval step.
In the State field, inform the value approved.

Repeat the steps 12-16, but add the new action inside the If not step and the value rejected for the State field.

Save the flow.

Note that when you save your trigger, you will be given a URL that you can use to invoke the trigger from external systems.

Set up ServiceNow Business Rule

Business Rules are server-side logic that execute when database records are queried, updated, inserted, or deleted. For more details, please check the ServiceNow Business Rules documentation.

To set up a ServiceNow Business Rule to send a request to Microsoft Power Automate every time there is a new pending approval, you can follow these general steps:

Navigate to the Business Rules module in ServiceNow. This can be done by typing "Business Rules" in the navigation bar and selecting the appropriate option.

Click the "New" button to create a new business rule:

Give the business rule a name and description that accurately describes its purpose. For example, MS Approvals.
Choose the table to which the business rule applies. This can be done by selecting the table from the drop-down menu in the "Applies to" field. For example, Approval [sysapproval_approver].
Specify the conditions that must be met for the business rule to run. This is done by adding conditions to the "When to run" section of the business rule. For example, you could specify that the rule should run after a new record is created or updated.
Add a filter condition to consider only pending approvals (state is requested).

Click on the Advanced tab to define the actions that the business rule should take when it runs. This is done by adding script to the "Script" section of the business rule. The script can be written in JavaScript and can perform a variety of actions, such as updating a field, sending an email notification, or creating a related record.

It's important to note that creating a business rule in ServiceNow requires some knowledge of JavaScript and the ServiceNow platform. If you're not familiar with these concepts, it may be helpful to seek assistance from a ServiceNow administrator or developer.

Add the following code:

(function executeRule(current, previous) {
	
	var snowURL = "https://dev128124.service-now.com/";
	var sysapproval = current.getValue("sysapproval");
	var approver = current.getValue("approver");
	var openedBy;
	
	var jsonTask ;
	var jsonApprover ;
	var jsonRequestor ;

    //this isnt the best practice. Consider change it to oauth2 authentication
	var user = 'CHANGE THIS VALUE';
	var password = 'CHANGE THIS VALUE';
	
	//GET TASK with the details of the pending approval 
	
	var taskRequest = new sn_ws.RESTMessageV2();
	
	taskRequest.setBasicAuth(user,password);
	taskRequest.setRequestHeader("Accept","application/json");
	taskRequest.setRequestHeader('Content-Type','application/json');
	
	taskRequest.setEndpoint(snowURL + "api/now/table/task?sysparm_query=sys_idIN" + sysapproval + "&sysparm_exclude_reference_link=true&sysparm_fields=number%2Cshort_description%2Copened_by%2Csys_id%2Cimpact%2Copened_at%2Cpriority%2Cdescription");

	taskRequest.setHttpMethod("GET");		
	
	var responseTask = taskRequest.execute();

	var taskBody = responseTask.getBody();

	jsonTask = new JSONParser().parse(taskBody);

	openedBy = jsonTask.result[0].opened_by;
	
	//GET APPROVER EMAIL that will be used to send the card to Teams Approvals
	
	var approverRequest = new sn_ws.RESTMessageV2();
	
	approverRequest.setBasicAuth(user,password);
	approverRequest.setRequestHeader("Accept","application/json");
	approverRequest.setRequestHeader('Content-Type','application/json');
	
	approverRequest.setEndpoint(snowURL + "api/now/table/sys_user?sysparm_query=sys_idIN"+ approver +"&sysparm_fields=sys_id,name,email");

	approverRequest.setHttpMethod("GET");		
	
	var responseApprover = approverRequest.execute();

	var approverBody = responseApprover.getBody();

	jsonApprover = new JSONParser().parse(approverBody);

	//GET REQUESTOR EMAIL that will be used on Teams Approvals card
	var requestorRequest = new sn_ws.RESTMessageV2();
	
	requestorRequest.setBasicAuth(user,password);
	requestorRequest.setRequestHeader("Accept","application/json");
	requestorRequest.setRequestHeader('Content-Type','application/json');
	
	requestorRequest.setEndpoint(snowURL + "api/now/table/sys_user?sysparm_query=sys_idIN"+ openedBy +"&sysparm_fields=sys_id,name,email");

	requestorRequest.setHttpMethod("GET");		
	
	var requestorResponse = requestorRequest.execute();

	var bodyRequestor = requestorResponse.getBody();

	jsonRequestor = new JSONParser().parse(bodyRequestor);

	//CALL POWER AUTOMATE TO SEND TO TEAMS APPROVALS
    try {

		var body = {
				"sysapproval": sysapproval,
				"sys_id": current.getValue("sys_id"),
				"due_date": current.getValue("due_date"),
				"sys_created_by": current.getValue("sys_created_by"),
				"approver": approver,
				"short_description": "" + jsonTask.result[0].short_description,
				"description": "" + jsonTask.result[0].description,
				"opened_by": "" + openedBy,
				"approver_email": "" + jsonApprover.result[0].email,
				"requestor_email": "" + jsonRequestor.result[0].email,
				"link_details" : snowURL + "now/nav/ui/classic/params/target/sysapproval_approver.do%3Fsys_id%3D" + current.getValue("sys_id")
		};
		
        var r = new sn_ws.RESTMessageV2();
        
        // Change the following URL by the one you have created as HTTP trigger on Power Automate
		r.setEndpoint("https://xxx.westus.logic.azure.com:443/workflows/xxxxxxxx56f6/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=EKb91O-VP86wsFeP144H63-vZHK8XFpcuu7HLHc7DEM");
		
		r.setHttpMethod("POST");
        r.setRequestBody(JSON.stringify(body));
	
		r.setRequestHeader("Accept","application/json");
		r.setRequestHeader('Content-Type','application/json');
      
        var response = r.execute();
        var httpStatus = response.getStatusCode();
		
    } catch (ex) {
        var message = ex.message;
		gs.error("Error message: " + message);
    }

    gs.info("Webhook target HTTP status response: " + httpStatus);
  
    
})(current, previous);

Click on Submit to save it.

To get to the list of pending approvals in ServiceNow:

In the navigation bar at the top of the screen, click on the "My Approvals" link. This will take you to the "My Approvals" page.

On the "My Approvals" page, you should see a list of all of your pending approvals. This list will include the details of each approval request, such as the name of the item being approved, the requester, and the date the request was submitted.

In case you can't see any pending approval, consider removing the filter on the top of the page by clicking on All.

To view the details of a specific approval request, click on the request in the list. This will take you to the approval form, where you can review the details of the request. Change the status to Requested and click on Update.

Switch back to Microsoft Teams and observe that your pending approval request is there:

Integrating ServiceNow with Microsoft Teams Approvals via Power Automate

luisdem — Mon, 17 Apr 2023 14:03:56 GMT

Summary
- Prerequisites
- Scenarios
  - Scheduled Trigger
  - HTTP Trigger

Integrating ServiceNow with Microsoft Teams Approvals via Power Automate

There are different ways to implement this integration, but in this post, we will discuss two scenarios. The first scenario involves setting up a scheduler trigger on Power Automate to retrieve pending approvals from Teams Approvals and update them in ServiceNow. The second scenario involves receiving pending approvals directly in ServiceNow and updating them accordingly. By the end of this post, you'll have a better understanding of how to integrate Microsoft Teams Approvals with ServiceNow and the benefits it can bring to your organization.

Prerequisites

Service Now Environment

Microsoft Teams

Go to the Microsoft Teams website (https://www.microsoft.com/en-us/microsoft-teams/group-chat-software) and click on the "Sign up for free" button.
Enter your email address and click on "Next". If you already have a Microsoft account, you can sign in with that account.
Create a new password and click on "Sign up".
Follow the prompts to complete the setup process, such as entering your name and company information.
Once your account is set up, you can download the Microsoft Teams app on your desktop or mobile device and start collaborating with your team.

Power Automate Environment

Scenarios

First, ensure that you have a valid account for both Microsoft Teams and ServiceNow, as well as access to Power Automate.

1. Scheduled Trigger

Here's a scenario on how to integrate Microsoft Teams Approvals with ServiceNow using Power Automate's scheduled trigger:

Open a web browser and go to the Power Automate portal.
Sign into Power Automate using your Microsoft account or organizational account.
Once you're signed in, you should see the Power Automate portal dashboard. On the left-hand menu, click on "Create" to create a new flow.
Choose a template from the available options, or start from scratch by selecting "Instant - from blank" or "Scheduled - from blank" depending on whether you want to trigger the flow manually or automatically at a scheduled time.

Give your flow a name, such as "Get pending approvals from ServiceNow". Set the trigger to run at a suitable interval, such as every 30 minutes, and click on Create.

Next, click on +New step to add a new actions to your flow:

In the search bar, type "ServiceNow" and select the "ServiceNow" connector from the list of available connectors. Choose the appropriate action from the ServiceNow connector, in this case, the "List Records" connector:

If this is your first time using the ServiceNow connector, you will be prompted to sign in to your ServiceNow account. Enter your ServiceNow instance name, username, and password to authenticate the connection.

The "Instance name" field should contain the name of your ServiceNow instance, such as "myinstance.service-now.com". The "Username" and "Password" fields should contain your ServiceNow login credentials.

Select the second Approval item from the Record Type tables in ServiceNow. This will enable you to retrieve pending approvals from the sysapproval_approver table instead of the sc_ic_aprvl_defn_staging one.

In case you want to know more about the ServiceNow tables, ServiceNow provides the REST API Explorer, which is a web-based tool that allows you to explore and test the ServiceNow REST APIs. You can use the REST API Explorer to understand the different REST APIs provided by ServiceNow and how to use them to perform various operations on your ServiceNow instance. It is available within your ServiceNow instance under the "System Web Services" menu.

Click on the Show advanced options item and set the query to filter the results to only include pending approvals in the "requested" state that were created within the last 30 minutes (the same interval from our Schedule trigger).

This is the query value: state=requested^sys_updated_on>@{getPastTime(30,'Minute','yyyy-MM-ddTHH:mm:ss')}

Click on the three dots (...) in the top right corner of the "List Records" step to access the dropdown menu. Select Rename, and in the "Rename step" dialog box, enter "Get pending approvals" as the new name for the step.

Add a new step after the "Get pending approvals" step. In the search box, type "apply" and select the "Apply to each" control connector.

In the "Select an output from previous steps" box, select the value result from the "Format pending approval result" step.
Click on the "Add an action" button to add a new action to the step.
In the search bar, type "ServiceNow" and select the "ServiceNow" connector from the list of available connectors. Choose the "Get Record" connector:

This step is needed to get the details about the approval, like short description, description and opened by.

In the Record Type field, make sure to select the second "Task" item in the dropdown list, which corresponds to the "task" table and not the first table which is for the staging environment:

In the System ID field, select the value Approval for.
Click on the three dots (...) in the top right corner of the "Get Record" step to access the dropdown menu. Select Rename, and in the "Rename step" dialog box, enter "Get Task Detail" as the new name for the step.
Click on the "Add an action" button to add a new action to the step. This step is to get the approver email.
In the search bar, type "ServiceNow" and select the "ServiceNow" connector from the list of available connectors. Choose the "Get Record" connector.
In the Record Type field, make sure to select the second "User" item in the dropdown list, which corresponds to the "user" table and not the first one which is for the staging environment.

In the System ID field, select the value Approver.
Click on the three dots (...) in the top right corner of the "Get Record" step to access the dropdown menu. Select Rename, and in the "Get Approver email" dialog box, enter "Get Task Detail" as the new name for the step.
Repeat the steps 19-21 to get the requestor email.
In the System ID field, select the value Opened By.

Click on the three dots (...) in the top right corner of the "Get Record" step to access the dropdown menu. Select Rename, and in the "Get Requestor email" dialog box, enter "Get Task Detail" as the new name for the step.

Follows the expected result:

The next step is sending the approval request to Microsoft Teams Approvals app.

Add a new action after the "Get Requestor email" step, but yet inside the Apply to each loop. In the search box, type "Approvals" and select the Start and wait for an approval:

Select Approve/Reject - Everyone must approve for the Approval type field.
Select the Short description for the title, the approver email for the Assigned to field and the description for the details field.

Add a new action after the "Start and wait for an approval" step, but yet inside the Apply to each loop. In the search box, type "Control" and select the Condition control:

Inform the value Outcome from the Start and wait for an approval step and the value Approve:

Add a new action for the If yes step. In the search box, type "ServiceNow" and select the Update Record control:

This action will update the corresponding approval records in ServiceNow with the latest information retrieved from Microsoft Teams.

In the Record Type field, make sure to select the second "Approval" item in the dropdown list, which corresponds to the "approval" table from production environment and not the first one which is for the staging environment.
In the System ID field, select the Sys ID from the Get pending approvals step.
In the Comments field, select the Responses Comments from the Start and wait for an approval step.
In the State field, inform the value approved.
Repeat the steps 32-35, but add the new action inside the If not step and the value rejected for the State field.

Save the flow and enable it to run at the scheduled interval you specified.

As approvals are requested and processed in Microsoft Teams, the scheduled flow will retrieve the pending approvals and update the corresponding records in ServiceNow.

Access Microsoft Teams, open the Approvals App and observe that ServiceNow pending approvals will be there:

2. Http Trigger

This topic is covered in the part 2.

Related - Azure App Logic and Adaptive Card solution

The following article demonstrates how to use Logic Apps (or Power Automate) to detect approval requests on ServiceNow and enable approvers to approve or reject requests directly from Teams via Adaptive Cards and Logic Apps.

Furthermore, the fact that this solution does not require premium connectors and only requires user access that is cheap is a significant advantage. This means that even smaller organizations with limited budgets can benefit from this solution and automate their approval processes without having to invest heavily in expensive tools and software. Overall, this solution seems like an excellent way to automate approval processes and improve the efficiency of organizational workflows.

Integrating ServiceNow and Teams with Logic Apps – Approvals

Bringing Open AI into an Outlook add-in: moving to Azure Open AI

Matteo Pagani — Fri, 17 Feb 2023 18:49:06 GMT

In the previous post we have learned how to use AI to help users write better business mails. We developed an add-in for Outlook that, using the AI models and the APIs provided by Open AI, can generate a business mail starting from one or two sentences and, using the Office SDK, to include it into the body of the mail.

For this sample project, we have directly leveraged the APIs provided by Open AI. We created an account on their website and we obtained an API key required to manage the authentication.

But what if you're an enterprise customer and you're already using Azure to host many of your applications and services? It would be great if there was a way to use the powerful models of Open AI, but leveraging at the same time the security, privacy and billing provided by Azure.

Well, actually, this way exists and it's the Azure Open AI service, which is part of the Cognitive Services family. Thanks to a partnership between Open AI and Microsoft, the same exact models that you can use with the Open AI APIs are available on Azure. The way they work is very similar, but the main difference is that the whole hosting infrastructure will be provided by Azure, with all its benefits around scaling and security.

In this post we're going to replace the Open AI API implementation we did the last time with a new one based on Azure Open AI. Let's start!

Getting access to Azure Open AI

The starting point is, of course, to have an Azure subscription. However, wait before you rush into code, because there's a catch, even if for a very good reason. Microsoft is pushing for a responsible and ethical approach on AI, to avoid many of the misuses and biases of this technology.

As such, before you go and create a new Azure Open AI service on your tenant, you must submit a nomination form and provide some important information, like who you are, what you're trying to build, the company you're working for, the ID of the subscription where you would like to host the service and so on. Once you have submitted the form, you will get a response within 10 days. If the request is approved, you will be able to open the Azure portal and start creating new instances of the Azure Open AI service.

The service creation is quite simple, since you don't have many options: you choose the subscription, the resource group, the location, the pricing tier and the name.

Once the service has been created, you can deploy one or more AI models, based on the scenario you're building. Move to the Model deployments section and click Create. Give it a name and, under the Model dropdown, you will find an extensive list of the available Open AI models. Choose text-davinci-003, which is the same one we have used in the previous post.

This is all we need to do to start using the model in your application.

Using the model from code

Using the model we have just deployed is quite simple since we just need to perform a HTTP request against the endpoint of our Azure Open AI instance. We're going to work on the taskpane implementation, specifically in the App.tsx file which contains the whole logic implementation. In the App component, we have created in the previous post a function called generateText(), which passes the text provided by the user to the Open AI APIs using the Open AI JavaScript library.

Let's see the new implementation that, instead, connects to the Azure Open AI service we have just deployed:

generateText = async () => {
  var current = this;

  const apiKey = "your-api-key";
  const endpoint = "your-url";
  const prompt = "Turn the following text into a professional business mail: " + this.state.startText;
  const deploymentName = "your-deployment-name";

  const url = endpoint + "openai/deployments/" + deploymentName + "/completions?api-version=2022-12-01";

  const payload = {
    prompt: prompt,
    max_tokens: 1000,
    temperature: 0.7
  };

  var response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "api-key": apiKey,
    },
    body: JSON.stringify(payload),
  });

  var data = await response.json();
  current.setState({ generatedText: data.choices[0].text });
};

In the beginning of the function, we initialize all the information we need to connect to our instance of Azure Open AI:

apiKey, which can be retrieved from the Azure portal, under the Keys and Endpoint section. Copy the value of KEY 1 and paste it inside the apiKey constant.

Please note: like for the Open AI APIs, we're using this approach just for testing purposes. It isn't suggested to do this in production, since we would easily expose the API key. The suggested way is to build a middleware between Azure Open AI and your add-in (like an Azure Function) and use Azure Key Vault to protect your API key.
endpoint, which is the URL of your Azure Open AI instance. You can find it in the Keys and Endpoints section as well.
prompt, which is the text we want to pass to Azure Open AI. In our case, it's the prompt that describes the outcome we want to achieve (Turn the following text into a professional business mail), followed by the text typed by the user, which is stored in the component's state.
deploymentName, which is the name we have chosen when we have deployed the model.

The next step is to build the full URL we need to reach to communicate with Azure Open AI, which has the following format:

https://your-endpoint.openai.azure.com/openai/deployments/your-deployment/completions?api-version=2022-12-01

The request is sent using a HTTP POST, so we need to create a JSON payload to include in the body with the inputs. The only required one is prompt, with the text we want to process; in our example, we are also passing max_tokens, to specify the maximum length of the text we want to get back, and the temperature (see the previous post for an explanation on this value). You can find the complete list of the supported body parameters in the official documentation. In most cases, there's a 1:1 match between the Open AI and the Azure Open AI parameters format.

Finally, we can submit the HTTP request using the standard fetch() API. Since it's not a standard GET operation, we need to pass some extra parameters other than the URL:

method, which is POST.
headers, since we need to add an extra header called api-key with the API key we have retrieved from the Azure portal.
body, which is the payload we have previously created transformed into JSON with the JSON.stringify() function.

The API will return a response like the following one:

{
    "id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
    "object": "text_completion",
    "created": 1646932609,
    "model": "ada",
    "choices": [
        {
            "text": ", a dark line crossed",
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ]
}

You can notice how this is the same exact format of the standard Open AI APIs we have used in the previous post. As such, we can retrieve the text generated by Open AI from the text property of the first item in the choices collection. The rest of the code is the same as the one we have seen in the previous post. We store the generated text into the component's state, so that it can be displayed in the second box. This way, the user will have the chance to edit it and then copy it inside the body's mail.

Wrapping up

In this post, we have learned how we can leverage the power of the Open AI models through Azure, which might be a better option for developers and companies who have already invested into this platform and already trust Microsoft. The work we have done has been quite easy: thanks to the simplicity of the Azure Open AI APIs and the compatibility with the Open AI ecosystem, we have been able to reuse most of the code and the models we have already learned in the previous post.

You can find the updated sample in the same GitHub repository, but on a different branch called azure-openai.

Happy coding!

Bringing OpenAI into an Outlook add-in: a business mail generator

Matteo Pagani — Tue, 07 Mar 2023 19:31:53 GMT

[Updated on 7th March 2023]

Open AI has made the ChatGPT model available through its APIs. The model is called gpt-3.5-turbo and the good news is that it's 10 times cheaper than the Davinci one. The model, in fact, is priced $0.002 / 1K tokens, while the Davinci one we have used in the original version of the project is priced $0.0200 / 1K tokens.

However, the way this model can be used in your applications is slightly different than the one we have used in the post to leverage the Davinci model. Let's look at how the generateText() function must be changed to use ChatGPT. But before, we must open a terminal on the folder which contains our project and upgrade the OpenAI library with the following command:

npm update openai

This command will install version 3.1.0, which includes a new API to interact with the ChatGPT model. Let's look at the complete code:

generateText = async () => { var current = this; const configuration = new Configuration({ apiKey: "your-API-key", }); const openai = new OpenAIApi(configuration); current.setState({ isLoading: true }); const response = await openai.createChatCompletion({ model: "gpt-3.5-turbo", messages: [ { role: "system", content: "You are a helpful assistant that can help users to create professional business content.", }, { role: "user", content: "Turn the following text into a professional business mail: " + this.state.startText }, ], }); current.setState({ isLoading: false }); current.setState({ generatedText: response.data.choices[0].message.content }); };

The first difference is that we have a new API to interact with ChatGPT, called createChatCompletion(), which we must use instead of createCompletion().

The second difference, even if it's a small one, is that we have to change the model name to gpt-3.5-turbo.

The third difference is the most important one. The prompt you pass to the model to generate text isn't based any more on a single sentence, but on on a collection of messages object. Each of them has two properties:

role, which is used to define who generated the prompt. It could be the user, the system or the assistant itself.
content, which is the actual text.

In the code sample, you can see two types of messages: one with system as role, which we're using to instruct the model on the type of outcome we want to achieve (you are an assistant that can generate business content); one with user as role, which is instead the actual ask (turn the following text into a business mail).

There's another reason why this model requires a collection of messages, instead of a single prompt like with Davinci. ChatGPT is born to support conversational scenarios, so that the user can interact with the AI without specifying the full context each time, like you would do with a human. However, the conversation history isn't managed by OpenAI, but it must be managed by the developer. In our scenario, we don't have to do this: we aren't using ChatGPT to have a conversation, but to generate a text to include in our mail, so we don't have to change the way the Outlook add-in works. In a conversational scenario, however, we would need to use the messages collection to provide the whole history, so that the model can infere the context. The following example from the official documentation will help you to understand better this concept:

const response = await openai.createChatCompletion({ model: "gpt-3.5-turbo", messages: [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Who won the world series in 2020?"}, {"role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020."}, {"role": "user", "content": "Where was it played?"} ], });

Other than the messages generated by the user, we pass back also the messages generated by ChatGPT using assistant as role. This way, the model is able to get the whole context and provide an answer to the last question (Where was it played?).

The source code on GitHub has been updated to use the new model.

The original post starts here

The tech world has always shown a lot of interest in Artificial Intelligence, especially in the last years. However, recently, interest has started to spread also outside the tech enthusiast bubble. Dall-E, the model developed by OpenAI to create images, started to give a new meaning to "generative AI", showing the capabilities of these new powerful AI models. But it's ChatGPT that really ignited the interest, by providing a conversational model that it's very close to the human one and that, most of all, can help you accomplishing many tasks: it can make searches, it can relate content together, it can generate summaries or lists, it can create stories, etc.

A few days ago, Microsoft demonstrated how ChatGPT isn't just a "toy" to play with, by announcing a new shift of the search experience with the integration of a conversational and content generation experience into Bing and Edge. AI becomes a copilot, that can assist you during your daily tasks and help you to be more productive and, as the new Microsoft mission states, "do more with less". And I'm sure, in the coming months, we'll see even more integrations; some of them have already been announced, like the ones in Teams and Viva Sales.

So, why don't we get ahead of the game and we start to play with the possibilities of using AI to improve productivity? In this blog post we'll combine the best of both worlds: the productivity offered by the Microsoft 365 ecosystem and the content generation capabilities of the latest AI models. We're going to build an Outlook add-in that, through OpenAI APIs, will help people to craft professional business mails from one or two sentences. We aren't going to use the real ChatGPT model, since it isn't available for public consumption yet, but we're going to use one of the many powerful GPT models offered by OpenAI. The goal of this blog post is to help you understand the capabilities of these models and the basic steps to integrate them. Once ChatGPT will be available (directly through Open AI or using another provider, like Azure Open AI, you will just need to swap the model (or the API implementation), but the basic architecture will stay the same.

Let's start!

Create the Outlook add-in

We're going to create the Outlook add-in using the new web-based model, so you will need the following tools installed on your machine:

The latest LTS version of Node.js.
Visual Studio Code
The Yeoman generator for Office add-ins.

Once you have all the requirements, open a terminal and run the following command:

yo office

Please note: since it's web based development, you might be tempted to work on this project using the Windows Subsystem for Linux, which typically delivers better performances, especially on the file system. However, if you want to have a good debugging experience, it's better to create the project in Windows, so that you'll be able to debug the add-in using Outlook for desktop.

You will be guided through a series of steps to scaffold the starting template for the project. Use the following settings:

Choose a project type: Office Add-in Task Pane project using React framework (here actually you can pick up the framework you prefer, but since React is the one I know better I'm going to use this template for this post).
Choose a script type: TypeScript (also in this case you can pick up the language you prefer, but I highly suggest TypeScript for everything that is nothing more than a "hello world" in the web ecosystem).
What do you want to name your add-in?: Give it a meaningful name, like "Outlook AI Mail generator".
Which Office client application would you like to support?: Outlook

Now the tool will scaffold the basic template and it will run npm install to restore all the dependencies. At the end of the process, you will find in the current folder a subfolder with the same name of the add-in you picked up during the wizard. Just open it with Visual Studio Code to start the coding experience.

The Outlook add-in template contains two basic implementations of the two scenarios supported by Office add-ins:

Task pane. The task pane is a HTML page that is displayed inside a panel placed on the right of the screen inside the application. The user can interact with the page and, through the Office SDK, perform operations that can interact with the context.
Commands. These are operations that don't require any UI interaction. You click on a button and an operation is performed. Also in this case, through the Office SDK you can retrieve the context and operate on it. For example, you can select some text in the mail body and the command is able to read it.

We're going to support both approaches, so that you can pick the one you like better.

For the taskpane, this is the final look & feel we're going to achieve:

The user will specify the text he wants to turn into a business mail in the first box. By pressing the Generate Text button, we're going to invoke the Open AI APIs, passing a prompt followed by the input text. The result returned by the API will be displayed in the second box. Users will have the chance to adjust and then, once they're done, they can click the Insert into mail button, which will use the Office APIs to include the text in the mail's body.

For the command, instead, we don't really have a user interface, just a button available in our ribbon:

The logic, however, is the same as the taskpane. The only difference is that the input text to process through Open AI won't be typed by the user in a dedicated box, but directly in the mail's body. Using the Office APIs, we'll retrieve the body and pass it to the Open AI APIs. Then, the result will be automatically pasted back into the body.

Now that we have a better idea of the result, let's start to work!

Configuring the manifest

An Office add-in includes a file called manifest.xml, which describes it: the name, the publisher, the supported actions, etc. Before we start working on the code, we must make some changes. Some of them are purely cosmetic. For example, you can use the DisplayName property to change the name of the add-in that will be displayed to the user inside Outlook; or the IconUrl one to change the icon.

A particularly important section, however, is the one called MailHost, which describes where and how the add-in will be integrated inside the Outlook surface. By default, the template includes the following extension point:

<ExtensionPoint xsi:type="MessageReadCommandSurface">

This means that the add-in will be integrated in the reading experience: you'll be able to invoke it when you're reading a mail. This isn't our scenario, however. We want this add-in to help us in writing a new mail, so we must change this value as in the following snippet:

<ExtensionPoint xsi:type="MessageComposeCommandSurface">

Finally, we can customize the section inside the ShortStrings element to change the labels that are associated to the buttons:

<bt:ShortStrings>
  <bt:String id="GroupLabel" DefaultValue="AI Generator Add-in"/>
  <bt:String id="TaskpaneButton.Label" DefaultValue="Business mail AI generator"/>
  <bt:String id="ActionButton.Label" DefaultValue="Generate business mail"/>
</bt:ShortStrings>

Now we can move to the code.

Building the task pane

We're going to focus on the taskpane folder of our solution, which includes the files that are used to render the web content displayed in the panel. Since I've picked up the React template, the taskpane.html page doesn't contain much. It includes only a div, called container, which is used by the index.tsx file to load the React application and render it into the div placeholder. The real application is stored inside the components folder: App.tsx is the main component, which defines the UI and includes the interaction logic. We also have some smaller components, which are used to render specific UI elements (like the header or the progress indicator).

Let's start to build the various elements we need step by step. Since we're going to make multiple changes compared to the default template, I won't go into the details on what you need to change. Just replace the existing components and functions with the ones I'm going to describe in the rest of the article.

Getting the initial text and pass to Open AI

As the first step, we need to define the state of our main component. To support our scenario, we need the state to store the initial text and the generated one. As such, we must update the AppState interface as following:

export interface AppState {
  generatedText: string;
  startText: string;
}

Let's initialize them as well in the constructor of the component with an empty string:

export default class App extends React.Component<AppProps, AppState> {
  constructor(props) {
    super(props);
    this.state = {
      generatedText: "",
      startText: "",
    };
  }
}

Now let's look at how we can define the UI, through JSX, the markup language (sort of) used by React, and the render() function of the component:

render() {
    return (
      <div>
        <main>
          <h2> Open AI business e-mail generator </h2>
          <p>Briefly describe what you want to communicate in the mail:</p>
          <textarea
            onChange={(e) => this.setState({ startText: e.target.value })}
            rows={10}
            cols={40}
          />
          <p>
            <DefaultButton onClick={this.generateText}>
              Generate text
            </DefaultButton>
          </p>
      </div>
  )
}

We have added a textarea, which is where the user is going to type the starting text, and a button, which will invoke the Open AI APIs. As for the textarea, we subscribe to the onChange event (which is triggered every time the user types something) and we use it to store the typed text inside the state, through the startText property.

Before implementing the onClick event of the button, however, we must take a step back and register to Open AI so that we can get an API key. Just go to https://openai.com/api/ and click on Sign Up (or Log In if you already have an account). Once you're in, click on your profile and choose View API keys. From there, click on Create new secret key and copy somewhere the generated key. You won't be able to retrieve it again, so do it immediately. The free plan gives you 18 $ of credits to be used within 3 months, which is more than enough for the POC we're building.

Now that we have an API key, we can start using the Open AI APIs. The easiest way to do it in our add-in is through the official JavaScript library. Open a terminal on the folder which includes your project and type:

npm install openai

Then, at the top of the App.tsx file, add the following statement to import the objects we need from the library:

import { Configuration, OpenAIApi } from "openai";

Now we can implement the onClick event that is triggered when the user clicks on the Generate text button:

generateText = async () => {
  var current = this;
  const configuration = new Configuration({
    apiKey: "add-your-api-key",
  });
  const openai = new OpenAIApi(configuration);
  const response = await openai.createCompletion({
    model: "text-davinci-003",
    prompt: "Turn the following text into a professional business mail: " + this.state.startText,
    temperature: 0.7,
    max_tokens: 300,
  });
  current.setState({ generatedText: response.data.choices[0].text });
};

First, we create a Configuration object, passing in the apiKey property the API key we have just generated.

Please note: we're doing this only for testing purposes, but this isn't a suggested approach for a production scenario. Since the add-in runs entirely client side, it's extremely easy to spoof the API key. You must use a more suitable approach like having a server-side middleware between the client and the API (like an Azure Function) and use services like Azure Key Vault.

Then we create a new OpenAIApi object, passing as parameter the configuration we have just created. Through this object, we can interact with the various models exposed by Open AI. The one related to text is accessible through the createCompletion() method, which requires as parameter an object with the following properties:

model, which is the name of the model to use. In this sample, we're using text-davinci-003, which is the most advanced GPT model available through the APIs at the time of writing this article. Soon, Open AI will make available also ChatGPT as one of the available options.
prompt, which is the text we want to process. We use a prompt that describes what we want to achieve (turn the following text into a professional business mail), followed by the text typed by the user (which we have previously stored in the component's state).
temperature, which is a value between 0 and 2 that controls how much randomness is in the output. As explained in this good article, the lower the temperature, the more likely GPT-3 will choose words with a higher probability of occurrence. In our case, we set 0.7, which is a good balance between "too flat" and "too creative".
max_tokens, which is the maximum number of words that will be returned by the API.

This method is asynchronous and based on JavaScript promises, so we can use the async / await pattern to invoke it. This means that the final line of our snippet will be called only when the API has returned a response. Specifically, the text generated by Open AI will be included in the text property of the first element of the data.choices collection. We store it in the generatedText property inside the component's state, so that we can later use it.

Use the generated text to craft our mail

Now that Open AI has generated the text of our business mail for us, we must display it to the user, give them the option to edit it and then use it as body of the mail. In order to do that, we need to add a new property in our state to store the final text to include in the mail, which might have some differences compared to the one generated by Open AI since we're giving the user the option to edit it. Here is the updated definition of the AppState interface:

export interface AppState {
  generatedText: string;
  startText: string;
  finalMailText: string;
}

Let's not forget to initialize it as well in the component's constructor:

export default class App extends React.Component<AppProps, AppState> {
  constructor(props) {
    super(props);
    this.state = {
      generatedText: "",
      startText: "",
      finalMailText: ""
    };
  }
}

Now that we have the property we need, let's add a new box and a new button to our application, by adding the following elements in JSX right below the ones we've added in the previous section:

<textarea
   defaultValue={this.state.generatedText}
   onChange={(e) => this.setState({ finalMailText: e.target.value })}
   rows={10}
   cols={40}
 />
 <p>
   <DefaultButton onClick={this.insertIntoMail>
     Insert into mail
   </DefaultButton>
</p>

The textarea control in React has a property called defaultValue, which we can set with a text that we want to display when the component is rendered. We connect it to the generatedText property available in the component's state. This way, once the Open API call has returned the generated text and stored it into the state, the box will automatically update itself to show it. Then, like we did with the previous box, we handle the onChange event, by saving the text typed by the user inside the finalMailText property of the component's state.

Finally, we have another button, which invokes a function called insertIntoMail(), which is described below:

insertIntoMail = () => {
  const finalText = this.state.finalMailText.length === 0 ? this.state.generatedText : this.state.finalMailText;
  Office.context.mailbox.item.body.setSelectedDataAsync(finalText, {
    coercionType: Office.CoercionType.Html,
  });
};

Here we can see the Office SDK in action. First, we determine if the user has made any change to the text generated by Open AI. Then, we call the Office.context.mailbox.item.body.setSelectedDataAsync() method, passing as parameter the final text (the one generated by the Open API plus any edit the user might have done). This method will take care of adding the text into the body of the mail, specifically where the text cursor is placed.

Building the command

Building the command requires less effort than the taskpane, since we don't have any UI. We just need to intercept the click on the button in the ribbon and manage it. The default commands.ts file inside the commands folder includes a function called action(), which we can use for this purpose.

First, let's create a new function that takes the body of the mail and processes it using Open AI:

function getSelectedText(): Promise<any> {
  return new Office.Promise(function (resolve, reject) {
    try {
      Office.context.mailbox.item.body.getAsync(Office.CoercionType.Text, async function (asyncResult) {
        const configuration = new Configuration({
          apiKey: "your-api-key",
        });
        const openai = new OpenAIApi(configuration);
        const response = await openai.createCompletion({
          model: "text-davinci-003",
          prompt: "Turn the following text into a professional business mail: " + asyncResult.value,
          temperature: 0.7,
          max_tokens: 300,
        });

        resolve(response.data.choices[0].text);
      });
    } catch (error) {
      reject(error);
    }
  });
}

The main difference with the taskpane is that, in this case, we are getting the text to turn into a business mail directly from the body of the mail. To do it, we use the Office SDK and, specifically, the Office.context.mailbox.body.getAsync() method. Being asynchronous, we receive the body in a callback, in which we implement the Open AI integration, which is the same we have seen for the taskpane. By using the Open AI library, we send a prompt followed by the text typed by the user to Open AI, by using the createCompletion() function and using the text-davinci-003 GPT model. Once we get a response, we return to the caller the text processed by Open AI, which is stored inside the text property of the first element of the data.choices collection.

Now we can implement the action() function:

function action(event: Office.AddinCommands.Event) {
  getSelectedText().then(function (selectedText) {
    Office.context.mailbox.item.setSelectedDataAsync(selectedText, { coercionType: Office.CoercionType.Text });
    event.completed();
  });
}

Also, in this case we're using code we have already seen in the taskpane implementation. We call the getSelectedText() function we have just created and, once we have the generated business mail, we use the Office.context.mailbox.item.setSelectedDataAsync() method to copy it into the mail's body. In the end, we call event.completed() to let Office know that the command execution is completed.

Testing and debugging the add-in

Visual Studio Code makes testing the add-in easy, thanks to a series of debug profiles which are created by Yeoman. If you move to the Debug tab of Visual Studio Code, you will find different profiles, one for each Office application. The one we're interested in is called Outlook Desktop (Edge Chromium). If you select it and you press the Play button, two things will happen:

A terminal prompt will be launched. Inside it, Visual Studio Code will run the local server (which uses Webpack to bundle all the JavaScript) that serves the add-in content to Outlook.
Outlook will start and you will see a security prompt asking if you want to sideload the add-in.

Now click on the button to compose a new mail and based on the size of your screen, you should see your add-in available in the ribbon (or, in case it doesn't fit, you'll see it by clicking on the three dots at the end of the ribbon).

When you click on it, a panel on the left will be opened, like the one we have seen at the beginning of the post. You will also be asked if you want to connect to the debugger, make sure to click Yes to confirm. Now type a simple sentence that you want to turn into a mail. For example, something like:

David, I'm planning to work on your garden tomorrow at 3 PM, but I might be a bit late.

Then click on Generate text and, after a few seconds, you should see a more carefully crafted text being displayed in the box below:

Dear David,

I hope this message finds you well. I wanted to let you know that I am planning to work on your garden tomorrow at 3 PM, however, I may be running a bit late. I apologize for any inconvenience this may cause.

Thank you for your understanding.

Sincerely,
[Your Name]

Now you can make the changes you need, then click on Insert into mail. You will find the text included inside the body of the mail, ready to be sent to your customer. In background, Visual Studio Code has attached a debugger to the WebView which is rendering the panel inside Outlook. This means that you can set breakpoints in your TypeScript code and do step-by-step debugging whenever it's needed. For example, you can set breakpoints inside the generateText() function and monitor the interaction with Open AI APIs. The local server, additionally, supports live reload, so whenever you make any change, you won't have to redeploy the add-in, but they will be applied in real time.

The same testing can be done also for the command. The difference is that you must type the text to turn into a business mail directly in the mail's body, then click on the Generate business mail button in the ribbon. A loading indicator will be displayed at the top of the window, and you'll be notified once the operation is completed. Also, in this case the Visual Studio Code debugger will be attached, so you can set breakpoints in your code if needed.

Deploying the add-in

Once you're done testing, you can choose to make available your plugin to a broader audience. The publishing story for Office add-ins is similar to the Teams apps ones:

You can share the add-in for manual sideloading, which is great for testing and limited distribution.
You can publish the add-in in your organization, so that all the employees can pick it up from the add-in store.
You can publish the add-in in the Office store, to make it available to every Office customer around the globe.

Regardless of your choice, Office is just the "interface" for your add-in, but it doesn't host it. This is why the only required component to deploy for an Office add-in is the manifest, which includes all the information on where the web app is hosted. If you explore the manifest.xml file we have previously edited, you will find the following tag, which defines the entry point of our taskpane:

<SourceLocation DefaultValue="https://localhost:3000/taskpane.html"/>

Ideally, once you're ready to deploy, this URL (and the other localhost references included in the manifest) will be replaced by the real URL of the web application.

If you want to start the process to make your add-in available to a broader audience, Visual Studio Code is still your best friend. The following document will guide on how to leverage the Azure extension for Visual Studio Code to generate the distributable version of the add-in and to publish it on Azure Storage, which is a perfect match for our scenario since the add-in is made only by static web content.

Once you have published your add-in, you can open any Outlook version (desktop, web, etc.), click on Get add-ins, move to the My add-ins section and, under Custom addins, click on Add a custom add-in. From there, you can either pick up the manifest.xml file of your project or specify the URL of the manifest published on Azure Storage. This way, people will be able to add it to Outlook without needing you to share any file.

Wrapping up

In this blog post we have learned how we can help users to be more productive by infusing software with the latest powerful AI models created by Open AI. Specifically, we focused on the Microsoft 365 ecosystem, by providing an Outlook "copilot" to help you write more professional business mails. And this is just the beginning! We know that new and powerful models are already available (like ChatGPT) and that Microsoft will directly offer new integrations. It's an exciting time to work in the tech space 😃

You can find the definitive version of the add-in on GitHub, with a few improvements that we didn't discuss in this blog post since they help to deliver a better UX, but they aren't strictly connected to the AI integration (like showing a progress indicator meanwhile Open AI processes the input text in the taskpane).

Happy coding!

Share a link to Teams in a canvas Power App

Matteo Pagani — Tue, 07 Feb 2023 08:33:19 GMT

Recently I worked with a customer on building a canvas Power App embedded in Microsoft Teams. The application acts as a catalogue and one of the requested features was enabling users to share an item from the catalogue to another user in Teams, with a deep link to open the application directly on the selected item. The scenario seemed quite straight forward at first, but I had to do a few research to implement it, especially for the first task, which is sharing the link over Teams. As such, I've decided to document my findings in this blog post.

Let's start!

Out of the box, searching on the Internet I couldn't find an easy way to perform sharing to Teams directly from an app. The two options I've explored weren't suitable:

When the application runs inside Teams, you can leverage the Teams connector to interact with the platform and perform tasks like detecting the theme, getting the name of the channel in which the app has been added, etc. Unfortunately, there isn't any available action to start sharing. You can post a message to a chat or a channel, but you must know upfront who the receiver will be. The sharing experience, instead, should allow the user to pick up the target as part of the process.
The official documentation offers a section that explains how to share to Teams. However, both approaches (integration into a personal or tab app or in a website), are focused on a pro-developer implementation, which requires to leverage the Microsoft Teams SDK or to include a JavaScript script.

So I started to play a bit with the second implementation, and I've discovered that the sharing experience is based on the https://teams.microsoft.com/share website. When you open this website in a browser, you will be authenticated with your Microsoft 365 account, which enables an auto-complete experience. As you can see from the image below, the Share To field gets automatically populated with people, chats, and channels from your tenant:

This is a good starting point! However, to support the scenario requested by the customer, I need to automatically include the link of the item to share from the catalogue in the body of the message. To better understand how the sharing website works, I created a quite simple HTML page and I followed the official documentation to include a basic sharing experience. With this approach, in fact, you can pass to the script two parameters to define the URL and the message, which is the same goal I was trying to achieve. This simple experiment helped me to discover the parameters that are passed to the URL to pre-populate the content of the message. Clicking on the sharing button, in fact, led the browser to open a new tab with the following URL:

https://teams.microsoft.com/share?href=https%3A%2F%2Fwww.mywebsite.com&msgText=This%20is%20a%20message&preview=false&s=1675706704556

As you can see from the URL, the sharing page accepts the two key parameters I was looking for:

href, which contains the URL to share.
msgText, which contains the text of the message.

Now that I have this information, it's very easy to integrate a sharing feature using the Launch() function in Power Apps, which you can use to open an external URL. You just need to pass:

As href, the Web URL of the Power App, which you can get by clicking on the three dots near your app in the Power Apps portal and choosing Details.

As msgText, a message that you want to include in the link.

This is an example of the function I've linked to the OnSelect() event of a Button control in my application:

Launch("https://teams.microsoft.com/share", { href: "https://apps.powerapps.com/play/e/default-7454e082-9a4c-4adf-a685-a5f2a4cb711a/a/3bb8fb0e-5d81-4855-a950-d9415c3ad896?tenantId=7454e082-9a4c-4adf-a685-a5f2a4cb711a", msgText: "Check this application" });

The first parameter passed to the function is the generic Teams share URL. Then, we pass a collection of parameters we want to pass in query string, which are the ones we have just learned about (msgText and href). If you preview your application and you press the button, a new tab in the browser will be opened with the link, the message and a link preview delivered through an Adaptive Card:

After you have clicked on Share, the link will be shared to the selected user or channel, as in the following image:

Now let's see how we have implemented the sharing so that the link opens the app on a specific item of the catalogue.

Supporting a deep link

A deep link is a link that doesn't open just the app on the home page, but it redirect the user to a specific content. In the web ecosystem, this scenario is typically implemented through routing or query string parameters. For example, a web application could support an itemId parameter in the URL with the id of an item. When this URL is opened, the application automatically routes the request to the appropriate page to show the details of the selected item.

https://www.mywebsite.com/details?itemId=534

Power Apps support this mechanism as well when they are consumed using a web browser. If you open a Power App on your browser through its Web URL, you can attach to it some custom parameters that you can retrieve in the application using the Param() function. Let's say, for example, that the URL of our Power App is https://apps.powerapps.com/play/e/default-7454e082-9a4c-4adf-a685-a5f2a4cb711a/a/3bb8fb0e-5d81-4855-a950-d9415c3ad896?tenantId=7454e082-9a4c-4adf-a685-a5f2a4cb711a. If we want to pass the information about a specific item, we can pass an extra itemId parameter to this URL, as in the following example:

https://apps.powerapps.com/play/e/default-7454e082-9a4c-4adf-a685-a5f2a4cb711a/a/3bb8fb0e-5d81-4855-a950-d9415c3ad896?tenantId=7454e082-9a4c-4adf-a685-a5f2a4cb711a&itemId=534

From a sharing perspective, this means that we just need to attach this parameter to our share button. We just need to make the value of the parameter dynamic, based on the selected item. For example, in my scenario, the catalogue is stored into a Dataverse table and it's displayed using a Gallery control. As such, the item template includes a share button which invokes the following function:

Launch("https://teams.microsoft.com/share", { href: "https://apps.powerapps.com/play/e/default-7454e082-9a4c-4adf-a685-a5f2a4cb711a/a/3bb8fb0e-5d81-4855-a950-d9415c3ad896?tenantId=7454e082-9a4c-4adf-a685-a5f2a4cb711a&itemId=" + ThisItem.ItemId, msgText: "Check this application" });

We have added the itemId parameter and we have set, as value, the ItemId property of the selected item, which is made accessible through the ThisItem object. ItemId is a property in the Dataverse table which contains the unique identifier of the item in the catalogue.

When the link is shared and the user clicks on it, the application will be opened in the normal way. However, the extra feature we can leverage is that we can read the value of the itemId parameter in the URL through the Param() function. For example, if you want to display its value in a label, we can set its Text property with the following function:

If(Param("itemId")<>Blank(), Param("itemId"), "Parameter is missing")

We pass to the Param() function the name of the parameter, which is itemId in our case. If it exists (we check this condition using the <>Blank() statement) we display its value, otherwise we display a warning message.

Now that you have understood how to retrieve a parameter to the URL, it's easy to build the startup experience of your application in a way that can display different content based on the parameter. For example, in the OnStart() event of the application, you could have some code like this:

If(Param("itemId")<>Blank(), 
    Set(CurrentItem, Param("itemId"));
    Navigate(DetailScreen)
);

If the application is opened through sharing (so the itemId parameter is included in the URL), we store its value in global variable (so that we can retrieve it later to query our Dataverse table, for example) and we navigate the user directly to the detail screen instead of the home screen.

Wrapping up

In this blog post, we have learned how to implement a full "Share to Teams" experience in Power Apps, including support for deep links. In the first part, we have learned how to enable the sharing feature, which requires some extra work since Power Apps doesn't offer it out of the box. Then we have seen how we can integrate a deep link experience, which enables users to open the app directly on specific content that was shared from the application.

Happy (low) coding!

Create a 3D collaborative app for Teams Meeting using Live Share SDK, Live Share Canvas and Babylon

freistli — Mon, 02 Jan 2023 02:06:05 GMT

Teams Live Share seamlessly integrates meetings with Fluid Framework. As a recent GA SDK in Oct, 2022, Live Share provides a free, fully managed, and ready to use Azure Fluid Relay backed by the security and global scale of Teams.

With this technology, participants in the same Teams meeting can easily interactively work together on the same content or object, for example, with real time shared annotations, operations, to exchange ideas efficiently.

Starting from the simple live canvas demo, I verified more functions by integrating below parts together:

and implement a collaborative inking 2D/3D objects teams meeting extension. It also supports switching different backend Fluid Relay Services. Regarding 3D rendering, it works in Teams Web App with WebGL2 and works in Teams Desktop App with WebGL. Here is a screen snapshot that two clients in the same live share session in teams meeting (one is teams web app, another is Teams Desktop App):

Developers can get main ideas of how Live Share works for Teams especially with Babylon 3D and Fluid UI packages from the project. Here is the pubic github repo, I shared setup/build/test steps in it as well:

freistli/LiveShareCanvasBabylon (github.com)

Enjoy Teams Platform Development!