Add Columns to the Work Cache
Add Column to Work Lists
Add Column to the Work Cache
Mapping a Column to the Work Cache
Mapping a Column from the XML Mapping File
Add Column to the Cache Report
Troubleshooting
When configuring work lists with additional columns you may want to include these columns in Work Cache reports. This topic explains the steps on how to do this.
Note: You need to be a Site Collection Administrator or a member of the BrightWork Cache Administrators group with full control for some of the actions below as noted in each section.
Add Column to Work Lists
Before you begin it is assumed you have added columns to your work lists. The supported lists are:
- Project Tasks (List Types 150, 171, 723)
- Project Goals (List Type 713)
- Project Risks (List Type 715)
- Project Issues (List Type 714)
- Change Requests (List Type 716)
- Project Requests (List Type 737)
- Workflow Tasks (List Type 107)
- Generic List (List Type 100)
- BrightWork Custom List (List Type 758)
The contents of the Generic List and BrightWork Custom List will only be added to the Work Cache list if the calculated Boolean column bwAddItemToWorkCache exists in the list and its calculated value is 'Yes'.
Add Column to the Work Cache List
The following steps require Site Collection Administrator access.
First, you need to add a column to the Work Cache list. This list is hidden to prevent accidental editing. The only time you typically need to access it is when you need to add columns or to add a view.
-
Navigate to the site collection home page, paste bwWorkItemCache after the site name and click Enter on your keyboard to open the hidden Work Cache list. For example the URL should be something like the following:
https://myserver/sites/mysitecollection/bwWorkItemCache - Add the column to the Work Cache list using the appropriate column type.
Use the same column type in the Work Cache list as the source list. For example; if the column is a Date and Time column in the list, create a Date and Time column in the Work Cache.
If you are adding a choice column to the Work Cache list, we recommend the default value is left blank.
The Work Cache list supports the addition of calculated columns. You do not need to map these columns from the source list to the Work Cache list.
We do not recommend adding Site Columns to the Work Cache list.
The name you use to add the column to the Work Cache list doesn't really matter as you will be mapping it in the next step; however, we recommend the same or a similar name to make the mapping maintenance process easier.
Note: When mapping columns of the same type to the Work Cache, there are two exceptions:
- Lookup columns from lists should be mapped to text columns, i.e. Single line of text columns, in the Work Cache. This applies to all Lookup columns including cascading lookup columns from third parties as well as single value and multi-value lookups.
- Choice Indicator Icon and Number Indicator Icon columns from lists should be mapped to Hyperlink or Picture columns, with the Format URL as Picture option, in the Work Cache.
Mapping a Column to the Work Cache
The following steps require Site Collection Administrator access.
Note: Work Cache mapping applies to the entire site collection. Therefore, even though the mapping is done in a template or project site, it impacts the entire site collection. So when making changes to Work Cache mapping, it is important to consider the impact of any changes on other sites within the site collection.
- Click the settings cog
in the top right and then click Site settings. - Click Map Columns to the Work Cache under BrightWork Settings.
You can then add new column mappings or manage existing mappings.
Tip! If you have not already added a column to the Work Cache list you can open the Work Cache list in a new browser tab by clicking the 'Work Cache' link at the top of the mapping page.
The option to select the source list is at the top of the page. Work Cache mapping allows you to map from the following lists:
- Project Tasks (List Types 150, 171, 723)
- Project Goals (List Type 713)
- Project Risks (List Type 715)
- Project Issues (List Type 714)
- Change Requests (List Type 716)
- Project Requests (List Type 737)
- Workflow Tasks (List Type 107)
- Generic List (List Type 100)
- BrightWork Custom List (List Type 758)
The Generic List and BrightWork Custom List will only appear as source list options if the calculated Boolean column bwAddItemToWorkCache exists in the list.
Work Cache Mapping Screen Elements
- Project List Column: Displays the selected source list's column names with their column types. The page shows list columns that are:
- Visible in the list's forms or views.
- Mapped to the Work Cache.
- Not in the BrightWork reserved column list.
- Work Cache Column: Displays the Work Cache column name that is being mapped to.
- Remove: Clicking on the Remove button will delete the specific mapping from the mapping file. This can be useful if you make a mistake and need to remove an incorrect mapping.
Caution: Consider the impact on other sites in the site collection before you remove a mapping.
Add a New Column Mapping
- Select a source list to map columns from using the drop-down.
- Click Add new column mapping.
- Select the list column you wish to map from in the Select Source Column drop-down list. If no options are available, it means that there is no source to map to the Work Cache.
- Select the Work Cache column you wish to map in the Work Cache Column drop-down list. If no options are available, it means that there is no column in the Work Cache of the correct type available to map to.
- Click Save and your mapping will appear in the list of mappings.
Mapping a Column from the XML Mapping File
It is possible but not advisable to manually map items to the Work Cache by updating the WorkItemCacheGlobalSettings.xml file.
Note: We recommend using SharePoint Designer 2013 (available as a free download from Microsoft) for updating the XML file. Having some experience with XML would be an advantage.
The following steps require Site Collection Administrator access.
You must update the global WorkItemCacheGlobalSettings.xml mapping file. This file maps columns from the supported lists to Work Cache columns.
- Open the top level site of your site collection in SharePoint Designer 2013.
For example, the URL should be something like:
https://myserver/sites/mysitecollection - Click All Files | _catalogs | bwConfigStore | WorkItemCacheGlobalSettings.xml.
- Click Edit File to open the file for editing.
-
Add an XML tag to the appropriate list template, for example:
<Field target="YourWorkCacheColumn" source="YourListColumn" />.
The WorkItemCacheGlobalSettings.xml is for specifying global mappings in a BrightWork site collection. Every site also has its own WorkCacheSettings.xml file.
If the column you want to map has a different internal name in a certain site (for example, one project template uses a column called Organization and the rest use a column called Department), update the local WorkCacheSettings.xml with the appropriate mapping information and it will override the global setting specified in the top level WorkItemCacheGlobalSettings.xml file.
Changes to the WorkCacheSettings.xml file are automatically included in Design Sync. This means that changes to this file should be made in the Template and synced, if Design Sync is being used.
Note: Take care editing the global mapping file as syntax errors will prevent all updates to the Work Cache.
Add Column to the Cache Report
Finally, add the column to the Shared or Personal report that uses the cache.
Troubleshooting
After going through this procedure if you find the new column's data is not appearing in the report, the first recommended step is to retrace the above steps checking each step of the procedure.
If the Work Cache mapping file was updated after the work item(s) themselves were updated, then there will have been no event triggered on the list to update the work item(s) in the Work Cache. To fix this either:
-
Edit and save the Work Item(s) in the project. This will trigger an update to the Work Cache Update queue which, when processed, updates the Work Cache.
- Open the Work Cache (as referenced in Add Column to Work Cache above) and delete the related item(s) directly from the Work Cache. Then perform a Refresh Work Cache to re-add the Work Item(s).