Comment on page
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.
- Try/Catch - Checks if a set of statements executed successfully, and executes additional statements based on the result
- 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
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 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.
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 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 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.
Set a custom HTTP header.
Pauses execution of the Function stack and goes to sleep. (Think of it like waiting or pausing to execute).
.png?alt=media&token=08f2940c-f435-4f0c-8b24-ab1f40ff20ab)
In this example, the Sleep function is set to pause for 5 seconds.
Gets The input from a Webhook and makes it available to use in the Function stack. For more information, see the Webhooks section.
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 the distance between two longitude/Latitude points
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).
.png?alt=media&token=9d65385f-99b0-475d-932d-2889f165dcc1)
In this example, the specified value for Stop & Debug to print out is the variable "merchant."
.png?alt=media&token=93aaf047-f2ae-499e-9b57-c1688c7c7413)
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.
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 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.
Last modified 2mo ago