# Frends Best Practices Collection This collection gathers a set of best practices for designing, building, operating, and maintaining integrations on the Frends platform. It is intended as a reference for developers and integration architects who want to produce solutions that are functional on day one and remain reliable, secure, and supportable over time. Each practice is kept concise and focused on a single point. Some topics naturally overlap. The collection is intended to grow and be revised as the platform evolves and as new patterns emerge from real-world usage. ### Design integrations before building them Define the business goal, source and target systems, message structures, mappings, ownership, acceptance criteria, operational needs, and failure scenarios before implementation starts. Frends development is more reliable when interface descriptions, sample payloads, recovery expectations, and non-functional requirements such as frequency, concurrency, and latency are agreed in advance. This reduces rework and helps keep Processes understandable and supportable over time. ### Keep Processes focused and easy to follow Build Processes so that each one has a clear purpose and limited responsibility. Avoid combining too many unrelated actions, transformations, and exception branches into a single long flow. Simpler Process structures are easier to test, easier to support, and less likely to become fragile when requirements change. When the logic grows, split it into meaningful reusable parts instead of expanding a single Process indefinitely. ### Use Subprocesses for reusable logic, not for everything Use Subprocesses when the same logic is needed in several places, such as shared error handling, common API call patterns, archive cleanup, or standard validation. This improves consistency and reduces duplicate maintenance. At the same time, avoid turning very small one-off logic into Subprocesses without a clear benefit, because unnecessary indirection makes solutions harder to read and debug. ### Avoid Remote Subprocesses in high-volume solutions Remote Subprocesses are not recommended for integrations or APIs with heavy traffic. They introduce extra overhead and can reduce scalability under load. If a Subprocess must be used in performance-sensitive solutions, keep the data passed to it small and send only the parameters or identifiers that are truly required. ### Split long-running work into separate stages Do not keep a single Process waiting longer than necessary for external events or delayed downstream actions. When possible, divide long-running logic into separate stages and continue processing only when the required external step has completed. This reduces resource usage and improves operational resilience. ### Give every Process a consistent naming pattern Use readable, descriptive, and standardized names for Processes and Subprocesses. Avoid special characters, brackets, and unnecessary complexity in names. Main Processes should follow an agreed convention that makes source, target, and purpose immediately visible, while Subprocess names should describe what they do and indicate whether they are shared or specific to a system or solution. Consistent naming improves discoverability, support, and onboarding. ### Name APIs from the business domain, not the implementation API names should reflect the business capability or domain they expose instead of the backend product or system behind them. Domain-based API naming makes integrations more stable over time, because backend systems may change even when the API contract stays the same. This also produces cleaner and more understandable API catalogs. ### Standardize Environment Variable naming Environment variables should be readable, descriptive, and grouped consistently, either by system name or by Process identifier. Use names that clearly communicate what the variable holds and which system or context it belongs to. Avoid abbreviations that are not widely understood across teams, and document the purpose of each variable as part of the solution's operating instructions. Consistent Environment Variable naming structure makes configuration easier to manage across teams, environments, and onboarding scenarios. ### Always include general error handling Every main Process should have an agreed general error handling approach. Error handling should not be left to individual Tasks alone. Frends supports local error handling with Catch and broader structures such as Scope\&Catch-based handling, and shared Subprocesses can be used for alerting, cleanup, or common failure logic. The important practice is that failures are anticipated and managed deliberately rather than treated as exceptions to design. ### Make failures visible even when they are handled If an error occurs, the Process should still clearly indicate a failed outcome even when custom handling is applied. A handled error should not create the false impression that execution completed successfully. This is important for monitoring, support work, and auditability. ### Distinguish between a failed execution and an error response Not every error response produced by a Process means the Process itself has failed. When a Process receives invalid or incorrect input, validates it successfully, and returns a structured error response to the caller, the Process has done its job correctly. Marking such executions as failed in Frends would misrepresent what actually happened and create unnecessary noise in monitoring and support work. Reserve failed execution status for cases where the Process encountered an unexpected condition it could not handle — not for cases where it handled an invalid request exactly as designed. ### Plan recovery step by step For every important step in a Process, define what happens if that step fails, whether the action can be retried, what state may remain partially completed, and how recovery should happen. Good Frends solutions are not only designed for success paths but also for safe recovery after interruptions, timeouts, or downstream system failures. ### Retry only transient failures Use retries only when the failure is likely temporary, such as timeouts or short service disruptions. Do not retry invalid requests or functional business errors that will fail again unchanged. Use a limited retry count to avoid unnecessary load and endless retry loops. When retries are exhausted, move the item to explicit error handling such as a dead-letter or manual review path if the use case requires it. ### Keep production logging minimal and intentional In production, logging should usually be set to **Only errors**. Verbose logging should be reserved for development, testing, or short-term troubleshooting. Logging too much can affect performance, increase data exposure risk, and make troubleshooting harder by flooding the logs with low-value information. ### Log identifiers, not unnecessary payloads Good operational logging includes useful identifiers such as correlation IDs, transaction IDs, order numbers, or promoted variables that help trace a Process execution. In most cases, this is more valuable than logging full message bodies. Especially in production, avoid storing business payloads unless there is a clear operational or compliance reason to do so. ### Log large payloads outside Frends When storing business payloads is required by the use case, consider storing them in an external database or system, rather than on the Frends platform through logging. Excessive logging in Frends may cause slowdowns to Processes and the Frends UI, making the service less stable and usable. External system for logging will often be more effective in querying and displaying the additional content, while Frends logging is good for promoting the related IDs to query with, as well as the occasional error and other runtime related data. ### Treat sensitive data in logs and archives as a design decision If Personally Identifiable Information (PII) or other sensitive data is logged or archived, document what is stored, why it is stored, who can access it, how long it is retained, and how deletion is handled. Sensitive values such as passwords, tokens, and secret credentials should not be logged. This is both a security and compliance best practice. ### Use Promoted Variables for operational visibility Promoted Variables are a practical way to improve monitoring and supportability. Promote key business identifiers so support teams can quickly find relevant Process executions without needing to inspect entire payloads. This enables faster troubleshooting and more precise monitoring rules. ### Prefer clarity before optimization Start by designing Processes that are correct, readable, and maintainable. Optimize only after there is a real performance need and after the slow or memory-heavy parts have been identified. Premature optimization often makes Frends solutions harder to understand without delivering meaningful benefit. ### Reduce unnecessary transformations and data movement Every extra conversion, reshape, and payload copy adds processing overhead and complexity. Keep data handling as direct as possible, especially in larger or more frequent integrations. Avoid passing large payloads between components when small identifiers or filtered datasets are enough. ### Use incremental reads instead of full reloads When reading from databases or other source systems, prefer incremental loading patterns such as timestamp-based filtering or tracked cursor values instead of repeatedly loading everything. This reduces load on source systems, speeds up execution, and lowers the amount of data each Process must handle. ### Select Tasks deliberately Choose Tasks that are designed for the operation being performed rather than adapting general-purpose Tasks to fit an unusual purpose. When a dedicated Task exists for a given protocol or system, prefer it over workarounds using more generic HTTP or file Tasks. Review the available Task catalog before building custom logic, as many common operations are already covered. Using the right Task for the job reduces the amount of custom code inside Processes, improves readability, and keeps the solution aligned with supported and testable patterns. ### Store credentials securely Store usernames, passwords, tokens, and similar secrets in Environment Variables using secret values where applicable instead of hardcoding them into Processes. ### Validate external input carefully When Processes accept input from APIs, files, SQL parameters, LDAP filters, or HTTP headers, validate and sanitize that input before use. Apply parameterized SQL, sanitize LDAP filter content, validate URLs and headers, and check file content and limits where relevant. Input validation is a core part of secure integration design. ### Do not place secrets in logged fields Sensitive values, even through secret Environment Variables, should not be used in fields which will be logged, or otherwise often exposed such as URL query parameters. Use secret fields in Tasks for placing the sensitive values to avoid them being logged in Frends, and use **Skip logging result and parameters** option to explicitly avoid logging any values and results in Frends that may contain sensitive information. Also consider where the value will be sent to, and in which format. For example URLs are more likely to be logged or exposed in intermediary systems, making them a poor location for confidential information. ### Design APIs with governance in mind API design should follow agreed conventions for naming, versioning, security, error handling, and documentation. A design-first approach using OpenAPI encourages better contracts and earlier review. API governance also benefits from review practices and a central catalog so that new APIs stay consistent and reusable. ### Deploy APIs and linked Processes together When deploying APIs, keep the API definition and linked Processes aligned. Separating their deployment can lead to warnings, errors, or inconsistent behavior. API deployments should also preferably target controlled environments such as Test or Production instead of relying on Development as the main operating state. ### Version changes deliberately Versioning should be part of both Process and API lifecycle management. Save changes with meaningful comments, preferably linked to the related work item, and maintain traceability from change to implementation reason. For APIs, versioning decisions should be made explicitly because some API properties cannot simply be changed in place after initial creation. ### Review solutions before handover Processes, Tasks, and related documentation should be reviewed by another developer before they are handed over to operations or a customer team. Review improves quality, catches maintainability issues early, and helps ensure the solution is understandable by someone other than the original developer. ### Document operations, not only implementation A good Frends solution should include operating instructions, not just technical build notes. Documentation should explain what the integration does, dependencies, common failures, recovery actions, support contacts, maintenance tasks, and how correct operation is verified. This is critical for long-term supportability. ### Test error scenarios on purpose Do not test only the happy path. Simulate downstream failures, invalid inputs, timeouts, and unavailable systems to verify that retries, alerts, logging, and recovery logic behave as expected. Frends solutions are production-ready only when failure behavior has been tested as deliberately as success behavior. ### Use conditional triggering to reduce empty runs Where supported by the use case, trigger Processes only when meaningful criteria are met rather than running frequent schedules that often do nothing. This reduces unnecessary executions and keeps monitoring cleaner. Trigger conditions should remain simple and should not contain business logic that changes data state. ### Keep integrations maintainable over time Good Frends development is not only about getting the first version running. It is about ensuring that the solution remains understandable, observable, secure, and changeable as systems, teams, and requirements evolve. Standardized naming, documented design, controlled logging, deliberate error handling, and disciplined reuse together create integrations that are easier to support and safer to scale. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.frends.com/guides/general/frends-best-practices-collection.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.