Content Development Guidelines for Turbine

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 RecordsRecords 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 organization should resemble a shallow tree

i.e. one condition and one outcome. Workflow can become overwhelming quickly when too much logic is added.

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.

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.

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

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.

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

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.