Dynamic Placeholders
Summary¶
Dynamic placeholders are values that can be used in Valo Teamwork Teams templates. Once correctly configured, those placeholders will be replaced during runtime with the corresponding values from the target team which is created based on a Valo Teamwork Teams template. This section demonstrates how to configure those dynamic placeholders.
Supported placeholders¶
| Placeholder | Description | Supported Tabs |
|---|---|---|
| {siteCollectionUrl} | Represents the site collection URL of the target Office 365 group which is part of the Team | Web site, Files |
| {groupId} | Represents the ID of the team/group | OneNote |
| {randomGuid} | Represents a random GUID that will be created during runtime | OneNote |
| {notebookId} | Represents the ID of a OneNote notebook | OneNote |
| {onenoteWebUrl} | Represents the OneNote notebook top level URL | OneNote |
| {notebookName} | Represents the name of the notebook. This placeholder will be replaced with the tab name | OneNote |
| {sectionName} | Represents the name of the notebook section. If not provided, this placeholder will be replaced with the tab name | OneNote |
| {sourceDocId} | Represents the sourceDoc ID of the file | Files |
| {planId} | Represents the plan ID of the Planner plan | Planner |
| {tenantName} | Represents the name of the tenant. E.g.: contoso | Planner |
| {groupDisplayName} | Represents the group/team display name. E.g.: Project | Planner |
Note
Files stand for Word, Excel, PowerPoint and PDF file tabs.
How to use the site collection url placeholder?¶
The example below creates a web site tab which points to the home page of the target site collection. Here is what the configuration looks like:
<Tab Name="HomePage as Website" SortOrderIndex="1" AppId="com.microsoft.teamspace.tab.web">
<Configuration>
<ContentUrl>{siteCollectionUrl}/sitepages/home.aspx</ContentUrl>
<WebsiteUrl>{siteCollectionUrl}/sitepages/home.aspx</WebsiteUrl>
</Configuration>
</Tab>
How to use the group display name placeholder?¶
The {groupDisplayName} placeholder can be used only in combination with the Plan XML element. Basically, it informs Teamwork to create the Planner plan with the same name as the target Team/Group. This is how the configuration looks:
<Planner>
<Plans>
<Plan ResourceId="j9OqsQDfXEm_HyiuBBULxJcAEhBN" Title="{groupDisplayName}">
</Plan>
</Plans>
</Planner>
How to use the placeholders for the Files tab?¶
Files tab supports two placeholders: {siteCollectionurl} and {sourceDocId}. The configuration below won't create the file! It only refers to an existing file inside the Shared Documents library. Check out the Team Extraction documentation to learn how to provision files and folders during Teams creation.
<Tab Name="Issues during TW installation" SortOrderIndex="1" AppId="com.microsoft.teamspace.tab.file.staticviewer.word">
<Configuration>
<EntityId>{sourceDocId}</EntityId>
<ContentUrl>{siteCollectionUrl}/Shared Documents/General/Issues during TW installation using PowerShell script.docx</ContentUrl>
</Configuration>
</Tab>
How to set up the OneNote tab?¶
Valo customers can either create OneNote tab that refers to existing OneNote notebooks inside the Office 365 tenant or they can create OneNote tabs that refer to the default OneNote notebook of an Office 365 Group / Team. This section covers the configuration of OneNote notebook tabs for default notebooks.
The configuration of the OneNote tab contains a high level of complexity, because of the amount of content that must be provided in order to set up this tab. Although there is a set of placeholders available, only a few can be used by the customer. {groupId}, {randomguid}, {notebookid}, {notebookName} and {onenoteweburl} are placeholders that can't be used arbitrarily. These placeholders must be always provided and will be replaced with corresponding value of the target OneNote notebook during runtime. Contrary to this, customers can use the {sectionname} placeholder in the ContentUrl property to define the name of a section that will be created within the OneNote notebook. Here is what the configuration of the section name looks like:
<ContentUrl>https://www.onenote.com/teams/TabContent?entityid={entityId}&subentityid={subEntityId}&auth_upn={upn}&notebookSource=New&notebookSelfUrl=https://www.onenote.com/api/v1.0/myOrganization/groups/{groupId}/notes/notebooks/{notebookId}&oneNoteWebUrl={oneNoteWebUrl}/{sectionName}&notebookName={notebookName}&ui={locale}&tenantId={tid}</ContentUrl>
Note
Instead of entering the {sectionName} placeholder at this point, the customer can also provide a custom value for the section's name.
What are sections there for?¶
Sections enable customers to have different OneNote tabs in different channels within the team that refer to the same default OneNote notebook. Instead of creating new OneNote notebooks for each tab / channel. Along to the section creation, a page will also always be created. This is necessary, otherwise the tab won't open pointing to the correct section. Note that customer can't define the page's name. It will always have the same name as the section. This is what a section looks like in Teams:
Note
Sections are recommended when customers want to have more than one OneNote tab inside the team. For instance, one section for each channel. If the customer only has one OneNote tab in his team, the oneNoteWebUrl configuration must be provided without the {sectionname} placeholder or a default value, otherwise a section will be created.
In the example below, the section name contains a custom value Default Notebook. Here is what the OneNote tab configuration looks like:
<Tab Name="First Notebook" SortOrderIndex="1" AppId="0d820ecd-def2-4297-adad-78056cde7c78">
<Configuration>
<EntityId>{randomGuid}_{notebookId}</EntityId>
<ContentUrl>https://www.onenote.com/teams/TabContent?entityid={entityId}&subentityid={subEntityId}&auth_upn={upn}&notebookSource=New&notebookSelfUrl=https://www.onenote.com/api/v1.0/myOrganization/groups/{groupId}/notes/notebooks/{notebookId}&oneNoteWebUrl={oneNoteWebUrl}/Default Notebook&notebookName={notebookName}&ui={locale}&tenantId={tid}</ContentUrl>
<RemoveUrl>https://www.onenote.com/teams/TabRemove?entityid={entityId}&subentityid={subEntityId}&auth_upn={upn}&notebookSource=New&notebookSelfUrl=https://www.onenote.com/api/v1.0/myOrganization/groups/{groupId}/notes/notebooks/{notebookId}&oneNoteWebUrl={oneNoteWebUrl}&notebookName={notebOokName}&ui={locale}&tenantId={tid}</RemoveUrl>
<WebsiteUrl>https://www.onenote.com/teams/TabRedirect?redirectUrl={oneNoteWebUrl}</WebsiteUrl>
</Configuration>
</Tab>
How to set up the Planner tab?¶
Planner tab supports two placeholders: {planId} and {tenantName}. If the configuration below is provided, Teamwork creates a new Planner plan within the target team:
<Tab Name="Team tasks" SortOrderIndex="1" AppId="com.microsoft.teamspace.tab.planner">
<Configuration>
<EntityId>{planid}</EntityId>
<ContentUrl>https://tasks.office.com/{tenantName}.onmicrosoft.com/Home/PlannerFrame?page=7&planId={planId}&auth_pvr=Orgid&auth_upn={upn}&mkt={locale}&isDefaultResource=True</ContentUrl>
<WebsiteUrl>https://tasks.office.com/{tenantName}.onmicrosoft.com/Home/PlanViews/{planId}</WebsiteUrl>
<RemoveUrl>https://tasks.office.com/{tenantName}.onmicrosoft.com/Home/PlannerFrame?page=13&planId={planId}&auth_pvr=Orgid&auth_upn={upn}&mkt={locale}</RemoveUrl>
</Configuration>
</Tab>
Important
Along with the placeholders for the Planner tab, you can also use two additional query string parameters in Planner plan configuration:
- isDefaultResource: defines a Planner plan as the default one. If there is more than one Planner tab marked as default (isDefaultResource=True), the placeholder replacement for all Planner tabs within the team will fail. If no Planner plan was marked as default, the first Planner tab from the first channel will be created as the default Planner plan.
- useTeamDisplayNameAsPlannerName: If provided useTeamDisplayNameAsPlannerName=true, Teamwork creates the Planner plan with the Team's display name.