blackberry athoc servicenow installation and …...client secret are used to update the application...

BlackBerry AtHoc Networked Crisis Communication

BlackBerry AtHoc ServiceNow Installationand Configuration GuideVersion 1.0 Release 7.6, November 2018

Copyright © 2018 BlackBerry Limited. All Rights Reserved.This document may not be copied, disclosed, transferred, or modified without the prior written consent of BlackBerry Limited. While all content is believed to be correct at the time of publication, it is provided as general purpose information. The content is subject to change without notice and is provided “as is” and with no expressed or implied warranties whatsoever, including, but not limited to, a warranty for accuracy made by BlackBerry Limited. The software described in this document is provided under written license only, contains valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States and other countries. Unauthorized use of software or its documentation can result in civil damages and criminal prosecution.

TrademarksTrademarks, including but not limited to ATHOC, EMBLEM Design, ATHOC & Design and the PURPLE GLOBE Design are the trademarks or registered trademarks of BlackBerry Limited, its subsidiaries and/or affiliates, used under license, and the exclusive rights to such trademarks are expressly reserved. All other trademarks are the property of their respective owners. Users are not permitted to use these marks without the prior written consent of AtHoc or such third party which may own the mark.

This product includes software developed by Microsoft (http://www.microsoft.com).

This product includes software developed by Intel (http://www.intel.com).

This product includes software developed by BroadCom (http://www.broadcom.com).

All other trademarks mentioned in this document are the property of their respective owners.

PatentsThis product includes technology protected under patents and pending patents.

BlackBerry Solution License Agreementhttps://us.blackberry.com/legal/blackberry-solution-license-agreement

Contact InformationBlackBerry AtHoc

311 Fairchild Drive

Mountain View, CA 94043

Tel: 1-650-685-3000

Email: [email protected]

Web: http://www.athoc.com

http://www.athoc.com/

https://us.blackberry.com/legal/blackberry-solution-license-agreement

Contents

CHAPTER 1: BLACKBERRY ATHOC SERVICENOW INTEGRATION 1

CHAPTER 2: SOFTWARE REQUIREMENTS 2

CHAPTER 3: CONFIGURE BLACKBERRY ATHOC FOR SERVICENOW INTEGRATION 3Create Client ID and Client Secret 3Create an SDK User 4View an template common name 4

CHAPTER 4: IMPORT UPDATE SETS 6Fix the Update Set XML Preview error 8

CHAPTER 5: CONFIGURE SERVICENOW PARAMETERS 10Configure BlackBerry AtHoc settings 10Create AtHoc Alerts tab 11Create a device pair 13Configure ServiceNow devices 16Get ServiceNow device label and value 17Set up OAuth 19Change the application status 21

CHAPTER 6: CONFIGURE SCHEDULED JOBS TIME INTERVAL 24

CHAPTER 7: SEND A TEST ALERT 26Track the alert status 27

CHAPTER 8: BLACKBERRY ATHOC CUSTOMER PORTAL 30

i

Chapter 1: BlackBerry AtHoc ServiceNow integration

Chapter 1: BlackBerry AtHoc ServiceNow integrationThe BlackBerry AtHoc ServiceNow integration enables IT administrators to share critical information about high-priority IT outages across their organization using multiple notification modalities, leading to a quicker time for responding to and fixing issues. The BlackBerry AtHoc ServiceNow integration provides an easy way for BlackBerry AtHoc alerts to be generated for ServiceNow incidents from ServiceNow.

The BlackBerry AtHoc ServiceNow integration provides the following capabilities:

l A single interface to manage IT issues and notify users.

l Multiple messaging modalities promote faster collaboration.

l Outages can be resolved more quickly and efficiently.

l Logging of alerts published under one ServiceNow incident.

1

Chapter 2: Software requirements

Chapter 2: Software requirementsThe ServiceNow and BlackBerry AtHoc have the following software requirements:

l ServiceNow Jakarta version

l BlackBerry AtHoc release 7.5

2

Chapter 3: Configure BlackBerry AtHoc for ServiceNow integration

Chapter 3: Configure BlackBerry AtHoc for ServiceNow integrationThis section describes how to create a Client ID, Client Secret, and SDK user. The Client ID and Client Secret are used to update the application registry in ServiceNow. A user with SDK role is required to configure the BlackBerry AtHoc settings in ServiceNow.

Create Client ID and Client SecretYou need the Client ID and Client Secret to update the AtHoc OAuth provider record.

Note: Ensure that you note down the Client Secret before navigating to any other page.To create a Client ID and Client Secret, complete the following steps:

1. Log in to the BlackBerry AtHoc management system as an administrator.

2. In the navigation bar, click the (Settings) icon.

3. In System Setup section, click API Applications. The API Applications screen opens.

4. Click New.

5. In the Basic section, in the Name field, type a name.

6. Select the Enabled status check box.

7. In the Authentication section, select the Password option for Grant Type.

8. Click Save. The Client ID and Client Secret are automatically generated.

3

BlackBerry AtHoc ServiceNow Integration Guide

9. Note down the Client ID and Client Secret.

Create an SDK UserTo create a new SDK user, complete the following steps:


2. In the navigation bar, click Users > Users.

3. Do one of the following:

l Create a new user. Click on the newly created user in the user details screen and click Grant Operator Permissions. For detailed information about how to create new user, see "Create a User" in BlackBerry AtHoc Enterprise User Guide.

l Click on an existing user. In the user details screen, click Grant Operator Permissions.

4. In the Operator Roles section, select SDK User from the Operator Roles list.

5. In the Password section, enter and confirm a password for the user.

6. Click Save.

View an template common nameEvery alert template has a common name that is generated automatically when you create a new alert template. You must enter the alert common name in the Settings page of ServiceNow.

To view the common name of an alert template, complete the following steps:


2. Click Alerts > Alert Templates.

3. Click New to create a new template or click an existing alert template.

4. In the alert template, scroll down to the end of the template. The Info section displays the

4

Chapter 3: Configure BlackBerry AtHoc for ServiceNow integration

common name.

Create a new alert templateTo create a new alert template, complete the following steps:


2. Click Alerts > Alert Templates.

3. Click New.

4. In the Alert Template section, enter a template name and description.

5. In the Content section, do the following steps:

a. In the Severity field, select the severity level from the dropdown list.

b. Enter the title and content of the alert.

c. In the Response Options field, click the Add Response Option link to define one or more responses that alert recipients can send to let you know that they have received the message.

6. In the Target Users section, click Select Personal Devices, and then select the devices you want to publish the alert to.

7. In the Schedule section, set a time in the Alert Duration field.

8. Click Save. A confirmation message is displayed at the top of the Alert Templates screen.

5

Chapter 4: Import update sets

Chapter 4: Import update setsThe entire ServiceNow BlackBerry AtHoc integration solution is available in the form of a ServiceNow update set. To deploy this integration solution you must import the update set to a customer's ServiceNow environment. You must import the following two update sets:

l GlobalScopeUpdateSet

l SN-IWS_Alert IntegrationUpdateSetTo import the update sets, complete the following steps:

1. Open the ServiceNow instance and log in with your credentials.

2. In the Filter navigator field, type Retrieved Update Sets. A list of results is displayed.

3. Click Retrieved Update Sets. The Retrieved Update Sets screen is displayed.

4. In the Related Links section, click Import Update Set from XML.The Import XML window opens.

5. Click Choose File and navigate to the update set and attach it.

6


Note: You can only import one update set at a time.

6. Click Upload. The update set is displayed in the Retrieved Update Sets window in Loaded state.

7. Click the Update set record. The Update set record opens.

8. Click Preview Update Set to preview the changes that are captured in the Update set. If you are uploading an existing Update set XML file, you can get an error. To resolve the error, see Fix the Update Set XML Preview error.

Note: With Preview Update set you can only preview the update set changes and cannot commit any changes.

7

Chapter 4: Import update sets

9. Click Commit Update Set.

10. On completion, refresh the main browser window for the changes to take effect.

11. Repeat steps 5 to 10 to import the second update set.

Fix the Update Set XML Preview errorWhen importing the latest Update Set XML for the second time, you can get the following error when previewing the Update Set XML.

To troubleshoot this error, complete the following steps:

8


1. After you click Preview Update Set, a progress bar with the error is displayed.

2. Click Close.

3. In the Update Set Preview Problems tab, click Skip remote update. The Commit Update Set window appears.

9

Chapter 5: Configure ServiceNow parameters

Chapter 5: Configure ServiceNow parametersYou must configure and change some BlackBerry AtHoc environment settings in the ServiceNow console. This section describes how to configure BlackBerry AtHoc settings, create AtHoc Alerts tab in an incident, configure ServiceNow devices, create and view pair devices, and set up OAuth in ServiceNow.

Each ServiceNow module has a star icon next to the name. Use these icons to select or view favorite modules. The star icon for each module can be selected or deselected. These icons are used to select frequently used modules and then display only the favorites in the application navigator.

Configure BlackBerry AtHoc settingsNote: You can only create one connection settings.

To view or update the properties of the BlackBerry AtHoc management system, complete the following steps:

1. Open the ServiceNow instance and log in with your credentials. The ServiceNow home page opens.

2. In the Filter navigator, type BlackBerry AtHoc and then click Settings.

10


3. Click New or open and existing record and complete the following fields:

l BlackBerry AtHoc System URL: https://<iwsserver.domain.com>

l BlackBerry AtHoc Organization ID: <Your Organization ID>

l Username: <Username of user with SDK USER role>

l Password:<Password of user with SDK USER role>

l Scope: openid profile athoc.iws.web.api offline_accessImportant: Copy this value in the Scope field and do not change the value.

l Organization Code: <OrganizationCode>

l Alert Template Common Name: <Common Name of Alert Template>

Note: For detailed information about how to get the common name of an alert template, see Alert template common name.

4. Click Validate.

5. If the connection is successful, click Save.

If you are saving the connection for the first time, a link "Click here to update" link is displayed.

Create AtHoc Alerts tabRelated lists appear on forms and display records in tables that have a relationship to the current record. You can create and send alerts from the AtHoc Alerts tab.

Note: Ensure you select Global application as the current application.To create an AtHoc Alerts tab in an Incident form, complete the following steps:


2. In the Filter navigator, type Incident and click Incident > All. The Incidents screen opens.

3. Click an incident. The Incident detail page opens without AtHoc Alerts tab at the bottom.

11


4. Right-click the header and from the list click Configure > Related Lists. The Configuring related lists window opens.

5. Click AtHoc Alerts> Incident . 6. Click the right arrow to add it to the Selected column.

12


7. Click Save. The AtHoc Alerts tab is displayed in the Incident detail page.

Create a device pairThis section describes how to create a pairing of ServiceNow devices with BlackBerry AtHoc devices.

The mapping of ServiceNow to BlackBerry AtHoc devices is stored as a JSON in a single record in ServiceNow database table. Due to this you can only create one pair devices record.

You can map only one ServiceNow device with one AtHoc device. For example, if you paired the ServiceNow Email device with the AtHoc Email-WorkName device, you cannot pair the ServiceNow Email device with the AtHoc Phone-WorkName device.

To create a ServiceNow AtHoc device pair, complete the following steps:


2. In the Filter navigator, type BlackBerry AtHoc and click Pair Devices. The Pair Devices screen opens.

13


3. Click New to create a new record or click an existing record to pair devices.

4. From the ServiceNow Device list, select an unpaired device.

If you don not see the device in the list, see Configure ServiceNow devices to configure a ServiceNow devices.

5. From the AtHoc Device list, select an unpaired device.

Note: The AtHoc Device list auto-populates the list of devices enabled on BlackBerry AtHoc for your organization.

6. Click Pair Selected. The mapping between the ServiceNow and AtHoc device is created in the Paired Devices table.

14


7. (Optional) Repeat steps 4 to 6 to map multiple ServiceNow and AtHoc devices to create device pairs.

8. Click Save.

View the paired devicesTo view the newly-created ServiceNow and AtHoc paired devices, complete the following steps:

1. Open the ServiceNow instance and log in with your credentials. The ServiceNow console opens.


15


3. Click the record to open it. You can see the list of paired devices.

Configure ServiceNow devicesNote: Ensure you select AtHoc Alerts as the current application.

To configure ServiceNow devices, complete the following steps:



3. Click New if there is no record of paired devices or click an existing record. The Pair Devices screen opens.

4. Right-click ServiceNow Device and click Show Choice List. The Choices screen opens.

5. Click New to configure a new ServiceNow device or click an existing record to modify it.

6. Fill in the following details:

l Table: Pair Devices x_80966_iws_alert_device_mapping

l Element: u_servicenow_device

l Language: en

16


l Label: <Label of the field present in USER TABLE and not displayed in the list>

l Value: <Value associated with Label>

The Label and Value should match with the corresponding Label and Value fields of the sys_user table of ServiceNow. For detailed information about how to get the label of the device in sys_user table, see Get ServiceNow device label and value.

7. Click Submit. 8. (Optional) Repeat steps 4 to 7 to configure other ServiceNow devices.


10. Click New or click an existing record to open.

11. Click ServiceNow Device list to view the list of configured devices.

Get ServiceNow device label and valueTo get ServiceNow device label and value, complete the following steps:


17


2. In the Filter navigator, type sys_user.LIST and press the Enter key. The Users table opens in a new tab.

3. Click any user record. The user record opens.

4. Right-click the field that you want to configure as ServiceNow device and click Configure Dictionary. For example, email, Business phone, or Mobile phone. The Dictionary Entry for the selected field opens.

5. Copy the values from the Column label and Column name fields.

18


6. Repeat steps 4 to 5 to get values for other fields that you want to configure as ServiceNow devices.

Set up OAuthThe ServiceNow BlackBerry AtHoc integration syncs users from ServiceNow to BlackBerry AtHoc using the REST API. The authentication type used in the REST API is OAuth Authentication. With OAuth authentication, you can access BlackBerry AtHoc resources from ServiceNow by obtaining a token instead of entering login credentials for each resource request.

Note: You must have ServiceNow administrator permissions.To enable OAuth authentication for the ServiceNow AtHoc integration, complete the following tasks:

1. Ensure the OAuth plug-in is active.

2. Ensure the OAuth activation property is set to true.

3. Update the application registry.

Activate OAuthBy default, the OAuth 2.0 plug-in is active on new and upgraded instances. If the plug-in is not active on your ServiceNow instance, you can activate the plug-in.

Note: You must have administrator permissions.To activate OAuth, complete the following steps:


2. In the Filter navigator, type System Definition and click Plugins. The System Plug-ins screen opens.

19


3. Search for OAuth 2.0 and check if the plug-in status is active.

4. If the status is inactive, complete the following steps:

a. Click OAuth 2.0. The System Plug-in window opens.

b. In the Related Links section, click Activate/Upgrade.

Set the OAuth propertyTo generate OAuth 2.0 tokens and register applications, the com.s-nc.platform.security.oauth.is.active property must be active for the instance.

Note: You must have administrator permissions.To set the OAuth properties, complete the following steps:

1. Open the ServiceNow instance and log in with your credentials. The ServiceNow console opens.

2. In the Filter navigator, type sys_properties.list and press the Enter key. The System Properties window opens.

3. Search for com.snc.platform.security.oauth.is.active and verify if the value is set to true.

4. If the value is not set to true, complete the following steps:

a. Click com.snc.platform.security.oauth.is.active b. To edit, click the here link.

c. In the Value field, type true.

d. Click Update.

20


Update the application registryFor detailed information about how to create a client ID and client secret, see the Create Client ID and Client Secret section.

To update the application registry, complete the following steps:


2. In the Filter navigator, type Application Registry and press the Enter key. The Application Registries screen opens.

3. Click AtHoc OAuth Provider. The Application Registry screen opens.

4. In the Client ID field enter the client ID.

5. In the Client Secret field, enter the client secret.

6. Update Redirect URL to https://<your_instance_name>.service-now.com/oauth_redirect.do.

7. Update Token URL to https://<i-wsserver.domain.com>/AuthServices/Auth/connect/token.

8. Click Update.

Change the application statusTo change the current application status to Global or AtHoc Alerts, complete the following steps:


2. In the navigation bar, click the Settings icon. The System Settings page opens.

21


3. Click Developer.

4. In the Developer section, from the application list select Global or AtHoc Alerts.

22


23

Chapter 6: Configure scheduled jobs time interval

Chapter 6: Configure scheduled jobs time intervalTo configure a scheduled job at specific time interval, complete the following steps:


2. In the Filter navigator, type Scheduled Jobs and click System Definition > Scheduled Jobs.

3. Search for the job with the following names:

l AtHoc Alert Publish Job—Scheduled job to publish an alert.

l AtHoc Alert Tracking Job—Scheduled job for tracking alert summary, details, and status.

l Update Alert Details—Scheduled job to update the alert details in the Alert table.

4. Click a scheduled job. The Scheduled Jobs screen opens.

5. From the Run list, select an interval to schedule the job.

24


6. In the Repeat Interval section, update the execution time interval.

Note: The default time interval is set to 1 minute.

7. Click Update.

25

Chapter 7: Send a test alert

Chapter 7: Send a test alertTo verify the configuration in ServiceNow, send a test alert.

To send a test alert from ServiceNow to Blackberry AtHoc, complete the following steps:


2. In the Filter navigator, type Incident and then click Incident > All. The Incident screen opens.

3. Click an incident record for which you want to create an alert. The incident record opens.

4. Click the AtHoc Alerts tab and click New to create a new alert. The New alert window opens.

5. Enter a title for your alert.

6. (Optional) Enter the content for your alert in the Body field.

7. (Optional) Select a severity for the alert from the Severity list.

8. (Optional) In the More info link field, enter a URL to include in the alert.

9. In the Target Groups section, select a target group.

10. In the Target Users section, select target users.

Note: You must either select a target user or target group from the Target Users or Target Groups section.

11. Select the delivery methods you want to use to send your alert. You must select at least one delivery method.

12. Click Send. A Send Alert confirmation message window is displayed.

13. Click Send. You are redirected to the Alert Tracking page that displays the alert status and tracking details.

26


Track the alert statusOnce you have successfully created an alert, you are redirected to the Alert Tracking page.

Observe the following to track the alert status:

1. When the User Sync API is executed, the Alert Tracking page displays any one of the following User Sync API statuses:

l User Sync failed: When the user sync with BlackBerry AtHoc fails for all the targeted users in the alert.

27

Chapter 7: Send a test alert

l User sync partially successful: When the user sync with BlackBerry AtHoc fails for some users targeted in the alert.

l Users Sync Complete: When the user sync with the BlackBerry AtHoc is successful for all users targeted in the alert.

2. When the User Sync API is complete or partially successful, the Alert Publish API is executed. The status of the sent alert is displayed on the Alert Tracking screen.

Note: Alert Publish API targets the alert to only synced users.

3. After the Alert Publish API status is successful, then Alert tracking APIs are executed. It might take a while for the alert tracking page to display the tracking details. Auto-Refresh functionality updates the tracking details once a minute. Click Refresh to view the latest tracking details immediately.

Note: After the Alert Tracking API is executed successfully, the API status is no longer displayed in the Alert tracking screen.

28


4. In the Delivery Summary section, click on the links to view the details of:

l Users for whom the user sync with BlackBerry AtHoc failed

l Total users targeted by the alert

l Actual users targeted by the alert

l Users reachable by the alert (Sent)

l Users unreachable by the alert (Not Sent)

l Groups that were added to Target Groups during alert creation

5. (Optional) Click View Tracking Details to view the list of targeted users and devices for the alert.

29

Chapter 8: BlackBerry AtHoc customer portal

Chapter 8: BlackBerry AtHoc customer portalBlackBerry AtHoc customers can obtain more information about BlackBerry AtHoc products or get answers to questions about their BlackBerry AtHoc systems through the Customer Portal:

http://www.athoc.com/customers/customer-support.html

The BlackBerry AtHoc Customer portal also provides support through computer-based training, Operator checklists, best practice resources, reference manuals, and user guides.

30

http://www.athoc.com/customers/customer-support.html

blackberry athoc servicenow installation and …...client secret are used to update the application...

Documents