Deploy the Return to the Workplace solution

This article provides step-by-step instructions to IT administrators for deploying the Return to the Workplace solution.

Estimated time to complete these steps: 60–90 minutes

Prerequisites

  • You should be a global administrator or Microsoft Power Platform administrator to perform the installation.

  • You must be a global administrator and must have a Power BI Pro license to configure and publish reports.

  • Sign in to Power BI and create a workspace to publish the report. More information: Create the new workspaces in Power BI and Give access to your workspace

Step 1: Sign up for Power Apps and create an environment

Sign up for Power Apps if you don't have it already, and purchase an appropriate license. More information: Power Apps pricing

After you've purchased Power Apps, create an environment with a Microsoft Dataverse database.

  1. Sign in to the Power Platform admin center.

  2. Create a Dataverse environment with a database. More information: Create and manage environments

    Important

    If you select a security group for the database while you're creating it, the apps can be shared only with users who are members of the security group.

  3. Create appropriate users, and assign security roles. More information: Create users and assign security roles

After you've created your environment and it is ready, you can access it by using the following URL: https://[myenv].[region].dynamics.com, where [myenv] is the name of your environment and [region] is the deployment region—for example, crm for US. Make a note of this environment URL.

Step 2: Install the package

You can install the Return to the Workplace solution from the Microsoft AppSource marketplace.

Note

If you are a US Government customer, you'll have to install using the deployment package available on GitHub. More information: Appendix: Deploy the app and publish Power BI dashboard (US Government customers only).

  1. Go to AppSource to install the Return to the Workplace solution.

    Installation page.

  2. Select GET IT NOW to install the solution in your environment. You'll be redirected to the actual installation page, where you can select the environment where you want to install it. Installation starts after you select the environment and accept the terms and agreement.

  3. After the app is installed, sign in to Power Apps and select your environment from the upper-right corner. In the left pane, select Apps to see the new apps.

    List of apps.

Tip

Note the URL of your Dataverse environment instance. You'll need it to connect the template app to the data.

Step 3: Configure and publish Power BI dashboards

The Return to the Workplace solution has three Power BI dashboards, one for executive leadership, one for facility managers, and one for health and safety leaders. You can publish the Power BI dashboards by using the template app from AppSource.

Note

If you are a US Government customer, you'll have to publish Power BI dashboards using the deployment package available on GitHub. More information: Appendix: Deploy the app and publish Power BI dashboard (US Government customers only)

Note

If you intend to customize the report, we advise that you use the PBIX files that can be found on GitHub. More information: Appendix: Deploy the app and publish Power BI dashboard (US Government customers only)

Install template app for dashboards

  1. Go to AppSource to install the Return to the Workplace – Location Readiness, Return to the Workplace - Facility Management, and Return to the Workplace - Workplace Care Management dashboards.

  2. Select GET IT NOW to install the solution in your environment.

    GET IT NOW.

    You're directed to an agreement pop-up window. Select Continue if you agree to the terms.

  3. Sign in to Power BI, and then select Install.

    Install.

  4. Enter a name for the workspace, and then select Continue.

    Workspace.

    Note

    Share the workspace with other users who require access. More information: Give access to workspace

Connect to data sources

  1. Select the icon on your Apps page to open the app.

  2. On the splash screen, select Connect.

    Connect.

  3. Enter the URL of the Dataverse environment (for example, https://[myenv].[region].dynamics.com), and then select Next.

    Dataverse environment name.

  4. Determine where the displayed URL is pointing to in the Dataverse environment:

    • If it's pointing to Dataverse, set the Authentication method to OAuth2 and set Privacy level setting for this data source to Organizational. Select Sign in.
    • If it's not pointing to Dataverse, set the Authentication method to Anonymous and set Privacy level setting for this data source to Public. Select Sign in.

    Privacy.

After you've configured your data sources, the report will be populated with your data. Repeat these steps for both dashboards.

Next, we'll configure the data refresh settings for the dataset.

Step 4: Schedule report refresh

  1. On the Datasets tab of your workspace, select Schedule refresh for the dataset of your report.

    Report available in the workspace.

  2. The first time you try to schedule data refresh, the Settings page displays a message that your credentials aren't valid. Under Data source credentials, select Edit credentials to specify your credentials.

    Update your credentials.

  3. On the next screen for the Dataverse data source, do the following:

    • For Authentication method, select Microsoft account.

    • For Privacy level setting for this data source, select Organizational.

    • Select Sign in.

      Configure Dataverse data source credentials.

    You'll be prompted to specify your credentials and sign in. After you've successfully signed in, you'll return to the Settings page.

    For all other data sources, do the following steps:

    • For Authentication method, select Anonymous.

    • For Privacy level setting for this data source, select Public.

    • Select Sign in.

      Configure other data source credentials.

  4. On the Settings page, expand Scheduled refresh, and then specify the schedule you want for refreshing data. Select Apply.

    Schedule refresh data.

    Note

    • There are limits to how many times data can be refreshed. Power BI limits datasets on shared capacity to eight daily refreshes. If the dataset resides on a Power BI Premium capacity node, you can schedule up to 48 refreshes per day in the dataset settings. More information: Data refresh
    • We recommend scheduling data to be refreshed every 30 minutes.
  5. Go back to your workspace, select the Reports tab, and then select the report to open it in a browser.

Step 5: Embed the Power BI report in the model-driven app

The facility manager Power BI dashboard is used in the model-driven app. Because these reports are published in a different location, you need to change the location.

  1. Go to Power Apps, select Solutions in the left pane, and create a new solution. After opening the solution, select Add existing, and then select Table.

  2. From the list of entities, select Facility (msft_facility), under the Forms tab, select Main - Information Form, and then select Add to finish the process.

    Enable Power BI.

  3. Within the newly created solution, select Export. On the right side of your browser, a window pops up. Select Publish, select Run to check whether the solution has any issues or dependencies, and then select Next. With the Version number and Unmanaged option selected, select Export.

  4. In the Download dialog box, select Save, and in the Download complete dialog box, select Open Folder. Right-click to select the compressed .zip file that you downloaded, and then select Extract All. Select a location to extract the files to, and then select Extract. The customizations.xml file is the file that you'll edit.

  5. Open the customizations.xml file, look for the section similar to the XML code specified in this example: /powerapps/maker/model-driven-apps/embed-powerbi-report-in-system-form#embed-without-contextual-filtering

    In this XML file you need to update the PowerBIGroupID, PowerBIReportID, and TileURL according to your Power BI workspace and report. You can find this information by opening the Facility Manager report in Power BI and examining the URL: https://powerbi.com/groups/PowerBIGroupID/reports/PowerBIReportID/ReportSection

    The TileURL can be found within the Power BI report. You can find it at the following destination ... (ellipsis) > Embed > Website or portal.

    Power BI TileURL.

    From the displayed Secure embed code window, capture the content of the link in the first field up to the end of the PowerBIReportID (as shown in the example code).

    See the article Embed Power BI report and verify if the changes that you made to the XML file apply as in the example.

  6. Save the XML file with the modifications you made and zip the files in the folder again. Now you have a .zip file with three files in it, including the updated customizations.xml file.

  7. Sign in to Power Apps, and select Solutions from the left pane. On the command bar, select Import. On the Select Solution Package page, select Browse to locate the compressed (.zip or .cab) file that contains the solution you want to import.

  8. Select Next. On the page that displays information about the solution, select Import.

You might need to wait a few moments while the import is completed. View the results, and then select Close.

Open a facility record in the Facility Safety Management app and you’ll see the embedded report on the General tab.

Step 6: Publish a theme

You can change the look and feel of the app by applying themes to match your company branding.

  1. Open the Facility Safety Management app or the Workplace Care Management app. In the top right, select the gear icon and select Advanced Settings.

    Advanced Settings.

  2. Go to Settings > Customizations.

    Customizations.

  3. Select Themes.

    Select themes.

  4. Select New. Enter the Name and determine which colors you want to use. You can also specify the logo, which is used in the site map.

    Deploy themes.

  5. Select Save, and then Publish.

    Sample theme.

Step 7: Share the canvas app to users

  1. Sign in to Power Apps. Select the Environment from the upper-right corner.

  2. On the left pane, select Apps.

  3. Select the Employee Return to the Workplace app.

    Select app.

  4. Select the app, and then select Share.

    Share app.

  5. Select users from the list of available users or groups with whom you want to share the app.

    Important

    Even if the user has access to the canvas app, you still need to assign the user with the Return to the Workplace - Employee security role.

Step 8: Set the security roles

In the Return to the Workplace solution, the following security roles are defined:

  • Return to the Workplace - Employee: Can check in and look at the details of a location.

  • Return to the Workplace - Facility Manager: Can look at facilities and plan phasing.

  • Return to the Workplace - Leadership: Can view details over the entire system.

  • Return to the Workplace - Health & Safety Leader: Manages employee cases.

  • Return to the Workplace - Verifier: Manages employee vaccination information in addition to having the same privileges as the Facility Manager.

Important

These security roles are indicative. They provide broad access for test and demonstration purpose. Review these roles carefully before moving to a production environment or when importing sensitive data.

To assign security roles

  1. Open the Facility Safety Management app or the Workplace Care Management app. In the top right, select the gear icon and then select Advanced Settings.

    Customizations Advance Settings.

  2. Go to Settings > Security.

    Security.

  3. Select Users, and then select the user to whom you want to give permissions.

    Select user.

  4. Select the user, and then select Manage Roles. After assigning the roles, select OK.

    Select roles

    Note

    When you want to assign security roles in bulk, you can use teams privileges. Teams privileges, which are based on Azure Active Directory security groups or Office 365 groups, can assign security roles based on the organization. More information: Manage teams. When applying teams privileges based on Azure Active Directory security groups or Office 365 groups, you need to change the user and team privileges in the security roles to Direct User/Basic access level and Team privileges. More information: Security roles

    Important

    The Return to the Workplace - Employee role has all the privileges required to access and use the employee app properly. When editing the role or when using a custom role, ensure that all the correct privileges are set up properly for the employee app to run.

Step 9: Assign users to field security profiles

When using the vaccination attestation feature that is introduced in version 1.5 of the solution, ensure that the users are assigned the proper field security profiles.

  1. In Power Apps, navigate to RTX Common Solution.

  2. Search for Return to the Workplace - Verifier access to vaccination related fields field security profile and select it from the solution.

  3. Under membership, select Users and select Add.

  4. Select the users that require read and edit access to the vaccination attestation solution settings fields, and select Add. Users that have the Return to the Workplace - Verifier role should be added under this profile.

  5. Search for Return to the Workplace - Employee access to vaccination related fields field security profile and select it from the solution.

  6. Under membership, select Users and select Add.

  7. Select the users that require read access to the vaccination attestation solution settings fields, and select Add. Users that have the Return to the Workplace - Employee role should be added under this profile for the employee app to function properly.

  8. Select Save and Close.

Tip

Instead of adding each user, create one or more teams that include all users that you want to grant read access.

Step 10: Enable flows

  1. Sign in to Power Apps. Select Environment from the upper-right corner.

  2. On the left pane, select Solutions.

  3. Select RTX Common Solution from the list of solutions (Return to the Workplace Portal for portal flows).

  4. Select the Share Guest Registration - Email solution and then select Save as. Connect the flow with the Dataverse (current environment) and Office 365 Outlook connector and then select Continue. Enter a name for the flow and select Save.

  5. Select My Flows on the left. After selecting Share Guest Registration - Email, select Turn on. Validate whether the flow is turned on to ensure that it can be used. Additionally, the flow should be shared with others to prevent issues with people who aren't allowed to enter it.

    Note

    The connection used for Office 365 Outlook is the email address used to send emails to guests. Use a service account for sending generic emails or use a shared mailbox.

  6. Repeat steps 4 and 5 for the following flows:

    • Notification - Send as email
    • Share Guest attestation - email
    • Share Guest attestation - email with portal link (portal only)
    • Contact - Create portal invitation (portal only)

    Note

    For the Contact - Create portal invitation (portal only) flow, a valid portal URL must be set in the email body of the send an email action step in the flow for the link to properly work. Replace 'portalURL' with the URL of the portal app of the environment that you are working on. You may consider creating an environment variable if you have multiple environments in your implementation.

Appendix: Deploy the Return to the Workplace portal

This section provides information on how to install the Return to the Workplace portal.

Important

Return to the Workplace portal is introduced in version 1.3. You need to update the existing Return to the Workplace solution in order to use the portal.

Step 1: Create a new portal

  1. Go to Power Apps. Select the environment where you want to install the portal.

  2. Select + Create from the left pane, and then select Portal from blank.

    Create portal.

  3. Enter appropriate values, and then select Create.

    • Name: The name of the portal that is displayed in Power Apps Studio.
    • Address: The URL that is created for the portal. Make sure to save this information for further configuration steps.
    • Language: The language of the portal.

    Portal details.

  4. You'll see a pop-up window that opens on the upper right displaying that the portal provisioning has started. Select Apps from the left pane, and you'll see the name of your portal from the list of available apps. As soon as provisioning completes, the link will be active.

    Portal provisioning notice.

Step 2: Install the package

You can install the Return to the Workplace Portal from AppSource.

Note

If you are a US Government customer, you'll have to install using the deployment package available on GitHub. More information: Appendix: Deploy the app and publish Power BI dashboard (US Government customers only).

  1. Go to AppSource to install the Return to the Workplace Portal.

    Portal page.

  2. Select GET IT NOW to install the solution in your environment. You'll be redirected to the actual installation page, where you can select the environment where you want to install it. Installation starts after you select the environment and accept the terms and agreement.

  3. After the app is installed, sign in to Power Apps and select your environment from the upper-right corner. In the left pane, select Solutions to see the new solution that is installed.

    List of solutions.

Step 3: Restart the portal

The deployment package also contains the actual portal data. To make sure that the portal is set up correctly, follow these steps:

  1. Go to Power Apps. Select Apps from the left navigation pane, and then select Portal Management app.

  2. Select Website, select Return to the Workplace website, and then change the URL to the URL that you created earlier.

  3. Select Save and Close, and then deactivate the Basic website. If you do not see a website named Basic here, proceed to the next step.

  4. Select Website Bindings. Validate if there is a binding for the URL indicated for the Return to the Workplace website.

  5. Go to Power Apps. Select Apps from the left pane. On the Portal, select ..., and then select Settings.

  6. In the Portal Settings pane on the right, select Administration to open the portal administration.

    Portal administration.

  7. Select Portal Actions, and then select Restart.

    Portal restart.

  8. Go to Power Apps. Select the portal and select Browse.

Appendix: Deploy the app and publish Power BI dashboard (US Government customers only)

Note

There are notable differences between the commercially available service and the service for Dynamics 365 US Government. Review these differences thoroughly before deciding in which environment to implement. More details: Dynamics 365 US Government - Feature availability

This section provides information for US Government customers about how to install the app and publish the Power BI dashboard using the deployment package.

Step 1: Download the latest deployment package

Download the latest deployment package (.zip) from https://aka.ms/rtw-solution. Before extracting the .zip file, you must unblock it.

To unblock the .zip file

  1. Right-click the .zip file, and then select Properties.

  2. In the Properties dialog box, select the Unblock check box, select Apply, and then select OK.

    Solution package properties.

After extracting the .zip file, you'll see the following in the extracted folder.

Folder Description
Package Contains the Package Deployer tool and the package that you'll import later to set up the solution in your environment.
Power BI Contains the Power BI Reports that will be used to configure reporting. More information: Step 3: Configure and publish Power BI dashboards

Step 2: Install the app by using the deployment package

  1. Go to the location where you extracted the deployment package (.zip file). Open the Package folder, and then run PackageDeployer.exe.

  2. On the next screen, select Continue.

  3. You'll be prompted to connect to your environment. Select Office 365 as the Deployment Type, select Show Advanced, and then type your credentials to connect to your environment.

    Deploy package.

  4. Select Login to continue.

  5. If you have access to more than one Dataverse environment, the next screen will prompt you to select the environment where you want to install the package. Select an environment, and then select Login.

    Select an environment.

  6. On the next screen, select Next.

  7. The next screen displays the environment name where the package will be installed. Review the information, and then select Next.

  8. The next screen validates whether all dependencies are available in your environment. Select Next.

  9. The next screen displays the installation status of the package. It might take a while for the package installation to complete.

  10. After the installation is complete, select Next.

  11. On the next screen, select Finish to complete and close the setup.

  12. After the app is installed, sign in to Power Apps and select your environment from the upper-right corner. In the left pane, select Apps to see the new apps.

    List of apps.

Tip

After installing the Return to the Workplace solution, note the URL of your Dataverse environment instance. You'll need it to connect the template app to the data.

Step 3: Publish by using the .pbit file in the deployment package

This section provides information about how GCC customers can use the Return to the Workplace - Location Readiness and Return to the Workplace - Facility Manager dashboard .pbit files available in the deployment package to publish the dashboards.

Prerequisites for installing Power BI

Install Power BI Desktop from Microsoft Store: Power BI Desktop

Note

If you installed Power BI Desktop by downloading it directly from the Download Center page in the past, remove it and then download it from Microsoft Store. The Microsoft Store version will be updated automatically as new releases become available. If you can't install from Microsoft Store, install the latest non–Microsoft Store version from the Download Center page.

Process

Follow the steps below for each .pbit file.

  1. Open Power BI Desktop, and sign in using your account.

  2. Go to the location where you extracted the deployment package (.zip file). In the Power BI Template folder, you'll find the appropriate .pbit file.

  3. Open the .pbit file in Power BI Desktop. You'll be prompted to enter the following value: Dataverse Environment. Enter the URL of the Dataverse environment (for example, https://[myenv].crm.dynamics.com, where [myenv] is the name of your environment). Select Load.

    Configure the Power BI dashboard.

  4. You'll be prompted to enter the credentials to connect to your Dataverse environment. Select Organizational account > Sign in to specify your Dataverse credentials.

    Connect to your Dataverse environment.

  5. After signing in, select Connect to connect to your data in Dataverse.

  6. After connecting to your Dataverse environment, you'll see a series of pop-up windows to configure access to data sources. These access-level and privacy-level settings should be configured to connect to the public data sources for the COVID-19 report data. Complete access level and privacy selections as shown in the following screenshots.

    Access Web Content level.

    Grant anonymous access to the Web Content.

    Anonymous access to the Web Content.

    Privacy level.

    Anonymous privacy select.

    Privacy level blob storage.

    After you've configured the access and privacy levels for COVID-19 public data, you must set the privacy level for Dataverse data to Organizational.

    Access Web Content level CDS.

  7. After a connection is successfully made, the Power BI report will be displayed. You'll be prompted to apply pending changes to your query. Select Apply changes.

    Note

    The report is blank because you haven't yet added data in the system.

  8. Select Publish. When prompted to save your changes, select Save.

    Save the Power BI workspace.

  9. You'll be prompted to save the file along with your Dataverse environment information. Enter a name, and save it on your computer. The file name you enter is displayed in your Power BI website.

  10. After saving the file, you'll be prompted to publish the report. In the Publish to Power BI page, select the workspace where you want to publish, and then select Select.

    Publish to Power BI.

    The report becomes available in your workspace.

  11. For the facility manager dashboard, the URL will be in the following format: https://app.powerbi.com/groups/3d6db5d0-22c7-4674-b957-0605c021511d/reports/bf9cd5a1-c176-4786-9c4e-684a79678575/ReportSection?redirectedFromSignup=1
    Copy the Power BI report URL to a text file, because you'll need to embed it in the model-driven app.

  12. Follow steps 1 through 11 for each dashboard.

Next, you must configure the data refresh settings for the dataset. More information: Step 4: Schedule report refresh

Service URLs for US Government customers

There is a different set of URLs to access Power Apps US Government environments and Power BI US Government tenants. The commercial version of the service URLs is used throughout the article. If you have a US Government organization, use the respective US Government URL for your deployment:

Commercial version URL US Government version URL
https://make.powerapps.com https://make.gov.powerapps.us (GCC)

https://make.high.powerapps.us (GCC High)
https://admin.powerplatform.microsoft.com https://gcc.admin.powerplatform.microsoft.us (GCC)

https://high.admin.powerplatform.microsoft.us (GCC High)
https://app.powerbi.com/ https://app.powerbigov.us (GCC)

https://app.high.powerbigov.us (GCC High)

For detailed information about the US Government plans for Power Apps and Power BI, see:

Feedback about the solution

To provide feedback about the Return to the Workplace solution, visit aka.ms/rtw-community.

Next step

Configure the Return to the Workplace solution