Utility Functions

Helper functions or one-off functions that don't have a category yet

Utility functions are a mix of helper functions or one-off functions that don't have a category yet. They contain functions that range from helping you debug and test your API endpoint, to functions that help you enforce.

• Preconditions - Set conditions that must be true If not met, the request will stop.

• Try/Catch - Checks if a set of statements executed successfully, and executes additional statements based on the result

• Throw Error - Throw a custom error message

• Debug Log - Similar to a Javascript console log, allows for logging of messages in a special Xano console log in the debugger

• CSV Stream - Stream a CSV's contents in chunks, allowing for processing of large CSV files in your function stacks

• HTTP Header - Set a custom HTTP Header for the API endpoint.

• IP Address Lookup - Provides geographical information based on an IP address

• Sleep - Pause the execution of the function stack for a period of time.

• Get All Raw Input - Used for Webhooks

• Get All Environment Variables - Pull all environment variables into a single object

• Calculate Distance - Map the latitude and longitude from two different points.

• Set Data Source - Forces database operations to utilize a specific data source

• Stop & Debug - Stop the execution of the function stack and print out a value.

• Post Process - Execute additional logic after the API response is returned.

• Return - Return a result and exit the function stack.

Preconditions

Preconditions are useful if you want to enforce that something is true and create an error message in the event it is not true.

Set conditions that must be true If not met, the request will stop. You can also specify an error message below.

Error Type	API Status Code
Standard	500 (Internal Server Error)
Not Found	404 (Not Found)
Access Denied	403 (Forbidden)
Too Many Requests	429 (Too Many Requests)
Unauthorized	401 (Unauthorized)
Bad Request	400 (Bad Request)

Try/Catch

Try/catch enables you to catch any errors that may occur in a specific stack of functions and execute additional logic based on that result. This function essentially enables fully custom error handling in Xano.

Try - Try these functions first Catch - Execute these functions if the Try statements return an error Finally - Execute these functions regardless of the result

In the below example, we are starting with a Delete File function, and trying to delete a file that does not exist.

Deleting a file that does not exist returns ERROR_CODE_NOT_FOUND and halts execution.

Normally, when an error occurs in the function stack, execution is halted entirely. If we wanted to deploy some customized error handling to change this behavior, we can do so by placing this function inside of a Try/Catch statement.

In the below iteration, we've moved Delete File into the Try portion of a Try/Catch statement. Now, when we run the endpoint again, the function itself is still failing, but the API itself still returns a success response.

Moving the function into Try/Catch

We can then use the Catch portion to read the error, using three variables only available via Try/Catch.

• code is the error code

• message is the error message

• result will be any accompanying data. Most functions will not output a result, and only return data in code and message

When we run this again and output those variables as part of our response, you'll see that the API still returns a 'Success' result, but we can view the error message returned by our function in our Try statement.

You can then use the Finally section to determine the behavior based on the result of your Try/Catch. In the below example, we're using a conditional statement to check if the try/catch code variable is empty. If it is empty, we return a success message. If it is not empty (which means there was an error in our Try statements), we return an error message.

Practical Example of using Try/Catch

Throw Error

Throw Error allows you to halt execution with a custom error message. This is different from a Precondition step because it does not restrict you to specific error codes. It can be used in combination with Try/Catch or on its own.

Debug Log

Debug Log allows you to output specific information in a new debug logging section of the Debugger. This is similar to how a console log statement in Javascript would behave. These steps will not run outside of Run & Debug.

This can be especially helpful for debugging data errors with loops or otherwise just giving you a quick view of a variable's contents during execution. You can insert whatever data you'd like into Debug Logs; they will accept any data type, and can also have filters applied.

In the below example, we're looping through results from a Query All Records statement, and outputting a specific value from each item to the new Debug Log.

And the result is available in the new Debug Log tab of the Debugger when we run.

CSV Stream

CSV Stream is a powerful function allowing you to 'stream' chunks of a CSV file in sequence to your function stack, allowing for processing of large CSV files.

A successful CSV stream function stack includes three essential parts.

• a file resource to ingest the CSV file This can come from either a File Resource input, or a file delivered by an external API, with a Create File Resource step applied

• a CSV stream function to stream the CSV data This function initiates the streaming of CSV data, and provides an output variable. This output variable is meant for use with a For Each loop

• a For Each loop to run through the individual CSV rows The loop is responsible for performing any functions you'd like on your CSV, such as adding each row to one of your database tables.

In the below example, we've added these three key components, and can now process the incoming CSV data.

CSV Stream is a much simpler alternative to the previously established method of array functions and object manipulation to process incoming CSV data.

HTTP Header

Set a custom HTTP header. This function is useful if you need your responses to deliver specific, custom headers. You can also use this to specify custom API response codes outside of the ones our Precondition function offers.

The duplicates parameter lets you decide to either replace headers that already exist with your new header, or allow for duplicate headers to exist.

IP Address Lookup

Takes in an IP address and returns geographical information based on that IP. This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.

Sleep

Pauses execution of the Function stack and goes to sleep. (Think of it like waiting or pausing to execute).

In this example, the Sleep function is set to pause for 5 seconds.

Get All Input (Webhooks)

Gets the input from a Webhook and makes it available to use in the Function stack. For more information, see the Webhooks section.

Get All Environment Variables

The Get All Environment Variables function

This function will gather all environment variables of your workspace and populate a single object with them. This allows you to more quickly access your environment variables using the GET filter, instead of manually populating them where they are needed elsewhere in your function stack.

In this example, we have 3 environment variables in our workspace. By using Get All Environment Variables, we can populate all of these in a single variable for easier access.

We can then use the GET filter to access each variable. For this example, we are populating a URL parameter for an API request.

Calculate Distance

Calculate the distance between two longitude/Latitude points

Stop & Debug

Stops execution of the Function Stack at a specified point and prints out the data. (This can be advantageous when testing and debugging complex logic in the Function Stack).

In this example, the specified value for Stop & Debug to print out is the variable "merchant."

In this example, Stop & Debug is inserted in the Function Stack where we wish to stop execution. Additionally, the specified data is printed out at the point where execution was stopped.

Set Data Source

This function allows you to specify which data source that database operations following it target. Remember that the order of operations in a function stack matters, so any database operations that come before your Set Data Source statement will use whatever is used normally.

Post Process

Post process allows you to execute additional logic after your API has provided a response. This can be useful if you want to see a response on your front-end without waiting for any additional processing to occur, but a background task does not meet your needs.

Example

In this function stack, we are setting var_1 with a value of "Hello" and calling an external API to send the contents of this variable.

Afterwards, we have added Post Process to update var_1 and send a new request to the same external API.

The function stack is set to respond with the contents of var_1.

This means that the following will happen in sequence:

1. Set var_1 to "Hello!"

2. Send var_1 to external API

3. The Xano API responds with "Hello!"

4. Set var_1 to "Goodbye!"

5. Send var_1 to external API

Below is a video of this example in action. Note how the external API recieves both 'Hello' and 'Goodbye', but the Xano API just responds with 'Hello'. Note: the video does not contain any audio.

Post Process will use the state of variables where it is defined. This means that while Post Process executes at the end of the function stack, the placement is still important to ensure that any variables it uses retain the appropriate content.

Post Process also enables the use of some special variables: body, headers, and status_code. These are only available during post process, and can be used to transmit any of the corresponding data back to a database table, or to an external API, to record the results of post process.

Return

Return will return a result and exit the Function Stack. Return can be especially useful with conditional logic that requires you to return something as soon as you have a certain result.

In this example, the Return function is shown in the response due to the condition that was met, despite var: result being defined in the response.