UI Builder Series || Exploring Transform Data Sources || Article 3 || Mutates Server Data Checked v/s Unchecked

[JagjeetSingh]

In previous article we created transform type of data sources; used them to execute server side logics and return the output. However, we didn't discuss an important checkbox which is available on the data broker form, "Mutates Server Data".

I am not sure what difference does it make on the backend processing but below are the key differences you'd notice while working with it.

The Problem with a transform data source where "Mutates Server Data" option is unchecked is that it triggers on page load, even if you set it to trigger at "only when invoked". Yes! you can observe this by adding logs to your script. It triggers whenever you set the input parameter and when the page is loaded. So setting the property "When to evaluate this data source" doesn't matter in this case.

For example observe below data source. This data source will trigger every time you set the category value. Even if you are not triggering it from any event or from script.

Imagine creating a record from your data source and it'd create multiple records because of this issue. I am not sure yet if this is a product issue or this is how it is supposed to work.

Solution: This problem can be solved by setting "Mutates Server Data" check to true. It can not be triggered immediately and is only triggered from events or page scripts.

What are the similarities, differences and how to use both type of data sources. See below.

		Mutates Server Data = false	Mutates Server Data = true	Example
Configuration		Inputs properties are set in JSON format.	Same.	[ { "name": "category", "label": "Category", "description": "Select the category to fetch excuse", "readOnly": false, "fieldType": "string", "mandatory": true } ]
		inputs can be accessed using input parameter.	Same	function transform(input) { //Execute your code here //Access inputs using input parameter. Ex. input.category }
Execution	From events	Refresh is used	Execute is used
	From script	Is triggered using "refresh()"	is triggered using "execute()"	//The inputs can be bound to client state parameters can using refresh() the data source is triggered. api.data.example_rest_transform_source_1.refresh(); // Data source with "Mutates Server Data" = false //The inputs are passed while executing the data source. execute() is used to trigger the data source. api.data.mutates_server_data_example_1.execute({ // Data source with "Mutates Server Data" = true 'category' : api.state.category });
Events		Data Fetch Initiated Data Fetch Succeeded Data Fetch Failed	Operation Initiated Operation Succeeded Operation Failed
Reading output	From script	api.data.YOUR_DATA_SOURCE_NAME.output	Output can only be read from the event "Operation Succeeded" event.payload.data.output	function handler({api, event, helpers, imports}) { //Reading output of a data source mutating server data let mutate = event.payload.data.output; //Reading output of a data source not mutating server data let nonMutate = api.data.example_rest_transform_source_1.output; }

In my experience we can say that the transform data source which doesn't mutates server data can be used for something that you want to trigger on page load and other one can be used when we you want to trigger some logic based on certain events or script conditions. This is what I've observed in OOTB data sources as well.

I hope the series was useful. Thank you for taking time to read it.

Leave your feedback please. 🙂

[Abhishek M]

Thanks @JagjeetSingh , this really helped for one of my requirement