Create Record
13 min
The Create Record native action creates a new record in a selected application from the playbook builder. The action maps data to application fields and returns the tracking ID of the created record.
Overview
The Create Record action enables you to programmatically create records in Swimlane applications from within playbooks. This is useful for automating record creation based on events, data from other systems, or calculated values from upstream actions.
Key Benefits
- Native Action: Integrated directly into the playbook builder for streamlined workflow creation.
- Flexible Field Mapping: Map data from upstream actions, playbook inputs, or expressions to application fields.
- Record Restrictions: Optionally restrict record access to specific users or groups.
- Tracking ID Output: Returns the tracking ID of the created record for use in downstream actions.
- At Most Once Execution: Ensures the record is created exactly once, even if the playbook is retried.
Inputs
The Create Record action requires the following inputs:
Required Inputs
- Application: Select an application by either:
- Application ID: The unique identifier of the application
- Application Name: The name of the application
- Note: You must provide either applicationId or applicationName, but not necessarily both.
- Fields: A dictionary/object mapping field keys to their values. Each field value can be:
- A static value
- A reference to a playbook property from upstream actions
- A reference to playbook inputs
- An expression that evaluates to a value
Optional Inputs
- Restrictions: Users and/or groups to restrict the record to:
- Users: Array of user IDs or usernames
- Groups: Array of group IDs or group names
Configuring the Create Record Action
Step 1: Select Application
- From the Inputs tab, select an application:
- Choose from the dropdown list of available applications, or
- Use an expression to reference an application ID or name dynamically
Step 2: Add Fields
- Click Add fields to open the field selection dialog.
- From the existing application fields, click on the desired fields to add to the record. You can select multiple fields.
- Click Dismiss to close the window and return to the Inputs tab.
Step 3: Map Field Values
After adding fields, map values to each field:
- For each field, click the + icon to set its value.
- Choose from:
- Playbook Property: Select a property from upstream actions or playbook inputs
- Expression: Write an expression to calculate the value dynamically
- Static Value: Enter a static value directly
Example: To map a value from an upstream HTTP Request action:
- Click the + icon next to a field
- Select Playbook Property
- Navigate to $actions.httpRequestName.result.body.fieldName
Step 4: Configure Restrictions (Optional)
If you need to restrict record access:
- Expand the Restrictions section.
- Add Users: Enter user IDs or usernames (can be static or from expressions).
- Add Groups: Enter group IDs or group names (can be static or from expressions).
Note: Restrictions determine who can view and access the created record. If not specified, the record follows the application's default access rules.
Step 5: Apply Changes
Click Apply to save your configuration.
Outputs
The Create Record action provides the following outputs:
Success Output
When the record is created successfully, the action returns:
- result.tracking-id: The tracking ID (trackingFull) of the newly created record. This can be used in downstream actions to reference the record.
Example: Access the tracking ID in downstream actions:
$actions.createRecordName.result['tracking-id']Error Output
If the record creation fails, the action returns:
- error: Error information containing details about why the record creation failed.
Common Error Scenarios:
- Application not found
- Invalid field values
- Required fields missing
- Permission errors
- Validation errors
Use Cases
Example 1: Create Record from Event Data
Scenario: Create a security incident record when a security event is received.
- Configure an event trigger to receive security events.
- Add a Create Record action.
- Select the "Security Incidents" application.
- Map event data to record fields:
- severity β $event.data.severity
- description β $event.data.description
- source_ip β $event.data.sourceIP
- Use the tracking ID in downstream actions to update or reference the record.
Example 2: Create Record with Restrictions
Scenario: Create a sensitive record restricted to a specific security team.
- Add a Create Record action.
- Select the application and configure fields.
- Configure restrictions:
- Groups: ["Security Team"]
- Users: ["[email protected]"]
- The created record will only be accessible to the specified users and groups.
Example 3: Create Record from Calculated Values
Scenario: Create a record with calculated risk scores.
- Add a Script action to calculate risk scores.
- Add a Create Record action.
- Map calculated values:
- risk_score β $actions.calculateRisk.result.score
- risk_level β Expression: $actions.calculateRisk.result.score > 80 ? "High" : "Medium"
Best Practices
- Validate Required Fields: Ensure all required fields in the application are mapped before creating records.
- Handle Errors: Use On Failure paths to handle record creation errors gracefully.
- Use Tracking ID: Store or use the tracking ID from the result for downstream operations like updating or referencing the record.
- Test Field Mapping: Test your field mappings with sample data to ensure values are correctly formatted and mapped.
- Consider Restrictions: Use restrictions when creating sensitive records that should only be accessible to specific users or groups.
- Use Expressions for Dynamic Values: Leverage expressions to calculate or transform values before creating records.
- Validate Application Selection: Ensure the application ID or name is correctly specified, especially when using dynamic references.
Troubleshooting
- Record Not Created:
- Verify the application ID or name is correct.
- Check that all required fields are mapped.
- Review error output for specific validation messages.
- Invalid Field Values:
- Ensure field values match the expected data types (string, number, date, etc.).
- Check that reference field values exist in the referenced application.
- Permission Errors:
- Verify the playbook has permission to create records in the selected application.
- Check that the user running the playbook has appropriate access.
- Tracking ID Not Available:
- Ensure the action completed successfully.
- Access the tracking ID using $actions.actionName.result['tracking-id'] syntax.
- Restrictions Not Applied:
- Verify user and group IDs/names are correct.
- Ensure the specified users and groups exist in the system.