Setting up the integration between PPM Pro and LeanKit requires a PPM Pro administrator and a LeanKit Board admin - can be the same person. PPM Pro Admin permissions and LeanKit Manage permissions are required.
Before You Begin
Before configuring the LeanKit/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 LeanKit as described below. After setup is complete, end-users can find information about using the tools together in Using PPM Pro and LeanKit (Phase 2).
For users of PPM Pro/LeanKit 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 (LeanKit 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 LeanKit projects, tasks, and issues/project logs.
Set Up Initial Sync
We assume that you have PPM Pro and LeanKit 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 LeanKit hostname, and setup and select PPM Pro's default LeanKit board.
You cannot begin configuring the integration until Customer Care lets you know they have enabled your customer instance, on both LeanKit 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 LeanKit, 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 LeanKit hostname and copy to clipboard. The hostname is the portion or your LeanKit URL appearing before "/board" or "/card". For example, if your LeanKit 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 LeanKit Board:
Identify/Create LeanKit 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 LeanKit Card Types. You will need to populate this list with the names of LeanKit card types you want to be able to create in LeanKit by PPM Pro.
Each LeanKit 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 LeanKit, 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 LeanKit. 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 LeanKit, 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 LeanKit (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 LeanKit Card Type lookup list mentioned above. The card type you choose for an entity's category tells LeanKit 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 LeanKit" 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 LeanKit standard fields as well. Depending on the number of LeanKit 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 LeanKit 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 LeanKit 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 LeanKit" 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 LeanKit" field in the Available Fields column and click the right arrow to move it to the Integration Details panel (similarly, if you created a LeanKit 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 LeanKit" field.
Only place the "Sync to LeanKit" field on a category that has a card type defined.
- Configure the "Sync with LeanKit" 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 LeanKit will be enabled automatically, as will the integration.
- To give users the option to enable the LeanKit 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/LeanKit 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 LeanKit 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 LeanKit card fields. PPM Pro fields are mappable to LeanKit fields of the same data type. Commonly mapped field examples include:
- PPM Pro String field such as "Problem Description" mapped to the LeanKit "Description" field
- PPM Pro standard Date field "Start Date" mapped to the LeanKit "Planned Start Date" field
- PPM Pro standard Date field "Target Date" mapped to the LeanKit "Planned Finish Date" field
- PPM Pro standard Date field "Complete Date" (or "Completion Date") mapped to the LeanKit "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 LeanKit list field, make sure to use the PPM Pro list "Integration Managed List: <custom list name)". See Mapping Custom LeanKit 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 LeanKit, you'll need to add the "Sync with LeanKit" 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 LeanKit fields - each category has unique mappings to LeanKit fields. For example, if you want to map PPM Pro project Description to the LeanKit Description field, you have to do that mapping on every category that you want to use in the integration.
Mapping Custom LeanKit List Fields
To map a custom LeanKit list field to a PPM Pro list field, do the following.
- Create a custom LeanKit 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 LeanKit list.
- Click Save.
- Add the field to your Details (or Additional Details or Settings).
- Map the field as you would any other field.
LeanKit Field Definitions
These fields appear in project Available Fields when the Sync to LeanKit field is enabled. You can place as many or as few of these fields on any category that also includes the "Sync with LeanKit" 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 LeanKit Fields that can be mapped to user-defined fields, including the LeanKit card's Description, Lane, Lane Class (values of "Not Started", "Started", or "Finished"), and Size.
|Available Field Name||Field Type||Definition||Mapping to LeanKit Field|
|LK Actual Finish||Date||The actual finish date from the integrated LeanKit project card.||The PPM Pro 'LK Actual Finish' or a 'Completion Date' field are usually manually mapped to the LeanKit 'Actual Finish Date' date field. Mapping to a Completion Date field works very well because when a LeanKit 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 LeanKit project card||Usually manually mapped to the LeanKit '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 LeanKit 'Blocked' field.|
|LK Blocked Flag||Boolean Checkbox||Shows whether the integrated LeanKit project card is blocked.||Usually manually mapped to the LeanKit 'Is Blocked' field.|
|LK Board||Select List||The LeanKit board the PPM Pro entity card is mapped to.||Auto-mapped and updated to the synced card's LeanKit board.|
|LK Card ID||Integer||The LeanKit 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 LeanKit 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 LeanKit.||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 LeanKit '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 LeanKit '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 LeanKit '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 LeanKit '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 LeanKit '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 LeanKit 'In progress' field.|
|LK <Issue/Project Log/Log> Default Board||Select List||The LeanKit 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 LeanKit '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 LeanKit '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 LeanKit 'Missed Finish' field.|
|LK Missed Start Child Cards||Integer||The number of child cards that missed their start dates.||Usually manually mapped to the LeanKit '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 LeanKit 'Not started' field.|
|LK Percent Complete||Percent||The percentage of cards (by count or by size) that are complete.||Usually manually mapped to the LeanKit 'Complete %' field.|
|LK Planned Finish||Date||The planned finish date of the integrated LeanKit 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 LeanKit 'Planned Finish Date' date field.|
|LK Planned Start||Date||The planned start date of the integrated LeanKit 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 LeanKit 'Planned Start Date' date field.|
|LK Priority||Select List||The priority of the integrated LeanKit card. Automatically maps to the LeanKit 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 LeanKit card. The LeanKit 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 LeanKit 'Projected Finish Date' field.|
|LK Task Default Board||Select List||The LeanKit 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 LeanKit boards configured for Planview Sync and user selection.|
|LK Top Lane||String||The LeanKit board's default lane. When a project is created, a corresponding LeanKit card is created and dropped into the Top Lane.||Usually manually mapped to the LeanKit 'Lane' field.|
|LK Total Cards||Integer||The sum of the sizes of all child cards.||Usually manually mapped to the LeanKit '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 LeanKit project card appears on a relevant LK 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 LeanKit 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 LeanKit, 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 LeanKit 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 LeanKit. 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 LeanKit Board/Enable Work Creation
To enable work creation, you'll create a relationship between a LeanKit 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 a LeanKit 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 LK 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.