Process Flow Design Best Practices Instructional Guide

Objective:

• Provide a comprehensive set of best practices for developing process flows in Adeptia Connect.

• Ensure consistency in the development, testing, and deployment phases.

• Improve overall system performance through optimized design practices.

• Reduce errors and minimize troubleshooting during process flow execution.

• Promote clarity and readability in process flow design.

• Implement efficient error handling to streamline issue resolution.

• Enhance the maintainability and scalability of process flows for future updates.

• Support long-term operational stability by adhering to standardized practices.

Table of Content

1. Development Practices

Open

a. Initial Design and Modeling: Before implementing a process flow, creating a preliminary design using modeling tools like Draw.io or Adeptia Connect’s built-in flow diagram is crucial. A well-structured design ensures the process flow is coherent and achieves the intended goals.

• Benefits:
  This preliminary step helps identify any potential issues early on, providing an opportunity to streamline processes before writing code.

• Action:
  Implement a basic "skeleton" structure of your process flow based on the design, allowing for incremental development and testing.

b. Frequent Saving and Autosave: While designing the flow, enable the autosave feature or regularly click save to avoid data loss in case of unexpected system crashes or power failures. This practice ensures that recent work is not lost and promotes development continuity.

• Recommendation:
  Enable autosave as a default. However, during complex modifications, it’s recommended to manually save versions at key milestones to track progress and troubleshoot effectively if required.

c. Streamlining Context Data: Avoid assigning large data streams to the context target during development, as this can negatively impact performance, particularly with memory usage.

• Best Practice:
  Leverage global variables or more efficient data management techniques for large data sets to prevent bottlenecks and crashes.

d. IT User for Development: Always use an IT user, rather than an admin, for creating process flows and related activities. This promotes adherence to development standards and separates operational roles from development activities.

e. Logging Levels: During the development phase, set the logging level to DEBUG. This level provides detailed information necessary for diagnosing issues. Upon migration to production, the logging level should be raised to prevent excess data capture and to focus on critical issues.

• Tip:
  Change the logging level to ERROR or WARN in production environments to minimize performance overhead while still capturing essential information.

2. Naming Conventions

a. Activity Naming Syntax: Establish a standard naming convention for all activities within a process flow. This will make the process flow easier to understand and maintain over time.

• Syntax Format:
  [Project/Organization]_[ActivityType]_[ActivityName]

  Example:
  PC_PF_B2BNonEDI where PC is the project acronym, PF refers to the Process Flow, and B2BNonEDI describes the flow activity.

b. Variable Naming: Variables should be named descriptively to clearly convey their purpose. This practice is essential for troubleshooting, reviewing code, and for developers who may work on the process flow in the future.

• Best Practice:
  Begin all variable names with the prefix var and use camel case to improve readability (e.g., varMailSubject, varFilePath).

• Rationale:
  A well-structured naming system reduces ambiguity and aids in understanding the role of each variable.

3. Designing Conventions

Example of wrong design convention:

Open

Example of right design convention:

a. Logical Sequence of Activities: When designing a process flow, the sequence of activities should follow a clear and logical progression from the start node to the end node. Ensure that the flow is easy to read, and that the data pathways are visually apparent.

• Action:
  Align activities in a structured, visually intuitive manner. Use consistent labeling and ensure that activities are connected logically, making it easy for developers and reviewers to understand the flow at a glance.

b. Labeling Activities: All activities should be properly labeled to reflect their functionality and purpose within the flow. This is essential for documentation, reviews, and future maintenance.

c. Optimizing Activity Use: Where possible, use Adeptia’s built-in activities. However, for complex or time-intensive tasks, consider combining multiple activities into a Custom Plugin to enhance performance.

• Recommendation:
  Reduce the number of discrete steps by using optimized custom activities, particularly when looping is required. This will help in reducing overhead and simplifying the process flow.

4. General Guidelines

a. Auto-save Settings: During modifications of an existing flow, turn off the auto-save feature. This prevents inadvertent saving of changes that may not yet be tested or validated.

b. Viewing Other Process Flows: In production environments, always open other process flows in view mode. This ensures that critical processes are not accidentally altered and reduces the risk of operational disruptions.

• Best Practice:
  Open flows in view mode to audit existing logic without risking accidental edits.

c. Repository Cleanup: Set the file repository retention option to "Delete on Success" to ensure that disk space is efficiently managed. This prevents storage overloads and maintains optimal performance.

• Action:
  Configure repository files under properties to automatically delete files upon successful completion of the process flow.

d. Context Variables: Avoid creating context variables unnecessarily. Where possible, use global variables within the process flow, as these are easier to manage and reduce overhead.

5. Working with Streams

a. Stream Management: When handling multiple streams, use the stream selector to manage them effectively. Ensure that each generated stream is consumed by subsequent activities and is properly closed upon completion.

• Best Practice:
  Check the streams list in the activity properties section to verify that streams are correctly managed.

b. Closing Streams: Failure to close streams, especially when using gateways, can lead to memory leaks. Ensure all streams are properly closed after they have been processed.

6. Gateway/Condition Handling

a. Decision Making: Gateways are used to direct the flow based on conditional logic. Ensure that any Java code used in conditions returns a true or false value. If not, the process flow will raise an exception.

• Tip:
  Clearly label the decisions or conditions applied in each gateway to enhance understanding.

b. Data Types: Verify that the data types used in the gateway condition match the data types assigned within the process flow. Incorrect data types will lead to runtime errors.

7. Configuring Retry in Case of Failure

a. Retry Mechanism: Activities that may fail due to external factors (e.g., server connectivity issues) should be configured with retry options. Set parameters such as maximum retries and wait time between retries.

• Best Practice:
  Set Activity Maximum Retries on Failure to 3 and Activity Wait Time between retries to 30 seconds. This ensures that the process attempts reconnection multiple times before aborting.

8. Exception Handling

1. Global Exception Handling: Where possible, use global exception handling for the process flow, rather than individual service exceptions for each activity. This reduces redundancy and simplifies error handling.

2. Use scripts when there are large no. of activities involved in the process flow and one needs to handle multiple exceptions occurring in multiple activities.

3. Custom Error Messages: Ensure that meaningful error messages or codes are included in the exception handler script. This will assist in diagnosing issues quickly during debugging or in production.

9. Parent/Child Process Flows

a. Repetitive Tasks:
Model repetitive tasks using child process flows to ensure modularity and reduce redundancy. This also simplifies debugging and maintenance.

b. Synchronization:
Use SPAWN for asynchronous invocation of child process flows and CALL for synchronous invocation, depending on the requirement.

10. Publishing Process Flows as Templates

a. Template Creation: To create reusable templates in Adeptia Connect, first ensure that the process flow is fully developed and tested. Templates allow for quicker deployment of standard workflows across projects.

1. Steps to Create Template:

   1. Navigate to Configure > Templates > Create Template.

   2. Provide a name and description for the template.

   3. Define key parameters and assign values to be used in the child flow.

   4. Set source and target data formats and define the event triggers.

   5. Save and exit the template configuration.

2. Select Process Flow in the select Process Flow type 

3. Select the Process Flow in the select Process Flow field. Only the Process flow published as a post-process flow will be populated in the field. 

4. Click Add Parameters to add parameters.

5. Define key and their values

6. The specified values will be put in the context of child flow 

7. Define the target data format and  layout 

8. Define the mapping in the field 

9. Click exit and Save the template 

Conclusion: By adhering to these comprehensive best practices, developers can create process flows in Adeptia Connect that are efficient, scalable, and maintainable. Following these guidelines ensures that process flows are robust, handle exceptions effectively, and are optimized for performance, minimizing the risk of errors and downtime.