L
luisdem
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:
- ServiceNow Service Catalog Graph Connector
- SharePoint Capability
- Plugin: 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.
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
- 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
Provisionin "Lifecycle" section. - Select
Preview in Copilot (Edge)orPreview in Copilot (Chrome)from the launch configuration dropdown. - Select your declarative agent from the
Copilotapp. - 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
- Declarative agents for Microsoft 365
- Extend Microsoft 365 Copilot
- Message extensions for Microsoft 365 Copilot
- Microsoft Graph Connectors for Microsoft 365 Copilot
- Microsoft 365 Copilot extensibility samples
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
Newand 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.
Code:
(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.
Code:
(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.
Continue reading...