Gateway Administration
Introduction
A gateway is a network node used to connect two networks with different transmission protocols. A gateway serves as an entry and exit point for a network as all data must pass through or communicate with the gateway prior to being routed.
In the context of Resolve Actions Pro, a gateway serves as a connecting point between the platform and external systems.
This document describes two functionalities that are part of the Gateway Administration section of Actions Pro platform. It gives details on how to monitor gateways and how to work with the gateway filters.
Gateway Administration
To check the status of one, several or all gateways available in the system, go to Main Menu > Remote Administration > Gateway Administration.
The Gateway Administration dashboard that appears displays information for all active gateways on the platform:
The Dashboard
In the first column on the Gateway Administration page is specified the instance on which a gateway is available. The Hierarchy column contains the queue of Primary gateways or Secondary, if a Primary has failed. You can sort the order of appearance in the Gateway Type column. Columns can be removed or others can be added using the Add/Remove Columns icon at the end of the Column title row.
The RSRemote Name column contains a number, for example, DEV-DOC01.EXAMPLE.COM which is the RSRemote identificatory. When you hover over this number on the grid, a longer number appears. It is called 'a composite name' and contains the UUID, followed by the DNS and the RSRemote number. This way each gateway has a unique identifier.
GUID (or UUID) is an acronym for 'Globally Unique Identifier' (or 'Universally Unique Identifier'). It is a 128-bit integer number used to identify resources. DNS stands for Domain Name Server.
Searching, Filtering and Sorting Information
On the Gateway Administration page you can use filters to diminish the unnecessary data, you can apply concrete search criteria to find a specific gateway, as well as you can sort the information in each column on the grid.
Searching Information
The Search field allows you to access directly а specific gateway by its name. Note that if you need to perform a search through the entire list, the Gateway Type filter must be set on All.
If, for example, you are searching for a REMEDY gateway but the Gateway Type is set to EWS, no gateways of the REMEDY type will be displayed, despite of the fact that there are such in the system.
The Gateway Type Filter
To see specific gateways filtered by their type, use the Gateway Type drop-down menu to select the type of gateways you want to review.
Example
Selecting the REMEDYX Gateway Type displays the available gateways in the system, their RSRemote Name identification number, the position in Hierarchy of each gateway - is it Primary or Secondary, their health check Status and Active status. The data in each column can be sorted by clicking the arrow icon next to the column title. After clicking on it, the arrow turns green which is an indicator of a selected column.
If you need to have additional information displayed in the grid or removed from it, click the Add/Remove Columns icon and then select the columns that you want.
The Active Gateways Filter
The Active Gateways only filter is selected by default. To check the status or get another information about non-active gateways, simply deselect the checkbox.
Sorting Information
You can sort the data in each column available on the Gateway Administration page.
For example, clicking on the arrows next to the Gateway (Queue) Name and Gateway Type columns sorts the information in ascending or in descending order, alphabetically.
The width of each column is adjustable and you can change the order of the columns.
Gateway Health Check
Currently, there are three types of gateways in Actions Pro for which health check is available: HTTP, IBM MQ and SNOW.
It is planned to implement Health Check for more gateways in future.
In Actions Pro, there are four status indicators in use - grey (no status), green (healthy = valid license and valid health check), yellow (warning) and red (expired).
All gateway status indicators have associated messages, providing appropriate information.
A gateway is considered healthy (green), if its license is valid and the individual gateway health check is good. Each gateway has a Health Check specific to that individual gateway.
Licensing check is implemented for all gateways on the Actions Pro platform.
The following table shows the various gateway status indicators.
Color | Gateway Health Status |
|---|---|
GREY | No status yet but Detailed status message is: |
GREEN | License is valid and root URL Detailed status message is: |
YELLOW FAILED_TO_RUN FAILED_TO_CONDUCT FAILED_TO_REPORT_IN_TIME | Gateway license is of type V2, environment is PRODUCTION and is expired. Detailed status message is: OR Failed to check license type is V2 and if license has expired and whether environment is PRODUCTION. Detailed status message is: OR Failed to access root URL Detailed status message is: Where OR RSView failed to conduct gateway health check as it could not get message handler name from HTTP gateway configured with specified queue name. Detailed message is OR Gateway failed to conduct health check and respond back with health check status report within 30 seconds to synchronous health check request via JMS by RSView. Detailed message is |
RED | Gateway license has expired indicating either license type is not V2 and gateway license has expired or license type is V2 and environment is notPRODUCTION and license has expired. Detailed status message is: |
HTTP Gateway
An HTTP gateway is a push type of gateway that receives information from 3rd parties. It is considered healthy (green) if license is valid and root URL "/" is accessible. Also:
- If user name and password are specified then HTTP Basic Authentication is used for accessing root URL "/".
- HTTP filters can also optionally set filter specific Basic Auth username and password which is different from the one specified in the above.note
In both the new React UI and old Extjs UI these fields are displayed irrespective of authentication type setting in blueprint. The values are used only if authentication type is set to BASIC in blueprint property file and is ignored if blank.
- If SSL is configured then uses https to access root URL.
- Access to root URL "/" means expected HTTP status Not Accessible (405) as root URL "/" of HTTP gateway is not accessible externally .
Gateway health check does not result in execution of any runbooks as no filter can be created with root URL "/" in HTTP gateway.
Implementation Details
PRIMARY RSView conducts gateway health checks every 10 minutes (by default) on all active gateways. Regarding the health check:
- Health check reports returned by gateways are stored in a database (gateway_health_check table).
- No health check history of gateways is maintained currently.
If a gateway fails to report back for two consecutive health check requests from RSView, it is considered as stale.
IBM MQ Gateway
IBM MQ gateway is a messaging gateway service that supports application integration by enabling the transfer of data across multiple platforms using queues, sending and receiving data as messages. The MQ Gateway Service only supports MQ Server to MQ Server connections.
Health Status check can only performed on Primary gateways. For a healthy (status GREEN):
- IBM MQ Gateway must have valid license
- the client IBM WebSphere MQ must be reachable
- all deployed filters must stayed connected to the queue manager
Implementation Details
IF the gateway's license is invalid then the gateway is considered unhealthy (RED). No further logic is applied.
ELSE IF there are deployed filters AND
- All deployed filters are currently connected to the queue manager then the gateway is healthy (GREEN).
- None of the deployed filters is connected to the queue manager then the gateway is unhealthy (RED).
- Some the deployed filters are connected and some aren't not connected to the queue manager then the gateway is unhealthy (YELLOW).
ELSE
- IF the IBM WebSphere MQ server is not reachable then the gateway is unhealthy (RED).
- ELSE the gateway is healthy (GREEN).
In case there are exceptions in attempts to access the queue manager OR in attempts to reach the IBM WebSphere MQ server, the status is RED.
SNOW Gateway
SNOW gateway service is of pull type - it is reaching out and pulling the necessary information from 3rd parties.
To have a healthy (status GREEN), a SNOW Pull Gateway must have valid license and must be able to PULL events from the client the gateway acting upon.
Implementation Details
IF the gateway's license is invalid then the gateway is considered unhealthy and the status is RED. No further logic is applied.
ELSE the last incident from the client for which the SNOW Pull Gateway is acting upon is queried.
- IF the query fails due to authentication or authorization then the gateway is considered unhealthy and the status is RED.
- ELSE IF the query fails due to the server is unreachable then the gateway is considered unhealthy and the status is RED.
- ELSE the gateway is healthy and the status is GREEN.
Gateway Administration: Actions
To activate the Actions options on the Gateway Administration page, click a gateway to highlight it and then open the Actions drop-down menu.
Actions: Gateway Configuration
Allows you to access the configuration settings of the selected gateway.
To change the settings, click Edit. This action locks the file, preventing others from making changes to it. Make the necessary changes on the file and click Save Changes, which unlock the configuration file.
In the confirmation prompt that appears, click Continue to deploy the new configuration setting to the gateway.
To go back to the Gateway Administration screen, click the arrow next to the Gateway Configuration title.
Similarly, you can use the same button to go back from the Gateway Filter Administration screen to the Gateway Administration Dashboard.
Actions: Gateway Details
Allows you to see more information about a gateway.
The green color of the icon in front of the filter name indicates that the item is deployed. If the filter is not deployed, the color of the icon is purple.
Actions: Filter Configuration
Allows you to access the list of filters for a gateway. The Gateway Filter Administration screen contains information about the gateway type, available filters and gateway addresses, whether a filter is deployed or not, and more.
By default, this page is set to open directly the Filters column. The gateway addresses column (in the case of this example: EWS Addresses) contains information about the gateway addresses and lists deployed filters, if any.
You can add or remove columns on the Gateway Filter Administration screen by clicking on the Add/Remove Columns icon.
You can also access the Gateway Filter Administration screen from the Main Menu > Remote Administration > Gateway Filter Administration.
Creating New Filter
You can add a new filter to an existing gateway from the Gateway Filter Administration screen and click the Create New button.
The New Filter Name screen displays, allowing you to fill in basic and additional settings to the filter, to use the vast Script area.
The Active checkbox is marked by default.
When you click the Save button, if the action was successful, a confirmation message displays.
The newly created filter appears on the related gateway filter page immediately.
The Save As action on the Save drop-down is inactive for creating new filters.
Editing an Existing Filter
To make changes on the settings of an existing filter, simply click on its name in the list.
On the filter information screen, edit the required information and click the Save button.
If you want to use an existing filter and save it under different name and with different settings:
- Click the Save As button which is now active.
- On the Save As New window, enter the new name and click Confirm.
If the Save As New action was successful, confirmation message appears.
The newly saved filter is listed on the grid immediately.
Deploying Gateway Filters
On the Gateway Filter Administration page you can execute the following actions:
- Remove and replace existing filters on a single gateway—Requires the selection of a single RSRemote queue. All previously deployed filters (if any) on the queue are undeployed before deploying the selected filters.
- Remove and replace existing filters on multiple gateways—Same as the previous strategy, but allows applying it to multiple RSRemote queues that you are prompted to select.
- Append to existing filters on multiple gateways—Deploys the selected filters to one or more RSRemote queues without affecting previously deployed filters (if any). If your selection contains filters that were previously deployed, they will be ignored. You are prompted to select the RSRemote queues where you want to deploy.
See Deploying or Undeploying a Filter for details.
Multiple Gateway Instances
You can set up multiple instances of pull gateways (such as ServcieNow) on a single RSRemote instance, which acts as a container for gateways.
Pull gateways, as the name suggests, pull incident or event data from external systems. There could be use cases where you require data from multiple external systems of the same type. Instead of deploying multiple RSRemote instances, you can set up multiple gateway instances on a single RSRemote.
List of Gateways Supporting Multiple Instances
The following pull-type gateways can be set up in a multi-instance fashion on a single RSRemote:
- Database (DB Gateway)
- Builder
- ServiceNow
- EWS
- RemedeyX
- Netcool
- CA Spectrum
Configuring Multi-instance Gateways
You configure multiple instances of the same gateway type by creating a customized copy of the gateway's blueprint.properties properties. Keep the following in mind when making the copy:
- To set the instances apart, suffix the gateway name in the properties with
-<unique alphanumeric suffix>where the suffix can be a single number or letter, or a combination of letters and numbers. It needs to be unique within the specific gateway type. - Each gateway instance's queue name must be unique.
- Only one of the gateway instances can be primary at any given time.
See thersremote.receive.servicenow.primaryandrsremote.receive.servicenow.secondaryproperties for details.noteIf the primary instance is not running, the secondary instance will take over to become primary.
Assume the existing set of ServiceNow gateway properties are not suffixed, as follows:
<rsremote instance name>.receive.servicenow.<….>=
...
<resremote instance name>.receive.servicenow.<….>=
To add another set of ServiceNow gateway properties, copy the existing lines and then modify them as follows:
<rsremote instance name>.receive.servicenow-2.<….>=
...
<resremote instance name>.receive.servicenow-2.<….>=
Multi-instance Gateway Example
The code sample below demonstrates the full blueprint.properties configuration of a pair of ServiceNOW gateway instances on a single RSRemote instance named rsremote and using queues named SERVICENOW and SERVICENOW2.
First (default) instance of the gateway:
rsremote.receive.servicenow.active=true
rsremote.receive.servicenow.queue=SERVICENOW
#if primary=true secondary must be false
rsremote.receive.servicenow.primary=true
#if secondary=true primary must be false
rsremote.receive.servicenow.secondary=false
#you may set it to false in primary/secondary
#so it simply distribute data to workers
rsremote.receive.servicenow.worker=true
rsremote.receive.servicenow.heartbeat=20
rsremote.receive.servicenow.failover=60
rsremote.receive.servicenow.interval=10
rsremote.receive.servicenow.url=https://xxxxx.service-now.com/api/now/v1/table/
rsremote.receive.servicenow.httpbasicauthusername=xxxxx
rsremote.receive.servicenow.httpbasicauthpassword=xxxxxxxxxx
rsremote.receive.servicenow.datetimewebservicename=GetServerDateTime
rsremote.receive.servicenow.uppercase=true
rsremote.receive.servicenow.datetimerestserviceurl=https://xxxxx.service-now.com/api/x_ressy_resolve_sy/resolve_servicenow_service/serverdatetime
rsremote.receive.servicenow.mutualtlsenabled=false
rsremote.receive.servicenow.mutualtlskeystore=
rsremote.receive.servicenow.mutualtlskeystorepass=
rsremote.receive.servicenow.mutualtlstruststore=
rsremote.receive.servicenow.mutualtlstruststorepass=
rsremote.receive.servicenow.headerredirenable=false
rsremote.receive.servicenow.headerredirurl=
rsremote.receive.servicenow.headerredirheader=
rsremote.receive.servicenow.headerredirencauth=true
rsremote.receive.servicenow.proxyhost=
rsremote.receive.servicenow.proxyport=
rsremote.receive.servicenow.proxyuser=
rsremote.receive.servicenow.proxypass=Second instance of the gateway:
rsremote.receive.servicenow-2.active=true
rsremote.receive.servicenow-2.queue=SERVICENOW2
#if primary=true secondary must be false
rsremote.receive.servicenow-2.primary=false
#if secondary=true primary must be false
rsremote.receive.servicenow-2.secondary=true
#you may set it to false in primary/secondary
#so it simply distribute data to workers
rsremote.receive.servicenow-2.worker=true
rsremote.receive.servicenow-2.heartbeat=20
rsremote.receive.servicenow-2.failover=60
rsremote.receive.servicenow-2.interval=10
rsremote.receive.servicenow-2.url=https://xxxxx.service-now.com/api/now/v1/table/
rsremote.receive.servicenow-2.httpbasicauthusername=xxxxx
rsremote.receive.servicenow-2.httpbasicauthpassword=xxxxxxxxxx
rsremote.receive.servicenow-2.datetimewebservicename=GetServerDateTime
rsremote.receive.servicenow-2.uppercase=true
rsremote.receive.servicenow-2.datetimerestserviceurl=https://xxxxx.service-now.com/api/x_ressy_resolve_sy/resolve_servicenow_service/serverdatetime
rsremote.receive.servicenow-2.mutualtlsenabled=false
rsremote.receive.servicenow-2.mutualtlskeystore=
rsremote.receive.servicenow-2.mutualtlskeystorepass=
rsremote.receive.servicenow-2.mutualtlstruststore=
rsremote.receive.servicenow-2.mutualtlstruststorepass=
rsremote.receive.servicenow-2.headerredirenable=false
rsremote.receive.servicenow-2.headerredirurl=
rsremote.receive.servicenow-2.headerredirheader=
rsremote.receive.servicenow-2.headerredirencauth=true
rsremote.receive.servicenow-2.proxyhost=
rsremote.receive.servicenow-2.proxyport=
rsremote.receive.servicenow-2.proxyuser=
rsremote.receive.servicenow-2.proxypass=