Web Gateway Registry in InterSystems IRIS

The InterSystems Web Gateway Registry registers each connected Web Gateway installation with InterSystems IRIS® and provides the infrastructure to allow InterSystems IRIS code to interact with those installations programmatically. Using the Web Gateway Registry, you can perform tasks such as: clearing a Web Gateway’s caches, reading and modifying a Web Gateway’s runtime configuration, and collecting status and log information.

Two classes implement the Web Gateway Registry:

%CSP.Mgr.GatewayRegistryOpens in a new tab — the registry itself. You can use the GatewayRegistry object to clear caches and (most importantly) to retrieve a list of GatewayMgr objects for some or all of the Web Gateways that your instance is connected to.
%CSP.Mgr.GatewayMgrOpens in a new tab — an object which represents an individual Web Gateway, and which provides a suite of methods for interacting with that Web Gateway.

This page describes how to initialize a GatewayRegistry object, retrieve GatewayMgr objects from it, and then use those objects to perform several useful Web Gateway administration tasks. It then concludes by highlighting the available methods for forcing a Web Gateway to reload its configuration after it has been changed by other means.

Note:

To apply changes to a Web Gateway configuration using the Web Gateway Registry, a user must be assigned a role which holds the %Admin_Manage:Use privilege. For read-only interactions, a user may hold either the %Admin_Manage:Use or %Admin_Operate:Use privilege.

Initialize Web Gateway Registry Objects

To manage the Web Gateway installations which are connected to your instance programmatically using the Web Gateway Registry, you must first initialize the Web Gateway Registry objects, as follows:

Instantiate a %CSP.Mgr.GatewayRegistryOpens in a new tab object using the %SYSTEM.CSP.GetGatewayRegistry()Opens in a new tab method, as in the following example:
```
 set wgReg = %SYSTEM.CSP.GetGatewayRegistry()
```
Use the GatewayRegistry object’s GetGatewayMgrs()Opens in a new tab method to retrieve a list of %CSP.Mgr.GatewayMgrOpens in a new tab objects. Each GatewayMgr represents the administrative interface for a single Web Gateway. As detailed in the class reference, GetGatewayMgrs() accepts an optional parameter which allows you to specify which subset of available GatewayMgr objects you wish to retrieve. If no parameter is specified—as in the following example—the method returns a list of GatewayMgr objects for active Web Gateways only, by default:
```
 set wgMgrList = wgReg.GetGatewayMgrs()
```
Identify the GatewayMgr objects which represent the Web Gateways that you want to manage. You can do this by inspecting the values for the GatewayMgr object’s Server, IPAddress, and Port properties, as in the following example:
```
 For n=1:1:wgMgrList.Count() {
     Set wgMgr = wgMgrList.GetAt(n)
     Write !, n, " : "
     Write wgMgr.IPAddress, ":", wgMgr.Port
```
Access GatewayMgr objects, as desired. For example:
```
 set targetWG = wgMgrList.GetAt(2);
```

Administer a Web Gateway Programmatically

Once you have initialized the Web Gateway Registry objects as described in the preceding section, you can administer a Web Gateway connected to your instance using the suite of methods that these objects provide. The examples which follow demonstrate how to perform several useful tasks using Web Gateway Registry methods; refer to the class referenceOpens in a new tab for comprehensive documentation of all the methods available.

List System-Wide Default Parameters

 do targetWG.GetDefaultParams(.params)
 zwrite params

Update System-Wide Default Parameters

 set newParams("Server_Response_Timeout")=30
 do targetWG.SetDefaultParams(.newParams)

List All Connected InterSystems IRIS Servers

 set status1 = targetWG.GetServers(.servers)
 for i=1:1:$ListLength(servers) {
   set server = $List(servers,i)
   write !, i, " : ", server
 }

List Parameters for a Server Access Profile

 do targetWG.GetServerParams("iristest", .serverParams)
 zwrite serverParams

Update a Server Access Profile’s Parameters

 set newServerParams("Maximum_Server_Connections")=250
 do targetWG.SetServerParams("iristest", .newServerParams)

List All Configured Application Paths

 set status2 = targetWG.GetApplicationPaths(.paths)
 for q=1:1:$ListLength(paths) {
   set path = $List(paths,q)
   write !, q, " : ", path
 }

List Parameters for an Application Access Profile

 do targetWG.GetApplicationParams("/csp/example", .pathParams)
 zwrite pathParams

Update an Application Access Profile’s Parameters

 set newAppParams("Application_Status")="Enabled"
 do targetWG.SetApplicationParams("/csp/example", .newAppParams)

Clear a Web Gateway’s Cache

 do targetWG.ClearCache("*")

Force the Web Gateway to Reload Its Configuration

There are occasions when the Web Gateway’s configuration is modified by external agents (i.e. agents other than the Web Gateway’s own Systems Management Suite).

There are two methods for interactively instructing the Web Gateway to reload its configuration, and in a way that doesn’t require a complete restart.

Using the InterSystems IRIS Web Gateway Registry

After initializing the GatewayMgr object which represents the target Web Gateway (targetWG), you can reload the Web Gateway’s configuration using the object’s ActivateCSPIni()Opens in a new tab method, as in the following example:

 set status3 = targetWG.ActivateCSPIni()

When successfully called, the Web Gateway reads its configuration file and activates all changes made.

Using Scripts External to InterSystems IRIS

Scripts should add the following line (case-sensitive) to the SYSTEM section of the modified Web Gateway configuration file:

[SYSTEM]
RELOAD=1

The Web Gateway caretaker daemon checks the RELOAD flag approximately every minute and, if correctly set, reloads and reactivates its configuration and removes the flag from the file. The following message is written to the Event Log after a successful reload operation:

Gateway Management 
Gateway Configuration Reloaded and Reactivated