Skip to main content


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

Integrating Agile Workbench with an external project management system

Updated on September 10, 2021

You can create a component that integrates the Agile Workbench tool with the external project management system of your choice. By integrating Agile Workbench with your preferred project management system, you can continue to use a real-time Agile methodology for your application development projects, leverage the features of the project management system that you are accustomed to, and use your project management system as the system of record.

This article is about integrating Agile Workbench with a project management system other than Pega® Agile Studio, JIRA, and CA Agile Central. For information about integration with those systems, see:

To create a component and integrate Agile Workbench with an external project management system, complete the following tasks:

  1. Configure the connection between your application and a project management system.
  2. Customize Agile Workbench.
  3. Customize the options to associate work items with rules.
  4. Create and package a component to use with other Pega Platform applications.

Configuring the connection between your application and a project management system

You configure integration with an external project management system on the Integration & security tab of the Application rule form by clicking Configure integration. For each dialog that is displayed for configuring this integration, you must create or customize rules and data transforms.

Before you integrate Agile Workbench with an external project management system, disconnect any existing integration to a project management system. On the Integration & security tab of the Application rule form, in the Agile Workbench integration section, click Configure integration, and then click Disconnect integration.

  1. To make your project management system display as an option on the Integrate your work dialog, create or customize the following rules and data transforms:

    • A new binary rule – Create this rule and upload an image of the logo for your project management system. For reference, see pzPegaAgileStudioLogo.

    • Data transform Code-Pega-List.pyProjectManagementSystems – Copy this rule from Pega-AppDefinition and append the name of your project management system and the image that you are using for its logo.

    • Data transform Rule-Application.pySetDefaultProjMgmtDetails – Set the default URL or sample URL of your project management system. For reference, see the data transform pzUpdateSystemAndNavigateIntegrationScreen.

    • When rule @baseclass.pyAllowIntegrationWithOtherPM – Copy this when rule and set the value to true.

    Integrate your work dialog that displays the logo for your project management system

    Integrate your work dialog that displays the logo for your project management system

  2. Configure the first Set up integration details dialog, where you enter the API URL for your project management system:

    • A new section rule – Create this rule and upload the same image of the logo for your project management system. For reference, see Rule-Application.pzPegaAgileStudioIcon.

    • Section rule Rule-Application.pySetupAppIntegrationURL – Copy rule pzSetupApplicationIntegrationAgileStudioURL and save it as a new rule. Update the rule to use the binary image section that you created, and a text input field for providing the URL of your project management system.

    • Section rule Application.pyTestConnection – Copy the rule of the same name from Pega-AppDefinition, and update the rule as necessary.

    • Activity Rule-Application.pyTestConnectivityForPMURL – Write logic to test the connectivity in this activity, and set messages. For reference, see the activity pzTestConnectivityForAgileStudio.

  3. Configure the next Set up integration details dialog, where you specify the combination of product, project, version, and release to associate with your Agile Workbench work items:

    • Section rule Rule-Application.pySetupApplicationIntegrationDetails – Copy the rule pzSetupApplicationIntegrationAgileStudioDetails and save it as a new rule. Add your binary image of the logo for your project management system, and add fields for providing the project, product, version, and release, as appropriate. These fields are equivalent to application and version.

    • Activity Rule-Application.pyStartIntegrationWithPMSystem – Write an activity that updates the application with data related to the integration. For reference, see pzStartIntegrationWithAgileStudio.

    Set up integration details dialog for your product and release

    Set up integration details dialog for product, project, version, and release

  4. Configure all Agile Workbench user stories and bugs to export to your project management system when you click Begin integration:

    • Activity Pega-Agile-Work-UserStory.pyExportUserStory – Override this activity and write code for exporting and creating an Agile Workbench user story in your project management system, creating a feature link, and resolving the Agile Workbench user story. For reference, see the pxExportUserStory activity.

    • Activity Pega-Agile-Work-Bug.pyExportBug – Override this activity and write code for exporting and creating an Agile Workbench bug in your project management system, creating a feature link, and resolving the Agile Workbench user story. For reference, see the pxExportBug activity.

    • Section rule Rule-Application.pyDisplayIntegrationStatus – Optional. To display errors for the export process, override this section to display additional information for work items that partially failed to export. For example, if Pulse comments or attachments did not export for some work items, you can provide a warning message to display in this section.

  5. Configure the Review integration details dialog. You can view this dialog when Agile Workbench is integrated with a project management system by clicking Configure integration on the Integration & security tab of the Application form:

    • Section rule Rule-Application.pyReviewIntegrationUpdateActions – Override this section to customize the visibility of the Update button. For reference, see the pzReviewIntegrationUpdateAction section.

    • Activity Rule-Application.pyDisconnectAppIntegration – Override this activity and write logic similar to pzDisconnectAppIntegration. This activity removes all the integration data from the application.

    • Section rule Rule-Application.pyReviewIntegrationInner – Override and update this user interface section to allow users to edit the URL and other integration details. For reference, see pzReviewIntegrationAgileStudioInner.

    • Data transform Rule-Application.pyPreProcessReviewIntegration – Override this data transform and write logic similar to pzPreProcessReviewIntegration, which updates the clipboard data with the required information from the application page.

    • Data transform Rule-Application.pyRemoveIntegrationDataPages – Override and update this data transform to remove the unused pages before creating new pages. This data transform cleans up unused data when the dialog is closed. For reference, see pzRemoveTempAppPage.

    Review integration details dialog

    Review integration details dialog

Customizing Agile Workbench

After you configure the connection between your application and an external project management system, you must customize Agile Workbench to correctly display work items from the project management system, and to support the ability to create and edit work items.

  1. Update the Agile Workbench header to display the name of your project management system by overriding the Pega-Agile-Work.pyAgileWorkBenchHeader section rule and configuring the integration details. The dynamic layout for the Agile Workbench header must have a when rule that evaluates to true only when Agile Workbench is integrated with your project management system. For reference, see the pzAgileWorkbenchHeader section.

    Agile Workbench header that displays the name of your project management system

    Customized Agile Workbench header

  2. Customize the grid view so that it loads the details for the bugs and user stories from your project management system.

    • Section rule Pega-Agile-Work-Bug.pyBugRowExtension – Override and customize this rule to define how bugs are displayed in the grid view of Agile Workbench. For reference, see the rule of this same name in the Pega-AppDefinition ruleset.

    • Section rule Pega-Agile-Work-UserStory.pyUserStoryRowExtension – Override and customize this rule to define how user stories are displayed in the grid view of Agile Workbench. For reference, see the rule of this same name in the Pega-AppDefinition ruleset.

    • Activity Embed-ProjectMgmt-Pagedata.pyMapUserStoryData – Override this activity and map the data fetched for a user story on D_pzProjectManagementAssets with the actual user interface properties. For reference, see step 6.3 in activity pzLoadProjectManagementUserStoryList.

    • Activity Embed-ProjectMgmt-Pagedata.pyMapBugData – Override this activity and map the data fetched for a bug on D_pzProjectManagementAssets with the actual user interface properties. For reference, see step 6.3 in activity pzLoadProjectManagementBugList.

    • Activity Code-Pega-List.pyLoadProjectManagementAssets – Override and call the connector in this activity to get the asset list data for the current application from another system. For examples of connectors, see data sources in data page D_pzProjectManagementAssets.

    • Data transform Pega-Int-ProjMgmt.pyLoadProjectManagementEndPointURL – Override this data transform to set the default endpoint URLs for CRUD operations on work items. After you set the URLs, the URLs are available on the D_pzProjectManagementURL data page and can be used as a single reference point, rather than forming the entire service URL each time. For reference, see the data transform pzLoadProjectManagementEndPointURL.

    A grid view with imported user stories

    An example grid view that shows user stories

  3. Customize the grid view to include options for filtering and sorting the list of bugs and user stories.

    • Data transform Pega-Agile-Work-Bug.pyDefaultSortFilters – Optional. Override this data transform to override the default filtering and sorting properties that are in the filtering and sorting overlays on the Bugs tab. For reference, see data transform pzDefaultSortFilters in class Pega-Agile-Work-Bug.

    • Data transform Pega-Agile-Work-UserStory.pyDefaultSortFilters – Optional. Override this data transform to override the default filtering and sorting properties that are in the filtering and sorting overlays on the Stories tab. For reference, see data transform pzDefaultSortFilters in class Pega-Agile-Work-UserStory.

    • When rule Pega-Agile-Work.pySearchWithIDOrLabel – Override this when rule to customize which properties on the clipboard that search must match when you enter text in the Search box. For example, to search for the pyLabel property on the clipboard by entering text in the Search box, the following type of condition is required in the when rule:

      @String.contains(@String.toUpperCase(.pyLabel),
      @String.toUpperCase(D_pzAgileWorkbench.pySearchTextForGaps))

    • Activity Code-Pega-List.pySortCriteriaExtension – Override this activity to customize the post-processing of sort selection based on different properties in the sort overlay. For reference, see pzSortBasedOnSelection activity.

    • Data transform Code-Pega-List.pyConfigureAssetSortOptions – Override this data transform to customize the sorting options that are available in the sort overlay on the Bugs and Stories tabs. For reference, see pzFilterAssetSortOptions.

    • Section Pega-Agile-Work.pyAssetFilterExtension – Override this extension section to customize the filter option Show only created by me for the grid view. For reference, see the section pzAssetFilter.

    The sort overlay for user stories

    Filter options for a user story

    The filter overlay for user stories

    Sort options for a user story

  4. Configure the ability to open and edit work items from the grid view. When you click a work item in the grid view, the work item is displayed in an Open screen where you can view and edit details.

    • Activity Pega-Agile-Work.pyOpenIntegratedWorkItemByID – Override this activity to get individual work object details from your project management system by using a Connect REST call and mapping the properties with user interface properties of the Open screen for work items. For reference, see the activity pzOpenIntegratedWorkItemByID.

    • Section Pega-Agile-Work.pyEditGapIdentifierItemWrapper – Override this section to add Pulse information for the opened work object from your project management system. For reference, see the section pzGapIdentifierPulse.

    • Section Pega-Agile-Work.pyHeaderAssetLabel – Override this section to display the header of the opened work item. For reference, see the section pzEditGapIdentifierItemWrapper.

    • Section Pega-Agile-Work.pyEditGapIdentifierPMItemDescription – Override this section to display the description of the opened work item. For reference, see the section pzEditGapIdentifierPMItemDescription.

    • Section Pega-Agile-Work-UserStory.pyEditGapIdentifierItemHeader – Override this section to display the ID of the opened user story. For reference, see the section pzEditGapIdentifierItem in the Pega-Agile-Work-UserStory class.

    • Section Pega-Agile-Work-Bug.pyEditGapIdentifierItemHeader – Override this section to display the ID of the opened bug. For reference, see the section pzEditGapIdentifierItem in the Pega-Agile-Work-Bug class.

    • Section Pega-Agile-Work-UserStory.pyEditGapIdentifierItem – Override this section to display priority, owner, and attachment information for the opened user story. For reference, see pzEditGapIdentifierItem in class Pega-Agile-Work-UserStory.

    • Section Pega-Agile-Work-Bug.pyEditGapIdentifierItem – Override this section to display severity, owner, and attachment information for the opened bug. For reference, see pzEditGapIdentifierItem in class Pega-Agile-Work-Bug.

    • Section Pega-Agile-Work.pyAssetLabel – Override this section to display the name or label of the opened work item on the form (not in the header). For reference, see the section pzAssetLabel.

    The Open screen for a user story

    The Open screen for a user story

  5. Configure the ability to create work items by clicking the Plus icon in the Agile Workbench header.

    • Activity Pega-Agile-Work-UserStory.pyCreateProjMgmtUS – Override this activity to create the user story in your project management system, promote a feature, and create the feature asset link on creation of the user story. For reference, see pxCreateAgileStudioUS.

    • Activity Pega-Agile-Work-Bug.pyCreateProjMgmtBug – Override this activity to create the bug in your project management system, promote a feature, and create the feature asset link on creation of the bug. For reference, see pxCreateAgileStudioBug.

    Options from the Plus icon in the Agile Workbench header

    Options from the Plus icon in the Agile Workbench header

  6. Customize where and how you can update work items in Agile Workbench.

    You can customize the following actions:

    • Complete, delete, and reject from a grid row
    • Reopen from a grid row
    • Inline update of priority and severity from a grid row
    • Save from the Open screen
    • Complete, delete, and reject from the Open screen
    • Reopen from the Open screen

     

    Customize the following rules to support these actions:

    • Section Pega-Agile-Work-Bug.pyBugRowExtension – Override and customize this section to match the user interface of the bug row in the grid. For reference, see Pega-AppDefinition.

    • Section Pega-Agile-Work-UserStory.pyUserStoryRowExtension – Override and customize this section to match the user interface of the user story row in the grid. For reference, see Pega-AppDefinition.

    • Activity Pega-Agile-Work.pyValidateLabel – Override this activity to apply validations on the name or label of the work item that is being updated. For example, you can validate that the name is not blank.

    • Activity Pega-Agile-Work-UserStory.pyUpdateProjMgmtUserStory – Override this activity to update the user story in your project management system. For reference, see pzUpdateUserStoryToProjMgmt.

    • Activity Pega-Agile-Work-Bug.pyUpdateProjMgmtBUG – Override this activity to update the bug in your project management system. For reference, see pzUpdateBugToProjMgmt.

    • Activity Pega-Agile-Work.pyUpdateProjMgmtAsset – Override this activity in specific classes, like Pega-Agile-Work-Bug or Pega-Agile-Work-UserStory, to update a work item inline, for example, to update the priority or severity. For reference, see pxUpdateBugWrapper.

    • Activity Pega-Agile-Work.pyUndoCreateProjMgmtAsset – Override this activity to support undo functionality in the Agile Workbench banner after creating a work item. This undo functionality should withdraw, or reject, the work item. For reference, see pzUpdateBugToProjMgmt.

    • When rule Pega-Agile-Work.pyShowReopen – Override this when rule to evaluate to true when a work item is not integrated or is integrated with this project management system. This when rule controls whether the Reopen button is displayed on the Open screen.

    • When rule Pega-Agile-Work.pyShowRejected – Override this when rule to evaluate to false if your project management system does not have the functionality to reject work items. This when rule controls whether the Reject option is displayed on the Mark as... menu on the Open screen.

    • Data transform Pega-Agile-Work-Bug.pySetStarRating – Override this data transform to set additional information on the user interface when the bug severity is changed.

    • Activity Pega-Agile-Work.pyReopenWorkItem – Override this activity to support reopening a work item from the banner, a bubble in the grid, and the Open screen. For reference, see the pzReopenWorkItem activity in class Pega-Agile-Work-Bug.

    • Navigation Pega-Agile-Work-UserStory.pyMarkAsNav – Override this navigation rule to add options to the Mark as... menu for user stories. The default options are Completed and Rejected. For reference, see pzMarkAsNav in class Pega-Agile-Work-UserStory.

    • Navigation Pega-Agile-Work-Bug.pyMarkAsNav – Override this navigation rule to add options to the Mark as... menu for bugs. The default options are Completed and Rejected. For reference, see pzMarkAsNav in class Pega-Agile-Work-Bug.

    Options for rejecting or completing a bug displayed in a banner on the grid view

    A banner that displays the options for rejecting or completing a bug from the grid view

    Options to complete or reject a bug from the Mark As menu

    Options for rejecting or completing a bug from the Mark As... menu on the Open screen

  7. Configure the ability to add and display attachments for work items on the Open screen.

    • Flow action Pega-Agile-Work.pyAttachmentOverlay – Override this flow action only if you need customization for invoking the overlay when the + Add attachment button is clicked in the Attachments user interface on the Open screen.

    • Section Pega-Agile-Work.pyAttachmentMenuWrapper – Override this section only if you need to customize the options that are available when the + Add attachment button is clicked. By default, the options are Record video, Capture screen, and Attach files.

    • Section Pega-Agile-Work.pyGapIdentifierAttachments – Override this section to implement a repeating dynamic layout of attachments on the Open screen.

    • Section Embed-DragDropFile.pyGapIdentifierPMAttachmentActions – Override this section to include a Delete icon or other icons for each attachment in the layout. For reference, see pzGapIdentifierPMAttachmentActions.

    • Section Embed-DragDropFile.pyGapIdentifierAttachmentElement – Override this section to display each item in a repeating dynamic layout of attachments on the Open screen. You can use the default layout, if you prefer.

    Options to add attachments, including videos and screen captures

    Adding attachments on the Open screen

  8. Customize the banners that display when you take actions on work items. You can add banners for when a work item is created, completed, rejected, or reopened. You also can provide the option to undo an action.

    • Section Pega-Agile-Work.pyBannerLabel – Override this section for the display of the name, or label, in the banner when you create, update, reject, complete, undo, or reopen a work item. For reference, see pyLabel in the pzAssetHeader section.

    • Section Pega-Agile-Work.pyAssetHeaderCompletedBanner – Override this section for the display of the customized banner when you complete a work item. For reference, see pyAssetHeaderCompletedBanner in Pega-AppDefinition.

    • Section Pega-Agile-Work.pyAssetHeaderRejectBanner – Override this section for the display of the customized banner when you reject, reopen, or delete a work item. For reference, see pyAssetHeaderRejectBanner.

    • Data transform Pega-Agile-Work.pySetBanner – Override and copy the data that is displayed in the banner when you take action (update, undo, complete, and so on) on a work item. For reference, see the pzSetBannerLabel data transform.

    • Data transform Pega-Agile-Work.pyCreateBanner – Override and set additional data that is displayed in the banner when you create a work item. For example, if the length of the label property that would display in the banner is longer than what pyLabel can store and you want to use a new property, you can set that value in the data transform.

    A creation banner for a user story with an Undo? option

    A creation banner for a user story with an Undo? option

Customizing the options to associate work items with rules

You can associate a user story or bug with development changes to rules, which helps to ensure transparency and traceability in your development environment. You can use the Current work feature to specify the default Work item to associate setting for when you create a rule, check in a rule, or save a rule as a new rule. Additionally, you can select a different work item in the Current work item section when you create a rule, check in a rule, or save a rule as a new rule.

  • To support associating work items from your project management system with rules, customize the following rules:

    • Activity Code-Pega-List.pyWorkBenchAssetsFromIntSystem – Override this activity to specify the list of work items that you can select from the Current work feature in the Developer toolbar, and from the the Current work item section when you create a rule, check in a rule, or save a rule as a new rule. For each work item that you specify, provide item and feature information. For reference, see pzWorkBenchAssetsFromIntSystem.

    • Activity Data-Preference-Operator.pySetCurrentWorkItem – Override this activity only for when making a selection in the Current work item section. The property and format for the work item ID is different than the default setting (pyDefaultWorkItemID).

    • Section Data-Portal.pyCurrentWork – Override this section only for the Current work item section. The property of the work item ID is different than the default setting (pyDefaultWorkItemID). For reference, see the same rule in the Pega-AppDefinition ruleset.

    The Current work feature in the Developer toolbar

    The Current work feature in the Developer toolbar

Create and package a component to use with other Pega Platform applications

Now, you can create and package a component, which is a collection of rulesets, so that you can add this integration capability to any application created in Pega Platform. For information about creating, packaging, and installing a component, see Components.

  • Previous topic Customizing the CA Agile Central integration component
  • Next topic Introducing PRPC 6.2 - Implementation and Methodology

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

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