.. _community_params_extractor: Parameters Extractor ==================== This module allow us to entering specific request parameters as URL path fragments instead of using the query string. For example, we want to be able to apply a cql_filter using a URL in the following form:: /geoserver////ows?service=WMS&version=1.3.0&request=GetMap As a simple example of usage, if the is something like:: K_140M the URL would become:: /geoserver///K_140M/ows?service=WMS&version=1.3.0&request=GetMap and this module will translate the URL to this new one:: /geoserver///ows?service=WMS&version=1.3.0&request=GetMap&cql_filter=seq='K140M' This module is configured by a set of rules that will be applied to the incoming URLs. Note that a get capabilities result will include the original URL maintaining the extra filter. This module also gives the possibility to echo existing URL parameters to the result of a get capabilities result. As an example, by default the following get capabilities request (note the existing cql_filter parameter):: /geoserver/ows?service=wms&version=1.3.0&request=GetCapabilities&cql_filter=CFCC=%27D68%27 will return a get capabilities document were the URLs will be of the type:: /geoserver/ows?SERVICE=WMS& if this module is configured to echo an existing cql_filter parameter the result would be:: /geoserver/ows?SERVICE=WMS&CQL_FILTER=CFCC%3D%27D68%27& This module is configured using three types of rules: echo parameter rules, basic rules and advanced rules. All of them can be managed in this module UI which is integrated in GeoServer UI. Echo Parameter Rules ----------------------------------- Echo parameter rules are very simple, they allow us to define that a certain existing URL parameter should be echoed to a get capabilities result. This type of rules only required one mandatory parameter which is the name of the existing URL parameter that should be echoed to a get capabilities result. Example of an echo parameter rule: .. figure:: images/echo_rule.png :align: center *Example of a echo parameter rule defined in the UI* This rule will echo the cql_filter of this URL:: /geoserver/ows?service=wms&version=1.3.0&request=GetCapabilities&cql_filter=CFCC=%27D68%27 to the get capabilities result:: /geoserver/ows?SERVICE=WMS&CQL_FILTER=CFCC%3D%27D68%27& Basic Rules ----------------------------------- Basic rules allow us to handle simple uses cases where we only want to extract a parameter from the URL. A basic rule is defined by three mandatory attributes: .. list-table:: :widths: 20 80 * - **Attribute** - **Description** * - ``Position`` - The position of the URL base path element to be selected * - ``Parameter`` - The name of the parameter produced by this rule * - ``Transform`` - Expression that defines the value of the parameter, use {PARAMETER} as a placeholder for the selected path element For commodity is also possible when defining this type of rules to configure that an existing parameter in the URL should be echoed to a get capabilities result. Example of a basic rule: .. figure:: images/basic_rule.png :align: center *Example of a basic rule defined in the UI* This rule will transform the URL:: /geoserver/tiger/wms/H11?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap in:: /geoserver/tiger/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27H11%27 Advanced Rules ----------------------------------- Advanced rules allow us to handle more complex uses cases where more flexibility is required. An advanced rule is defined by three mandatory attributes and four optional ones: .. list-table:: :widths: 10 80 10 * - **Attribute** - **Description** - **Mandatory** * - ``Match`` - Regex match expression with groups, for example ^(?:/[^/]*){3}(/([^/]+)).*$ selects the URL base path third element - Yes * - ``Activation`` - If defined this rule will only be applied to URLs that match this regex expression - No * - ``Parameter`` - The name of the parameter produced by this rule - Yes * - ``Transform`` - Expression that defines the value of the parameter, use $1 ... $n as placeholders for groups defined in the match expression - Yes * - ``Remove`` - The match expression group to be removed from URL, by default 1 - No * - ``Combine`` - Defines how to combine parameter existing value ($1 existing value, $2 new value), by default the value is overridden - No For commodity is also possible when defining this type of rules to configure that an existing parameter in the URL should be echoed to a get capabilities result. Example of an advanced rule: .. figure:: images/advanced_rule.png :align: center *Example of an advanced rule defined in the UI* This rule will transform the URL:: /geoserver/tiger/wms/H11?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27D68%27 in:: /geoserver/tiger/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&CQL_FILTER=CFCC%3D%27D68%27+or+CFCC%3D%27H11%27 No that this rule will also echo an existing cql_filter parameter to the get capabilities result. Rules Management ----------------------------- Rules can be managed and tested in the rules management UI. Besides the basic operations like add, remove and update is also possible to activate or deactivate rules. A deactivated rule will be ignored by this module. Follow a print screen of the rules management UI with all the rules previously defined: .. figure:: images/rules_management.png :align: center *Rules management UI* Note that the first rule (the advanced one) is not active.