Choose Which URL Paths Route Requests Through the Web Gateway
After you extend your web server configuration with the InterSystems Web Gateway module, the next step in the process of setting up a Web Gateway connection for your InterSystems web applications is to specify which requests your web server passes along to the Web Gateway to handle, based on the request’s URL’s relative path (that is, omitting components such as the protocol, hostname, and port number).
However, the paths you choose to configure are also important for other stages of the routing process:
-
The Web Gateway uses the request’s relative path (omitting URL components such as the protocol, hostname, and port number) to determine which InterSystems IRIS application server receives the request, based on the application access profiles you define.
-
The InterSystems IRIS application server determines the web application it should invoke for a given request by matching the request’s relative path with the name of one of its web applications.
-
To target a particular InterSystems IRIS instance on a system with multiple instances, the relative paths for which you choose to route requests must include a prefix which uniquely identifies each instance, but which does not prevent the application server from matching the request’s path with one of its web applications.
This page details the relevant criteria used to determine how a request is routed at each stage, based on the relative path specified in the request’s URL. Consider these criteria as you decide the URL paths you use to host your web applications.
This page also includes information about routing requests in the following situations:
-
Multiple InterSystems IRIS instances hosted by a single web server.
-
Multiple InterSystems IRIS instances hosted by a single web server, where the instance prefixes used to address each instance must be customized.
-
Using Apache virtual hosts to route application requests using different host names.
From the Web Server
Generally, a web server applies rules of inheritance when it determines how to handle requests sent to a URL path; if no it applies the configuration directives for the most specific path which matches the given request path.
For example, if the web client sends a request to the relative URL path /Accounts/Invoices, an Apache web server checks its configuration for <Location> blocks in following order, applying the directives within the most specific block it finds.
-
<Location /Accounts/Invoices>
-
<Location /Accounts>
-
<Location />
Refer to your web server’s documentation for details about its routing behavior. How you configure your web server to invoke the Web Gateway for requests at a particular URL path also varies depending on the web server you are using. See this section of the Setup Overview page for a summary; see the appropriate section of Extend Your Web Server Configuration for details.
Through the Web Gateway
The Web Gateway also applies rules of inheritance for application paths; it uses the application access profile for the most specific path which matches to a given request path.
Given the example request from the preceding section (/Accounts/Invoices), the Web Gateway checks whether valid application access profiles are defined for paths in the following order, applying the profile for the most specific path it finds:
-
/Accounts/Invoices
-
/Accounts
-
/ (root)
The Web Gateway automatically defines application access profiles for the /csp and / (root) paths.
Each time you allow the installer to automatically configure your web server to serve the web applications for a new or upgraded instance, the installer overwrites the existing /csp and / (root) application access profiles so that they route requests to your most recently installed or upgraded instance. To avoid inconvenience, when you manually configure an application within the /csp path (such as /csp/foo/bar), define an application access profile for a path subordinate to /csp (such as /csp/foo or /csp/foo/bar).
Application paths are case-sensitive. Application paths cannot contain any dots (periods), because these lead to ambiguity. For example, given the path /csp/samples/menu.csp/csp/foo/bar/baz.cls, the Web Gateway could either interpret this as a request for /csp/samples/menu.csp/csp/foo/bar/baz.cls or as a REST request for /csp/samples/menu.csp (where PATH_INFO is /csp/foo/bar/baz.cls).
To an InterSystems IRIS Application Server
When an InterSystems IRIS application server receives a request from the Web Gateway, it attempts to match the request’s relative URL path to the name of a web application configured on that InterSystems IRIS instance. It then calls the appropriate code for the web application. As with the web server and the Web Gateway, the application server applies rules of inheritance. Given a request for /Accounts/Invoices, the application server would attempt to call application code for an /Accounts/Invoices application first. If no such application is defined, it would attempt to call application code for an /Accounts application.
You may want to host multiple InterSystems IRIS instances on a single web server, and target certain application requests to a certain instance. Taking the previous example, perhaps your organization has a Payable instance (for tracking payments owed to vendors) and a Receivable instance (for tracking payments owed from customers). Both instances host code for the same /Accounts/Invoices application, but the data is different. To make /Accounts/Invoices data available from both Payable and Receivable with a single web server, the request URL must identify the target instance in a way which does not interfere with the ability of the target application server to match the request to the application. The remainder of this section describes how to accomplish this.
Target Applications on Multiple InterSystems IRIS Servers
Some InterSystems IRIS web applications serve a function which is specific to a single InterSystems IRIS instance. For example, every instance includes the code to serve the Management Portal web application. However, the Management Portal provides an interface to administer one instance in particular.
In a system with multiple InterSystems IRIS instances, you can route requests addressed to a specific instance by configuring application access profiles for paths which include the instance’s CSPConfigName parameter as a prefix to the application path. By default, this parameter is the name of the instance, in all lowercase characters. Before an InterSystems IRIS application server determines what application code to invoke in response to a request, it discards the value of its CSPConfigName from the beginning of the application path associated with the request. This allows the web server and the Web Gateway to target an instance uniquely using CSPConfigName as a prefix without requiring any customization to the behavior of that instance’s applications.
Consider the system illustrated in the following diagram:
-
The web client requests the application path for the iris2 instance’s Management Portal home page. The application path is prefixed with the default CSPConfigName for the target instance (iris2).
-
The configuration directives for the hypothetical Apache web server invoke the Web Gateway for requests sent to all relative URL paths within the /iris2 path. This includes the client’s current request.
-
Within the Web Gateway configuration, an application access profile associates requests within the /iris2 path with the server access profile named iris2.
-
The Web Gateway sends the request to the InterSystems IRIS application server at the IP address and port specified by the server access profile iris2.
-
The InterSystems IRIS application server for the iris2 instance discards the first part of the request’s relative path because it matches the default value for the instance’s CSPConfigName: the instance name. Based on the remaining portion of the path (/csp/sys/UtilHome.csp) it calls the appropriate application code for the /csp/sys application.
-
The /csp/sys application code returns the response to the Web Gateway, which relays the request back to the client through the web server.
When an InterSystems IRIS installer automatically configures an instance to connect to the web server during an installation or upgrade, it adds a web server configuration directive and a Web Gateway application access profile corresponding to the instance’s default CSPConfigName automatically. If you are configuring the Web Gateway for an instance manually, you must configure your web server and add this application access profile manually. (If you have not already done so, you may need to add a server access profile for the instance first.)
On Windows systems, additional configuration is necessary to enable the InterSystems IRIS launcher for an InterSystems IRIS instance with modified web connection details. See Define a Remote Server Connection in System Administration Guide.
Address Each InterSystems IRIS Server Using a Custom Instance Prefix
If you do not want the instance name for an InterSystems IRIS application server to appear in the web application URL, follow the procedure described in this section, substituting your own names and application access requirements for those provided.
For example: assume you want to serve the Management Portal for two instances named iris1 and iris2, but that you would like to use walter as the substitute name for iris1 and perry as the substitute name for an instance named iris2, as depicted in the following image:
To serve the Management Portal for each instance using these substitute names, you would perform the following steps:
-
Ensure that both of the following conditions are met:
-
Your web server is invoking the Web Gateway for requests that are sent to /walter/csp/sys and /perry/csp/sys (or parent directories).
-
The Web Gateway configuration includes server access profiles for both iris1 and iris2, named accordingly.
-
-
In an ObjectScript shell on the iris1 instance, run the following command:
d $System.CSP.SetConfig("CSPConfigName","walter")
-
In an ObjectScript shell on the iris2 instance, run:
d $System.CSP.SetConfig("CSPConfigName","perry")
-
Using the Web Gateway management pages, add an application access profile for the application path /walter/csp/sys (or /walter/csp, or /walter) with a Default Server of iris1.
-
Add an application access profile for the application path /perry/csp/sys (or /perry/csp, or /perry) with a Default Server of iris2.
CSPConfigName also accepts a comma delineated list for CSP configuration names. This allows you to have multiple configuration names instead of a single one. For example:
d $System.CSP.SetConfig("CSPConfigName","perry,perry1,perry2,perry3")
To see other CSP global parameters, enter %SYS>d $system.CSP.DisplayConfig().
On Windows systems, additional configuration is necessary to enable the InterSystems IRIS launcher for an InterSystems IRIS instance with modified web connection details. See Define a Remote Server Connection in System Administration Guide.
Configuring Apache Virtual Hosts
As an alternative to the instance prefix mechanism described in the previous sections, the Web Gateway supports using Virtual Host names to serve applications on multiple InterSystems IRIS instances. Apache Virtual Hosts provide a way of transparently serving different applications at different host names using a single web server. Refer to the Apache documentation for details about Virtual Hosts: https://httpd.apache.org/docs/2.4/vhosts/Opens in a new tab
For example, you can configure a single Apache web server to host InterSystems IRIS applications at two distinct web sites: www.virtualhost1.com and www.virtualhost2.com.
If you have configured the web server to invoke the Web Gateway for requests to a virtual host name within the web server’s global configuration, the Web Gateway can route requests for a virtual host name to a specific InterSystems IRIS instance. Simply create an application access profile for an application path beginning with two forward slashes (//).
The following configuration procedure allows the Web Gateway to send requests for www.virtualhost1.com/csp/sys/UtilHome.csp can to the Management Portal home page for an instance named IRISserv1 and requests for www.virtualhost2.com/csp/sys/UtilHome.csp to the Management Portal home page for an instance named IRISserv2:
-
Navigate to the Web Gateway management pages main menu.
-
Create server access profiles for irisserv1 and irisserv2.
-
Create application access profiles for //virtualhost1.com/csp/sys/ and //virtualhost2.com/csp/sys/. Configure them as follows:
-
Set the Server 0 for path //virtualhost1.com/csp/sys/ to the server access profile irisserv1.
-
Set the Server 0 for path //virtualhost2.com/csp/sys/ to the server access profile irisserv2.
-
Although the Web Gateway supports the use of virtual host names in application access profiles, issuing Apache configuration directives to invoke the Web Gateway (that is, CSPFileTypes and CSP On/Off) within a <VirtualHost> directive block is not supported and will yield an error. In other words, you cannot enable the Web Gateway for the desired Virtual Hosts alone; you must enable the Web Gateway within the web server’s global configuration.
On Windows systems, additional configuration is necessary to enable the InterSystems IRIS launcher for an InterSystems IRIS instance with modified web connection details. See Define a Remote Server Connection in System Administration Guide.