Overwriting request values passed to API main processes using custom functions

Overview

This tutorial explains how to overwrite a request to an API main process via a user-defined custom function.

Custom functions enable you to:

  • Convert user-input values to specified formats and pass them to target APIs
  • Pass additional constants to target APIs

What you'll learn

For this tutorial, we will implement a process to convert upper-case input in an inquiry reply message into lower-case.
This comprises the following steps:

Creating your custom function

In the left sidebar menu, select [Operation] -> [Custom function].

Image from Gyazo

On the Custom function list screen, click [Add] in the upper right corner.

Image from Gyazo

Enter the title, category, and identifier of the custom function.

To organize your custom functions for easy access, group them into categories by the module or feature they are used by. You can add and modify categories in the Custom function category list.

For this tutorial, we will use the following values:

FieldValue
Title/rcms-api/1/inquiry/4/message/send
CategoryAPI
Identifiercaseconvert_fxn

Note: Titles of custom functions within the same category must be unique. We recommend using the URI path of the associated endpoint as your function title. In this example, we are using the endpoint for sending reply messages to a specified form (inquiry ID = 4).

Image from Gyazo

In "Process", select [Kuroco Smarty] as the language and paste the code below into the editor:

{* Initialize $request variable to save output as string array *}
{assign_array var="request" values=""}

{* e.g. Convert upper-case user input value to lower-case *}
{if isset($smarty.post.body)}
  {assign
    var="request.body"
    value=$smarty.post.body|lower}
{/if}

Image from Gyazo

When you are done, click [Add] at the bottom of the screen to save your function.

Image from Gyazo

Linking your function to an endpoint

Next, create an endpoint for this conversion feature and connect the function to it.

Creating a new endpoint

In the left sidebar menu, click [API] and select the API where you want to add the target endpoint.

Image from Gyazo

On the endpoint list screen, click [Add new endpoint] to open the configuration dialog.

Image from Gyazo

For this tutorial, we will enter the values below:

FieldSub-fieldValue
Path-(rcms-api/1/)inquiry/4/message/send
ModelCategoryForm
ModelInquiryMessage, v1
Operationsend
Basic settingsid4

Substitute the form id 4 with your form ID, which can be obtained from the Form list screen.

When you are done, click [Add] at the bottom of the dialog box to save the endpoint.

Image from Gyazo Image from Gyazo

Linking the endpoint with your function

On the endpoint list screen, click [Pre-processing] for the endpoint you created above.

Image from Gyazo

In the fields that appear below the endpoint, input the following:

  • Category: API
  • List: /rcms-api/1/inquiry/4/message/send

Image from Gyazo

Verifying the implementation

As a final step, send a request from the Swagger UI and check the stored value to verify if the conversion function is working as expected.

API request

On the endpoint list screen, click [Swagger UI].

Image from Gyazo

Select the endpoint you created and click [Try it out].

Image from Gyazo

To test this function, we would send a string containing upper-case letters as the API request.
For this tutorial, paste the code below into the "Request body" and click [Execute]:

Request body
{
  "name": "Taro Diverta",
  "email": "taro@diverta.co.jp",
  "body": "IMPORTANT MESSAGE. REPLY ASAP.",
  "from_id": 0,
  "from_module": "string",
  "validate_only": false
}

To avoid getting an error response, make sure to fill out all the required fields in your request body. You can view and modify the required fields for a form on the corresponding Field settings screen.

Image from Gyazo

You should see the following response. Note down the ID for later use.

Image from Gyazo

Checking the saved value

In the sidebar menu, select [Campaign] -> [Form].

Image from Gyazo

On the Form list screen, click the title of the form that is using this custom function.

Image from Gyazo

In the form editor, click the [Answers] tab.

Image from Gyazo

In the Answers list, find the entry in the "No." column that corresponds to the ID you noted from the API response. Click this number to view the answer details.

Image from Gyazo

Verify that the input value has been converted to lower-case.

Image from Gyazo

If the conversion failed, check for the following issues:

  • The function has not been properly linked to the endpoint.
  • You have linked the wrong custom function.
  • The variable name (request) is incorrect.
  • The item to be validated has been specified incorrectly.
  • There are errors in the validation logic.

If you have any other questions, please use our contact form or Slack workspace.