Skip to main content


Pre-processing is a user-defined custom function that is called before executing the main process of API endpoints. You can set pre-processing to the configured endpoints.


The processing logic implemented in the pre-processing is not reflected in the API information (Swagger UI) page or the openapi.json file, so there may be differences between the information displayed on the screen and the actual specifications. For this reason, it is recommended that the specifications of the customised parts are described in the endpoint description instead.

Steps to set up pre-processing in endpoints

Pre-processing can be set up in the following steps.

  1. Write the pre-processing logic in the custom function
  2. Add the custom function in the pre-processing settings of the endpoint

The detailed information of the above steps are as follows:

Write the program in the custom function

Access the custom function editor page and create a custom function for the pre-processing logic.

Image from Gyazo To avoid confusion with custom functions created for other purposes, it is recommended to set it up according to the following rules.

  • Create a category to group the pre-processing custom functions together
  • Set the title of the custom function to be the same as the path name of the endpoint, so that it is easier to identify and associate them together.

Associate the custom function with the endpoint settings

1. Access API list page

Select the API on the side menu and access API list page.

Image (fetched from Gyazo)

2. Select the endpoint

Select the endpoint you want to implement and click the [Pre-processing] button.

Image (fetched from Gyazo)

3. Add a pre-process and select the custom function

Select the category that the custom function is grouped under then select the custom function by its title under the Contents field to associate the custom function to the pre-processing of the endpoint.


The endpoint may not work as expected if the incorrect custom function is selected in the endpoint's pre-processing settings.

Image (fetched from Gyazo)

Variables of pre-processing

Variables used in pre-processing have reserved words with specific meanings. These variables may be used to customize the behaviour of the endpoint.

$metaData reference (read only)
$urlData reference (read only)
$bodyData reference (read only)
$errorsCustom error handling (write action)
$requestModify API request body (write action)

Variables for reference

The following variables are reference variables that are always assigned by default when pre-processing is executed.
They are used to determine the endpoint information and the request value passed.

Variable nameDescription
$metaMeta data of the endpoint
$urlURL component
$bodyRequest body


This variable contains the meta data of the associated endpoint.

$metaobjectAll meta data of the endpoint

This variable contains the following data.

KeyTypeInitial valueDescription
$meta.mimeobjectMIME type and MIME sub-type
$meta.mime.typestringMIME type
$meta.mime.subtypestringMIME sub-type
$meta.output_formatstring"json"_output_format specified in query parameter
$meta.langstringDetermined based on the following priorities:
[Browser language > Main language settings]
_lang specified in query parameter
$meta.charsetstring"utf8"_charset specified in query parameter
$meta.api_headerobjectAPI settings
$meta.post_jsonstringGET: null
POST: "{}"
JSON body in text format


This variable contains the component of the URL specified by the client.

Variable nameTypeDescription
$urlobjectEndpoint path and query parameter data

This variable contains the following data.
Among the following, $url.query contains the same value as $smarty.get.

$url.pathstringPath of the endpoint
$url.queryobjectQuery parameter

For example, for requests sent to the following endpoint: https://your-api-domain/rcms-api/1/endpoint_name?p1=VALUE1&p2[]=VALUE2_0&p2[]=VALUE2_1&p3[k1]=VALUE3_1&p3[k2]=VALUE3_2

The following value will be set in $url:

"path": "/rcms-api/1/endpoint_name"
"query": {
"p1": "VALUE1",
"p2": [
"p3": {
"k1": "VALUE3_1",
"k2": "VALUE3_2"


This variable references the components of the URL specified by the client.
It contains the same value as $

Variable nameTypeDescription
$bodyobjectEndpoint's request body

Variables for API control

The following variables are not declared at the time the pre-process runs.
Initialising them and populating them with values allows you to control the behavior of the endpoint.

Variable nameUsage
$errorsCustom error handling
$requestModify API endpoint's request body

Do not declare these variables for any purpose other than their intended one within the pre-processing custom function, as this may lead to to unintended behavior of the API endpoints.


This variable can be used to perform custom error handling in the endpoint.

You can implement your own validation process on the endpoint by determining the input value and storing the resulting error message in an array.

Variable nameTypeInitial valueDescription
$errorsobjectnullAPI endpoint's error codes and messages

Code example

{* Initialize it as an empty array. *}
{assign_array var='errors' values=''}
{* Validate input value. *}
{if $ === 'VALUE'}
{* Add error message in the array. *}
{assign var='errors.' value='An error has occurred.'}

Error response format

HTTP status codeerrors[].codeerrors[].message
422unprocessable_entityMessages stored in errors object
// Response example
"errors": [
"code": "unprocessable_entity",
"message": "An error has occurred."
"x-rcms-request-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxx"

If $errors object contains more than 1 element, the response format is as follows:

{"code": "unprocessable_entity", "message": "messages stored in errors object"}

If the $errors array contains multiple element, an object is outputted for each of the errors.

{"code": "unprocessable_entity", "message": "error message 1"},
{"code": "unprocessable_entity", "message": "error message 2"},
// ...


This variable can be used to modify the request values passed to the pre-process custom function.

Variable nameTypeInitial valueDescription
$requestobjectnullCustom request body for the pre-processing

By setting a value in this variable in the following format, you can add or overwrite the request value (GET / POST) to be passed to the pre-process custom function.

{assign var='request.***(target key name)' value='***(value)'}

To set the value based on the existing request value from the API endpoint, use the following reference variable.

Variable nameRemark
$url.queryAlternative variable name: $smarty.get
$bodyAlternative variable name: $

Code sample

{* Initialize as empty array *}
{assign_array var='request' values=''}

{* Determine if there is a request value *}
{if $url.query.filter}
{* overwrite query parameter *}
value="`$url.query.filter AND topics_id in [1, 2, 3]"}

Reference tutorial

Here is the tutorial on how to implement a pre-processing:


If the pre-processing is not working as expected, check the following points:

  • Check if the API pre-processing is associated with the custom function properly.
  • Check if the associated custom function is correct.
  • Check if the variable names are correct.
  • Check if the data format stored in the variables are correct.
  • Check if the custom function syntax is correct.


If you have any other questions, please contact us or check out Our Slack Community.