Script Definitions#

Create, manage, and organize your custom JavaScript scripts in Automan.

Overview#

Script Definitions are the core building blocks of Automan. A definition contains:

• Name - A descriptive name for the script
• Description - Optional documentation about what the script does
• JavaScript Code - The actual script that executes
• Triggers - Optional event triggers that execute the script
• Cron Schedule - Optional scheduled execution configuration

Definitions can be used in multiple contexts:

• Workflow post functions
• Automation actions
• Event triggers
• Scheduled (cron) jobs

Accessing Definitions#

1. Navigate to Apps > Automan
2. The Definitions tab is the default view

Creating a Definition#

Step 1: Start Creation#

Click the New Definition button in the top right corner.

Step 2: Fill in Details#

1. Name (required) - Enter a descriptive name
2. Description (optional) - Add documentation about the script’s purpose

Step 3: Write Code#

Use the JavaScript code editor to write your script. The editor provides:

• Syntax highlighting
• Line numbers

Step 4: Configure Triggers (Optional)#

Select event triggers to automatically execute this script when events occur:

Step 5: Test the Script#

Click Run Script to test your code before saving:

Step 6: Save#

Click Save to create the definition.

Editing a Definition#

1. Click on a definition row in the list
2. Make your changes
3. Click Save

Changes are saved as a new version, preserving the history.

Definition Tags#

Definitions automatically display tags showing how they are used:

Bulk Operations#

Selecting Multiple Definitions#

1. Use the checkboxes on the left to select definitions
2. Or use the header checkbox to select all

Bulk Duplicate#

1. Select one or more definitions
2. Click Duplicate (N) button
3. Confirm the operation

New definitions are created with “(Copy)” appended to the name.

Bulk Delete#

1. Select one or more definitions
2. Click Delete (N) button
3. Confirm the operation

Warning: Deletion is permanent and cannot be undone.

Version History#

Automan automatically saves a new version each time you modify a definition’s code.

Viewing History#

1. Edit a definition
2. Click the History tab
3. View the list of versions with timestamps and authors

Viewing Version Code#

1. Click View Code on any version row
2. A modal shows the code from that version

Restoring a Previous Version#

To restore a previous version:

1. View the code from the history
2. Copy the code
3. Go to the General tab
4. Paste the code
5. Save

Searching Definitions#

Use the search box to filter definitions by name:

1. Type in the search field
2. Results filter in real-time
3. Clear the search to show all definitions

Code Editor Features#

The Automan code editor provides several features to help you write scripts:

JavaScript Support#

• Most of ES2023+ syntax support
• Async/await support
• Modern JavaScript features

Available Globals#

The following globals are available in your scripts:

Example Script Structure#

// Log the event for debugging
console.log("Event received:", event);

// Access environment variables
const apiKey = process.env.MY_API_KEY;

// Make a Jira API call
const response = await requestJira(
  route`/rest/api/3/myself`
);
const user = await response.json();

console.log("Current user:", user.displayName);

// Return a value (for automation actions)
{ success: true, user: user.displayName };

Testing Scripts#

Before deploying, test your scripts using the Run Script button.

Test Results#

After running a test, you’ll see:

• Status - Success or Failed
• Duration - Execution time in milliseconds
• Console Output - All console.log() messages
• Return Value - The script’s return value (if any)
• Error - Error message and stack trace (if failed)

Test Event Object#

When testing, the event object contains:

{
  type: "test"
}

For more realistic testing, you may need to manually fetch data:

// Simulate testing with a specific work item
const testIssueKey = "PROJ-123";
const response = await requestJira(route`/rest/api/3/issue/${testIssueKey}`);
const issue = await response.json();

// Now work with the work item data
console.log("Testing with work item:", issue.key);

Definition States#

A definition can be in various states based on its configuration:

Active Definition#

• Has code saved
• May have triggers, cron, or be used in workflows/automations
• Will execute when triggered

Empty Definition#

• No code saved
• Will not execute even if triggers are configured
• Useful as a placeholder

Orphaned Definition#

• Not used in any workflow post function or automation
• No triggers or cron configured
• May be a candidate for deletion

Best Practices#

Naming Conventions#

• Use descriptive names: “Auto-assign high priority work items” instead of “Script 1”
• Include the context: “Workflow: Close subtasks on parent resolution”
• Prefix by area: “Report: Weekly status summary”

Documentation#

• Use the description field to document purpose and behavior
• Add comments in code for complex logic
• Note any dependencies (environment variables, custom fields)

Organization#

• Group related scripts with similar naming prefixes
• Use tags (shown automatically) to understand usage
• Regularly review and clean up unused definitions

Code Quality#

• Handle errors gracefully with try/catch
• Log meaningful messages for debugging
• Avoid hardcoding values - use environment variables
• Test before deploying

Troubleshooting#

Definition Not Executing#

1. Check that code is saved (not empty)
2. Verify triggers are configured correctly
3. For workflow/automation, ensure the definition is properly linked
4. Review the Executions tab for errors

Related Topics#

• Workflow Post Functions - Using definitions in workflows
• Automation Actions - Using definitions in automation rules
• Event Triggers - Subscribing to Jira events
• Scheduled Scripts - Running scripts on a schedule
• Environment Variables - Managing secrets and configuration