--- title: PingGateway route properties description: 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. component: pinggateway version: 2025.9 page_id: pinggateway:reference:Properties canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/Properties.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/Properties.html section_ids: Properties-usage: Usage Properties-simple: Simple property configured inline Properties-group: Group property configured inline Properties-extfile: Properties configured in one or more external files Properties-properties: Properties Properties-example: Examples property_variables_configured_in_one_file: Property variables configured in one file property_variables_configured_in_multiple_files: Property variables configured in multiple files --- # PingGateway 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 ```json { "properties": { "": "valid JSON value" } } ``` ### Group property configured inline ```json { "properties": { "": { "": "valid JSON value", ... } } } ``` ### Properties configured in one or more external files ```json { "properties": { "$location": expression } } ``` In this example, `description1` and `description2` prefix the variable names contained in the external file. ```json { "properties": { "description1": { "$location": expression }, "description2": { "$location": expression } } } ``` ## Properties * `""`: *configuration expression<[string](preface.html#definition-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. ```json { "properties": { "appLocation": "https://app.example.com:8444" }, "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: ```json { "properties": { "ports": [8444, 8445, 8446], "appLocation": "https://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: ```json { "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 [Getting started with PingGateway](../getting-started/preface.html), requests to `ig.example.com:8080/hello` or `ig.example.com:8080/welcome` can access the route. * `""`: *<[object](preface.html#definition-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: ```json { "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: ```json { "type": "AuditService", "config": { "eventHandlers": [ { "class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler", "config": { "name": "csv", "logDirectory": "${directories.auditlog}", . . . ``` * `"$location"`: *configuration expression<[string](preface.html#definition-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. By default, the files use ISO-8859-1 encoding, although ISO-8859-1 is now deprecated in favor of UTF-8. To use UTF-8 encoding, set the system property `org.forgerock.config.resolvers.properties.encoding` to `UTF-8`. For example, this file is correct: ```json { "openamLocation": "https://am.example.com:8888/am/", "portNumber": 8444 } ``` This file would cause an error: ```json { "openam.location": "https://am.example.com:8888/am/", "port.number": 8444 } ``` ## 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: ```json { "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: ```json { "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. ```json { "openamLocation": "https://am.example.com:8888/am/", "appPortNumber": 8444 } ``` ### Property variables configured in multiple files In the following example, the property variables are contained in two files, defined as a set of strings: ```json { "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: ```json { "appUrl": "https://app.example.com" } ``` The file `myPortProperties.json` contains the port number of an application: ```json { "appPort": 8444 } ``` The base config file, `config.json`, can use the properties as follows: ```json { "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}", . . . ```