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.

How to 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.

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.

Occurrence in a module

Code in mappable parameters

Copy

[
    {
        "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 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.

Occurrence in a module

Code

Copy

{
    "type": "banner",
    "title": "This is an info",
    "text": "Here is a description of info.",
    "theme": "info"
}

Occurrence in a module

Code

Copy

{
	"type": "banner",
	"title": "This is a warning",
	"text": "Here is a description of warning.",
	"theme": "warning"
}

Occurrence in a module

Code

Copy

{
	"type": "banner",
	"title": "Headline, if needed...",
	"text": "Minimum recommended length of message text. (50 characters)",
	"theme": "danger"
}

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.

Occurrence in a module

Code in communication

Copy

[
	{ // 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

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.

Occurrence in a module

Code in communication

Copy

{
        "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

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:

1. Remove the current primary connection.

2. Map the new connection as the primary connection.

3. Map the deprecated connection as the alternative connection.

1st step

2nd step

3rd step