Ivanti Service Manager

⚠️

Important

You must purchase this integration separately for both your Remote Support software and your Ivanti Service Manager solution. For more information, contact BeyondTrust's Sales team.

Support and IT organizations using Ivanti Service Manager can integrate with BeyondTrust Remote Support to improve service levels, centralize support processes, and strengthen compliance. This document describes the installation and configuration of the BeyondTrust Remote Support integration with Ivanti.

The integration between Ivanti and BeyondTrust Remote Support enables service desk technicians to launch a secure remote support session directly from within Ivanti.

The Ivanti integration with BeyondTrust Remote Support provides the following functionality:

• A self-service user can start a BeyondTrust click-to-chat session directly from an incident within Ivanti.
• A representative can generate a session key directly from an incident, change, or service request.
• Details of all BeyondTrust sessions initiated from an incident, change, or service request context are linked to the associated item and are viewable as a list as well as in a detailed view on each item type.
• While in a BeyondTrust session linked to a Ivanti item, a custom link in the BeyondTrust representative console allows a representative to launch a browser window directly to the Ivanti item in order to view additional information.
• A BeyondTrust Jump session can be initiated to access a configuration item from an incident, with the Jump session details being linked to the incident.
• If a session originates outside the normal Ivanti workflow, with a ticket for the incident already existing in Ivanti, the representative can manually link the session to the Ivanti ticket to ensure all details are captured in the Ivanti system.
• With assistance from BeyondTrust Professional Services, the integration can automatically generate incidents in Ivanti when a session is received, thus saving a number of steps for the support representative.

Prerequisites

To complete this integration, please ensure that you have the necessary software installed and configured as indicated in this guide, accounting for any network considerations.

Applicable versions

• BeyondTrust Remote Support: 18.1 and newer
• Ivanti Service Manager (formerly HEAT Software): 2015.2 and newer (includes cloud and on-premises releases)

Network considerations

The following network communication channels must be open for the integration to work properly.

Prerequisite installation and configuration

The Ivanti Service Manager integration is a BeyondTrust Middleware Engine plugin.

ℹ️

Note

For more information on installing and working with the BeyondTrust Middleware Engine, see the Middleware Engine Guide.

Configure Ivanti Service Manager

ℹ️

Note

Before importing the package, use a text editor to ensure all URLs to the B Series Appliance have been updated. To do so, search for support.example.com and replace any instances with the hostname of the B Series Appliance.

A development package is provided as part of the integration: BeyondTrust Standard Integration - Core - 1.x.x.MetadataPatch.

⚠️

Important

Before applying any development package, we recommend that you first back up the database in case changes need to be rolled back.

The Core development package contains all the necessary business objects, quick actions, etc., needed by the integration.

Once the contents of the Core development package have been verified:

1. Make sure you have taken the steps described in the note above to find and replace the example B Series Appliance hostname in the package file.
2. Log in to the Ivanti tenant as an administrator and access the admin UI.
3. Under Build > Development Package > Packages, select Import Package and browse to the file.
4. When the development package is successfully imported, a new BeyondTrust API Role should be listed under Configure > Users and Permissions > Roles.
5. Select the role and add a new employee to be used for API calls.
6. Ensure that Internal Auth is enabled.
7. Ensure that an Internal Auth Password is set.
8. Ensure that Password Expiration is disabled.

Update the user interface

1. Under Build > Business Objects, select Change > Layouts, and then click the Change layout.
2. In the Views in this layout grid, select formView to edit the view.
3. Click the Edit link to the right of the Toolbar section.
4. In the Toolbar Editor, find and select the BeyondTrust - Generate Session Key action from the list at the bottom and drag it into position as the first item in the right half of the toolbar menu.
5. Configure the new toolbar button as follows:

6. Click Save on the Button Editor and Save again on the Toolbar Editor.
7. Scroll to the bottom of the Child Panels grid and click the link to Add Child Panel.
8. Configure the new panel as follows:

9. Click the Edit link in the Toolbar column and drag all of the toolbar buttons for the panel to the trash so that no buttons show on the BeyondTrust Sessions panel.
10. Click Save at the top to save all changes to the layout.
11. Repeat steps 1 through 10 for the Change.SDA and Change.SDM layouts and/or any custom layouts you may be using instead of these default layouts.
12. Under Build > Business Objects > Service Request, select the Service Request business object, and then repeat steps 1 through 10 for the ServiceReqLayout.New layout and/or any custom layouts you may be using instead of these default layouts.
13. Under Build > Business Objects > Incident, select the Incident business object, and then repeat steps 1 through 10 for the IncidentLayout.ServiceDesk layout and/or any custom layouts you may be using instead of these default layouts.
14. With the Incident business object still selected, swap from Layouts to Forms, and then select the IncidentDetails.ServiceDesk form.
15. Check the box to Show layout cells, and select the cell containing the Assets control.
16. Click the link above the form to Insert Row Above.
17. Expand the toolbar to the left of the form to show Incident > Fields, and then drag the CILink field into the newly created row.
18. Click the new control to select it, and then configure it as follows:

19. Collapse the Incident tree in the toolbar, expand it to show Other items, and then drag a URL Button to the right of the CILink field.
20. Select the new button and configure it as follows:

21. Click Save at the top to save changes to the form.
22. Select the Incident.WebSelfService.Edit form.
23. Expand the toolbar to show Other items, and then drag a Command Button to the right of the Close Incident button on the form.
24. Select the new button and configure it as follows:

25. Click Save at the top to save changes to the form.

Configure Remote Support

Several configuration changes are necessary on the B Series Appliance to integrate with Ivanti Software. You must make these changes on each B Series Appliance for which you intend to create a plugin configuration, described in Configure the Ivanti plugin for integration with BeyondTrust Remote Support.

All of the steps in this section take place in the BeyondTrust /login administrative interface. Access your Remote Support interface by going to the hostname of your B Series Appliance followed by /login (e.g., https://support.example.com/login).

Verify the API Is enabled

This integration requires the BeyondTrust XML API to be enabled. This feature is used by the BeyondTrust Middleware Engine to communicate with the BeyondTrust APIs.

Go to /login > Management > API Configuration and verify that Enable XML API is checked.

Create an OAuth API account

The Ivanti Service Manager API account is used from within Ivanti Service Manager to make Remote Support Command API calls to Remote Support.

1. In /login, navigate to Management > API Configuration.
2. Click Add.
3. Check Enabled.
4. Enter a name for the account.
5. OAuth Client ID and OAuth Client Secret is used during the OAuth configuration step in Ivanti Service Manager.
6. Under Permissions, check the following:
   • Command API: Full Access.
   • Reporting API: Allow Access to Support Session Reports and Recordings, and Allow Access to Presentation Session Reports and Recordings.
7. Click Save at the top of the page to create the account.

Add an outbound event URL

1. Go to /login > Management > Outbound Events.
2. In the HTTP Recipients section, click Add and name it Integration or something similar.
3. Enter the URL to use:
   • If using an appliance ID of default: http://:/ERSPost. The default port is 8180.
   • If using an appliance ID other than default: http://:/ERSPost?appliance= where is the hostname where the BeyondTrust Middleware Engine is installed. The default port is 8180. The is an arbitrary name, but note the value used, as it is entered later in the plugin configuration. This name accepts only alphanumeric values, periods, and underscores.
4. Scroll to Events to Send and check the following events:
   • Support Session End
   • Customer Exit Survey is Completed
   • Representative Survey is Completed
   • Someone Joins a Support Session (Optional)
5. Click Save.
6. The list of outbound events contains the event just added. The Status column displays a value of OK if communication is working. If communication is not working, the Status column displays an error which you can use to repair communication.

Add custom fields

Under Configuration > Custom Fields, add two new custom fields. Enter the following values:

Add a custom link

BeyondTrust custom links can be configured to allow representatives to quickly access the Ivanti item that is associated with the session.

1. Browse to Rep Console > Custom Links.

2. Click Add.

3. Enter a name for the link, and then set the URL to

   https://support.example.com/files/IvantiCustomLink.html?view=1&externalKey=%SESSION.CUSTOM.EXTERNAL_KEY%
   

   with support.example.com as your BeyondTrust site hostname.

ℹ️

Note

The page referenced in the custom link URL does not yet exist but is created at the end of the next section (Configure the Ivanti plugin).

4. Click Save to save the new link.

Configure the Ivanti plugin

Now that you have configured Ivanti Service Manager and the BeyondTrust Appliance B Series, deploy and configure the Ivanti plugin.

ℹ️

Note

For more information on installing and working with the BeyondTrust Middleware Engine, please see the BeyondTrust Remote Support Middleware Engine Installation and Configuration document .

1. Copy the provided plugin ZIP file to the server hosting the BeyondTrust Middleware Engine.

2. Extract the plugin ZIP file to the Plugins folder in the directory where the BeyondTrust Middleware Engine is installed.

3. Restart the BeyondTrust Middleware Engine Windows service.

4. From the server, launch the middleware administration tool. The default URL is http://127.0.0.1:53231.

5. The Ivanti Plugin shows in the list of plugins. Click the clipboard icon to add a new configuration.

BeyondTrust Appliance B Series

The first portion of the plugin configuration provides the necessary settings for communication between the plugin and the B Series Appliance. The configuration sections include:

1. Plugin Configuration Name: Any desired value. Because multiple configurations can be created for a single plugin, allowing different environments to be targeted, provide a descriptive name to indicate how this plugin is to be used.
2. Appliance Id: This can be left as Default or can be given a custom name. This value must match the value configured on the outbound event URL in the B Series Appliance. If outbound events are not being used, this value is still required, but any value may be used.
3. BeyondTrust Appliance B Series Host Name: The hostname of the B Series Appliance. Do not include https:// or other URL elements.
4. BeyondTrust Integration API OAuth Client ID: The client ID of the OAuth account.
5. BeyondTrust Integration API OAuth Client Secret: The client secret of the OAuth account.
6. Locale Used for BeyondTrust API Calls: This value directs the B Series Appliance to return session data in the specified language.
7. Disabled: Enable or disable this plugin configuration.
8. Allow Invalid Certificates: Leave unchecked unless there is a specific need to allow. If enabled, invalid SSL certificates are allowed in calls performed by the plugin. This would allow, for example, self-signed certificates. We do not recommend this in production environments.
9. Use Non-TLS Connections: Leave unchecked unless it is the specific goal to use non-secure connections to the B Series Appliance. If checked, TLS communication is disabled altogether. If non-TLS connections are allowed, HTTP access must be enabled on the BeyondTrust /login > Management > API Configuration page. We strongly discourage using non-secure connections.

ℹ️

Note

When using OAuth authentication, TLS cannot be disabled.

1. Outbound Events Types: Specify which events the plugin processes when received by the middleware engine. Keep in mind that any event types selected here must also be configured to be sent in BeyondTrust. The Middleware Engine receives any events configured to be sent in BeyondTrust but passes them off to the plugin only if the corresponding event type is selected in this section.
   • Support Session End
   • Customer Exit Survey is Completed
   • Representative Survey is Completed
2. Polling Event Types: If network constraints limit connectivity between the B Series Appliance and the middleware engine such that outbound events cannot be used, an alternative is to use polling. The middleware engine regularly polls the B Series Appliance for any sessions that have ended since the last session was processed. At this time, only the Support Session End event type is supported.

ℹ️

Note

One caveat to polling behavior versus the use of outbound events is that if a session has ended but the customer exit survey has not yet been submitted within the same polling interval, the customer exit survey is not processed. This does not apply to representative surveys since the session is not considered to be complete if a representative survey is still pending.

2. Polling Interval: Enter only if polling is used. This determines how often the middleware engine polls the B Series Appliance for sessions that have ended.
3. Retry Attempt Limit: Enter the number of retries that can be attempted if the plugin fails to process an event.
4. Retry Outbound Event Types: Specify which outbound events the plugin retries if it fails to process an event.
5. Retry Polling Event Types: Specify which polling events the plugin retries if it fails to process an event.

Ivanti Service Manager instance

The remainder of the plugin configuration provides the necessary settings for communication between the plugin and the Ivanti Software instance. The configuration settings include:

1. Ivanti SDK Web Services URL: The SDK Web Services URL for the Ivanti instance. For example, https://ivanti.example.com/ServiceAPI/FRSHEATIntegration.asmx).
2. Ivanti Username: The username of the API account.
3. Ivanti Password: The password of the above user.
4. Ivanti Tenant ID: The ID of the tenant instance targeted by the integration. If unknown, you can find this by logging into the ConfigDB web interface and viewing the Tenants list. The Tenant ID is listed as the Login URL in the list and detail views.
5. Enable Automatic Incident Creation on Session Start: If checked, the plugin processes support_conference_member_added events and the external key to determine whether to create a ticket within Ivanti or not. The plugin attempts to create the ticket only if this setting is enabled, if the conference member joining the conference is a representative, and if the external key is a JSON string.
6. Ticket Owner Info Source: By default, the integration uses the BeyondTrust representative's username to identify them as the owner of the newly created ticket. Optionally, it can also use the representative's public display name in various formats or ignore the representative's information altogether, instead always using the default value supplied in the JSON string configured for Ticket Default Data.
7. Ticket Default Data: A JSON string containing values that can be used to prepopulate certain fields on the newly created ticket.

Once all settings have been entered, Save the configuration.

Test settings and generate HTML content

Once the proper configuration has been entered and saved, use the tool's Test this Plugin Configuration function to verify the settings. In addition to verifying settings for both BeyondTrust and Ivanti, the page outputs a snippet of HTML that is used in the creation of an intermediate page used for custom links. Once the settings are successful and the markup is generated, create the custom link as described below.

Create the custom link page

Create an empty text file using Notepad or another text editor and copy and paste the HTML content from generated content on the plugin test page into the file.

1. Save the file as IvantiCustomLink.html.
2. Repeat the above steps to copy the JS content into a separate file, and save the file as IvantiCustomLink.js
3. Log in to the BeyondTrust /login interface and upload both files to the file store, under Public Portals > File Store.

Report templates

On the BeyondTrust Middleware Engine server, in the \Plugins\\Templates folder, there are multiple files ending with *.hbs. These are Handlebars template files. These files are used by the plugin to format the session report and exit surveys that are added to the corresponding ticket each time a BeyondTrust session ends or each time a survey is submitted. The templates can be edited if desired.

ℹ️

Note

If you are editing a template, we recommend copying and saving the original in case the changes need to be reverted.

See the Handlebars website for more information.

Use cases

Generate session key

Support staff can generate a session key that can be given to the end user over the phone or via email to initiate a support session that is automatically associated with the selected ticket.

Import BeyondTrust session data into ticket

Once the session ends, the ticket is automatically updated with information gathered during the session, including:

• Chat Transcript (including files transferred, special actions, and other events)
• System Information (the General section plus other select details such as disk, memory, and network)
• Session Notes
• Surveys (customer and representative)

Jump to configuration item

Support staff can leverage BeyondTrust Jump Technology to access a configuration item associated with a ticket directly from the Ivanti ticket. By default, the button attempts to Jump to a pinned Jump Client, but the URL can be modified to perform one of the other Jump types as needed.

Click-to-chat for self service users

Self Service users can open their submitted tickets and start a chat support session directly from the Ivanti ticket. This allows the user the quickest path to resolution while also providing the representative with the necessary context to assist the user. Sessions can be elevated to full support sessions if enabled and when necessary.

Access ticket from representative console

Using BeyondTrust's custom links ability, a representative can access the associated ticket directly from within the representative console. This saves time searching for the ticket in Ivanti and provides the representative with any available issue details, history, or other context to help quickly resolve the issue.

Manually associate sessions with tickets

Whether a representative has just created a ticket for the current session or has found that one already exists, even sessions originating outside the scope of a Ivanti item can be manually associated with the appropriate item, allowing session details to be automatically added to the ticket when the session ends.

To make this association, the representative enters the numeric ID of the Change, Incident, or Service Request into the External Key field while in session. Because these numeric IDs are not unique across business objects in Ivanti, the representative can indicate the appropriate item type with a -c (change), -i (incident) , or-s (Service Request) appended to the end of the number. For example, 15302-i would be associated with Incident #15302.

Automatic ticket creation

Simplify workflows and reduce the number of clicks necessary for a support representative by automatically creating a ticket from a session.

ℹ️

Note

This feature requires a separate services engagement to implement.