Parameter Transformation is an option for the advanced processing of inputs from a request. It allows to

1. have different names for parameters submitted and parameters declared in endpoints.xml

2. produce parameter values different from submitted values

3. validate input data and create custom error messages, implementing custom validation rules

4. process XML body as input (content type "application/xml")

To use parameter-transformation add a tag <parameter-transformation> to the endpoint-definition in the endpoint-folder. The xslt (mandatory) is from the directory "parameter-transformation-xslt" under application. You may use subdirectories to organize XSLT in this directory.

Optionally zero or many data sources may be added. Syntax for adding data sources is the same as for Data Source Transformation.

<endpoint name="foo">
  <parameter-transformation xslt="xslt-from-directory-parameter-transformation-xslt">
    <!-- optional: zero or many data sources -->
    <xml-from-application file="books.xml"/>
    </parameter-transformation>
  ...
</endpoint>

Default behaviour without parameter transformation

In the absence of "parameter transformation" the default behaviour for processing data inputs is:

• Data can be sent as GET or POST parameters only. It is not possible to supply request type "application/xml" as an input.

• The name of the parameter sent must be existing as a parameter-name in endpoints.xml.

• Sending parameters not existing in endpoints.xml will cause an error.

• For every parameter existing in endpoints.xml a value must be submitted, unless a default-value exists. Otherwise this will cause an error.

• The value of each parameter equals the value of the respective parameter submitted.

Alternative behaviour with parameter transformation

1. If the request is a GET/POST with parameters then all parameters are taken and <parameter name="x" value="y"/> elements are created - no matter if declared in <endpoints.xml> or not. If the request is a POST with an XML body then the XML is taken as is.

2. Any optionally specified data sources are executed. Any GET and POST parameters may be accessed with the ${x} syntax (see the data source descriptions for where parameters may be used). Any parameter which is referenced but not supplied with the request is left empty (an error is not produced) as the point of the parameter transformation is to determine errors. An error being produced by a missing parameter would then not allow the parameter transformation to produce a custom <error> output.

3. Input from [1] and [2] are placed into an XML called "parameter-transformation-input.xml". See Parameter Transformation Input for details.

4. The XSLT (from directory parameter-transformation-xslt under application) is applied on "parameter-transformation-input.xml". The generated output is called "parameter-transformation-output.xml". The generated output requires a specific schema. See Parameter Transformation Output for details.

5. If the result of the transformation includes <error>Param 'x' must be an integer</error>, this error message is returned to the user, and no further processing is performed. The absence of an error tag is considered a success (i.e. there is no “success” tag or similar).

6. Parameter values are extracted from the result of the transformation.

7. Normal parameter processing steps are taken (default values are applied, an error if values are missing, etc.).

The parameter-transformation-xslt will use parameter-transformation-input.xml as an input and will generate parameter-transformation-output.xml.

The required output scheme is:

<parameter-transformation-output>
    <parameter name="foo" value="xxx"/>
    <parameter name="fang" value="xxx"/>
    ...
    <parameter name="long" value="xxx"/>
<parameter-transformation-output>

• Each parameter existing in endpoints.xml must be present in the output, except if the parameter has a default-value (which will be applied if the parameter were missing in the output).

• Output of a parameter not existing in endpoints.xml will raise an error.

• If the same parameter appears multiple times, then later values override earlier values.

Raise Custom Error

Optionally an <error> tag can be added. If existing, an error will be raised. The custom error message is taken from this tag. Note that an empty error tag <error/> will also raise an error, but with an empty error message.

<parameter-transformation-output>
    <error>This is my error-message</error>
    <parameter name="foo" value="xxx"/>
    <parameter name="fang" value="xxx"/>
    ...
    <parameter name="long" value="xxx"/>
<parameter-transformation-output>

Inputs from request and data from optionally added data sources are automatically placed into a temporary XML called <parameter-transformation-input>.

The custom XSLT ("parameter-transformation-xslt") will be applied to this XML.

OpenEndpoints will automatically insert additional useful tags:

Tags added to <input-from-request>

• all parameters submitted in the originating request, having <parameter name="xxx" value="xxx"/>. This explicitly includes the system parameters hash and environment (if not omitted; otherwise the parameter is not existing).

• endpoint: name of the endpoint that has been called.

• debug-requested: if existing the request had a parameter "debug=true". Otherwise this tag will be omitted.

• <http-header name-lowercase="user-agent">Foo</http-header> This may be present multiple times, or not at all. HTTP Headers are case insensitive so e.g. “User-Agent” and “user-AGENT” are the same header. Therefore these are normalized to all lowercase.

• <cookie name="Session">12345</cookie> This may be present multiple times, or not at all. Cookies on the other hand are case sensitive, so it’s possible to have “Session” and “SESSION” as two different cookies with different values, so these aren’t normalized to lowercase.

• ip-address

Tags added to <input-from-application>

• application: the name of the application

• application-display-name: the display-name of the application, if available from the database.

• git-revision: if the application was published from Git via the Service Portal then this contains the Git hash for the revision. (If the application is deployed in "single application mode" then this tag is omitted.)

• debug-allowed: if existing debugging is set to "allowed" in the database. Otherwise this tag will be omitted.

• secret-key: one separate tag for each secret-key

• random-id-per-endpoint: the database request-log adds a random id per request per application

• base-url: The base-url of the application is taken from an environment variable.

Example: Request sent from web form

<parameter-transformation-input>

    <!-- This file shows the example input to a parameter-transformation. In this case input was submitted from a webform (POST or GET) -->

        <input-from-request>
            <endpoint>my-endpoint</endpoint>
            <debug-requested/>

            <!-- only present when debug=true; otherwise missing -->
            <environment>preview</environment>
            <hash>ed99c4d96dac277331f08216bf7227e10dab64edcd05d7e02ad4d090c22f369b</hash>
            <http-header name-lowercase="user-agent">Foo</http-header>
            <cookie name="Session">12345</cookie>

            <!-- only present when IP address was available; otherwise missing -->
            <ip-address>1.2.3.4</ip-address>

            <!-- list of all parameters submitted or - if not submitted - having default-value from endpoints xml -->
            <parameter name="some" value="some value"/>
            <parameter name="more" value="some other value"/>
            <parameter name="examples" value="and so on"/>
        </input-from-request>

        <input-from-application>
            <application>application-name</application>
            <application-display-name>The Application</application-display-name>

            <!-- or missing, if not available -->
            <debug-allowed/>

            <!-- only present when debug-mode enabled in service portal; otherwise missing -->
            <!-- if you have multiple secret keys, then all of them will be listed -->
            <secret-key>foo</secret-key>

            <base-url>https://endpoints.com/</base-url>
        </input-from-application>

    <!-- You can add any additional data-sources with the parameter-trasformation element. Data from those will be available below. -->
    <whatever-the-data-source-command-returns/>
</parameter-transformation-input>

Example: Json Payload

The json paylod is converted to xml.

<parameter-transformation-input>

    <!-- This file shows the example input to a parameter-transformation. In this case input was submitted within a JSON body (POST) -->
    <input-from-request>
        <endpoint>my-endpoint</endpoint>
        <debug-requested/>

        <!-- only present when debug=true; otherwise missing -->
        <environment>preview</environment>
        <hash>ed99c4d96dac277331f08216bf7227e10dab64edcd05d7e02ad4d090c22f369b</hash>

        <!-- only present when IP address was available; otherwise missing -->
        <ip-address>1.2.3.4</ip-address>

        <!-- the json body is converted to xml -->
        <json>
            <some>some value</some>
            <more>some other value</more>
            <examples>and so on</examples>
        </json>
    </input-from-request>

    <input-from-application>
        ...
    </input-from-application>

    <!-- You can add any additional data-sources within the parameter-trasformation tag. Data from those will be available below. -->
    <whatever-the-data-source-command-returns/>
</parameter-transformation-input>

Example: XML Paylod

<parameter-transformation-input>
    <!-- This file shows the example input to a parameter-transformation. In this case input was submitted within a XML body (POST) -->
    <input-from-request>
        <endpoint>my-endpoint</endpoint>
        <debug-requested/>
        <!-- only present when debug=true; otherwise missing -->
        <environment>preview</environment>
        <hash>ed99c4d96dac277331f08216bf7227e10dab64edcd05d7e02ad4d090c22f369b</hash>
        <!-- only present when IP address was available; otherwise missing -->
        <ip-address>1.2.3.4</ip-address>
        <!-- the xml body as submitted -->
        <xml>
            <some>some value</some>
            <more>some other value</more>
            <examples>and so on</examples>
        </xml>
    </input-from-request>

    <input-from-application>
        ...
    </input-from-application>

    <!-- You can add any additional data-sources with the parameter-trasformation element. Data from those will be available below. -->
    <whatever-the-data-source-command-returns/>
</parameter-transformation-input>

How-to debug

1. Create the parameter-transformation-tag

2. Allow debugging and send a request with debug=true. For details see Debug Mode

3. The generated parameter-transformation-input.xml is available in the request-log.