Backward Compatible Design: Planning for Subsequent Deployments

Appian Max Team — Tue, 23 Apr 2024 13:08:11 GMT

Current Revision posted to Article by Appian Max Team on 4/23/2024 1:08:11 PM

Changes to an existing application may have an impact on in-flight processes. Process design changes can cause unexpected behavior in production. Following a backward compatible design and running Health Check as a part of each sprint will help prevent problematic designs such as passing CDTs by reference.

Below is a list of design best practices to create a backward compatible design and to facilitate subsequent deployments of an application. Best practices for general application implementation are available in the Project Initiation Best Practices Checklist

Process Models

Appian loads the latest version of a process model when instantiating a new process. Therefore, when making changes to process models that are also subprocesses, take into account the impact to the existing parent processes.

Do

Account for null parameters in process design when adding new parameters to a process as in-flight processes will not pass values for the newly created parameters.

Don’t

Add required process parameters as in-flight processes will break when calling subprocesses with new required process parameters.
- This precaution is only necessary if there are in-flight processes which call the modified process model.
- Mitigate the impact of additional required process parameters by leveraging the available tools for managing in-flight processes.
Add new required parameters to receive message events.

CDTs and Entities

In-flight processes will continue to use the old version of the CDT when a CDT is modified by an application deployment or during development.

Do

Verify that new interfaces and new processes launched as a subprocess will work with a null value for the new CDT field as old versions of the CDT will not have a value for that new field when passing a value to subprocesses.
Verify that absence of a field will not break Web Service Integrations or database integrations.
Use the function index(...) instead of the dot notation to access the attribute of a CDT

Don’t

Delete or rename CDT fields as database writes will break when attempting to write the deleted field to the database.
Don't pass a CDT by reference to a sub-process.

Expression Rules and Interfaces

Process models always run the latest version of a given expression rule or interface. Therefore, it’s important that a rule will work with all in-flight versions of the process.

Do

Use the keyword syntax when calling a expression rule or interface instead of relying on parameter position.
Create test cases to verify that the expression works for both new and legacy capabilities. This includes calling the expression rule with null values for new parameters.
Create a new expression rule instead of modifying an existing rule when new process parameters are required.

Don’t

Change rule parameter order or change rule parameter names.
Count on processes using named parameters to account for changes to parameter order.

Integrations

In-flight processes must be designed to properly integrate with future versions of integrations.

Do

Use subprocesses for integrations so processes always use the latest version of an integration process model.
Design applications with short lived processes so each process always has the latest approach for integrating with an endpoint.

Plug-ins

Do

Create a new version of the smart service with new inputs/outputs and deprecate the old one.
When deprecating a smart service, update the smart service icon and image to clearly indicate that the version of the smart service should not be used anymore.

Don’t

Don’t change the plug-in or smart service module key.
Don’t add new required parameters to existing functions.

Tags: Delivery, Architecture

Backward Compatible Design: Planning for Subsequent Deployments

matt.cosenza — Tue, 31 Oct 2023 19:31:17 GMT

Revision 4 posted to Article by matt.cosenza on 10/31/2023 7:31:17 PM

Process Models

Do

Account for null parameters in process design when adding new parameters to a process as in-flight processes will not pass values for the newly created parameters.

Don’t

Add required process parameters as in-flight processes will break when calling subprocesses with new required process parameters.
- This precaution is only necessary if there are in-flight processes which call the modified process model.
- Mitigate the impact of additional required process parameters by leveraging the available tools for managing in-flight processes.
Add new required parameters to receive message events.

CDTs and Entities

In-flight processes will continue to use the old version of the CDT when a CDT is modified by an application deployment or during development.

Do

Verify that new interfaces and new processes launched as a subprocess will work with a null value for the new CDT field as old versions of the CDT will not have a value for that new field when passing a value to subprocesses.
Verify that absence of a field will not break Web Service Integrations or database integrations.
Use the function index(...) instead of the dot notation to access the attribute of a CDT

Don’t

Delete or rename CDT fields as database writes will break when attempting to write the deleted field to the database.
Don't pass a CDT by reference to a sub-process.

Expression Rules and Interfaces

Process models always run the latest version of a given expression rule or interface. Therefore, it’s important that a rule will work with all in-flight versions of the process.

Do

Use the keyword syntax when calling a expression rule or interface instead of relying on parameter position.
Create test cases to verify that the expression works for both new and legacy capabilities. This includes calling the expression rule with null values for new parameters.
Create a new expression rule instead of modifying an existing rule when new process parameters are required.

Don’t

Change rule parameter order or change rule parameter names.
Count on processes using named parameters to account for changes to parameter order.

Integrations

In-flight processes must be designed to properly integrate with future versions of integrations.

Do

Use subprocesses for integrations so processes always use the latest version of an integration process model.
Design applications with short lived processes so each process always has the latest approach for integrating with an endpoint.

Plug-ins

Do

Create a new version of the smart service with new inputs/outputs and deprecate the old one.
When deprecating a smart service, update the smart service icon and image to clearly indicate that the version of the smart service should not be used anymore.

Don’t

Don’t change the plug-in or smart service module key.
Don’t add new required parameters to existing functions.

Tags: Delivery, Architecture

Backward Compatible Design: Planning for Subsequent Deployments

matt.cosenza — Tue, 31 Oct 2023 15:31:31 GMT

Revision 3 posted to Article by matt.cosenza on 10/31/2023 3:31:31 PM

Process Models

Do

Account for null parameters in process design when adding new parameters to a process as in-flight processes will not pass values for the newly created parameters.

Don’t

Add required process parameters as in-flight processes will break when calling subprocesses with new required process parameters.
- This precaution is only necessary if there are in-flight processes which call the modified process model.
- Mitigate the impact of additional required process parameters by leveraging the available tools for managing in-flight processes.
Add new required parameters to receive message events.

CDTs and Entities

In-flight processes will continue to use the old version of the CDT when a CDT is modified by an application deployment or during development.

Do

Verify that new interfaces and new processes launched as a subprocess will work with a null value for the new CDT field as old versions of the CDT will not have a value for that new field when passing a value to subprocesses.
Verify that absence of a field will not break Web Service Integrations or database integrations.
Use the function index(...) instead of the dot notation to access the attribute of a CDT

Don’t

Delete or rename CDT fields as database writes will break when attempting to write the deleted field to the database.
Don't pass a CDT by reference to a sub-process.

Expression Rules and Interfaces

Process models always run the latest version of a given expression rule or interface. Therefore, it’s important that a rule will work with all in-flight versions of the process.

Do

Use the keyword syntax when calling a expression rule or interface instead of relying on parameter position.
Create test cases to verify that the expression works for both new and legacy capabilities. This includes calling the expression rule with null values for new parameters.
Create a new expression rule instead of modifying an existing rule when new process parameters are required.

Don’t

Change rule parameter order or change rule parameter names.
Count on processes using named parameters to account for changes to parameter order.

Integrations

In-flight processes must be designed to properly integrate with future versions of integrations.

Do

Use subprocesses for integrations so processes always use the latest version of an integration process model.
Design applications with short lived processes so each process always has the latest approach for integrating with an endpoint.

Plug-ins

Do

Create a new version of the smart service with new inputs/outputs and deprecate the old one.
When deprecating a smart service, update the smart service icon and image to clearly indicate that the version of the smart service should not be used anymore.

Don’t

Don’t change the plug-in or smart service module key.
Don’t add new required parameters to existing functions.

Tags: Delivery, Architecture

Backward Compatible Design: Planning for Subsequent Deployments

matt.cosenza — Fri, 20 Oct 2023 14:56:23 GMT

Revision 2 posted to Article by matt.cosenza on 10/20/2023 2:56:23 PM

Process Models

Do

Account for null parameters in process design when adding new parameters to a process as in-flight processes will not pass values for the newly created parameters.

Don’t

Add required process parameters as in-flight processes will break when calling subprocesses with new required process parameters.
- This precaution is only necessary if there are in-flight processes which call the modified process model.
- Mitigate the impact of additional required process parameters by leveraging the available tools for managing in-flight processes.
Add new required parameters to receive message events.

CDTs and Entities

In-flight processes will continue to use the old version of the CDT when a CDT is modified by an application deployment or during development.

Do

Verify that new interfaces and new processes launched as a subprocess will work with a null value for the new CDT field as old versions of the CDT will not have a value for that new field when passing a value to subprocesses.
Verify that absence of a field will not break Web Service Integrations or database integrations.
Use the function index(...) instead of the dot notation to access the attribute of a CDT

Don’t

Delete or rename CDT fields as database writes will break when attempting to write the deleted field to the database.
Don't pass a CDT by reference to a sub-process.

Expression Rules and Interfaces

Process models always run the latest version of a given expression rule or interface. Therefore, it’s important that a rule will work with all in-flight versions of the process.

Do

Use the keyword syntax when calling a expression rule or interface instead of relying on parameter position.
Create test cases to verify that the expression works for both new and legacy capabilities. This includes calling the expression rule with null values for new parameters.
Create a new expression rule instead of modifying an existing rule when new process parameters are required.

Don’t

Change rule parameter order or change rule parameter names.
Count on processes using named parameters to account for changes to parameter order.

Integrations

In-flight processes must be designed to properly integrate with future versions of integrations.

Do

Use subprocesses for integrations so processes always use the latest version of an integration process model.
Design applications with short lived processes so each process always has the latest approach for integrating with an endpoint.

Plug-ins

Do

Create a new version of the smart service with new inputs/outputs and deprecate the old one.
When deprecating a smart service, update the smart service icon and image to clearly indicate that the version of the smart service should not be used anymore.

Don’t

Don’t change the plug-in or smart service module key.
Don’t add new required parameters to existing functions.

Backward Compatible Design: Planning for Subsequent Deployments

joel.larin — Wed, 06 Sep 2023 15:01:35 GMT

Revision 1 posted to Article by joel.larin on 9/6/2023 3:01:35 PM

asdfa