diff --git a/docs/content/docs/connections/index.mdx b/docs/content/docs/connections/index.mdx index ffdabcf10..f80582cf9 100644 --- a/docs/content/docs/connections/index.mdx +++ b/docs/content/docs/connections/index.mdx @@ -3,3 +3,192 @@ title: Connections description: Connect your blocks to one another. --- +import { Callout } from 'fumadocs-ui/components/callout' +import { Tabs, Tab } from 'fumadocs-ui/components/tabs' +import { Steps, Step } from 'fumadocs-ui/components/steps' +import { Files, Folder, File } from 'fumadocs-ui/components/files' +import { ConnectIcon } from '@/components/icons' + +Connections are the pathways that allow data to flow between blocks in your workflow. They define how information is passed from one block to another, enabling you to create sophisticated, multi-step processes. + + + Properly configured connections are essential for creating effective workflows. They determine how data moves through your system and how blocks interact with each other. + + +## How Connections Work + +When you connect two blocks in Sim Studio, you're establishing a data flow relationship: + + + + Create Connection: Draw a connection line between an output port of one block and an input port of another block + + + Connection Tag: A connection tag appears, representing the data that can flow between the blocks + + + Use Connection Data: Reference data from the source block in the destination block using connection tags + + + Data Transformation: Optionally transform or filter the data as it passes between blocks + + + +![Connections in action](public/connections.gif) + +## Connection Tags + +Connection tags are visual representations of the data available from connected blocks. They provide an easy way to reference outputs from previous blocks in your workflow. + +### Using Connection Tags + +
+
+

Drag and Drop

+

+ Click on a connection tag and drag it into input fields of destination blocks. A dropdown will appear showing available values. +

+
+ +
+

Angle Bracket Syntax

+

+ Type <> in input fields to see a dropdown of available connection values from previous blocks. +

+
+
+ +## Connection Data Structure + +When you connect blocks, the output data structure from the source block determines what values are available in the destination block: + + + + ```json + { + "content": "The generated text response", + "model": "gpt-4", + "tokens": { + "prompt": 120, + "completion": 85, + "total": 205 + }, + "toolCalls": [...] + } + ``` + + + ```json + { + "status": 200, + "body": { ... }, + "headers": { ... }, + "error": null + } + ``` + + + ```json + { + "result": "Function return value", + "stdout": "Console output", + "executionTime": 45 + } + ``` + + + +## Accessing Nested Data + +You can access nested properties from connected blocks using dot notation: + + + + + + + + +## Dynamic References + +Connection references are evaluated at runtime, allowing for dynamic data flow through your workflow: + +```javascript +// In a Function block, you can access connected data +const userName = input.userBlock.name; +const orderTotal = input.apiBlock.body.order.total; + +// Process the data +const discount = orderTotal > 100 ? 0.1 : 0; +const finalPrice = orderTotal * (1 - discount); + +// Return the result +return { + userName, + originalTotal: orderTotal, + discount: discount * 100 + '%', + finalPrice +}; +``` + +## Connection Types + +Sim Studio supports different types of connections based on the blocks being connected: + +
+
+

Data Connections

+

+ Pass data between blocks for processing or transformation +

+
+ +
+

Control Connections

+

+ Determine execution flow based on conditions or routing decisions +

+
+ +
+

Feedback Connections

+

+ Create loops by connecting later blocks back to earlier ones +

+
+
+ +## Best Practices + +### Organize Your Connections + +Keep your workflow clean and understandable by organizing connections logically: + +- Minimize crossing connections when possible +- Group related blocks together +- Use consistent flow direction (typically left-to-right or top-to-bottom) + +### Validate Data Flow + +Ensure that the data being passed between blocks is compatible: + +- Check that required fields are available in the source block +- Verify data types match expectations +- Use Function blocks to transform data when necessary + +### Document Connection Purpose + +Add comments or descriptions to clarify the purpose of connections, especially in complex workflows: + +- What data is being passed +- Why this connection exists +- Any transformations or conditions applied to the data + +### Test Connection References + +Verify that connection references work as expected: + +- Test with different input values +- Check edge cases (empty values, large datasets) +- Ensure error handling for missing or invalid data + diff --git a/docs/public/connections.gif b/docs/public/connections.gif new file mode 100644 index 000000000..fb8acbaf7 Binary files /dev/null and b/docs/public/connections.gif differ