Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Creating and using custom tasks

Updated on July 14, 2022

Deployment Manager supports a range of tasks to support the different application deployment scenarios for Pega powered applications out-of-the-box. Although comprehensive, the default task configurations cannot account for every use case for every customer. The orchestrator-based custom task functionality allows you to create unique tasks specific to your business needs which can be included in pipelines. Any task not shipped with Deployment Manager is considered to be a custom task.

Note: A ruleset is required to associate a task definition with an implementation, which should be added to the application. Custom tasks are likely to be shared by multiple teams and reused where applicable, therefore it is recommended to create a dedicated component for each task.

Common use cases for custom tasks are:

  • Updating project management systems with deployment results
  • Customized notifications
  • Additional automated testing capabilities

At this time, task executions are only supported on the orchestrator environment. It is possible to create tasks that interact with candidate environments through service APIs, but this should be done with caution as direct communication between the orchestrator and the candidate environments will be restricted in the future.

Tip: For assistance in authoring a task component in Deployment Manager 5.1 or 5.2, import the PDM Task Definition found here.

Create a task definition

A task definition establishes the characteristics of a task including its name, description, and parameters. The task definition determines how the task is presented in the Deployment Manager portal and how it should be configured while working with a pipeline model.

Define a task by creating an instance of the PegaDevOps-Data-Task class and associate the definition record to the task ruleset to ensure it is packaged alongside the implementation. Refer to the following table for the required properties for the task instance.
Note: Properties marked with an asterisk (*) are mandatory.

Task definition properties

Property nameData typePurpose
TaskType*TextAlphanumeric identifier for the task type (no spaces).
PurposeTextPurpose of the task.
TaskLabel*TextEnter task label by default which appears in pipeline model.
TaskCategoryTextEnter the task category like Package & Deploy, Quality Metrics, Versioning,
DescriptionTextExplain in detail why this task is requires? what is processes? Etc.
Input parameters Page List of class Embed-PegaDevOps-ParameterThis list contains input parameter required for task processing.
Output parametersPage List of class Embed-PegaDevOps-ParameterThis list contains expected out parameters post task processing.
Supported environment types*Page List of class Embed-PegaDevOps-ParameterThis list contains task supported environment templates. Pick values from PegaDevOps-Data-EnvironmentTemplate class
taskIconClassTextEnter an icon class for visibility in the pipeline configuration for the task. See https://design.pega.com/components-icons for the icon classes.

Implement the task runtime

The task runtime executes in the background when it has been queued up by an active deployment. The Deployment Manager agent handles polling active deployments and delegates to the appropriate task runtime when required.

To implement the task runtime, follow these steps and associate them to a ruleset included in the system runtime context:

  1. Create an abstract class that inherits from the class Embed-PegaDevOps-TaskRuntime-.
    For example, a custom task that integrates with Bamboo named Embed-PegaDevOps-TaskRuntime-Bamboo.
  2. Override the SetTaskInformation data transform in the newly created class. This data transform sets the .taskType property value to the TaskType from the task definition.
  3. Override the RunTask activity. Pass the following required parameters to this activity. Use this activity to implement the task runtime.
    ParameterData type
    TaskPagePage of class PegaDevOps-Int-Task
    OrchestratorString

Posting results to orchestrator synchronously

To update the task status to the orchestrator synchronously, create a page of an integration class PegaDevOps-Int-Task, and call the ResourceUpdateInt action API activity.

Working with the callback

Running the task asynchronously requires a callback to update the system on completion of the task.

To set this up, follow the steps below.

  1. Before calling Task PUT service, fetch the access token from the orchestrator using https://<orchestrator host name:port>/prweb/PRRestService/oauth2/v1/token, client ID and client secret (from General Settings option while setting up orchestrator).
  2. When task processing is complete, post the resulting status back to the orchestrator using the following service endpoint:
    PUT https://<hostname>/prweb/api/DeploymentManager/v1/tasks/{id}
    The orchestrator returns one of three possible statuses:
    • Success - Resolved-Completed
    • Failure - Resolved-Rejected
    • Prompt for user input - Pending-Input
      • User input can be associated with appropriate default Deployment Manager privileges.
  3. Add the component application to System Runtime Context so the job scheduler can pick up and process the custom task.

Useful utilities for implementing task runtimes

The implementation contained within the RunTask activity is completely open-ended, however there are many utilities that hep make the process of implementing a task easier.

  • If a task is successful, call the ResolveTaskSuccess activity and pass the following parameters:
    • Task ID - Value is available in TaskPage under the taskID property.
    • Orchestrator URL - Available as an input parameter to the RunTask activity.
  • If a task fails, call the ResolveTaskWithError activity and pass the following parameters:
    • Task ID - Value is available in TaskPage under the taskID property.
    • Orchestrator URL - Available as an input parameter to the RunTask activity.
    • Error message - String with error message.
  • To perform CRUD actions against a Deployment Manager resource:
    • Create a page of an integration class, for instance, PegaDevOps-Int-Deployment.
    • Call one of the action API activities on that page:
      • ResourceCreateInt
      • ResourceUpdateInt
      • ResourceDeleteInt
  • If any REST API needs to be called, use the D_ExecuteRestConnector data page and pass the parameters below:
    • MethodName - Type of method used by the REST API (Post, Put, Delete, Get, etc.).
    • AuthenticationProfile - Authentication profile to authenticate before service processing.
    • ResourcePath - Service resource path.
    • RequestJSON - Request JSON.
Note: Task implementations should only use rules present in the PegaDeploymentManagerIntegrations and PegaDevopsShared rulesets.

Debugging tasks

Use the following steps to run and trace the implementation of your custom tasks in context:

  1. Temporarily disable DeploymentManagerAgentScheduler job scheduler from Admin Studio.
  2. Add the custom task to a pipeline, preferably as one of the first tasks.
  3. Start a deployment and progress to the custom task.
  4. Open and track the RunDeploymentManagerAgent activity.
  5. Run the RunDeploymentManagerAgent activity.

If the task runs successfully when run manually, but encounters an issue when executed by the job scheduler:

  1. Trace the job scheduler named DeploymentManagerAgentScheduler from Admin Studio.
  2. To trace task updates posted to Deployment Manager, enable tracer for the service DeploymentManager/v1/tasks.

Role based approval

This example component demonstrates how to author custom tasks. This is a customized version of the manual approval tasks included with Deployment Manager, with the parameter ability allowing users to provide approvals based on their role.

  1. Download the role based approval component here.
  2. Import the component to the Deployment Manager orchestrator.
  3. Add the component application, RoleBasedApproval_20210326T192535225:01.01.01, to the system runtime context.
  4. You can now add the role based approval task in each of your pipeline stages.

Tags

Pega Platform 8.7 DevOps

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us