Setting up the PPM Pro - AgilePlace Integration (v2)
Setting up the integration between PPM Pro and AgilePlace requires a PPM Pro administrator and an AgilePlace Board admin - can be the same person. PPM Pro Admin permissions and AgilePlace Manage permissions are required.
Before You Begin
Before configuring the AgilePlace/PPM Pro integration, you must first enlist Customer Care to enable support for the feature. Once the feature is enabled, you will configure PPM Pro and AgilePlace as described below. After setup is complete, end-users can find information about using the tools together in Using PPM Pro and AgilePlace (Phase 2).
For users of PPM Pro/AgilePlace integration v1: You cannot have v1 and v2 integration active at the same time. When you notify Customer Care to enable V2, the V1 integration will be disabled.
The following are the steps to configure the integration - please do them in order, note that some are optional based on your needs. If you would like to see a demo showing start to finish configuring and setting up the integration, please see the June 2021 Release Webinar recording from approximately 12:00-37:05. Here is also a spreadsheet showing sample mappings (AgilePlace card type to PPM Pro category mappings, field mappings, and other considerations), that may be helpful in deciding how best to integrate your own PPM Pro and AgilePlace projects, tasks, and issues/project logs.
Set Up Initial Sync
We assume that you have PPM Pro and AgilePlace instances already set up and running. The first thing to do once the feature is enabled by Customer Care is to give PPM Pro the AgilePlace hostname, and setup and select PPM Pro's default AgilePlace board.
You cannot begin configuring the integration until Customer Care lets you know they have enabled your customer instance, on both AgilePlace and PPM Pro. You can double-check this is the case by logging into PPM Pro, navigating to Admin/Organization/Info, and confirming that you see these two fields within the Basic Information section:
Set Up Default LK (Available) Board
- In AgilePlace, open the board you wish to use in the integration with PPM Pro and choose Board Settings.
- In the modal that opens, click "Planview Sync" from the list of links down the left side of the modal, as shown below:
- Enable the checkbox next to "Available for integration with supported Planview products" as shown in the screenshot above. We will finish configuring this board later - for now now, this board can participate in the integration, but no work creation has been enabled.
- Grab your AgilePlace hostname and copy to clipboard. The hostname is the portion or your AgilePlace URL appearing before "/board" or "/card". For example, if your AgilePlace URL is https://customer.leankit.io/board/10123649309, then the hostname is "https://customer.leankit.io".
Set PPM Pro Admin/Organization/Info Fields
- Log in to PPM Pro and navigate to Admin/Organization/Info.
- Paste in Hostname.
- Locate the field "LK Default Board" drop list and choose the board you just configured. Multiple boards can be integrated, and any other boards you enable for the integration will appear in this list. The selected value is just used as a default - you can select a different board when creating a project, but if for some reason you do not select a board, or you only ever want to use one board, this default board will be used.
- Save. Note: You need to set both of these required fields before you can save the changes in PPM Pro.
Below is an example of valid values for both the Hostname and Default AgilePlace Board:
Identify/Create AgilePlace Card Types and Populate PPM Pro Lookup List
When the integration is enabled, a new empty PPM Pro lookup list will be created, called Organization AgilePlace Card Types. You will need to populate this list with the names of AgilePlace card types you want to be able to create in AgilePlace by PPM Pro.
Each AgilePlace board has at least one card type, often more. Any card type can be used in the integration to create a card of that type, based on a PPM Pro linked category (categories are linked by card types). Once you identify or create the card types you wish to use you'll populate a PPM Pro lookup list with the card type names, explained below. Once you populate the lookup list you can map card types to PPM Pro project, task, and issue/project log categories. If you're going to use multiple boards and plan on moving integrated cards between them, make sure the card type names match on the boards.
- In AgilePlace, navigate to Card Types for the board you are using for the integration (shown below).
- Peruse the list of card types (and create additional types if necessary) and jot down which ones you want PPM Pro entities to create cards for in AgilePlace. For example, you might want to include Agile Task, Defect, Risk, and Issue.
- In PPM Pro, navigate to Admin/Setup/Lookup Lists and locate the list "Organization LeanKit Card Type", as shown below
- Click New and enter a card name, such as "Agile Task". Repeat for each card type you want to use with the integration. Note that this lookup list is not maintained automatically. If a card type is removed from AgilePlace, you'll have to manually remove it from the PPM Pro lookup list, and if you add a value in PPM Pro, you'll have to add it manually in AgilePlace (remember the lookup list value titles must be spelled exactly the same as the corresponding card type names).
Configure Entity Categories (Default LK Card Type)
Each card type can only be mapped to one category across all entity types (projects/tasks/issues).
You can make one or more entity (project, task, issue/project log) categories integration-ready by selecting a card type from the category's LK Default Card Type field. This list is comprised of the values you entered in the Organization AgilePlace Card Type lookup list mentioned above. The card type you choose for an entity's category tells AgilePlace to create a card of that type when you create an entity of that category. The category also tells the system which field mappings to honor. See Mapping Fields.
In addition, for project categories you'll need to include the "Sync with AgilePlace" field in its Details (or Additional Details or Settings) so the integration can be activated and de-activated. Finally, if you want your task and issue/project log categories to be able to sync to boards other than the project board (syncing to project board is default behavior), you can optionally add the Default Task Board and the Default Issue Board fields. You may also want to add and map other AgilePlace standard fields as well. Depending on the number of AgilePlace fields you add, consider if it makes sense to add these to existing categories or perhaps to copy a category specifically for integration and add fields to it; you might not want to clutter existing category details unnecessarily if a majority of their entity instances will not be integrated.
With the AgilePlace integration enabled an additional section for project, task, and issue/project log categories called LeanKit Default Card Type appears on the categories grid all the way to the right side (for readability, we moved the section next to Title for this project categories screenshot). Once you select the default card type for a category (described below), the value will appear in the category's LK Default Card Type section (rather than a checkbox like other selected sections):
Note: The instructions that follow are for setting up a project category. If you want to include tasks and/or issues/project logs you'll follow the same instructions for their respective categories.
- Navigate to Admin/Setup/All Entities/Projects/Categories and take a look at the list of categories. Decide whether to use an existing category or create a new one. This example uses the category Agile Feature Work.
- Edit the category and select a value for the LK Default Card Type field (in the example, Feature) you want to assign to projects of this category. The screenshot below shows the LK Default Card Type field and its possible values. These values come directly from the lookup list you configured above. Also, in this example Additional Details has been renamed to "Integration Details" and we will be putting integration fields in that section (instead of Details or Settings - any of these sections is fine).
- After you select the card type click Save.
You can now see that "Feature" appears as the assigned Default AgilePlace Card Type for the Agile Feature Work category:
- Navigate to Admin/Setup/All Entities/Projects/Additional Details. (These instructions assume you will put the "Sync to AgilePlace" field on Additional Details, which was renamed Integration Details above).
- Choose the Category you are using for the integration (in this example Agile Feature Work) from the Categories droplist at the top-left of the screen.
- Select the "Sync with AgilePlace" field in the Available Fields column and click the right arrow to move it to the Integration Details panel (similarly, if you created a AgilePlace section, put the field there). Note: This is only necessary for project categories. When configuring Details fields for tasks or issues, you do not need and will not see the "Sync with AgilePlace" field.
Only place the "Sync to AgilePlace" field on a category that has a card type defined.
- Configure the "Sync with AgilePlace" field; you can configure it to allow the end user to edit it, or you can enable it and put it in a read-only state, which will make any project created with that category sync immediately.
- To enable the field and prevent users from editing, select the field and click the Variable Properties tab. Show on New can be set to Yes or No, but Show on Edit must be set to Yes - View Only. When users create a project, Sync to AgilePlace will be enabled automatically, as will the integration.
- To give users the option to enable the AgilePlace integration or not, make Show on New - Yes and Show on Edit - Yes Editable. When users create or edit a project, they will have the option of enabling or disabling the integration.
- (Optional) Add the LK Task Default Board and LK Issue Default Board fields if you want users to be able to change which board a task or issue/project log is synced to. By default synced tasks and issues/project logs will appear on the default project board. Note: This is only for project categories. When configuring Details fields for tasks or issues, you do not need and will not see the default board fields.
For users of PPM Pro/AgilePlace integration V1, if you had standard LK V1 fields on your project details, when you deactivate V1 and activate V2, those V1 standard fields will remain on your project details. However, you must remap the fields.
Add PPM Pro standard and user-defined fields to the Details, Additional Details, and Settings sections for your synced entity (project, task, or issue/project log) categories. You can also include any of the LK fields that became available (see AgilePlace Field Definitions) when the integration was enabled.
These fields are "auto-mapped", meaning the system takes care of the mapping and updating (they are read-only for users). The screenshot below shows the LK available fields:
You can add some or all of these fields to the Details, Additional Details, or Settings section of the appropriate project, task, or issue/project log category(ies).
You can also add PPM Pro standard and user-defined fields to your entity category and manually map them to AgilePlace card fields. PPM Pro fields are mappable to AgilePlace fields of the same data type. Commonly mapped field examples include:
- PPM Pro String field such as "Problem Description" mapped to the AgilePlace "Description" field
- PPM Pro standard Date field "Start Date" mapped to the AgilePlace "Planned Start Date" field
- PPM Pro standard Date field "Target Date" mapped to the AgilePlace "Planned Finish Date" field
- PPM Pro standard Date field "Complete Date" (or "Completion Date") mapped to the AgilePlace "Actual Finish Date" field
The screenshot below shows an example of a user-defined Date field (UDF Date) mapping. To map, select the field in PPM Pro (make sure the Mappings tab is selected) and click the drop list under Map to Associated Field by Category.
User-defined fields are unique per board. When mapping a custom field that appears on multiple boards, you'll see the field name followed by the board name in parentheses (board name). If an end user moves a user-defined card from one board to another, field data does not transfer with it (and won't be synced as it is essentially a new field).
If mapping a custom AgilePlace list field, make sure to use the PPM Pro list "Integration Managed List: <custom list name)". See Mapping Custom AgilePlace List Fields.
The drop list contains LK date fields that are available to map to the PPM Pro UDF Date field.
Similarly, if you click the UDF String field, you'll see a list of available string fields, as shown below:
Note: If you want multiple project categories to inter-operate with AgilePlace, you'll need to add the "Sync with AgilePlace" field to those project category details, as well as add any LK-prefaced fields that you want to use. Different project, task, or project log/issue categories can use different sets of AgilePlace fields - each category has unique mappings to AgilePlace fields. For example, if you want to map PPM Pro project Description to the AgilePlace Description field, you have to do that mapping on every category that you want to use in the integration.
Mapping Custom AgilePlace List Fields
To map a custom AgilePlace list field to a PPM Pro list field, do the following.
- Create a custom AgilePlace list field, or use an existing one.
- In PPM Pro, create a custom List field.
- From the List to Use drop list, select the list called "Integration Managed List: <custom list name>", where <custom list name> is the name of the custom AgilePlace list.
- Click Save.
- Add the field to your Details (or Additional Details or Settings).
- Map the field as you would any other field.
AgilePlace Field Definitions
These fields appear in project Available Fields when the Sync to AgilePlace field is enabled. You can place as many or as few of these fields on any category that also includes the "Sync with AgilePlace" field. Note that while some of these fields are automatically mapped, others will need to be manually mapped after adding to details. Many mapping updates are also one-way, for example, the LK Board cannot be edited within PPM Pro because its value is automatically determined based on what board the corresponding card resides.
NOTE: The table below shows current Available Field Names for standard fields that may appear in project, task, and issue/project log entity Available Field lists. There are additional AgilePlace Fields that can be mapped to user-defined fields, including the AgilePlace card's Description, Lane, Lane Class (values of "Not Started", "Started", or "Finished"), and Size.
|Available Field Name||Field Type||Definition||Mapping to AgilePlace Field|
|LK Actual Finish||Date||The actual finish date from the integrated AgilePlace project card.||The PPM Pro 'LK Actual Finish' or a 'Completion Date' field are usually manually mapped to the AgilePlace 'Actual Finish Date' date field. Mapping to a Completion Date field works very well because when an AgilePlace card moves into a Finish lane, the card's Actual Finish Date is automatically set which causes the corresponding entity Completion Date to be updated with the same date.|
|LK Actual Start||Date||The actual state date from the integrated AgilePlace project card||Usually manually mapped to the AgilePlace 'Actual Start Date' field of to 'Start Date' (if you want the PPM Pro Start Date automatically updated when the card moves into a Started lane).|
|LK Blocked Child Cards||Integer||The number of child cards that are blocked.||Usually manually mapped to the AgilePlace 'Blocked' field.|
|LK Blocked Flag||Boolean Checkbox||Shows whether the integrated AgilePlace project card is blocked.||Usually manually mapped to the AgilePlace 'Is Blocked' field.|
|LK Board||Select List||The AgilePlace board the PPM Pro entity card is mapped to.||Auto-mapped and updated to the synced card's AgilePlace board.|
|LK Card ID||Integer||The AgilePlace card ID that is synced with a PPM Pro entity.||Auto-mapped and updated to the synced card's ID.|
|LK Card Lane Status||String||
Not Started, Started, Finished.
Note that these values map from the LK "lane class" attribute as follows:
|Auto-mapped and updated to the synced card's Lane Class.|
|LK Card Type||Lookup List||The AgilePlace Card Type that is synced with the PPM Pro entity.||Auto-mapped and updated to the synced card's Card Type.|
|LK Card URL||Linked Entity URL||The URL to the integrated card for this project in AgilePlace.||Auto-mapped and updated to the synced card's URL.|
|LK Complete Cards||Integer||The sum of the sizes of all completed child cards. The default card size is 1.||Usually manually mapped to the AgilePlace 'Complete' field.|
LK Earliest Actual Start
|Date||The earliest actual start data of all child cards. For example, if there are 3 child cards, with start dates 4/1, 5/1, and 6/1, then the earliest start date is 4/1.||Usually manually mapped to the AgilePlace 'Earliest Actual Start Date' field.|
|LE Earliest Planned Start||Date||The earliest planned start data of all child cards. For example, if there are 3 child cards, with planned start dates 4/1, 5/1, and 6/1, then the earliest planned start date is 4/1.||Usually manually mapped to the AgilePlace 'Earliest Planned Start Date' field.|
|LK Exception Count||Integer||The number of child cards that have an exception, such as being blocked.||Usually manually mapped to the AgilePlace 'Exceptions' field.|
|LK Exception Percentage||Percent||The percentage of child cards based on count that have an exception, such as being blocked.||Usually manually mapped to the AgilePlace 'Exceptions %' field.|
|LK In Progress Child Cards||Integer||The sum of the sizes of all child card that are in progress.||Usually manually mapped to the AgilePlace 'In progress' field.|
|LK <Issue/Project Log/Log> Default Board||Select List||The AgilePlace board on which newly created synced project issues will appear. If no value is selected, the project LK board will be used.||Auto-mapped and updated based on LeanKit boards configured for Planview Sync and user selection. NOTE: the Available Field name could vary depending on how your environment was configured.|
|LK Latest Actual Finish||Date||The latest actual finish date of all child cards. For example, if there are 3 child cards, with finish dates 4/1, 5/1, and 6/1, then the latest actual finish date is 6/1.||Usually manually mapped to the AgilePlace 'Latest Actual Finish' field.|
|LK Latest Planned Finish||Date||The latest planned finish date of all child cards. For example, if there are 3 child cards, with planned finish dates 4/1, 5/1, and 6/1, then the latest planned finish date is 6/1.||Usually manually mapped to the AgilePlace 'Latest Planned Finish' field|
|LK Missed Finish Child Cards||Integer||The number of child cards that missed their finish dates.||Usually manually mapped to the AgilePlace 'Missed Finish' field.|
|LK Missed Start Child Cards||Integer||The number of child cards that missed their start dates.||Usually manually mapped to the AgilePlace 'Missed Start' field.|
|LK Not Started Child Cards||Integer||The sum of the sizes of all child cards that are not yet started. The default size is 1.||Usually manually mapped to the AgilePlace 'Not started' field.|
|LK Percent Complete||Percent||The percentage of cards (by count or by size) that are complete.||Usually manually mapped to the AgilePlace 'Complete %' field.|
|LK Planned Finish||Date||The planned finish date of the integrated AgilePlace card. When the LK Card is first created/synched, the LK Planned Finish is initially populated with the PPM Pro project Target Date.||The PPM Pro 'LK Planned Finish' or a 'Target Date' field are usually manually mapped to the AgilePlace 'Planned Finish Date' date field.|
|LK Planned Start||Date||The planned start date of the integrated AgilePlace card. When the LK Card is first created/synched, the LK Planned Start is initially populated with the PPM Pro project Scheduled From Date.||The PPM Pro 'LK Planned Start' or a 'Start Date' field are usually manually mapped to the AgilePlace 'Planned Start Date' date field.|
|LK Priority||Select List||The priority of the integrated AgilePlace card. Automatically maps to the AgilePlace card's Priority field.||Auto-mapped and updated to the synced card's Priority.|
|LK Projected Finish||Date||Displays the “Projected finish” field from the History and Health section on a AgilePlace card. The AgilePlace card’s projected finish date will be brought into PPM Pro against the associated project. See Viewing Card History and Health for more information.||Usually manually mapped to the AgilePlace 'Projected Finish Date' field.|
|LK Task Default Board||Select List||The AgilePlace board on which newly created synced project tasks will appear. If no value is selected, the project LK board will be used.||Auto-mapped and updated based on AgilePlace boards configured for Planview Sync and user selection.|
|LK Top Lane||String||The AgilePlace board's default lane. When a project is created, a corresponding AgilePlace card is created and dropped into the Top Lane.||Usually manually mapped to the AgilePlace 'Lane' field.|
|LK Total Cards||Integer||The sum of the sizes of all child cards.||Usually manually mapped to the AgilePlace 'Total' field.|
|Sync with LeanKit||Boolean Checkbox||
Required on a project in order to activate the integration.
When this setting is selected, the integration will be triggered and a corresponding AgilePlace project card appears on a relevant AgilePlace Board, using the PPM Pro project Title as the Card name. Data updates will occur based on the integration card and field mappings. When this setting is deselected, the integration is no longer active, and if reselected the same project card and board are used (assuming they still exist, otherwise it would create a new card) and resyncs the data per the mappings.
|Auto-mapped and updated based on AgilePlace boards configured for Planview Sync and user selection.|
Identify/Create PPM Pro Project Template
If you plan to support work creation or creating a PPM Pro project from within AgilePlace, you'll need to have at least one project template. You can create a PPM Pro project template for the integration just as you would any other template: the template should define the project elements, such as sections, tasks, project logs/issues, and so on, that are the foundation for any instantiated projects. And don't forget to enable the "Can Be Template" property usually located in the Settings section.
When configuring the template, make sure that it is using a category whose Default LK Card Type matches the selected card type you will use in AgilePlace to define work creation (in this example, Feature).
See Creating a Project Template for information about creating project templates.
You'll need to go into PPM Pro and get the ID of the project template you want to use when creating projects from AgilePlace. You can find the project ID either by opening the project template and copying the ID from the Details section, or selecting the project in the Projects list and using the ID inspector (from the Help menu, choose Developer Tools > ID Inspector to display a nameless modal). Click the project in the grid, and the ID will appear in the modal. Copy the ID to your clipboard.
Configure AgilePlace Board/Enable Work Creation
To enable work creation, you'll create a relationship between an AgilePlace lane, a supported card type, and a PPM Pro project template.
- Select an included card type (the same card type defined in the project template category in PPM Pro - in this example, Feature).
- Select the lane you wish to enable to trigger creation of the associated project - in the screenshot below the lane is "Doing Now". Creation is triggered when an AgilePlace card is created or moved into this lane.
- Enter the Project Template ID (see note at top of this section) that matches the selected Included Card type. For example, when the Project Card Type is is dropped into the Doing Now lane, it generates a project for the corresponding template (identified by ID) which has a Default Card Type that matches the selected card type (Project). There can be multiple included card types, each associated with a project template with the matching Default AgilePlace Card type. As configured in the screenshot below, when a card is dropped in the Doing Now lane or the Under Review lane, a project is created based on the associated template.