Manage breaking changes
When you make changes in an app, make sure your changes will not break existing scenarios.
Ideally, the removal of the connections, modules, and fields should be announced to the users in advance.
Contact the helpdesk with a request for e-mail notification to users.
Common breaking changes
Base
Any changes might break scenarios.
Connection
Changing the refresh call for OAuth connection.
Module's Communication
Changing response.output.
Changing response.type.
Adding response.valid for 2xx response.
Changing response.trigger.
Adding a condition.
Adding an additional call (chaining request).
Changing a linked connection.
Module's Parameters
Changing required from false to true.
Removing a parameter.
Changing type (if the original type can be coerced to the new type, it’s fine. e.g. number -> text. See type coercions.
Adding validate.
Setting the select parameter mappable to false.
Setting the select parameter dynamic to false.
Webhook's Communication
Any changes might break scenarios.
RPC
Changing parameter required from false to true.
Changing RPCs building dynamic parameters.
Custom Functions
Any changes might break scenarios.
Remove a parameter from a module
It's important to avoid removing mappable parameters from a module without a clear indication or notification to the user. Even if it doesn't immediately cause a scenario to fail, it could still impact its functionality or disrupt the underlying process. Therefore, it's best to communicate any changes to the user. Also, the user should be able to see and work with the original input in the deprecated parameter/s.
In situations where a mappable parameter needs to be removed, there are several ways to handle the deprecation. The appropriate approach depends on the specific circumstances and how the API manages parameter deprecation in its endpoint.
Below, are methods ranked in order of least to greatest impact:
Add the [Deprecated] string to the module's label
The parameter should be put into advanced parameters and the [Deprecated] string should be attached to the label. Additionally, you can add instructions to the help.
[
{
"name": "firstName",
"type": "text",
"label": "First Name",
"help": "This field is a replacement for the deprecated `Name` field."
},
{
"name": "lastName",
"type": "text",
"label": "Last Name",
"help": "This field is a replacement for the deprecated `Name` field."
},
{
"name": "email",
"type": "email",
"label": "Email"
},
{
"name": "name",
"type": "text",
"label": "Name [Deprecated]",
"advanced": true,
"help": "This field has been deprecated and divided into `First Name` and `Last Name` parameters."
}
]Add a banner
If you need to make sure that the user notices the deprecated parameters, you can use the banner element.
There are three distinct message types available, each with a specific icon and guidelines for appropriate use. The recommended length of the message is 50 to 300 characters.
{
"type": "banner",
"title": "This is an info",
"text": "Here is a description of info.",
"theme": "info"
}
{
"type": "banner",
"title": "This is a warning",
"text": "Here is a description of warning.",
"theme": "warning"
}
{
"type": "banner",
"title": "Headline, if needed...",
"text": "Minimum recommended length of message text. (50 characters)",
"theme": "danger"
}Perform an additional check before the request is sent and throw an error if the deprecated parameter is present in the payload
If the called API service is too strict about using the deprecated parameters, you can do the error execution on the app's side.
[
{ // when parameter name exists
"condition": "{{parameters.name}}",
"response": {
"valid": {
"condition": false, //to throw response as error
"type": "DataError",
"message": "You cannot use the parameter 'name' as it has been removed.\nPlease read the module's note message."
}
}
},
{ // when parameter name doesn't exist
"condition": "{{!parameters.name}}",
"url": "/api/users",
"method": "POST",
"body": "{{omit(parameters, 'name')}}",
"response": {
"output": "{{body}}"
}
}
]Shut down a module
If you need to make sure that the module is not used anymore, you can throw an error whenever the module is executed.
{
"response": {
"valid": {
"condition": "{{'a' === 'b'}}",
"message": "You cannot use this module anymore as it has been shut down.\nPlease read the module's note message."
}
}
}Deprecate a connection
If you need to deprecate a connection, create a new connection to use as the functional alternative and rename the now-deprecated connection so it contains the (deprecated) string.
Then, do the following:
Remove the current primary connection.
Map the new connection as the primary connection.
Map the deprecated connection as the alternative connection.
Last updated