Manage breaking changes

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

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

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

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

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

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

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}}"
		}
	}
       
]

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.

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."
            }
        }
  }

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: