Tasks and Task Manager

When in the Workflow editor, notice the collapsible task palette on the left side of the Editor page.

Tasks are split into different expendable categories. Individual Tasks can be dragged and dropped on the Editor's graphical interface. From there, you connect Tasks together in a left-to-right flow. Click the pencil icon on any Task to access configuration parameters for a Task.

Task Manager

Task management involves the following:

  • Verified or Community Tasks
  • Task scope and management
  • Task versioning
  • System Tasks
  • Template Tasks

Verified or Community Tasks

Tasks can be managed via Task Manager and can be labeled as verified or community contribution. We may refer to Tasks as Template Tasks.

Tasks provided out-of-the-box with an installation are labeled as verified, with a blue ribbon icon located to the right of the Task in the palette.

Users are welcome to create their own Tasks, that will be labeled as a community contribution. The Boomerang community provides support to verified Tasks. These Tasks are described in more detail below.

Task scope and management

Task Manager is available at the Team and Global levels, depending on the user role. It is the centralized place to define and manage the Tasks available to Workflows and are based on the Tekton® Task model, however abstracts the experience so you don't need to be working in YAML directly in Kubernetes®.

Tasks follow the Tekton Task model, along with Kubernetes standards that allow you to define what you want to happen at the execution of the Task, as well as parameters that are needed.

Team Task Manager

The Team Task Manager can be found under Manage > Team Tasks and allows users in the team to create and manage Tasks scoped to the team and only available to that team. For more information, see How to Manage Team Tasks.

Global Task Manager

All of the shared Tasks across the instance of Boomerang Flow are Global Tasks that can be used by all teams.

YAML Definition

The YAML specification has three important sections to be aware of: metadata, params, and steps. Its important to note that the full Tekton Task specification is not yet fully supported. We cannot run multi-step Tasks, nor do we allow resources to be specified. For more information, see Known Issues and Limitations.

Metadata

This includes the standard name and labels metadata matching all Kubernetes object. In addition, this is the area where we store a series of annotations related to the end user experience. This is where we store the choices made in the UI that don't directly relate to the Task definition itself needed for the execution.

Annotations Description
boomerang.io/icon This is the icon for the Task as seen in the Workflow Editor.
boomerang.io/params This is the metadata around a Task parameter to allow it to be rendered in the Workflow Editor. These map to the parameters in the spec block and will be defaulted if not provided.
metadata:
  annotations:
    boomerang.io/icon: Add
    boomerang.io/params:
      - required: true
        placeholder: ''
        defaultValue: ''
        readOnly: false
        key: enterpriseId
        label: Authentication - Enterprise ID
        type: text
        helperText: Box enterprise id

Params

As part of the spec block, this is where you define parameters that are needed for the execution of the Task.

spec:
  params:
    - name: enterpriseId
      type: string
      description: ''
      default: ''
    - name: clientId
      type: string
      description: ''
      default: ''
    - name: clientSecret
      type: string
      description: ''
      default: ''

Steps

This is the definition that defines what the Task does.

spec:
  steps:
    - name: Add Box Folder
      image: boomerangio/box-service:0.0.10
      command: null
      args:
        - -props
        - box
        - add
        - folderName

Task Versioning

We may publish a new version of a Task if we want to add additional parameters or functionality. In doing so, these may introduce breaking changes. So Workflows won't be automatically updated to use the latest version of the Task.

There will be a caution icon displayed on your Workflow tile to let you know that there is a more recent version available of a Task. You can view the comparison of the previous version and what the new version looks like. You can continue to run your Workflow with the previous version, but we suggest you upgrade to the latest version.

System Tasks

System Tasks are special Tasks that affect the logic of the Workflow and do not execute inside a container, but instead affect the processing of the DAG. System Tasks are identified by their system label, that appears to the top left of a Task when dragged onto the editor.

Task Name Description Result Parameters
Acquire Lock Attempts to obtain a lock with the specified name. If no other Workflow in the team is using a lock with that name, a lock with that name and is created. If another Workflow in the team is using a lock with the specified name, the current Workflow waits until the lock is available.
Manual Approval This Task creates a pause in Workflow execution. An approver can mark their approval from the execution screen. Once an approver marks 'approve' or 'deny', then the Workflow will resume Task execution.
  • approvalStatus - approved or rejected
  • approvalDate - Date and time of the action
  • approvalUserName - Username of the approver
  • approvalUserEmail - Email of the approver
  • approvalComments - Additional comments added by the approver
Manual Task A step with a series of instructions in Markdown that can be followed by an end user. Can be utilized for manual steps that may occur in a Workflow. It can then be marked as successfully completed or not and still follows the link states.
Release Lock This Task releases a lock with the specified name.
Run Custom Task A special type of System Task. With the Custom Task, you can bring your own container and run that as a Task. Custom Tasks also have a specialized ability to dynamically create result parameters, see Getting To Know Parameters.
Run Workflow Runs the selected Workflow separately. It only triggers the Workflow, it does not wait for completion. Additionally, you can pass in parameters to the Workflow if they have been defined.
Set Result Parameter Create a parameter that is set on the result of the Workflow. This Task accepts a name and value.
Set Workflow Result Status Ability to override and set the Workflow's execution status. This allows you to mark the Workflow as failed but continue processing, for example sending an email or raising a ticket after a failure.
Switch A Switch is a subtype of a system Task which allows for simple branch-based decisions.
This Task acts as a logical gate for Workflows. The Switch Task takes a value. This could likely be a result parameter from a previous Task or an input parameter to the Workflow.
You have the ability to conditionally control the path of execution, based on the value supplied to the switch. If a link coming off the switch has a set label that does not match the value of what was supplied to the switch, then those subsequent connected Tasks will not be executed.
Wait For Event Wait for an event from an external system to resume Workflow execution. The event can be a webhook or a Cloud Event. Visit the eventing architecture for more information.

Template Tasks

The following Tasks are available as verified Tasks. Their result parameters that are available for use are identified, refer to Getting To Know Parameters for more information on how to use result parameters or provide input to Tasks with parameters.

Artifactory

Task Name Description Result Parameters
File Download Supplies login credentials to Artifactory (via username/password or username/API Token) and the direct URL route to the desired file. The file will be downloaded and named based upon the Destination Path specified.
File Upload Similar to the above plugin, specifies the URL to include the path in Artifactory, and specifies the name of the file at the end of the path that is displayed in Artifactory.

Communication

Task Name Description Result Parameters
Send Email with Postmark Template Using Postmark, send an email with template using a template ID and variables. You can optionally specify tags and a message stream.
  • To
  • SubmittedAt
  • MessageID
  • ErrorCode
  • Message
Send Email with SendGrid Using your SendGrid API Key, send a basic email.
Send Email with SendGrid Template Using your SendGrid® API Key, send a Dynamic Template email using a template ID and dynamic data.
Send Twilio SMS Reference the Twilio API

Communication with Slack

The following Slack® Tasks are to be used in conjunction with a Slack application. To integrate them with Slack API, first we'll need to Create a New Slack App, and add Bots feature. Next we need to add at least one scope to the Bot Token Scopes based on the Slack Task-specific requirements. Next we will Install to Workspace the bot and allow the requesting access permission.

Once the newly created application is installed in your workspace, the UI will show us the Bot User OAuth Token which needs to be used in the Slack Tasks as token field.

Task Name Description Result Parameters
Create Slack Channel Create a Slack channel using a Slack application. Relies on the Slack underlying API conversations.create. The Slack bot/user's required scopes are channels:manage, groups:write, im:write, mpim:write. Result called response, containing:
  • ok
  • channel
Delete Slack Channel Archives a Slack conversation using a Slack app. Not all types of conversations can be archived. Relies on the Slack underlying API conversations.archive. The Slack bot/user's required scopes are channels:manage, groups:write, im:write, mpim:write. Result called response, containing:
  • ok
Find Slack Member By Email Find a Slack user with an email address using a Slack app. Relies on the Slack underlying API users.lookupByEmail. The Slack bot/user's required scope is users:read.email.
  • slackUserId
Find Slack Member By Id Find a Slack user based on the Slack user Id using a Slack app. Relies on the Slack® underlying API users.info. The Slack bot/user's required scope is users:read.email. Result called response, containing:
  • ok
  • user
Get Slack Channel Info Retrieves the Slack channel information using a Slack app. For further reading on the underlying API conversations.info. The Slack bot/user's required scopes are channels:read, groups:read, im:read, mpim:read. Result called response, containing:
  • ok
  • channel
Get Slack Channel Members Retrieve the Slack channel members using a Slack app. Relies on the Slack underlying API conversations.members. The Slack bot/user's required scopes are channels:read, groups:read, im:read, mpim:read. Result called response, containing:
  • ok
  • members
  • response_metadata
Get Slack Channels Retrieves the Slack channels using a Slack app. For further reading on the underlying API conversations.list. The Slack bot/user's required scopes are channels:read, groups:read, im:read, mpim:read. Result called response, containing:
  • ok
  • channels
  • response_metadata
Invite Members to Channel Invite Slack users to a conversation using a Slack app. Relies on the Slack underlying API conversations.invite. The Slack bot/user's required scopes are channels:manage, groups:write, im:write, mpim:write. Result called response, containing:
  • ok
  • channel
Remove Member from Channel Removes a user from Slack conversation using a Slack app. Relies on the Slack underlying API conversations.kick. The Slack bot/user's required scopes are channels:manage, groups:write, im:write, mpim:write. Result called response, containing:
  • ok
Send Custom Slack Message Allows for more configuration and creates a custom JSON payload if the simple Slack message does not meet your needs. Refer to the Slack API.
Send Simple Slack Message Uses the wrapper plugin around the Slack Messaging API.
Send Slack Message with File Contents Similar to the simple Slack message, this plugin allows you to attach contents of a file.
Upload Slack File with Message Uploads a file to Slack.
Slack User Look Up Derives a Slack username from an email, using the Slack API. Usually used as a step before sending a Slack message to a user.

File Utilities

Task Name Description Result Parameters
Check File Contains String Specifies a direct path that includes the file name. The plugin will search to find a specified regex pattern for the file.
Check File or Folder Exists Searches for a file or folder. You can have the Task fail if the folder/file is not found.
Create File Specifies a file location and its contents.
Read File to Parameter Specifies a file and the desired result parameter name. The file gets stored as a result parameter string and can be referenced as a value in later Tasks. content
Replace String in a File Within a specified file, replaces the first instance of a string with the value supplied by the user during configuration.
Replace Tokens in a File Within a specified file or files, replace all occurrences of tokens between a start and end pattern that all available as Parameters, so @parmaeter@ would be replaced with the value of that parameter. files

GitHub

Task Name Description Result Parameters
Add Issue To Project Adds an issue to GitHub® Issues Project.
  • result
Create Team in Organization Creates a GitHub® team in the organization. The authenticated user must be a member or owner of the organization where the team is created.
  • team
Delete Team from Organization Deletes a GitHub team from the organization. To delete a team, the authenticated user must be an organization owner or team maintainer. If you are an organization owner, deleting a parent team will delete all of its child teams as well.
Find Issues and Label Finds issues in a repository based on time since last activity, and adds a label and a comment. This is useful for marking issues inactive or reminding users to update an issue.
Find Issues and Remove Finds GitHub issues and removes them with optional days since activity and labels.
Find Repositories in Org Finds GitHub repositories in a particular organization filtered by the desired visibility.
  • repositories
  • repositoriesPrettyPrint
Get All Organizations Lists all GitHub organizations, in the order that they were created on GitHub. The Task offers a pagination capability powered by the First organization ID and Number of organizations parameters.
  • organizations
Get All Teams In Organization Lists all teams in an organization that are visible to the authenticated user's token. The Task offers a pagination capability powered by the Page Number and Number of teams per page parameters.
  • teams
Get Organization Info Retrieves a GitHub organization details based on its name.
  • organization
Get Github Repository Get the GitHub repository details based on the GitHub URL.
  • result
Get Team In Organization Retrieves a GitHub team details based on its name.
  • team
Invite Collaborator to Project Invites a GitHub user identified via email to collaborate to a repository.
Invite Member to Team Adds an organization member to a GitHub team. If the user is already a member of the team, the Task will update the role of the team member's role.
  • result of the invitation
Invite User to Organization Adds a member to a GitHub organization.
  • result of the invitation
Make Repositories Private Loops through and changes repositories to private visibility.
Remove Collaborator From Project Removes a GitHub Collaborator from a repository.
Remove Member from Team Removes a team membership between a user and a GitHub team, within an organization.

IBM Services Essentials

Task Name Description Result Parameters
Send Platform Email Configures an email to be sent from the platform.
Send Platform Notification Sends a platform-wide notification. For more information on platform notifications, see the IBM Services Essentials documentation.
Create Support Center Ticket Raise a support center ticket as issue or query. Should be used when you got a problem, found a bug or just need some help.

ServiceNow

Task Name Description Result Parameters
Get Incidents Gets incidents from ServiceNow® with optional state.
Update Incidents Updates incidents from ServiceNow.

Utilities

Task Name Description Result Parameters
Execute HTTP Call Makes an HTTP request, and specifies an endpoint. response with the content of the HTTP request
Execute Shell Script Supply your own script. This is a special type of Task that also allows dynamic creation of result parameters, see Getting To Know Parameters.
File JSONPath To Parameter Takes the first value returned by a valid JSONPath expression from a File content and sets as an output parameter. evaluation - The value based on the applied expression
JSONPath To Parameter Takes the first value returned by a valid JSONPath expression and sets as an output parameter. evaluation - The value based on the applied expression
Run Python Script Execute a Python script. The returned result of the script is returned as the result value of the Task. output - Python script standard output standard and error content.
Sleep Sleeps for a specified duration, in milliseconds.

Box

Task Name Description Result Parameters
Add Box Folder Adds a Box® folder with the specified name. If no parent folder is provided, then the Box root folder is used.
  • status - OK or Error
  • id
Add User To Box Folder Adds an user to the specified Box folder.
  • status - OK or Error
Download File From Box Downloads a file from Box to the provided path.
  • status - OK or Error
Get Box Folder Info Gets the details of a Box folder.
  • status - OK or Error
  • folder
List Box Folders Retrieves and lists an user's Box folders.
  • status - OK or Error
  • folders
Remove Box Folder Removes a Box folder.
  • status - OK or Error
Remove User From Box Folder Removes an user from a Box folder.
  • status - OK or Error
Upload File To Box Uploads the file at the specified path to the desired Box folder.
  • status - OK or Error
  • id

Google Sheets

In order to integrate the following tasks with the Google® Sheets API, we'll need to :

For more information, please visit Google for Developers Guide.

For information regarding the supported cell ranges and different ID's, please see Google Sheets Concepts.

Task Name Description Result Parameters
Add Sheet Adds a new sheet to an existing Google spreadsheet.
Append Data Appends data to an existing Google spreadsheet. response - the API response
Clear Data Clears the cell data in the specified ranges from a Google spreadsheet.
Copy Sheet To Another Spreadsheet Copies a sheet from a Google spreadsheet to another.
Create Spreadsheet Creates a new Google spreadsheet with the provided name. spreadsheet - the API response
Delete Sheet Deletes a sheet from an existing Google spreadsheet.
Get Data Gets the cell data in the specified ranges from a Google spreadsheet. rows - the list of row cell data from the provided ranges
Update Data Updates the cell data from a Google spreadsheet. response - the API response