How to set up and use Task Publishing in Teams

Task Publishing was recently made available in Microsoft Teams. The general info about Task Publishing can be found in here. In this article I lay out how you can get started while following also the documentation presented here.

21.1.2021 updated this post with task list housekeeping (unpublish, duplicate, delete)

Microsoft defines Task Publishing very well in that Support article:

As a Teams user who has been enabled for task publishing by your organization, you can create a list of tasks to send to any number of teams in your org. Each team gets its own copy of the list for assigning and completing tasks and tracking team progress. If you’re a team manager, find out how to assign and track tasks in Teams.


Task list publishing is how operations managers and other organization planners distribute tasks to the teams who perform the work. Each team receives one copy of the list, so local managers can assign tasks to their workers. Managers who are part of teams in the hierarchy between the local manager and the task list publisher can track assignment and completion of tasks, but cannot change anything. 

In short: specific users can create and publish tasks lists to selected teams – and tasks are automatically added to target team’s Tasks (Planner) boards. Target teams define by themselves who are responsible of those tasks and take care of marking them complete. Teams are selected using a hierarchy and filters, that makes it easy to target these task lists to big number of teams at once – and follow up the progress how tasks are being assigned & completed.

In this blog post I go through steps needed to create your hierarchy and prepare the tenant for Task Publishing and also how you create tasks lists and publish them. That is followed by the team (end user/employee) experience coming back to the reporting/following up part how tasks completion is being tracked. Don’t forget to read the conclusion part in the end either.

If you are looking a guide how to create and use Task Publishing then skip directly to chapter 3 (creation of lists).

I am not defining every step on preparing the tenant for Task Publishing (chapters 1-2) in full detail since that documentation found here is very detailed. Keep that open as well when configuring the hierarchy.

1. Create your hierarchy file

This seemed to be a bit tricky one – I had to do this a few times to get it right.

Mandatory columns

  • TargetName (ie: the name of the element shown in the hierarchical structure)
  • ParentName (parent name from the hierarchical structure)
  • TeamsID (guid of the team)

Then you can set properties how you can limit the teams where the list will be published to. I used Size and Department:Maintenance. The difference between these two is that I can specify the values freely for the Size for each team and Department:Maintenance is a 1/0 (or true/false if you prefer) setting for each team. You could add more “checkboxes” for Departments by defining more columns “under” that Department. One example could be Department:Sales

Then the last parts are #columns. These are actually definitions for buckets where tasks will be written in Tasks (Planner) in the team. If that bucket in Planner doesn’t exist it will be created. In the hierarchy you just leave these values empty for all teams. I had strange errors when I tried to set these. 🤓🤣 So take that as a learning: do not set them in the hierarchy file.

So here is the hierarchy file I used – TeamID I replaced with a [Team GUID] text.

TargetName,ParentName,TeamId,Size,Departments:Maintenance, #Contract, #OnSite
Platform Company,,[Team GUID],,,,
ePlatform,Platform Company,,,,,
IoT Platform,Platform Company,,,,,
Platform Firstline,ePlatform,[Team GUID],Large,1,,
eTeam 2,ePlatform,[Team GUID],Medium,1,,
Spotlight,IoT Platform,[Team GUID],Small,,,
Platform IT,IoT Platform,[Team GUID],Medium,,,

Yes – I know that those names are not the best example (far from it) but perhaps it however makes it more clear how this hierarchy can be set up. However do not forget the read the Docs about setting publishing up for more details. My example also doesn’t have too complex hierarchy defined (only one root that spreads out to different leaves).

In the example I have set up that two teams (Platform Firstline and eTeam 2) are Maintenace teams (they have that property set to 1) and the rest are without a property.

Leaf rows with a TeamID are teams that tasks can be published to. In this case I have four teams that can be used to receive task lists. The top team is not counted it: it is the team that the list is being published from.

The hierarchy then looks like this, with a single top level entity (Platform Company)

Size and Departments can be used to filter the list of teams where the task list is published to – making it easy to select all teams in ePlatform for example (that match the filters on the left).

2. Upload the task publishing hierarchy to Teams

  1. You need PowerShell for this
  2. If you have existing Microsoft Teams installation you need to uninstall it to be able to enable preview version (status in 20th of January 2021).
    Uninstall-Module MicrosoftTeams
  3. Install Public Preview version of Teams PowerShell
    Install-Module MicrosoftTeams -AllowPrerelease -RequiredVersion “1.1.9-preview”
  4. Import Teams Module
    Import-Module -Name MicrosoftTeams
  5. Connect to Teams
  6. Upload the hierarchy csv
    Set-TeamTargetingHierarchy -FilePath “c:\[your path]\HierarchyFile.csv”
  7. Check Status
  8. If you have errors – get more details out with

If Get-TeamTargetingHierarchyStatus is anything else but a success you have errors in your hierarchy file and you need to fix them and try again.

You can always reapply a new hiearchy: it will overwrite the existing one. Yes – there can be only one hierarchy, and you can not reference to a single team twice in it.

When everything is good and you see & can navigate to Published lists in Tasks by Planner and To Do app you are one step closer to using Task Publishing.

However – you must see the + New list in the bottom left of the app.

If you don’t see that it means that your hierarchy, despite being a successfully imported, has some issues. You need to get back to your hierarchy definition and try to make it simpler to figure out the error.

3. Creating a task list and publishing it

When you hit + New list you give your task list a name.

After that you can start adding tasks. This is where you can see what the bucket means in the hierarchy file.

When you add a new task you can specify the bucket where the task ends in that team tasks (Planner). This makes it possible to create more complex task lists that will look nicely grouped (bucketed) in the receiving end – after all there are people taking care of those tasks so make it as easy as possible for them!

Remember to hit that ok sign at the end of the row to save it. Or x to cancel adding the row.

Once you have added the row you can do changes – but you need to use … menu

You can also change Priority (the default sorting order is Urgent first) and due dates via the same meny.

Once your list is done you can hit Publish!

In the screen that opens you define those teams that will be receiving these task lists

Filters on the left are and filters: meaning that you can choose more of them and only those teams matching all selected filters will be displayed and are thus selected as targets. Remember that these properties here were defined in the hierarchy file.

I can choose the teams which I want to receive this Task list and once I am happy I hit Next.

Then you have to confirm that Yes – I am 100% that these are my targets and this is my list of tasks that needs be published.

After that the task list is being published

Then we can see that the list was published and there are tasks in those teams to be done:

When people in target teams update tasks to have a responsible person (assigned to) taking care of them it will be eventually updated to this screen (it takes some time to update).

You can also choose to view per team how they are progressing with tasks (top right section: Teams)

4. Employee / team view

For employees these are tasks in Planner. They can take a look via the Tasks By Planner and To Do application or in their team channel.

They can see whatever info was provided in the publishing list: name, urgency and due date for example. And in this view the buckets are very self-explanatory: users can see tasks in according buckets.

Using the standard … menu tasks can be assigned to persons for example.

Let’s complete a couple of these tasks and return to Publisher view.

5. Following up on tasks

The real beauty of Task Publishing is in following up how tasks are progressing.

First you want to put your eyes to the top-right section of Published Lists view in Tasks by Planner and To Do app. There is a … menu that includes a Refresh function. It is very handy when updating the task status.

We can already see that Assigned-information has been updated. Completed information takes a bit more time to update to the Publishing report. Of course this is not usually that urgent – these task lists are ideal to stores, maintenance workers, planning for budgets etc that usually take time anyway.

This view shows how tasks are being processed overall. There is a per task completion percentage.

Team view shows how tasks are being progressed overall and per team:

Now the completion information has come through and we can see how people are assigning and completing tasks in different teams and in hierarchy overall (ie: one area could have completed everything but other areas might have not).

Going back to the published Tasks-view you can see that there is a … menu at the end of each task that can open up more info: View report and View details

View report shows , on that selected task, which teams have assigned/completed it and what are still in the process

View details opens the Planner card so you can see what kind of details were entered during the creation of the task list

And that is it!

6. Housekeeping: Unpublishing and deleting lists

Sometimes it is good to do some housekeeping – especially if you have been testing the app out. Published lists can be unpublished by selecting Unpublish from the … menu.

When you choose to Unpublish the list it will remove tasks in target teams and pulls it back to a draft mode for further editing. The progress on tasks is lost when the list is unpublished.

When you Unpublish a list it is returned to Drafts. However it can not be re-Published and you can not add new tasks there. You can open existing tasks and edit them though. The best thing would be to rename the unpublished list to something else and then duplicate it back to the real name.

This brings us to duplication. From the … menu in the list there is the option to Duplicating it. Duplicated list goes to drafts so you can edit it further.

Since all team information (where it was published to) is cleared you get a fresh start.

When you have some testing lists you can rename or clear them out when they are still in the draft phase (or you have unpublished the list). Deletion is permanent.

7. Conclusion

Task Publishing is a very powerful feature that can be used in many scenarios, not just with Firstline workers, to spread out tasks to different teams and follow up on the task completion progress. It is a really useful view to track on how tasks are being processed and progressed through out different sets of teams.

Of course when starting to use this feature it is really important to make sure everyone in the team knows what they are expected to do: checking out tasks, assigning them to responsible persons and marking them done. At least the last part. Otherwise it enforces the task published to resort to old ways: asking the status from all teams as often as needed.. So using this feature in adopted and smart way can save a lots of time from all parties.

The set up of this feature is a bit tricky. The hierarchy needs to be specified and you can’t have multiple different versions in the tenant: just one. The good side are those properties that be used to support lots of different scenarios and also the possibility to create several hierarchy structures in one file (multiple top level teams that spread to out leaves : as long as every team is included only once in the list). It is not that easy to create manually so it would be a lot better way to create a hierarchy structure in database, SharePoint list or in other source and then programmatically create the hierarchy file. That way updates are also a lot easier to be applied.

I hope you found this blog post helpful and adding / clarifying to the information provided in Microsoft Support and Docs sources. Let me know in comments!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.