This article only applies to your community if your Firstup contract includes this functionality. Please contact your Customer Success Manager with any questions about feature availability for your community.
The ServiceNow integration connects your Firstup community to your ServiceNow instance. You can enable knowledge search, IT productivity features, or both, depending on your community’s requirements and contract.
- Search integration: Lets you search for ServiceNow knowledge articles from your Firstup member Experience.
- Productivity integration: Lets you access IT records and complete supported actions, such as commenting on incidents and approving requests, from your Firstup member Experience.
Before setup begins, tell your Firstup representative which capabilities you want to enable. Firstup configures the integration using the connection details you provide. Knowledge search also requires the ServiceNow Knowledge API plugin (sn_km_api) to be installed on your ServiceNow instance.
Authentication Overview
The ServiceNow integration supports two authentication methods:
- Service account: Firstup uses the username and password of a dedicated account you create in ServiceNow to retrieve read-only data. The account’s roles and access controls determine which records it can access.
- User authentication: You sign in to ServiceNow through OAuth 2.0 Authorization Code Flow to allow Firstup to act on your behalf. Actions that modify ServiceNow records, such as commenting, adding work notes, or approving requests, require this authentication and follow your ServiceNow permissions.
For OAuth, configure the authorization-code grant with refresh tokens enabled. Firstup does not send a scope in the authorization request, so leave the OAuth application’s scope empty. Access remains subject to the authenticated user’s ServiceNow roles and access controls.
Firstup recommends configuring both authentication methods for the productivity integration. A read-only productivity configuration can use a service account alone, with unsupported actions disabled by Firstup.
After a member connects their ServiceNow account through OAuth, the integration also uses their token to read data, including knowledge search results. Otherwise, knowledge search uses the configured service account.
Service Account Table Access
| ServiceNow table | Data area |
|---|---|
incident |
Incidents |
change_request |
Change requests |
sc_request |
Service requests |
sc_req_item |
Requested catalog items |
sc_task |
Catalog tasks |
alm_asset |
Assets |
sysapproval_approver |
Approvals |
ServiceNow roles and access controls govern the service account’s access to these tables. Work with your ServiceNow administrator and Firstup representative to confirm the permissions required for your configuration.
Actions that modify records, such as adding comments or work notes and approving or rejecting requests, require you to authenticate with your individual ServiceNow account through OAuth. These actions follow your account’s ServiceNow permissions.
Knowledge search uses the ServiceNow Knowledge API rather than the productivity tables listed above. These table-access requirements do not define the permissions needed for a search-only configuration.
Enable Knowledge Search
Enable knowledge search to let users find ServiceNow knowledge articles from your Firstup member Experience.
These steps are only applicable when enabling the ServiceNow search integration.
- Ask your ServiceNow administrator to confirm that the Knowledge API plugin (
sn_km_api) is installed on your ServiceNow instance. If it is not installed, your administrator must install it before knowledge search can be used. - Ask your ServiceNow administrator to configure a dedicated service account with permission to call the Knowledge API and read the knowledge bases and articles intended for search. Confirm the required roles and Can Read user criteria on your ServiceNow instance.
- Review the service account's knowledge access to ensure that all articles it can read are appropriate for every member who can use the search integration.
- Provide Firstup with your ServiceNow instance URL, instance subdomain, and service account credentials. Your Firstup representative will confirm how to share credentials securely.
- Firstup configures knowledge search for your community and enables the
search_enabledsetting. - Test knowledge search with a member who has not connected a ServiceNow account. Confirm that expected articles appear and that restricted articles are excluded. If members also use connected accounts, test that their results follow their individual ServiceNow access rules.
Studio does not check whether the Knowledge API plugin is installed when enabling the integration. The integration can be enabled without the plugin, but knowledge searches will fail until it is installed.
- Members with a connected ServiceNow account: Searches use the member's OAuth token and follow their ServiceNow article access rules.
- Members without a connected ServiceNow account: Searches use the integration's service account. Results follow the service account's access rules, rather than the individual member's permissions.
ServiceNow search does not prompt members to connect their accounts before searching.
Restrict the service account's knowledge access to articles that every member who can use the search integration is permitted to see. Members without a connected ServiceNow account can receive results for any article the service account can read.
You do not need to configure webhooks to enable knowledge search. Webhooks are only required if you want ServiceNow to send push notifications to Firstup.
Configuration Parameters
Firstup configures the integration using the details you provide. Tell your Firstup representative whether you want knowledge search, productivity features, or both, so they can confirm the values required for your setup.
Connection Details
Provide your ServiceNow instance URL and the service account credentials requested by Firstup. Your representative will confirm how to share credentials securely.
| Parameter | Description |
|---|---|
url |
Your full ServiceNow instance URL, such as https://your-subdomain.service-now.com. |
sn_instance |
Your ServiceNow subdomain only. For the example above, this is your-subdomain. |
username |
The username of the dedicated ServiceNow service account used by the integration. |
password |
The password for the dedicated ServiceNow service account. |
Knowledge Search
| Parameter | Description |
|---|---|
search_enabled |
Enables ServiceNow knowledge article search in your Firstup community. Your ServiceNow instance must have the Knowledge API plugin (sn_km_api) installed. |
Productivity Features
Agree with Firstup which actions you want users to perform. Actions that modify ServiceNow records require individual user authentication through OAuth and remain subject to each user’s ServiceNow permissions.
| Parameter | Description |
|---|---|
enable_edit |
Enables editing of supported records, such as incidents and change requests. |
enable_approval |
Enables approval actions for supported requests. |
enable_comment |
Enables comments on supported requests. |
enable_worknote |
Enables adding work notes to supported incidents and tasks. |
rejection_reason_required |
Determines whether users must provide a reason when rejecting a request. |
approval_comments_field |
Specifies the ServiceNow field used to store approval comments. |
approval_comments_plain_text |
Determines whether comments are appended to the comments log as plain text. |
OAuth Parameters
When OAuth is required for your configuration, provide Firstup with the client ID and client secret from your ServiceNow OAuth application. Follow Configure OAuth Authentication to create the application.
| Parameter | Description |
|---|---|
sn_client_id |
The client ID of the OAuth application you create in ServiceNow. |
sn_client_secret |
The client secret of that OAuth application. |
Optional Push Notifications
Webhooks are only required if you want ServiceNow to send push notifications to Firstup. Tell your Firstup representative if you want this capability so they can confirm the additional setup.
| Parameter | Description |
|---|---|
event_authentication_token |
The token included in webhook requests from ServiceNow to Firstup. Firstup will confirm its configuration as part of notification setup. |
oAuth Client Credentials
Before you begin, ask your Firstup representative to confirm the redirect URL for your Firstup environment. Use that URL when configuring your ServiceNow OAuth application.
If you are unsure of how to setup your ServiceNow integration from the steps below, reach out to Firstup who can configure your integration, or assist you.
- Go to System oAuth > Application registry create and click New.
- Select the Create an OAuth API endpoint for external clients.
- Complete the required fields:
- Enter a name for the integration application - (example - Firstup Integration)
-
Redirect URL: Enter the callback URL provided by your Firstup representative.
- Click Submit. The app is saved.
- Open the app and copy the client_id.
- Click on the lock icon next to the Client Secret to reveal. Copy this client_secret.
Comments
0 comments
Article is closed for comments.