Set up your squad targeting hierarchy

  • Article
  • 15 minutes to read
  • Applies to:
    Microsoft Teams

Setting upward a team targeting hierarchy volition allow your organization to publish content to a big set of teams. The team targeting hierarchy defines how all the teams in your hierarchy are related to each other, which users tin can publish tasks, and which teams users have permissions to publish to. Publishing features are disabled for all users unless a team targeting hierarchy is set up upwards for your organization. To set up a team targeting bureaucracy, yous'll need to create a file that defines the hierarchy and and then upload it to Teams to apply it to your arrangement. After the schema is uploaded, apps within Teams can use it.

Important

For the initial release, only the Tasks app supports hierarchical teams. Applying a team targeting hierarchy to your organization volition enable chore publishing in the Tasks app. You won't come across a bureaucracy of teams in other areas of Microsoft Teams.

Here's an example of how the hierarchy is represented in the Tasks app in Teams. Afterward a task list is created, members of the publishing team can then select the recipient teams to send (publish) the job list to. When selecting teams, the publishing squad can filter by hierarchy, by attributes, or a combination of both.

Screenshot of task publishing.

Terminology

The following terms volition be important as yous navigate hierarchies. Teams volition be referred to as nodes.

  • Root nodes are the topmost nodes in the bureaucracy. In the instance, Retail Communications is a root node.
  • Parent nodes and kid nodes are terms that represent a relationship betwixt two continued nodes. In the example, District 01 is a child node of Area 1.
  • Multiple levels of children are referred to as descendants. District 01, Shop 01, Shop 03, Shop 07, Commune 02, and District 03 are all descendants of Area ane.
  • A node with no children is called a leaf node. They are at the lesser of a hierarchy.
  • Recipient teams are teams that have been selected to receive a specific set of content to be published. They must exist leaf nodes.

Programme your hierarchy

Before you create the schema that defines your hierarchy, you demand to practice some planning and decide how y'all want to shape your organization. One of the first priorities is deciding which organizational groups need to publish tasks to other groups. Each node in the hierarchy represents a working grouping or group of groups.

Permissions to publish

Permission to publish depends on whether a user is a fellow member of any teams in the bureaucracy plus the human relationship of that team or prepare of teams to other teams in the hierarchy.

Note

The owner of a team is as well granted publishing permissions.

  • If a user is a member of at least 1 team that has descendants in the hierarchy, that user tin publish to those descendants without being a member of all teams they want to publish to.
  • If a user is a member of a least one team in the bureaucracy but isn't a fellow member of whatever team with descendants in the hierarchy, that user can see and receive published content from their organization.
  • If a user isn't a member of whatsoever squad in the hierarchy, that user won't meet whatsoever publishing-related functionality.

Guidelines

  • There tin can only be one hierarchy file practical per arrangement. However, yous tin include different parts of your organization together equally distinct hierarchies of nodes within ane file. For example, Contoso Pharmaceuticals has a Pharmacy root node and a Retail root node. Both root nodes have multiple rows of descendants and there's no overlap between them.
  • Only leafage nodes can be recipients of a publication. Other nodes in the hierarchy are helpful for selecting recipients of a publication.
  • A team can but be represented i time in a bureaucracy.
  • A bureaucracy can contain upwardly to xv,000 nodes. Nosotros programme to piece of work with customers to raise this limit for larger organizations.

Example hierarchy

For example, in the post-obit bureaucracy, Recall, Communications, and HR can publish tasks to every bottom node (team) in the hierarchy, merely Northeast Zone tin can just publish tasks to the New York Store and Boston Store teams. The example bureaucracy allows the Remember, Communications, and Hr groups to publish tasks that use to the unabridged company, such every bit benefits information or letters from the CEO. Northeast Zone can publish tasks like personnel scheduling, weather data, and and so on, merely to the New York Shop and Boston Shop teams.

Team hierarchical example.

Create your bureaucracy

Note

The remainder of this article discusses setting up a team bureaucracy in the context of publishing tasks to recipient teams. Refer to Manage the Tasks app for your organization in Teams for an overview of the Tasks app, where job publishing appears when enabled.

The schema that defines your hierarchy is based on a comma-separated values (CSV) file. The file must exist in UTF-eight format. Each row in the CSV file corresponds to one node within the hierarchy of teams. Each row contains information that names the node inside the bureaucracy, optionally links information technology to a team, and includes attributes that can be used to filter teams in apps that back up it.

Yous can besides define buckets, which are categories that the publishing team tin can use to organize content sent to recipient teams to brand information technology easier for them to view, sort, and focus on relevant content.

Add required columns

The CSV file must contain the following three columns, in the post-obit guild, starting at the beginning column. A node must be linked to a squad for it to receive tasks.

Column name Required Clarification
DisplayName Yeah This field is the proper name of the node. The name can be upward to 100 characters long and incorporate only the characters A-Z, a-z, and 0-9. Node names must be unique.
ParentName Yep This is the name of the parent node. The value you specify hither must match the value in the DisplayName field of the parent node exactly. If you want to add more than one parent node, separate each parent node name with a semicolon (;). You can add up to 25 parent nodes, and each parent node proper name can be up to 2500 characters long. A node can accept multiple parent nodes simply if the parent nodes are root nodes.

Of import Be careful not to create a loop where a parent college up in the hierarchy references a child node lower in the hierarchy. This isn't supported.
TeamId Yep, if the squad publishes tasks or receives tasks from a parent node This contains the ID of the squad you desire to link a node to. Each node must refer to a unique team, and so each TeamId value may appear only once in the hierarchy file. To get the ID of a team y'all want to link a node to, run the following PowerShell command: Get-Squad | Export-Csv TeamList.csv. This command lists the teams in your arrangement and includes the name and ID for each team. Observe the name of the team you want to link to, and so copy the ID into this field.

Note

If a node isn't a root node or a leaf node and y'all don't need the team membership to grant the respective permissions for publishing and reporting, yous can leave the TeamId blank. This method can be used to add more granularity when choosing recipient teams or for viewing completion reports without having a respective team.

Add attribute columns

After you add together the 3 required columns, you can add optional attribute columns. These attributes can be used to filter nodes so that you can more than easily select the ones you desire to publish tasks to. At that place are two means to define your attributes, depending on whether values for that attribute are mutually exclusive.

Means to add together attributes Clarification Example
If the values for an attribute are mutually exclusive, the column name you specify becomes the proper noun of the attribute. Each row can contain i value for that attribute, and each aspect cavalcade can have up to 50 unique values. Each value can be up to 100 characters long. The prepare of aspect values y'all specify in the attribute column will be displayed as filter values for that aspect when selecting recipient teams using the team targeting bureaucracy. Yous want users to be able to filter stores by layout. The values for this attribute are mutually exclusive because a store tin can have only 1 layout.

To add together an aspect to filter stores by layout, add a column named Shop layout. In this case, values for the Store layout attribute are Compact, Standard, and Large.
If you need to indicate multiple values for an attribute and the values aren't mutually exclusive, use the AttributeName:UniqueValue format for the column names.

IMPORTANT Make sure to use the English-but colon (:) equally unicode isn't supported as an attribute column delimiter.

 The text cord earlier the colon (:) becomes the proper noun of the aspect. All columns that contain the same text cord before the colons (:) are grouped together into a department in the filtering menu. Each of the strings later on the colon get the values for that section.

Each row can take a value of 0 (aught) or 1 for that attribute. A value of 0 means that the attribute doesn't apply to the node and a value of ane means that the attribute applies to that node.

 You want users to exist able to filter stores by section. A store can have multiple departments and then the values for this aspect aren't mutually exclusive.

In this example, we add Departments:Vesture, Departments:Electronics, Departments:Foods, Departments:Domicile and Garden, Departments:Sporting appurtenances as attribute columns. Departments becomes the attribute name and users can filter by the Clothing, Electronics, Foods, Domicile and Garden, and Sporting goods departments.

When yous add an attribute column, keep the post-obit in heed:

  • The column proper noun yous specify or the column proper name that you specify before the colon (:) becomes the name of the aspect. This value volition be displayed in the Teams apps that use the hierarchy.
  • You lot can have up to 50 attribute columns in your hierarchy.
  • The column proper name tin can be up to 100 characters long and contain only the characters A-Z, a-z, and 0-ix, and spaces. Column names must exist unique.

Add together bucket columns

Y'all can add bucket columns to create buckets, which are groupings into which tasks can be organized. Each bucket gets its ain column in the CSV file. The buckets you create are fabricated available to the publishing team. The publishing squad can so use these buckets to categorize tasks for the recipient teams. If a bucket doesn't already exist on a squad, buckets are created on-demand when tasks are published.

By categorizing the work items i time centrally, the publishing team can pre-organize the task list for all the tens, hundreds, or thousands of recipient teams that receive the task listing. The recipient teams can then sort and filter their tasks by bucket to focus on the area most relevant to their work.

When you lot add a bucket column, note the following:

  • The column name becomes the name of the bucket. Each bucket you specify will announced in the Buckets list in the Teams apps that employ the bureaucracy.
  • We recommend that you don't include sensitive information in bucket names. At this time, publishing teams can't remove a bucket through publishing after it'due south created.
  • The cavalcade name must be preceded by a hashtag (#). It can be up to 100 characters long and contain only the characters A-Z, a-z, and 0-9. For example, #Operations and #Frozen Goods.
  • A hierarchy may comprise up to 25 bucket columns. We plan to work with customers to increase this limit for larger organizations.

Instance

Here'southward an instance of a schema CSV file that would exist created to support the hierarchy shown in the previous paradigm. This schema contains the post-obit:

  • Three required columns named TargetName, ParentName, and TeamId
  • Three aspect columns named Store layout, Departments:Vesture, and Departments:Foods
  • Iii bucket columns named Fresh Foods, Frozen Foods, and Women's Wear

The Shop layout attribute has values that include Compact, Standard, and Large. The Departments aspect columns can be set to a value of 0 (zero) or 1. The Store layout and Departments attributes aren't shown in the prototype above. They're added here to assistance show how attributes can be added to node entries. The aforementioned is truthful for the three bucket columns.

              TargetName,ParentName,TeamId,Store layout,Departments:Vesture,Departments:Foods,#Fresh Foods,#Frozen Foods,#Women's Wear Recollect,,db23e6ba-04a6-412a-95e8-49e5b01943ba,,,,,, Communications,,145399ce-a761-4843-a110-3077249037fc,,,,,, HR,,125399ce-a761-4983-a125-3abc249037fc,,,,,, East Regional Office,HR;Communications;Remember,,,,,,, West Regional Part,HR;Communications;Recall,,,,,,, Northeast Zone,Due east Regional Function,,,,,,, Southeast Zone,East Regional Function,,,,,,, New York Shop,Northeast Zone,e2ba65f6-25e7-488b-b8f0-b8562d5de60a,Large,i,i,,, Boston Shop,Northeast Zone,0454f08a-0507-437c-969a-682eb2fae7fc,Standard,1,1,,, Miami Shop,Southeast Zone,619d6e4e-5f68-4b36-8e1f-16c98d7396c1,Compact,0,1,,, New Orleans Shop,Southeast Zone,6be960b8-72af-4561-a343-9ac4711874eb,Compact,0,1,,, Seattle Shop,West Regional Zone,487c0d20-4e55-4dc2-8187-a24c826e0fee,Standard,1,1,,, Los Angeles Store,West Regional Zone,204a1287-2efb-4a8a-88e0-56fbaf5a2389,Large,1,1,,,

Apply your bureaucracy

Note

To perform this step, y'all must install and use the Teams PowerShell public preview module from the PowerShell Gallery. For steps on how to install the module, see Install Teams PowerShell.

Note

Authorities Community Cloud (GCC) customers must use cmdlet preview version ii.four.0-preview or later to ensure data is routed to the GCC surround, rather than the public cloud environment.

Afterward you've divers your hierarchy in the schema CSV file, you're ready to upload it to Teams. To do this, run the following command. You must be a global admin or Teams service admin to practice this stride.

              Set-TeamTargetingHierarchy -FilePath "C:\ContosoTeamSchema.csv"

Update your bureaucracy

You can upload a new hierarchy to supervene upon the one-time one using the aforementioned PowerShell command as higher up. Each time you upload a new hierarchy, it replaces the previous hierarchy.

Cheque the status of your bureaucracy

You can run the following control to check the status of your hierarchy upload.

              Get-TeamTargetingHierarchyStatus

The command will return the following fields:

Field Description
Id The unique ID for the upload.
Status Upload condition. Values include Starting, Validating, Successful, and Failed
ErrorDetails Details if there'due south an upload error. For more than data almost the error details, see the Troubleshooting department. If there's no fault, this field is blank.
LastUpdatedAt Timestamp and date of when the file was last updated.
LastModifiedBy The ID of the last user who modified the file.
FileName The file name of the CSV.

Remove your hierarchy

If y'all want to immediately disable the Published lists tab for all users in your organization, you can remove your hierarchy. Users won't have admission to the Published lists tab or any of the functionalities on the tab. This includes the power to create new task lists to publish, access draft lists, publish, unpublish, and duplicate lists, and view reporting. Removing the hierarchy doesn't unpublish tasks that were previously published. These tasks will remain bachelor for recipient teams to complete.

To remove your hierarchy, run the following command. You must be an admin to perform this step.

              Remove-TeamTargetingHierarchy

When confirming deletion, the status message will still display the previous schema is present, although attempting to delete over again returns an error that the object is null.

Create a sample hierarchy

Install the Teams PowerShell module

Sample script

The following script can exist used to create the teams and upload a .csv file to your Microsoft Teams tenant. If you have an existing hierarchy, this script volition replace it.

Create teams for a simple hierarchy

              $tm1 = New-Squad -DisplayName "HQ" $tm2 = New-Team -DisplayName "North" $tm3 = New-Team -DisplayName "Store one" $tm4 = New-Team -DisplayName "Store 2" $tm5 = New-Team -DisplayName "South" $tm6 = New-Squad -DisplayName "Store 3" $tm7 = New-Squad -DisplayName "Store 4"

Utilize team data to create comma-separated output (DisplayName, ParentName, TeamId)

              $csvOutput = "DisplayName" + "," + "ParentName" + "," + "TeamId" + "`n" $csvOutput = $csvOutput + $tm1.DisplayName + "," + "," + $tm1.GroupID + "`northward" $csvOutput = $csvOutput + $tm2.DisplayName + "," + $tm1.DisplayName + "," + $tm2.GroupID + "`n" $csvOutput = $csvOutput + $tm3.DisplayName + "," + $tm2.DisplayName + "," + $tm3.GroupID + "`n" $csvOutput = $csvOutput + $tm4.DisplayName + "," + $tm2.DisplayName + "," + $tm4.GroupID + "`north" $csvOutput = $csvOutput + $tm5.DisplayName + "," + $tm1.DisplayName + "," + $tm5.GroupID + "`due north" $csvOutput = $csvOutput + $tm6.DisplayName + "," + $tm5.DisplayName + "," + $tm6.GroupID + "`northward" $csvOutput = $csvOutput + $tm7.DisplayName + "," + $tm5.DisplayName + "," + $tm7.GroupID

Salve output to a .csv file in the Downloads folder

              $csvOutputPath = $env:USERPROFILE + "\downloads\testhierarchy-" + (Get-Engagement -Format "yyyy-MM-dd-hhmmss") + ".csv"  $csvOutput | Out-File $csvOutputPath

Upload the hierarchy

              Gear up-TeamTargetingHierarchy -FilePath $csvOutputPath Get-TeamTargetingHierarchyStatus

Troubleshooting

How to view mistake details

Yous tin run the following command to understand what is causing an fault and return the mistake details.

              (Get-TeamTargetingHierarchyStatus).ErrorDetails.ErrorMessage

You receive an fault message when you upload your schema CSV file

Take note of the error bulletin as it should include troubleshooting information to signal why the schema couldn't be uploaded. Review and edit your schema CSV file based on the data in the error bulletin and then try again.

You receive an "Error: InvalidTeamId" error message when you upload your schema CSV file

When you lot effort to upload your schema CSV file, yous get the following mistake message:

              Error: InvalidTeamId Description: TeamID in row # doesn't match a valid Group ID. Please view our documentation to learn how to get the proper GroupID for each team.

Check to make sure that y'all're using the correct TeamId for the team in your schema CSV file. The TeamId should be the same equally the Group ID of the Microsoft 365 group that backs the team. You can look upward the Group ID of the squad in the Microsoft Teams admin center.

  1. In the left navigation of the Microsoft Teams admin center, become to Teams > Manage teams.
  2. If the Group ID cavalcade isn't displayed in the table, select Edit columns in the upper-right corner of the table, and then turn on Grouping ID.
  3. Find the squad in the list, and then locate the Group ID.

Make sure that the TeamId in your schema CSV file matches the Grouping ID that'south displayed in the Microsoft Teams admin heart.

  • Manage the Tasks app for your organization in Teams
  • Teams PowerShell overview