Adding Input Mappings

Input mappings allow you to add parameters to a query so that you can set the parameter value when executing the query. For example, when you define a query as SELECT *, FROM TEST_TABLE, WHERE ID=1, an input mapping is a parameter that sets the value of ID.

Clicking the Add New Input Mappings link brings up the following page.

It provides the following options:

Parameter type

This is the data type of the input mapping, which determines how the input mapping parameter will be given in the target query.

SCALAR: In the target query, the parameter will be used as one value.
ARRAY: In the target query, the parameter will contain one or many values for a mapped parameter.

Note that ARRAY parameter type cannot be used with the QUERY_STRING data type (SQL type).

In the context of RDBMS and SQL datasources, an ARRAY parameter mapped to an SQL query will be expanded to multiple comma separated parameters at runtime. For example, this can be used in SQL statement conditions such as SELECT ... WHERE ... IN(?).

SQL type

The data type of the corresponding SQL parameter can be selected from this menu. Note that the QUERY_STRING data type cannot be used if the parameter type is set to ARRAY. Find more from here about data types.

Default value

Default values help you automatically assign a value to a parameter when a user has not entered a specific parameter value in a request. Default values are added when defining queries. Therefore, this value gets automatically added to the query if it is ignored by the user.

You can refer to Internal Property Values using Default Values. You can use special system variables that are defined as default values. At the moment, it only provides a variable for retreiving the username of the current user authenticated in a secured data service. You can access this variable as follows:

#{USERNAME}: Dynamically replaces the input mapping with the current user's username when a data service request is processed.

#{NULL}: Sets the current input mapping value to null.
         It's the same as providing "xsi:nil" in the incoming message's input parameter element.

#{TENANT_ID}: Represents the current tenant ID.
              This is useful in a Stratos deployment where multiple tenants live in the same server.

#{USER_ROLES}: This value contains the list of user roles that the current calling user has.
               If the parameter mapped is of type ARRAY, it will have the full list of user roles.
               If it's a SCALAR, it will only contain the first user role of the user.

For a demonstration of the usage of default values, see Default Values Sample.

IN/OUT Type

These are used in stored procedures which takes out parameters and in/out parameters. IN is the usual parameter we used to give to provide some value inside. OUT are basically, it only returns a value from a stored procedure, INOUT, does both.

Validators

Validators are added to individual input mappings in a query. Input validation allows data services to validate the input parameters in a request and stop the execution of the request if the input doesn’t meet required criteria. WSO2 Data Service Server provides a set of built-in validators for some of the most common use cases. It also provides an extension mechanism to write custom validators.

Long Range validator

Validates if an integer value is in the specified range. The validator requires a minimum and a maximum value to set the range. For example,

Double Range validator

Validates if a floating point is in the specified range. The validator requires a minimum and a maximum value to set the range. For example,

Length validator

Validates the string length of a given parameter against a specified length. For example,

Pattern validator

Validates the string value of the parameter against a given regular expression. For example,

Custom validators

Used to add your own validation logic by implementing the interface org.wso2.carbon.dataservices.core.validation.Validator. The definition of the interface is as follows:

public interface Validator {
    public void validate(ValidationContext context, String name, ParamValue value) throws ValidationException;
}

If the validation fails, the validate method in the interface by default throws an exception of type ValidationException . The parameters of the method are as follows:

context : Is of type ValidationContext, which contains information about the full set of parameters passed into the request. When the validation logic depends on other parameters, the validation context can be used to check the names/values of the rest of the parameters.
name : A string value that represents the name of the parameter to be validated.
value : Is of type ParamType, which represents the value of the parameter to be validated. It is either SCALAR or ARRAY.

After creating a custom validator class, package it in a JAR file and place in in <DSS_HOME>/repository/component/lib directory, which is the server's classpath location for external libraries.