Automations (Beta)
The Automations feature is currently in Beta.
Automations are created by configuring an Event Filter in SD Elements with one or more Action Plans.
For step-by-step examples of Automations, see Automations use cases |
Each Event Filter can be configured to watch for a certain Event that satisfies some criteria. Some examples of such Events are verification scans, task status changes, and new project creation. When one of these Events occurs, an automation might then execute an Action, like adding a note to a task, or sending an email notification.
Not all Actions are useful with all Events. For example, a "Modify task status" Action is not applicable to a "Project was created" Event as no tasks exist in a brand new project.
You can manage Automations through either the API or the UI. In the UI, the Automations page can be accessed through the gear icon menu.
User permissions
To create and edit Automations, a user needs permissions for:
-
Automations → Create and edit automations
Security context
Automations run as "SD Elements Service-Bot", not the user that created the Automation. Service-Bot is an account used for scheduled issue tracker syncs and security tool imports, as well as Automations. The account has full access to all data in an instance. Be aware that if a user has the Automations permission, that user indirectly has access to perform Actions with full administrative access.
What are Events?
Events are specific outcomes that occur in SD Elements with predefined criteria. Events are used to trigger Actions, or automated responses. For example, when the Event of a SAST code scanner running and importing results into SD Elements with zero high and zero critical findings occurs, SD Elements can automatically fulfill the Action of marking the relevant task as 'Complete'.
What are Actions?
Actions are specific tasks that are performed based on predefined criteria. Actions can be carried out automatically based on how they are defined.
What are placeholders?
Placeholders are variable strings that can be used in Actions. They are replaced with real values from the Event when it is executed.
Each Event defines a set of placeholders that are available to use in the Actions. Refer to the section on a specific Event to see what placeholders it provides.
Example:
An Event Filter using the "Project Created" Event provides the placeholder ${project_name} amongst others. An email notification is added with the following subject.
"subject": "New project: ${project_name} created"
When a user creates a new project called "Mobile App", configured recipients will receive an email with the subject line: "New project: Mobile App created"
Available placeholders
Placeholders for: project created, project survey locked |
|
---|---|
Placeholder |
Description |
${application_name} |
The name of the project’s parent application. |
${business_unit_name} |
The name of the project’s parent business unit. |
${project_members} |
A string of comma-separated email addresses of members of the project. |
${project_name} |
The name of the project. |
${survey_url} |
A URL that links to the survey page for the project. |
Placeholders for: Verification tool ran |
|
Placeholder |
Description |
${scanner_name} |
The name of the scanner tool if available. |
${scan_results_url} |
The URL to scan results if available. |
${scan_details} |
The metadata information reported by the scanning tool with details of the scan. It has the following template:
|
Details
Events and Actions are described with the following details:
-
Description: An explanation of the Event or Action.
-
Criteria: A list of all parameters that can be accepted by the Event or Action. This is indicated by the parameter’s label in the user interface and its API key (Label / API Key).
-
Placeholders: A list of all placeholders that can be accepted by the Event or Action.
-
Notes: Important information particular to an Event or Action.
Events for Automations
Project Created
Represents an Event where a project was created.
Criteria |
Description |
Placeholders |
Notes |
---|---|---|---|
Application / |
The application in which the new project was created. |
|
Should not be combined with |
Business Unit / |
The business unit in which the new project was created. |
Project Survey Locked
Represents an Event where a project survey was locked.
Criteria |
Description |
Placeholders |
Notes |
---|---|---|---|
Application / |
The application in which a project’s survey was locked. |
|
None. |
Business Unit / |
The business unit in which a project’s survey was locked. |
Task Status Changed
Represents an Event where a task’s status was modified.
A Task Status Changed event has either:
-
Occurred over a time period
-
Not occurred over a time period
1. Has occurred over a time period |
|||
---|---|---|---|
Criteria |
Description |
Placeholders |
Notes |
Task / |
The task that had its status changed. |
None. |
None. |
Task Status / |
The status that the task transitioned to.
|
||
2. Has not occurred over a time period |
|||
Task Status Changed Events that are marked as having not occurred over a time period require a threshold. |
Verification tool ran
Represents an Event where a verification integration process was run. This event occurs when you import scan results through a manual upload or a remote connection sync.
A Verification tool ran event has either:
-
Occurred over a time period
-
Not occurred over a time period
1. Has occurred over a time period |
|||
---|---|---|---|
Criteria |
Description |
Placeholders |
Notes |
|
|
The criteria for this Event must be in JSON for both the UI and the API. Provide the criteria in this format:
|
|
|
Used only if the "has not occurred over a time period" option is selected. |
||
severity_counts (Optional) |
|||
2. Has not occurred over a time period |
|||
Verification tool ran Events that are marked as having not occurred over a time period require a threshold. |
Actions for Automations
Transition Task Status
Action that transitions a task to a specific status.
Criteria |
Description |
Placeholders |
---|---|---|
Task / |
The task to automatically transition.
|
None. |
Status / |
The status to automatically transition a task to. |
None. |
Add note / |
A flag that enables a note to be added to a task after a successful transition. Defaults to 'true'. |
All |
Note / |
Custom text to use for the note that is added to the task after a successful transition. If left empty, it uses the default message: "Task status automatically transitioned to <new status>." |
All |
Add Task Note
Action that adds a note to a task.
Criteria |
Description |
Placeholders |
---|---|---|
Task / |
The task to receive the note. |
None. |
Note / |
The text to appear in the note. Has access to placeholders. |
None. |
Send Email Notification
Action that sends an email to a list of recipients.
Criteria |
Description |
Placeholders |
---|---|---|
Recipients / |
The list of email addresses the email is sent to. |
|
Subject / |
Subject line of the email. |
All |
Message / |
Body of the email. |
All |
Limits and restrictions
-
The Project Created Event can perform only Send Email Notification as an Action.
-
If an event of the type being configured in the automation wizard has never occurred, automation will be unable to complete that event.
-
The option has occurred over a time period has a slightly different criteria format from the option has not occurred over a time period.
-
Selecting the option has not occurred over a time period requires you to indicate a time period in days, such as 30 days.
-
-
The number of Recipients is limited to 100. If it expands to over 100 because of the project_members placeholder, it will fail.
-
You can save an Event without an Action, but it will not perform anything.
Threshold
Some Events support Threshold criteria. Threshold criteria are configured to perform Actions when the chosen Event has not occurred for some period of time.
For example, you can configure a 14-day Threshold on a Verification tool ran Event, and add a Send email notification Action. At the end of the first sprint, someone runs a Verification scan on the project. If, after 14 days, no one runs a Verification scan on this project again, an email will be sent to the recipients configured in the Action.
When does a notification email send with a 14-day Threshold? Condition 1: A Threshold of 14 days passes (1 sprint) Condition 2: No Verification scan has run since the last scan |
||
Days passed |
Verification tool ran Event |
Email Action |
---|---|---|
<14 |
Has not run |
Not sent |
<14 |
Has run |
Not sent |
14 |
Has run |
Not sent |
14 |
Has not run |
Sent |
In this example, the email notification will only send once both conditions are satisfied. |
Threshold configuration
Threshold criteria must be configured as its own automation. To do this, create a separate Automation using Verification tool ran to detect actual Verification scans.
A user can set additional criteria on Threshold Events, such as scanner categories or findings. This additional criteria allows a user to create an Automation to set a specific process task, "T1368: Perform security testing using SAST tools", to 'Incomplete' if a SAST scan with no critical findings has not occurred in a set period of time. For more information about process tasks, see Process Tasks.
Threshold limitations
The date and time of the last matching Event is used to determine whether a Threshold is crossed. One limitation of configuring findings in the criteria is that if all past scans had findings that exceeded the criteria settings, then there is no last matching Event to use in checking the Threshold. In these cases, the Threshold Event will never perform its Actions until at least one matching Event has occurred.
For instance, if you want to be notified if 6 months have passed since there was a scan with zero critical findings, the Threshold will never trigger if you never have a scan with no critical findings.
The Threshold looks for a scan with zero critical findings, and then sees how long ago that was. With no initial successful scan, the feature has no Event or date to use as a baseline to determine if the Event occurred beyond the Threshold time. If there is no starting line, it can never start.
Process Tasks and Activities
For more details about Process Tasks and Activities, please see Process Tasks.