--- title: PingGateway route properties description: Properties simplify deploying PingGateway to different environments without changing route configurations. You store the configuration centrally with properties variables set differently for each installation. component: pinggateway version: 2026 page_id: pinggateway:reference:Properties canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/Properties.html revdate: 2025-10-02T14:29:53Z 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-reloadable-usage: Reloadable properties in an external file 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 Properties-reloadable-example: Reloadable properties --- # PingGateway route properties Properties simplify deploying PingGateway to different environments without changing route configurations. You store the configuration centrally with properties variables set differently for each installation. You can declare properties variables in the PingGateway configuration or in an external file and use them in expressions in routes and in `config.json` to set configuration parameters. All the routes in a Router inherit the properties variables you declare. You can use a property defined in `config.json` in any of the routes in the configuration. ## Usage ### Simple property configured inline ```json { "properties": { "": "valid JSON value" } } ``` ### Group property configured inline ```json { "properties": { "": { "": "valid JSON value", "": "valid JSON value" } } } ``` ### Properties configured in one or more external files ```json { "properties": { "$location": "" } } ``` In this example, `description1` and `description2` prefix the variable names contained in the external file. ```json { "properties": { "description1": { "$location": "" }, "description2": { "$location": "" } } } ``` ### Reloadable properties in an external file PingGateway can reload the properties from a local file. This format uses an ID for location: ```json { "properties": { "$location:<_id>": "" } } ``` You can define multiple reloadable properties files by using different IDs. ## Properties * `""`: *configuration expression<[string](preface.html#definition-string)>* Named variable to use in the PingGateway configuration. Use the variable in expressions to set configuration parameters in `config.json` and in routes. The variable takes any valid JSON value: string, number, boolean, array, object, or null. This example declares `appLocation` in `config.json` and uses it to set the `baseURI` parameter of the handler: ```json { "properties": { "appLocation": "https://app.example.com:8444" }, "handler": { "type": "Router", "baseURI": "${appLocation}", "capture": "all" } } ``` This example defines a `ports` variable and uses it in an `appLocation` variable: ```json { "properties": { "ports": [8444, 8445, 8446], "appLocation": "https://app.example.com:${ports[1]}" }, "handler": { "type": "Router", "baseURI": "${appLocation}", "capture": "all" } } ``` This example defines the request path in a route condition using the variable `uriPath`: ```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}')}" } ``` * `""`: *<[object](preface.html#definition-object)>, required* Named group of variables to use in the PingGateway configuration. This example defines a `directories` group in `config.json` for use in route configurations: ```json { "properties": { "directories": { "config": "${openig.configDirectory.path}", "auditlog": "/tmp/logs" } } } ``` Combine the group name and variable name with dot notation in your expressions, such as `${directories.auditlog}`: ```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* Location and name of one or more local JSON files containing property variables. The expression resolves to a local file. Using a `file://` URL in the configuration is deprecated. PingGateway expects `.json` files and with property variables in a key/value format. The key mustn't contain the dot (`.`) separator. By default, the files use UTF-8 encoding. To use deprecated ISO-8859-1 encoding, set the deprecated system property `org.forgerock.config.resolvers.properties.encoding` to `ISO-8859-1`. For example, this file uses the correct format: ```json { "openamLocation": "https://am.example.com:8443/am/", "portNumber": 8444 } ``` This file causes an error due to the `.` separators in the key names: ```json { "openam.location": "https://am.example.com:8443/am/", "port.number": 8444 } ``` - `"$location:<_id>"`: *configuration expression<[string](preface.html#definition-string)>, required* Location with a unique ID, whose value is a local JSON or Java properties file defining property variables. * The expression resolves to a local file PingGateway can read from and write to. Using a `file://` URL in the configuration is deprecated. * Update the file with an HTTP PUT request to the [routes REST API](../about/api-descriptor.html#get-api-descriptors-for-a-router). The body of the request must use JSON-format properties, even if the local file is a Java properties file. When the local file is a Java properties file, PingGateway writes a comment header with a timestamp for the change. * When changes to the properties prevent a route from reloading, PingGateway reverts to the previous state of the properties. * When you define multiple reloadable properties files with different IDs, use different property names in each file. PingGateway doesn't guarantee the order in which it resolves a property with the same name in different files. * Although you can define reloadable properties files as properties in `admin.json` and `config.json`, PingGateway only reloads those files at startup time. * By default, the files use UTF-8 encoding. To use deprecated ISO-8859-1 encoding, set the deprecated system property `org.forgerock.config.resolvers.properties.encoding` to `ISO-8859-1`. Find an example in [Reloadable properties](#Properties-reloadable-example). ## Examples ### Property variables configured in one file This example uses an expression to set the location of the file with property variables: ```json { "properties": { "$location": "${openig.configDirectory}/myProperties.json" } } ``` This example uses a string to set the location of the file with property variables: ```json { "properties": { "$location": "/Users/user-id/.openig/config/myProperties.json" } } ``` The file location takes any real URL. The file `myProperties.json` contains the base URL for AM and the port number of an application: ```json { "openamLocation": "https://am.example.com:8443/am/", "appPortNumber": 8444 } ``` ### Property variables configured in multiple files This example uses two files with property variables: ```json { "properties": { "urls": { "$location": "/path/to/myUrlProperties.json" }, "ports": { "$location": "/path/to/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": "/Users/user-id/.openig/config/myUrlProperties.json" }, "ports": { "$location": "/Users/user-id/.openig/config/myPortProperties.json" } }, "handler": { "type": "Router", "name": "_router", "baseURI": "${urls.appUrl}:${ports.appPort}" } } ``` ### Reloadable properties This example `test` route stores a `baseURI` property in a local `props.json` file. Notice the [`"$location:<_id>"` format](#Properties-reloadable-reference), where `<_id>` is `props`: ```json { "properties": { "$location:props": "&{ig.instance.dir}/props.json" }, "baseURI": "&{baseURI}", "handler": "ReverseProxyHandler" } ``` The `props.json` file contains the `baseURI` property: ```json { "baseURI": "http://localhost:8081" } ``` When you make changes to the properties, PingGateway reloads this route with the new `baseURI` value: 1. Get the `props` property resource for the route to check the current properties values. The resource `_id` matches the ID in the `"$location:<_id>"` property: ```console $ curl 'localhost:8085/api/system/objects/_router/routes/test/resources/props' ``` Output ```json {"_id":"props","format":"JSON","content":{"baseURI": "http://localhost:8081"}} ``` To read all the property resources for the test route, get `localhost:8085/api/system/objects/_router/routes/test/resources?_queryFilter=true` instead. 2. Update the `props` property by modifying the resource with an HTTP PUT request. The body of the request is the `"content"` of the resource with the changes: ```console $ curl \ --request PUT \ --url 'http://localhost:8085/api/system/objects/_router/routes/test/resources/props' \ --header 'Content-Type: application/json' \ --data '{"baseURI":"http://localhost:8080"}' ``` Output ```json {"_id":"props","format":"JSON","content":{"baseURI":"http://localhost:8080"}} ``` PingGateway rewrites the `props.json` file, then reloads this route with the new `baseURI` value.