Managing breaking changes

Breaking change

When you make changes in an app, you need to make sure they will not break existing scenarios. Please, check the below list of common breaking changes.

App's Element or Block Breaking Changes

App's Element or Block	Breaking Changes
Base	Any changes might break scenarios.
Connection	Changing `refresh` call for OAuth connection.
Module's Communication	Changing `response.output`. Changing `response.type`. Adding `response.valid` for `2xx` response. Changing `response.trigger`. Adding `condition`. Adding additional call (chaining request). Changing 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 select parameter `mappable` to `false`. Setting 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.

Base

Any changes might break scenarios.

Connection

Changing refresh call for OAuth connection.

Module's Communication

Changing response.output.

Changing response.type.

Adding response.valid for 2xx response.

Changing response.trigger.

Adding condition.

Adding additional call (chaining request).

Changing 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 select parameter mappable to false.

Setting 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.

How to remove a parameter from a module

Ideally, the removal of the field/s should be announced to the users in advance.

Please, contact us via the helpdesk with a request for e-mail notification for users, that use the modules in question.

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.

1. Adding `[Deprecated]` string into 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."
    }
]

2. Adding an HTML banner

If you need to make sure that the user notices the deprecated parameters, you can use the HTML banner.

If your code with the HTML banner in the label parameter contains more than 256 letters, implement an RPC to return the HTML banner instead.

[
    {
	"type": "html",
	"label": "<div class=\"i-exception i-exception-warning\"><h5>Deprecated Parameters</h5><p>◉ <b>Name</b>: This field has been divided into <i>First Name</i> and <i>Last Name</i> fields.</p><p>◉ <b>Email</b>: This field has been deprecated and should not be used anymore.</p></div>"
    }, 
    {
        "name": "name",
        "type": "text",
        "label": "Name [Deprecated]",
	"help": "This field has been deprecated and divided into `First Name` and `Last Name` parameters."
    },
    {
        "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 [Deprecated]"
    }
   
]

3. Do 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}}"
		}
	}
       
]

How to shut down a module

Ideally, the removal of the module should be announced to the users in advance, so that they have enough time to update their scenarios.

Please, contact us via the helpdesk with a request for e-mail notification for users, that use the modules in question.

If you need to make sure that the module is not used anymore and the user acknowledges it at least from the error log, 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."
            }
        }
  }

How to deprecate a connection

Ideally, the removal of the connection should be announced to the users in advance, so that they have enough time to update their scenarios.

Please, contact us via the helpdesk with a request for e-mail notification for users, that use the connection in question.

If you need to deprecate a connection create a new connection, that should be used as the functional alternative, and rename the now deprecated connection so it now contains the (deprecated) string. Then, do the following: