---
title: Content Development Guidelines for Turbine
slug: content-development-guidelines-for-turbine
docTags:
createdAt: 2025-08-11T11:12:45.000Z
---
Swimlane Turbine provides users with the flexibility to build rich applications backed by robust automations. Given the degree of flexibility, it is best to adhere to the following best practice recommendations when building content in Swimlane Turbine.
| **Area** | **Requirements** | Notes |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Applications and Applets** | Fields **must** have descriptive names. | |
| | Field names **should** only be plural form if the content is an array or list | |
| | Field Help Text **should** only be used for fields which are being used to collect information in a process which the intended audience will experience infrequently | And when the field name does not make that which is being requested intuitive / obvious to the average high school graduate. |
| | Applet Field names **must **always include a differentiating value | To avoid name conflicts when adding to an Application, for example, “Phishing Reported Date Time”. |
| | **Should** only display fields to the user that are relevant to what they are doing. | Use Workflow to hide/show sections. |
| | **Must** avoid the risk to storing large amounts of data within a single record. | Pay special attention to records with large data sizes and how the data is stored. [Application Records](docId\:vqA4TreCaBb7JwX_L_nHt) have a limit of 100MB with fields being able to hold 30MB of data. |
| | **Must** limit the amount of expected reference records in a single reference field. | Special attention needs to be placed on reference fields that could have several hundred or thousands of reference records added to them, as performance degradation can occur with records with 1000+ references added. |
| | In a many-to-one reference relationship between records, design the content so that the side with the least amount of reference records is viewed in the UI, rather than the record with the many. | Records that are viewed should not contain many referenced records. |
| | Support fields **should** be hidden under a dedicated “Support” tab or section. | |
| | Descriptions on the values for Selection fields **should** be used when the number of options is seven or greater. | |
| | There **must** not be unbounded List fields. If a large (100+) list of values is required, use a dedicated application and a reference field to store the data. Another option is to use a text field, and then in Canvas, split the text field into an array using Native Transformation **Split** or **Regex Split**. | |
| | Text fields **should** contain a placeholder value | Placeholder values help the user understand the type of data that should be stored. It also may be used to better inform AI models of the intention of the field. |
| | Orchestrator **must** use a Date field if Time is not required when capturing a timestamp. | Be intentional when selecting a Date field vs a Date & Time field. If time is not required, Date field is preferred. |
| | Numeric fields **should** include minimum and maximum values. | Basic built-in guardrails keeping numeric field values within the desired range results in a more accurate outcome. |
| | Applications/Applets **must** have a useful description. | |
| | Saved Reports **should** not use “contains” searches, as these searches are comparatively expensive. | Keyword searches using the Condition Builder is preferred. |
| **Workflow** | Workflow organization **should** resemble a shallow tree | i.e. one condition and one outcome. Workflow can become overwhelming quickly when too much logic is added. |
| **Widgets** | **Must** minimize the number of widgets being *displayed* at any one time by moving widgets into tabs or sections. | Each Widget behaves like another webpage embedded in the view, that is, each Widget gets a copy of the Record, each Widget has it’s own event listeners, etc. Visualizing fewer widgets on the screen at one time will reduce performance impact on the browser. |
| | **Should** consolidate functionality of multiple widgets into one if possible. | Balance between widget complexity and reusability. That is, use one widget with three action buttons rather than three widgets each with one action button. |
| | **Should **consider reusability of the widget. | Reusability of widgets is also important. Consider how the widget can be used in other use cases when designing. |
| | **Must** include widget configuration parameters at the top half of the widget code. | Describe what the widget does, any field inputs, and any configuration settings. |
| | **Should** not hardcode values into the widget code. Use application/applet fields instead. | That is pull data from a selection field, rather than hard code the selection values directly into the widget code. |
| **Canvas Playbooks** | Playbook names **must** reflect the Solution/Use Case in which it supports. | For example, Collaboration Extension, Alert Ingestion |
| | Playbooks **must **have a detailed description. | |
| | Record Event triggers **must** have condition filters. | Record Create and Record Update. |
| | **Should** check for existing components before create new ones. | Components are meant to be reusable snippets of code. Attempt to discover if a component already exists that meets your needs before creating a new one. |
| | **Should **limit the usage of nested sub-Components if you have readability/complexity concerns. If you are working through a multi-step process, consider bringing the data back up to the root level and starting the next stage in the process from there. | That is, Alert Ingestion, Enrichment, Correlation, Knowledge Base Article Lookup, Hero AI Case Summarization are all stages in a process, in a single flow, that should be at the root of the flow and not nested deeply within components.
This also helps to keep Components reusable. |
| | **Should** stagger Hourly Cron (Scheduled) Trigger | When using a Cron to trigger a playbook, try not to set the execution time to 0 past the hour. Stagger executions to prevent high playbook execution volume at the top of every hour. |
| **Canvas Components** | Component names **must** reflect that action that is being performed. | For example, convert CrowdStrike Alerts into TEDs, Strip HTML from String. |
| | Components **must** have a detailed description. | |
| | Components **should**only use Interfaces if they intend to be swappable. Otherwise, user-defined is preferred. | For example, VICs. |
| | Components **should** always validate their inputs | |
| | Components **must **never fail silently. More on values below. | |
| | Failures that break a business process **should** propagate. These are seen more as “errors”. | For example, a record search returned an empty result, a VIC was unable to authenticate to an email provider. |
| | Failures that don’t break the business progress **should** be highlighted in the content, but the Flow should continue to execute. These are seen more as “warnings”. | For example. no Knowledge Base Articles were discovered. |
| | Default values of Component inputs **should** be set. | For example, max\_token count |
| | | |
| | Components **should** be designed as if their inputs and outputs will not change. | |
| **Canvas Automation** | Consideration **must** be made to the concept that Component execution has more overhead than flat actions runs (actions outside of a component that run in a Flow). | Consider this when using Components in Canvas. Components are **best** used for re-usability, and not *solely* for readability. Readability use cases for Components are also valid. |
| | Infinite loops **must** be avoided. | Infinite loop protection mechanisms are in place on all Turbine Cloud regions.
\* A Flow with a record update trigger can not modify that same invoking record |
| | Trigger Conditions **must** be used for all Record Events Triggers. Especially Record Update triggers. | |
| | Multiple updates to the same record within a single flow **should** be avoided. | Instead, group record updates into a single UPSERT at the end of the Flow. |
| | Record Search actions **must** only return the necessary fields. | |
| | “Contains” searches in playbook actions **should** be avoided. | |
| **Canvas Actions** | Action names **should** be short and start with a verb. | For example, normalize Alert Data, Call Crowdstrike update Alert, Send Slack Message |
| | Actions doing external API calls **must** be configured with at least 3 retries with a 15-30 second wait | |
| **Data Transformations** | Data transformations **must** use native transformation actions as a priority where possible. | |
| | Data transformations **must** have a descriptive title | |
| | Data transformations **must** have a descriptive block description | |
| | Advanced data transformations **must** use inline comments. | |
| | Script actions **should** not be used in high volume flows if advanced JSONATA is possible. | |
| **Error Handling** | **Should** use Python Script Action to raise errors. | raise ComponentInputError (This is a custom error message) |
| | Exception classes **should** be used to create custom error types. | class ComponentInputError(Exception) |
| | **Should** write errors to a dedicated application field. | |