Planview AgilePlace
Overview
Whether deeply steeped in Lean software principles, or are simply looking for better ways to communicate, project teams have found the benefit of being able to visualize the work as it flows through the process using virtual Kanban boards and Planview AgilePlace (formerly LeanKit).
By synchronizing cards representing defects, user stories and other work items to analogous artifacts in other systems, teams can get use purpose-built tools to work on the artifacts, while getting the benefit of using Kanban boards for visual management.
For example:
- Developers prefer to see their work in Jira, Microsoft Azure DevOps (formerly TFS) or Visual Studio Team Services (formerly VSO), IBM RTC, CA Agile Central (Rally), or others;
- Testers like to do their work in Micro Focus ALM/Quality Center, IBM RQM, Tosca, or others;
- The PMO wants to use their PPM tools
- Business analysts want to use requirements management tools, and
- The service desk wants to use tools that support ITSM
All of these practitioners can use their favorite tools to create and update their work items, while Planview Hub works in the background to keep the team Kanban board up to date. Or, use the Kanban board to drag and drop work items into the next stage. Hub will seamlessly update the work item in the relevant tool.
Key Features and Benefits
- Improved visibility into the overall status of projects by using boards to visualize overall project status and WIP (work in process).
- Eliminates the need to manually update the virtual boards, or use brittle point to point integration techniques.
- Synchronizes artifacts across the lifecycle allowing free flow of information between AgilePlace and other tools.
- Allows you to implement Lean software methods across your project or just within discipline or team.
Common Integration Patterns
Demo Videos
Connector Setup Details
This section describes the basic steps needed to prepare your AgilePlace instance for use with Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.
Minimal User Permissions & Hub User
We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization.
In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.
Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'
See AgilePlace help documentation on how to create a custom user in your repository.
Create a AgilePlace user account to be used by Hub and ensure that:
- User must be an account administrator.
- User must be able to create and update artifacts in the AgilePlace boards to be synchronized.
- Users should be added to the list of users of a board (Board Settings > Board User Access).
Connecting to the Planview AgilePlace Repository
Standard Authentication
Required Fields:
- Location/Connection URL
- Example Format: https://server.leankit.io/
- Username
- Password
Optional Fields:
- Use Card Type as Artifact Type (Deprecated): This setting defines how card types are differentiated.
- Enable this setting to expose card types as different artifacts (legacy behavior, deprecated).
- If disabled (default), there will be only one artifact type ('Card') available, and card types will be exposed via a separate field.
- Throttling Settings: This field indicates the number of API calls that can be made per minute.
- By default, AgilePlace has a limit of 160 API calls per minute for each user account. When setting up your AgilePlace repository, a recommended setting for this field is 144 API calls per minute. If you experience performance delays, this limit can be raised with assistance from customer care. If your user account rate limit is raised or lowered, you will need to change the setting in the Hub configuration to always be slightly lower than the limit defined by AgilePlace. See details below.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
- Connection Security: If checked, insecure connections to this repository will be allowed. See details here.
API Token Authentication
Required Fields:
- Location/Connection URL
- Example Format: https://server.leankit.io/
- API Token
Optional Fields:
- Use Card Type as Artifact Type (Deprecated): This setting defines how card types are differentiated.
- Enable this setting to expose card types as different artifacts (legacy behavior, deprecated).
- If disabled (default), there will be only one artifact type ('Card') available, and card types will be exposed via a separate field.
- Throttling Settings: This field indicates the number of API calls that can be made per minute.
- By default, AgilePlace has a limit of 160 API calls per minute for each user account. When setting up your AgilePlace repository, a recommended setting for this field is 144 API calls per minute. If you experience performance delays, this limit can be raised with assistance from customer care. If your user account rate limit is raised or lowered, you will need to change the setting in the Hub configuration to always be slightly lower than the limit defined by AgilePlace. See details below.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
- Connection Security: If checked, insecure connections to this repository will be allowed. See details here.
Learn more about how to set up your repository in Planview Hub here.
Other Configuration Settings
Creating a Clickable Card Header that Links to the Target Artifact
By taking advantage of AgilePlace's custom card ID functionality, you can set up your integration to provide a clickable link on the AgilePlace card that will redirect you to the corresponding artifact in your target repository.
The example below walks through how to configure a clickable link on your AgilePlace card that will send you to the corresponding Jira issue.
First, custom card ID settings should be set up as follows:
- Enable header
- Display text from unique card ID
- Generate a link from the custom card ID
-
The link structure should mirror the URL structure in your target repository (Jira, in this example), including '{ID}' as a placeholder for the unique ID in your target repository.
-
Within Hub, configure your Field Mapping so that it contains a one-way field flow from Jira Key (Formatted ID) → AgilePlace Card ID (customID).
This will enable LeanKit to store text in the header that contains a hyperlink pointing to the Jira target artifact:
Relationships between 'Cards' and 'Tasks'
Planview Hub: 18.1 - 18.3
In AgilePlace, all artifacts are technically 'cards.' However, it is important to understand the distinction between what we will refer to here (within Hub) as "Cards with Card Class: Card" and "Cards with Card Class: Task."
In AgilePlace, users can configure different types of cards, and assign them to either Card Type, Task Type, or both. Cards with Card Type will show up on the main board in AgilePlace, while cards with Task Type will show up on the Task Board of an individual card. It is possible for a type to be assigned as both a Card Type and a Task Type. If your AgilePlace board has types that are assigned to both Card Type and Task Type, you will need to follow the instructions below to ensure your integration is flowing the desired artifacts.
- Cards with Card Class: Card: These are artifacts that live on your main board in AgilePlace, which are created when selecting 'Create a Card.' In the Card Types configuration, they will be cards with 'Card Type' selected. Note that depending on how your AgilePlace instance is configured, you could potentially have a type that is assigned to both the 'Card Type' and the 'Task Type.' Also note that the names of these cards can be configured however the user would like – so if one of them happens to be named 'task' or 'card,' that will not necessarily impact whether it is 'Card Type' or 'Task Type' (which can be very confusing!). The crucial piece of information is whether it's assigned to the 'Card Type' (meaning that it shows up on the AgilePlace board) or to the 'Task Type' (meaning that it shows up on the Tasks Board within an individual card).
- Cards with Card Class: Task: When you open a "Card with Card Class: Card," you have the option of creating "Tasks" which are associated with that Card. These Tasks do not show up on the main board, but rather live on a "Tasks Board" within the Card itself. These tasks are what we are referring to when we say "Cards with Card Class: Task" in Hub. In the Card Types configuration within AgilePlace, these will be cards with 'Task Type' selected. Note that depending on how your AgilePlace instance is configured, you could potentially have a type that is assigned to both the 'Card Type' and the 'Task Type.' Also note that the names of these cards can be configured however the user would like – so if one of them happens to be named 'task' or 'card,' that will not necessarily impact whether it is 'Card Type' or 'Task Type' (which can be very confusing!). The crucial piece of information is whether it's assigned to the 'Task Type' (meaning that it shows up on the Task board of an individual card).
If your AgilePlace instance has a Card Type that is assigned to both 'Card Type' and 'Task Type,' there are some important steps to take when creating an integration that will flow both 'Cards with Card Class: Card' and 'Cards with Card Class: Task' and their relationships to a target repository:
In this example, let's say you are trying to flow Issues with Card Class: Card and Issues with Card Class: Task along with their relationships to a target repository.
You'll see that in our AgilePlace instance, Issues are configured to have both 'Card Type' and 'Task Type' available:
1: Your AgilePlace collection for both integrations will simply be a 'AgilePlace Cards' collection. (In this example, it will be a AgilePlace 'Issues' collection).
Here, we mean 'cards' in the technical sense. As in - all artifacts (both with 'Card Class: Card' and 'Card Class: Task') in AgilePlace are technically 'Cards.' Because of this, you will only create one AgilePlace collection: AgilePlace Cards, which will cover both 'Cards with Card Class: Card' and 'Cards with Card Class: Task' of that Card Type. This collection can participate in both integrations. Step 3 will explain how you will tell Hub whether to flow 'Card Class: Cards' or 'Card Class: Tasks.'
2: Since 'Cards with Card Class: Card' and 'Cards with Card Class: Task' have different possible statuses (lanes), a custom data transformation extension will be needed to flow status into AgilePlace.
In AgilePlace, 'Cards with Card Class: Card' have different possible statuses (lanes) than 'Cards with Card Class: Task' (see images above for details). Since your collection will contain both 'Cards with Card Class: Card' and 'Cards with Card Class: Task,' you will see both status options available. Statuses that apply to 'Cards with Card Class: Task' will have (Task) appended to the end.
To flow statuses (lanes) out of AgilePlace, simply map the values to the model, as desired. To flow statuses into AgilePlace, a custom data transformation extension is required. Please contact customer care for guidance on configuring this extension.
3: When you configure your individual integrations, use artifact filtering to determine if you are flowing "Card Class: Cards" or "Card Class: Tasks"
Since all artifacts in AgilePlace are technically cards, you will use a Hub-created field called 'Card Class' to distinguish between the two. This field will essentially check to see if the artifact has a container card of not. If it has a container card (i.e., if it lives on the 'tasks board' of a card), then the field value will be 'task.' If it does not have a container card (i.e., if it lives on the main board), then the field value will be 'card.'
Thus, if you set Artifact Filtering on your integration to only flow artifacts whose 'Card Class' is 'Task,' you will only flow artifacts that live on the 'Tasks Board' of individual cards. Alternately, if you set Artifact Filtering on your integration to only flow artifacts whose 'Card Class' is 'Card,' you will only flow artifacts that live on the main board in AgilePlace.
This means that you must:
- Add a 'Card Class' field to your model: this will be a single select with values 'Card' and 'Task'
- Map the 'Card Class' model field to the 'Card Class' AgilePlace Collection field
- Configure Artifact Filtering at the Integration Level utilizing the 'Card Class' field
Below, you can see artifact filtering that will only allow "Card Class: Tasks" to flow:
4: To configure Artifact Relationship Management (ARM), use the AgilePlace 'Container Card' relationship field
Here is an example of how to configure the relationship fields for an integration:
This will enable you to:
- Flow AgilePlace Issues with Card Class: Card to Jira Epics
- Flow AgilePlace Issues with Card Class: Task to Jira Stories
- Preserve the relationships between the two
Note: You will also need to configure a AgilePlace Issues to Jira Epics integration (filtering for AgilePlace Card Class = Card) for the scenario above, though that integration will not require a relationship mapping.
Person Reconciliation
For person reconciliation, the following fields are available:
|
Fields Used for Hub’s Default Person Reconciliation Algorithm |
Field Names for Person Reconciliation Extensions (Note that these are case sensitive) |
Label in Planview AgilePlace |
|---|---|---|
|
ID |
ID |
ID |
|
Username |
username |
Username |
|
Email Address |
emailAddress |
Email Address |
|
N/A |
fullName |
Display Name |
Learn more about how to configure person reconciliation in Planview Hub here.
Full Scan
In general, a full scan is not required to synchronize updates from this repository. However, it is possible that some read-only fields may require a full scan. Please consult with customer care for additional details.
API Rate Limiting
Planview Hub: 21.4 and later
In Planview Hub 21.4, a new Throttling Settings field was added to limit the number of API calls that can be made per minute to a repository. By default, the AgilePlace repository implements an API rate limit of 160 API calls per minute per user account. This limit can be raised or lowered upon request to AgilePlace.
When setting a value in the Throttling Settings field, you should set the value to lower than the AgilePlace repository API limit (i.e., 160). The suggested value is 144.
Supported Features
Special Features Supported
|
Feature |
Custom Type Supported? |
Applicable Hub Versions |
Applicable Repository Versions |
|---|---|---|---|
|
|
|||
|
|
N/A |
Planview Hub: All |
Any supported repository version: |
|
|
N/A |
Planview Hub: All |
Any supported repository version: |
|
State Transitions (Transitions for 'Blocked Reason' on 'Is Blocked' status, no transitions required to change 'Lane') |
N/A |
Planview Hub: All |
Any supported repository version: |
Time Worked (Worklogs)
Comments
Supported Artifacts
Supported Work Items
Learn about the difference between containers and work items in Planview Hub here.
|
Supported Work Item Type |
Applicable Hub Versions |
Applicable Repository Versions |
Unique URL? |
|---|---|---|---|
| Card (any type of card) |
Planview Hub: All |
Any supported repository version: |
Yes |
Supported Containers
Learn more about containment in Planview Hub here.
|
Containers that can synchronize between repositories |
Applicable Hub Versions |
Applicable Repository Versions |
Unique URL? |
|---|---|---|---|
|
N/A |
|
|
|
|
Containers used to define the boundary of a collection (When clicking 'Manage Projects' on a Repository) |
|
|
|
|
Boards |
Planview Hub: All |
Any supported repository version: |
N/A |
|
Containers used for artifact routing |
|
|
|
|
Boards |
Planview Hub: All |
Any supported repository version: |
N/A |
Supported Field Types
Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.
|
Standard Field Type |
Does Hub support custom fields of this type? |
How is field type referenced in the repository? |
Sample Repository Fields Supported |
Particular Repository Fields NOT Supported |
|---|---|---|---|---|
|
|
|
Text |
Title, Card ID Blocked Reason (Read Only), Custom ID (Read Only), Custom Icon ID (Read Only), Custom Icon Title (Read Only), Custom ID Prefix (Read Only) |
|
|
|
|
Dropdown |
Type, Priority, Lane Board (Read Only) |
|
|
|
|
|
Tags |
|
|
|
N/A |
|
Is Blocked |
|
|
|
|
Date |
Planned Start, Planned End Created On (Read Only) Connected Card Fields (Read Only) |
Connected card date fields: Earliest Planned Start Latest Planned Finish Actual Start Not Started Actual Finish |
|
|
N/A |
|
Actual Start, Actual Finish Updated On (Read Only), Moved on (Read Only) Connected Card Fields (Read Only) |
|
|
|
|
|
|
|
|
|
|
Numeric |
Score |
|
|
|
N/A |
|
Size, Index(Read Only), ID (Read Only) Connected Card Fields (Read Only) |
|
|
|
N/A |
|
Creator(Read Only), Modified by (Read Only) |
|
|
|
N/A |
|
Assigned Users |
|
|
Supported in: Planview Hub: 18.1 and later Learn how to configure relationships in Planview Hub here. |
N/A |
|
Parent Card Child Card |
|
|
|
|
|
Description |
|
|
|
N/A |
External Link |
External Link, Card ID Hyperlink Header (Read Only) |
|
|
|
|
|
|
|
Functional Limitations
|
Category |
Limitation |
Applicable Hub Versions |
Applicable Repository Versions |
|---|---|---|---|
|
Good to Know |
Score Field By default, the Score field values synchronize with decimals. If customization is required, reach out to customer care. |
Planview Hub: 23.4 and later |
Any supported repository version: |
|
Third Party Functional Limitation |
Score Field If synchronizing the Score field with other connectors, you must enter a value within the range of 1 to 99. |
Planview Hub: 23.4 and later |
Any supported repository version: |
|
Good to Know |
Assigned User Field The Assigned User field is ordered by the internal AgilePlace ID which is auto-generated within the system. |
Planview Hub: All |
Any supported repository version: |
|
Third Party Functional Limitation |
CardID Field When Mirror from Parent Card is used, the CardID field is locked in a read-only mode. If using this function, you should not attempt to write to the CardID field. |
Planview Hub: All |
Any supported repository version: |
|
Good to Know |
Parent Cards & Child Cards Because AgilePlace allows one child to have multiple parents, it is not recommended to synchronize the parent/child links to repositories that have single parent to multiple children links. This is due to the unpredictable behavior a user might see upon attempting to integrate many to many links into one to many links. |
Planview Hub: 18.4 and later |
Any supported repository version: |
|
Third Party Functional Limitation |
Connected Card Fields Since the Connected Card fields are calculated on the AgilePlace server side based on data on the child card, the connected card fields are read only and cannot accept data via a Hub integration. |
Planview Hub: 18.3 and later |
Any supported repository version: |
|
Known Defects |
Change Detection Sometimes AgilePlace doesn't update the card version on null writes of custom fields. The value does get updated, just not the artifact version. This means that change detection can sometimes fail when a null value is written to custom String, Numeric, Date, or Single-Select fields. |
Planview Hub: All |
Any supported repository version: |
|
Known Defects |
Attachments Attachment size information is corrupt for attachments created before . This was a AgilePlace API limitation that has been resolved but this still applies to files attached to cards before the fix date. |
Planview Hub: All |
Any supported repository version: |
|
Third Party API Limitation |
Attachments An error occurs when trying to flow attachments 50MB or greater into AgilePlace. This is a known AgilePlace bug that they are aware of and have created an issue. |
Planview Hub: All |
Any supported repository version: |
|
Third Party API Limitation |
Cards and Tasks When moving a Card to become a Task or vice versa as a result of an integration, the Card will always become a Task in the 'ToDo' lane and the Task will always become a Card in the Lane where its previous Container Card exists.
|
Planview Hub: 18.1 - 18.3 |
Any supported repository version: |