Route properties

Configuration parameters, such as host names, port numbers, and directories, can be declared as property variables in the PingGateway configuration or in an external JSON file. The variables can then be used in expressions in routes and in config.json to set the value of configuration parameters.

Properties can be inherited across the router, so a property defined in config.json can be used in any of the routes in the configuration. Storing the configuration centrally and using variables for parameters that can be different for each installation makes it easier to deploy PingGateway in different environments without changing a single line in your route configuration.

Usage

Simple property configured inline

{
  "properties": {
    "<variable name>": "valid JSON value"
  }
}

Group property configured inline

{
  "properties": {
    "<group name>": {
      "<variable name>": "valid JSON value", ...
    }
  }
}

Properties configured in one or more external files

{
  "properties": {
    "$location": expression
  }
}

In this example, description1 and description2 prefix the variable names contained in the external file.

{
  "properties": {
    "description1": {
      "$location": expression
    },
    "description2": {
      "$location": expression
    }
  }
}

Properties

"<variable name>": configuration expression<string>

The name of a variable to use in the PingGateway configuration. The variable can be used in expressions in routes or in config.json to assign the value of a configuration parameter.

The value assigned to the variable can be any valid JSON value: string, number, boolean, array, object, or null.

In the following example from config.json, the URL of an application is declared as a property variable named appLocation. The variable is then used by the baseURI parameter of the handler, and can be used again in other routes in the configuration.
```
{
  "properties": {
    "appLocation": "http://app.example.com:8081"
  },
  "handler": {
    "type": "Router",
    "baseURI": "${appLocation}",
    "capture": "all"
  }
}
```
In the following example, the property variable ports is added to define an array of port numbers used by the configuration. The ports variable is referenced in the appLocation variable, and is resolved at runtime with the value in the ports array:
```
{
  "properties": {
    "ports": [8080, 8081, 8088],
    "appLocation": "http://app.example.com:${ports[1]}"
  },
  "handler": {
    "type": "Router",
    "baseURI": "${appLocation}",
    "capture": "all"
  }
}
```

In the following example route, the request path is declared as the property variable uriPath, with the value hello, and the variable is used by the route condition:

{
  "properties": {
    "uriPath": "hello"
  },
  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "headers": {
        "Content-Type": [ "text/plain; charset=UTF-8" ]
      },
      "entity": "Hello world!"
    }
  },
  "condition": "${matchesWithRegex(request.uri.path, '^/welcome') or matchesWithRegex(request.uri.path, '&{uriPath}')}"
}

When PingGateway is set up as described in the Quick install, requests to ig.example.com:8080/hello or ig.example.com:8080/welcome can access the route.

"<group name>": <object>, required

The name of a group of variables to use in the PingGateway configuration. The group name and variable name are combined using dot notation in an expression.

In the following example from config.json, the property group directories contains two variables that define the location of files:

{
  "properties": {
    "directories": {
      "config": "${openig.configDirectory.path}",
      "auditlog": "/tmp/logs"
    }
  }
}

The group name and variable name are combined using dot notation in the following example to define the directory where the audit log is stored:

{
  "type": "AuditService",
  "config": {
    "eventHandlers": [
      {
        "class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
        "config": {
          "name": "csv",
          "logDirectory": "${directories.auditlog}",
          . . .

"$location": configuration expression<string>, required

The location and name of one or more JSON files where property variables are configured.

Files must be .json files, and contain property variables with a key/value format, where the key cannot contain the period (.) separator.

For example, this file is correct:

{
  "openamLocation": "http://am.example.com:8088/openam/",
  "portNumber": 8081
}

This file would cause an error:

{
  "openam.location": "http://am.example.com:8088/openam/",
  "port.number": 8081
}

Examples

Property variables configured in one file

In the following example, the location of the file that contains the property variables is defined as an expression:

{
  "properties": {
    "$location": "${fileToUrl(openig.configDirectory)}/myProperties.json"
  }
}

In the following example, the location of the file that contains the property variables is defined as a string:

{
  "properties": {
    "$location": "file:///Users/user-id/.openig/config/myProperties.json"
  }
}

The file location can be defined as any real URL.

The file myProperties.json contains the base URL of an AM service and the port number of an application.

{
  "openamLocation": "http://am.example.com:8088/openam/",
  "appPortNumber": 8081
}

Property variables configured in multiple files

In the following example, the property variables are contained in two files, defined as a set of strings:

{
  "properties": {
    "urls": {
      "$location": "file://path-to-file/myUrlProperties.json"
    },
    "ports": {
       "$location": "file://path-to-file/myPortProperties.json"
    }
  }
}

The file myUrlProperties.json contains the base URL of the sample application:

{
  "appUrl": "http://app.example.com"
}

The file myPortProperties.json contains the port number of an application:

{
  "appPort": 8081
}

The base config file, config.json, can use the properties as follows:

{
  "properties": {
    "urls": {
      "$location": "file:///Users/user-id/.openig/config/myUrlProperties.json"
    },
    "ports": {
      "$location": "file:///Users/user-id/.openig/config/myPortProperties.json"
    }
  },
  "handler": {
    "type": "Router",
    "name": "_router",
    "baseURI": "${urls.appUrl}:${ports.appPort}",
    . . .

PingGateway 2024.9