Many enterprise customers across various industries are looking to adopt Generative AI to drive innovation, user productivity, and enhance customer experience. Generative AI–powered assistants such as Amazon Q Business can be configured to answer questions, provide summaries, generate content, and securely complete tasks based on data and information in your enterprise systems. Amazon Q Business understands natural language and allows users to receive immediate, permissions-aware responses from enterprise data sources with citations. This capability supports various use cases such as IT, HR, and help desk.
With custom plugins for Amazon Q Business, you can enhance the application environment to enable your users to use natural language to perform specific tasks related to third-party applications — such as Jira, Salesforce, and ServiceNow — directly from within their web experience chat.
Enterprises that have adopted ServiceNow can improve their operations and boost user productivity by using Amazon Q Business for various use cases, including incident and knowledge management. Users can search ServiceNow knowledge base (KB) articles and incidents in addition to being able to create, manage, and track incidents and KB articles, all from within their web experience chat.
In this post, we’ll demonstrate how to configure an Amazon Q Business application and add a custom plugin that gives users the ability to use a natural language interface provided by Amazon Q Business to query real-time data and take actions in ServiceNow. By the end of this hands-on session, you should be able to:
Create an Amazon Q Business application and integrate it with ServiceNow using a custom plugin.
Use natural language in your Amazon Q web experience chat to perform read and write actions in ServiceNow such as querying and creating incidents and KB articles in a secure and governed fashion.
Prerequisites
Before proceeding, make sure that you have the necessary AWS account permissions and services enabled, along with access to a ServiceNow environment with the required privileges for configuration.
AWS
Have an AWS account with administrative access. For more information, see Setting up for Amazon Q Business. For a complete list of AWS Identity and Access Management (IAM) roles for Amazon Q Business, see IAM roles for Amazon Q Business. Although we’re using admin privileges for the purpose of this post, it’s a security best practice to apply least privilege permissions and grant only the permissions required to perform a task.
Subscribe to the Amazon Q Business Pro plan which includes access to custom plugins to enable users to execute actions in third-party applications. For information on what is included in the tiers of user subscriptions, see Amazon Q Business pricing document.
ServiceNow
Obtain a ServiceNow Personal Developer Instance or use a clean ServiceNow developer environment. You will need an account that has admin privileges to perform the configuration steps in ServiceNow.
Solution overview
The following architecture diagram illustrates the workflow for Amazon Q Business web experience with enhanced capabilities to integrate it seamlessly with ServiceNow.
The implementation includes the following steps:
The solution begins with configuring Amazon Q Business using the AWS Management Console. This includes setting up the application environment, adding users to AWS IAM Identity Center, selecting the appropriate subscription tier, and configuring the web experience for users to interact with. The environment can optionally be configured to provide real-time data retrieval using a native retriever, which pulls information from indexed data sources, such as Amazon Simple Storage Service (Amazon S3), during interactions.
The next step involves adjusting the global controls and response settings for the application environment guardrails to allow Amazon Q Business to use its large language model (LLM) knowledge to generate responses when it cannot find responses from your connected data sources.
Integration with ServiceNow is achieved by setting up an OAuth Inbound application endpoint in ServiceNow, which authenticates and authorizes interactions between Amazon Q Business and ServiceNow. This involves creating an OAuth API endpoint in ServiceNow and using the web experience URL from Amazon Q Business as the callback URL. The setup makes sure that Amazon Q Business can securely perform actions in ServiceNow with the same scoped permissions as the user signing in to ServiceNow.
The final step of the solution involves enhancing the application environment with a custom plugin for ServiceNow using APIs defined in an OpenAPI schema. The plugin allows Amazon Q Business to securely interact with ServiceNow’s REST APIs, enabling operations such as querying, creating, and updating records dynamically and in real time
Configuring the Amazon Q Business application
To create an Amazon Q Business application, sign in to the Amazon Q Business console.
As a prerequisite to creating an Amazon Q Business application, follow the instructions in Configuring an IAM Identity Center instance section. Amazon Q Business integrates with IAM Identity Center to enable managing user access to your Amazon Q Business application. This is the recommended method for managing human access to AWS resources and the method used for the purpose of this blog.
Amazon Q Business also supports identity federation through IAM. When you use identity federation, you can manage users with your enterprise identity provider (IdP) and use IAM to authenticate users when they sign in to Amazon Q Business.
Create and configure the Amazon Q Business application:
In the Amazon Q Business console, choose Application from the navigation pane and then choose Create application.
Enter the following information for your Amazon Q Business application:
Application name: Enter a name for quick identification, such as my-demo-application.
Service access: Select the Create and use a new service-linked role (SLR). A service-linked role is a unique type of IAM role that is linked directly to Amazon Q Business. Service-linked roles are predefined by Amazon Q Business and include the permissions that the service requires to call other AWS services on your behalf.
Choose Create.
After creating your Amazon Q Business application environment, create and select the retriever and provision the index that will power your generative AI web experience. The retriever pulls data from the index in real time during a conversation. On the Select Retriever page:
Retrievers: Select Use native retriever.
Index provisioning: Select Starter, which is ideal for proof-of-concept or developer workloads. See Index types for more information.
Number of units: Enter 1. This indicates the capacity units that you want to provision for your index. Each unit is 20,000 documents. Choose Next.
Choose Next.
After you select a retriever for your Amazon Q Business application environment, you can optionally connect other data sources to it. Because a data source isn’t required for this session, we won’t configure one. For more information on connecting data sources to an Amazon Q Business application, see connecting data sources.
Choose Next.
As an account admin, you can add users to your IAM Identity Center instance from the Amazon Q Business console. After you add users or groups to an application environment, you can then choose the Amazon Q Business tier for each user or group. On the Add groups and users page:
Choose Add groups and users.
In the Add new users dialog box that opens, enter the details of the user. The details you must enter for a single user include: Username, First name, Last name, email address, Confirm email address, and Display name.
Choose Next and then Add. The user is automatically added to an IAM Identity Center directory and an email invitation to join Identity Center is sent to the email address provided.
After adding a user or group, choose the Amazon Q Business subscription tier for each user or group. From the Current subscription dropdown menu, select Q Business Pro.
For the Web experience service access, select Create and use a new service role.
Choose Create application.
Upon successful completion, Amazon Q Business returns a web experience URL that you can share with the users you added to your application environment. The Web experience URL (in this case: https://xxxxxxxx.chat.qbusiness.us-east-1.on.aws/) will be used when creating an OAuth application endpoint in ServiceNow. Note that your web experience URL will be different from the one shown here.
Enhancing an Amazon Q Business application with guardrails
By default, an Amazon Q Business application is configured to respond to user chat queries using only enterprise data. Because we didn’t configure a data source for the purpose of this post, you will use Admin controls and guardrails to allow Amazon Q to use its LLM world knowledge to generate responses when it cannot find responses from your connected data sources.
Create a custom plugin for ServiceNow:
From the Amazon Q Business console, choose Applications in the navigation pane. Select the name of your application from the list of applications.
From the navigation pane, choose Enhancements, and then choose Admin Controls and guardrails.
In Global Controls, choose Edit.
In Response settings under Application guardrails, select Allow Amazon Q to fall back to LLM knowledge.
Configuring ServiceNow
To allow Amazon Q Business to connect to your ServiceNow instance, you need to create an OAuth inbound application endpoint. OAuth-based authentication validates the identity of the client that attempts to establish a trust on the system by using an authentication protocol. For more information, see OAuth Inbound and Outbound authentication.
Create an OAuth application endpoint for external client applications to access the ServiceNow instance:
In the ServiceNow console, navigate to All, then System OAuth, then Application Registry and then choose New. On the interceptor page, select Create an OAuth API endpoint for external clients and then fill in the form with details for Name and Redirect URL. The other fields are automatically generated by the ServiceNow OAuth server.
The Redirect URL is the callback URL that the authorization server redirects to. Enter the web experience URL of your Amazon Q Business application environment (which is the client requesting access to the resource), appended by oauth/callback.
For this example, the URL is: https://xxxxxxxx.chat.qbusiness.us-east-1.on.aws/oauth/callback
For Auth Scope, set the value to useraccount. The scope API response parameter defines the amount of access granted by the access token, which means that the access token has the same rights as the user account that authorized the token. For example, if Abel Tuter authorizes an application by providing login credentials, then the resulting access token grants the token bearer the same access privileges as Abel Tuter.
Choose Submit.
This creates an OAuth client application record and generates a client ID and client secret, which Amazon Q Business needs to access the restricted resources on the instance. You will need this authentication information (client ID and client secret) in the following custom plugin configuration process.
Enhancing the Amazon Q Business application environment with custom plugins for ServiceNow
To integrate with external applications, Amazon Q Business uses APIs, which are configured as part of the custom plugins.
Before creating a custom plugin, you need to create or edit an OpenAPI schema, outlining the different API operations that you want to enable for your custom plugin. Amazon Q Business uses the configured third-party OpenAPI specifications to dynamically determine which API operations to perform to fulfill a user request. Therefore, the OpenAPI schema definition has a big impact on API selection accuracy and might require design optimizations. In order to maximize accuracy and improve efficiency with an Amazon Q Business custom plugin, follow the best practices for configuring OpenAPI schema definitions.
To configure a custom plugin, you must define at least one and a maximum of eight API operations that can be invoked. To define the API operations, create an OpenAPI schema in JSON or YAML format. You can create OpenAPI schema files and upload them to Amazon S3. Alternatively, you can use the OpenAPI text editor in the console, which will validate your schema.
For this post, a working sample of an OpenAPI Schema for ServiceNow is provided in JSON format. Before using it, edit the template file and replace <YOUR_SERVICENOW_INSTANCE_URL> in the following sections with the URL of your ServiceNow instance.
You can use the REST API Explorer to browse available APIs, API versions, and methods for each API. The explorer enables you to test REST API requests straight from the user interface. The Table API provides endpoints that allow you to perform create, read, update, and delete (CRUD) operations on existing tables. The calling user must have sufficient roles to access the data in the table specified in the request. For additional information on assigning roles, see Managing roles.
{
“openapi”: “3.0.1”,
“info”: {
“title”: “Table API”,
“description”: “Allows you to perform create, read, update and delete (CRUD) operations on existing tables”,
“version”: “latest”
},
“externalDocs”: {
“url”: “https://docs.servicenow.com/?context=CSHelp:REST-Table-API”
},
“servers”: [
{
“url”: “YOUR_SERVICENOW_INSTANCE_URL”
}
],
“paths”: {
“/api/now/table/{tableName}”: {
“get”: {
“description”: “Retrieve records from a table”,
“parameters”: [
{
“name”: “tableName”,
“in”: “path”,
“description”: “Table Name”,
“required”: true,
“schema”: {
“type”: “string”
}
},
{
“name”: “sysparm_query”,
“in”: “query”,
“description”: “An encoded query string used to filter the results like Incidents Numbers or Knowledge Base IDs etc”,
“required”: true,
“schema”: {
“type”: “string”
}
},
{
“name”: “sysparm_fields”,
“in”: “query”,
“description”: “A comma-separated list of fields to return in the response”,
“required”: false,
“schema”: {
“type”: “string”
}
},
{
“name”: “sysparm_limit”,
“in”: “query”,
“description”: “The maximum number of results returned per page”,
“required”: false,
“schema”: {
“type”: “string”
}
}
],
“responses”: {
“200”: {
“description”: “ok”,
“content”: {
“application/json”: {
“schema”: {
“$ref”: “#/components/schemas/incident”
}
}
}
}
}
},
“post”: {
“description”: “Create a record”,
“parameters”: [
{
“name”: “tableName”,
“in”: “path”,
“description”: “Table Name”,
“required”: true,
“schema”: {
“type”: “string”
}
}
],
“requestBody”: {
“content”: {
“application/json”: {
“schema”: {
“type”: “object”,
“properties”: {
“short_description”: {
“type”: “string”,
“description”: “Short Description”
},
“description”: {
“type”: “string”,
“description”: “Full Description for Incidents only”
},
“caller_id”: {
“type”: “string”,
“description”: “Caller Email”
},
“state”: {
“type”: “string”,
“description”: “State of the incident”,
“enum”: [
“new”,
“in_progress”,
“resolved”,
“closed”
]
},
“text”: {
“type”: “string”,
“description”: “Article Body Text for Knowledge Bases Only (KB)”
}
},
“required”: [
“short_description”,
“caller_id”
]
}
}
},
“required”: true
},
“responses”: {
“200”: {
“description”: “ok”,
“content”: {
“application/json”: {}
}
}
}
}
},
“/api/now/table/{tableName}/{sys_id}”: {
“get”: {
“description”: “Retrieve a record”,
“parameters”: [
{
“name”: “tableName”,
“in”: “path”,
“description”: “Table Name”,
“required”: true,
“schema”: {
“type”: “string”
}
},
{
“name”: “sys_id”,
“in”: “path”,
“description”: “Sys ID”,
“required”: true,
“schema”: {
“type”: “string”
}
},
{
“name”: “sysparm_fields”,
“in”: “query”,
“description”: “A comma-separated list of fields to return in the response”,
“required”: false,
“schema”: {
“type”: “string”
}
}
],
“responses”: {
“200”: {
“description”: “ok”,
“content”: {
“application/json”: {},
“application/xml”: {},
“text/xml”: {}
}
}
}
},
“delete”: {
“description”: “Delete a record”,
“parameters”: [
{
“name”: “tableName”,
“in”: “path”,
“description”: “Table Name”,
“required”: true,
“schema”: {
“type”: “string”
}
},
{
“name”: “sys_id”,
“in”: “path”,
“description”: “Sys ID”,
“required”: true,
“schema”: {
“type”: “string”
}
}
],
“responses”: {
“200”: {
“description”: “ok”,
“content”: {
“application/json”: {},
“application/xml”: {},
“text/xml”: {}
}
}
}
},
“patch”: {
“description”: “Update or modify a record”,
“parameters”: [
{
“name”: “tableName”,
“in”: “path”,
“description”: “Table Name”,
“required”: true,
“schema”: {
“type”: “string”
}
},
{
“name”: “sys_id”,
“in”: “path”,
“description”: “Sys ID”,
“required”: true,
“schema”: {
“type”: “string”
}
}
],
“requestBody”: {
“content”: {
“application/json”: {
“schema”: {
“type”: “object”,
“properties”: {
“short_description”: {
“type”: “string”,
“description”: “Short Description”
},
“description”: {
“type”: “string”,
“description”: “Full Description for Incidents only”
},
“caller_id”: {
“type”: “string”,
“description”: “Caller Email”
},
“state”: {
“type”: “string”,
“description”: “State of the incident”,
“enum”: [
“new”,
“in_progress”,
“resolved”,
“closed”
]
},
“text”: {
“type”: “string”,
“description”: “Article Body Text for Knowledge Bases Only (KB)”
}
},
“required”: [
“short_description”,
“caller_id”
]
}
}
},
“required”: true
},
“responses”: {
“200”: {
“description”: “ok”,
“content”: {
“application/json”: {},
“application/xml”: {},
“text/xml”: {}
}
}
}
}
}
},
“components”: {
“schemas”: {
“incident”: {
“type”: “object”,
“properties”: {
“sys_id”: {
“type”: “string”,
“description”: “Unique identifier for the incident”
},
“number”: {
“type”: “string”,
“description”: “Incident number”
},
“short_description”: {
“type”: “string”,
“description”: “Brief description of the incident”
}
}
}
},
“securitySchemes”: {
“oauth2”: {
“type”: “oauth2”,
“flows”: {
“authorizationCode”: {
“authorizationUrl”: “YOUR_SERVICENOW_INSTANCE_URL/oauth_auth.do”,
“tokenUrl”: “YOUR_SERVICENOW_INSTANCE_URL/oauth_token.do”,
“scopes”: {
“useraccount”: “Access equivalent to the user’s account”
}
}
}
}
}
},
“security”: [
{
“oauth2”: [
“useraccount”
]
}
]
}
The URL for the ServiceNow instance used in this post is: https://devxxxxxx.service-now.com/. After updating the sections of the template with the URL for this specific instance, the JSON should look like the following:
“servers”: [
{
“url”: “https://devxxxxxx.service-now.com/”
}
“securitySchemes”: {
“oauth2”: {
“type”: “oauth2”,
“flows”: {
“authorizationCode”: {
“authorizationUrl”: “https://devxxxxxx.service-now.com/oauth_auth.do”,
“tokenUrl”: “https://devxxxxxx.service-now.com/oauth_token.do”,
“scopes”: {
“useraccount”: “Access equivalent to the user’s account”
}
}
}
}
}
To create a custom plugin for ServiceNow:
Sign in to the Amazon Q Business console.
Choose Applications in the navigation pane, and then select your application from the list of applications.
In the navigation pane, choose Enhancements, and then choose Plugins.
In Plugins, choose Add plugin.
In Add plugins, choose Custom plugin.
In Custom plugin, enter the following information:
In Name and description, for Plugin name: Enter a name for your Amazon Q plugin.
In API schema, for API schema source, select Define with in-line OpenAPI schema editor.
Select JSON as the format for the schema.
Remove any sample schema that appears in the inline OpenAPI schema editor and replace it with the text from the provided sample JSON template, updated with your ServiceNow instance URL.
In Authentication: Select Authentication required.
For AWS Secrets Manager secret, choose Create and add a new secret. You need to store the ServiceNow OAuth authentication credentials in a Secrets Manager secret to connect your third-party application to Amazon Q. In the window that opens, enter the details in the form:
Secret name: A name for your Secrets Manager secret.
Client ID: The Client ID from ServiceNow OAuth configuration in the previous section.
Client secret: The Client Secret from ServiceNow OAuth configuration in the previous section.
OAuth callback URL: The URL the user needs to be redirected to after authentication. This will be your web experience URL. For this example, it’s: https://xxxxxxxx.chat.qbusiness.us-east-1.on.aws/oauth/callback. Amazon Q Business will handle OAuth tokens in this URL.
In Choose a method to authorize Amazon Q Business: Select Create and add a new service role. The console will generate a service role name. To connect Amazon Q Business to third-party applications that require authentication, you need to give the Amazon Q role permissions to access your Secrets Manager secret. This will enable an Amazon Q Business custom plugin to access the credentials needed to sign in to the third-party service.
Choose Add plugin to add your plugin.
Upon successful completion, the plugin will appear under Plugins with Build status of Ready and Plugin status Active.
Using Amazon Q Business web experience chat to take actions in ServiceNow
Users can launch your Amazon Q Business web experience in two ways:
AWS access portal URL provided in an invitation email sent to the user to join AWS IAM Identity Center.
Web experience URL shared by the admin.
Navigate to the deployed web experience URL and sign with your AWS IAM Identity Center credentials.
After signing in, choose the New conversation icon in the left-hand menu to start a conversation.
Example: Search Knowledge Base Articles in ServiceNow for user issue and create an incident
The following chat conversation example illustrates a typical use case of Amazon Q Business integrated with custom plugins for ServiceNow. These features allow you to perform a wide range of tasks tailored to your organization’s needs.
In this example, we initiate a conversation in the web experience chat to search for KB articles related to ”log in issues” in ServiceNow by invoking a plugin action. After the user submits a prompt, Amazon Q Business queries ServiceNow through the appropriate API to retrieve the results and provides a response with related KB articles. We then proceed by asking Amazon Q Business for more details to see if any of the KB articles directly addresses the user’s issue. When no relevant KB articles pertaining to the user’s issue are found, we ask Amazon Q Business to summarize the conversation and create a new incident in ServiceNow, making sure the issue is logged for resolution.
User prompt 1 – I am having issues logging in to the intranet and want to know if there are any ServiceNow KB articles on log-in issues. Perform the search on both Short Description and Text field using LIKE operator
Before submitting the preceding prompt for an action to create an incident in ServiceNow, choose the vertical ellipsis to open Conversation settings, then choose Use a Plugin to select the corresponding custom plugin for ServiceNow.
If this is the first time a user is accessing the custom plugin or if their past sign-in has expired, the user will need to authenticate. After authenticating successfully, Amazon Q Business will perform the requested task.
Choose Authorize.
If the user isn’t already signed in to ServiceNow, they will be prompted to enter their credentials. For this example, the user signing in to ServiceNow is the admin user and API actions performed in ServiceNow by Amazon Q Business on behalf of the user will have the same level of access as the user within ServiceNow.
Choose Allow for Amazon Q Business to connect to ServiceNow and perform the requested task on your behalf.
Upon executing the user’s request after verifying that they are authorized, Amazon Q Business responds with the information that it retrieved. We then proceed to retrieve additional details with the following prompt.
User prompt 2 – Can you list the KB number and short description in a tabular form?
Because there no KB articles related the user’s issue were found, we will ask Amazon Q to summarize the conversation context to create an incident with the following prompt.
User prompt 3 – The error I get is “Unable to Login After System Upgrade”. Summarize my issue and create an incident with detailed description and add a note that this needs to be resolved asap.
In response to your prompt for an action, Amazon Q displays a review form where you can modify or fill in the necessary information.
To successfully complete the action, choose submit.
Note: The caller_id value entered in the following example is a valid ServiceNow user.
Your web experience will display a success message if the action succeeds, or an error message if the action fails. In this case, the action succeeded and Amazon Q Business responded accordingly.
The following screenshot shows that the incident was created successfully in ServiceNow.
Troubleshooting common errors
To have a seamless experience with third-party application integrations, it’s essential to thoroughly test, identify, and troubleshoot unexpected behavior.
A common error encountered in Amazon Q Business is API Response too large, which occurs when an API response size exceeds the current limit of 100 KB. While prompting techniques are essential for obtaining accurate and relevant answers, optimizing API responses to include only the necessary and relevant data is crucial for better response times and enhanced user experience.
The REST API Explorer (shown in the following figure) in ServiceNow is a tool that allows developers and administrators to interact with and test the ServiceNow REST APIs directly from within the ServiceNow environment. It provides a user-friendly interface for making API requests, viewing responses, and understanding the available endpoints and data structures. Using this tool simplifies the process of testing and integrating with ServiceNow.
Clean up
To clean up AWS configurations, sign in to the Amazon Q Business console.
From the Amazon Q Business console, in Applications, select the application that you want to delete.
Choose Actions and select Delete.
To confirm deletion, enter Delete.
This will take a few minutes to finish. When completed, the application and the configured custom plugin will be deleted.
When you delete the Amazon Q Business application, the users created as part of the configuration are not automatically deleted from IAM Identity Center. Use the instructions in Delete users in IAM Identity Center to delete the users created for this post.
To clean up in ServiceNow, release the Personal Developer Instance provisioned for this post by following the instructions in the ServiceNow Documentation.
Conclusion
The integration of generative AI-powered assistants such as Amazon Q Business with enterprise systems such as ServiceNow offers significant benefits for organizations. By using natural language processing capabilities, enterprises can streamline operations, enhance user productivity, and deliver better customer experiences. The ability to query real-time data and create incidents and knowledge articles through a secure and governed chat interface transforms how users interact with enterprise data and applications. As demonstrated in this post, enhancing Amazon Q Business to integrate with ServiceNow using custom plugins empowers users to perform complex tasks effortlessly, driving efficiency across various business functions. Adopting this technology not only modernizes workflows, but also positions enterprises at the forefront of innovation.
Learn more
Amazon Q main product page
Get started with Amazon Q
Introducing Amazon Q, a new generative AI-powered assistant (preview)
Improve developer productivity with generative-AI powered Amazon Q in Amazon CodeCatalyst (preview)
Upgrade your Java applications with Amazon Q Code Transformation (preview)
New generative AI features in Amazon Connect, including Amazon Q, facilitate improved contact center service
New Amazon Q in QuickSight uses generative AI assistance for quicker, easier data insights (preview)
Amazon Q brings generative AI-powered assistance to IT pros and developers (preview)
About the Author
Siddhartha Angara is a Senior Solutions Architect at Amazon Web Services. He helps enterprise customers design and build well-architected solutions in the cloud, accelerate cloud adoption, and build Machine Learning and Generative AI applications. He enjoys playing the guitar, reading and family time!
