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 Microsoft 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 Microsoft 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 then 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 (a US Government customer) 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 the other 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 a 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. To embed the dashboard into the app, follow the instructions in Embed a Power BI report in a model-driven app main form.

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 dashboard. In the upper-right corner, 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 a name for the theme and determine which colors you want to use. You can also specify the logo, which is used in the site map.

    Create a theme.

  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 (Preview): Manages worker vaccination and test attestation 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 purposes. 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.

    Select user.

  4. Select the user to whom you want to give permissions, 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 Microsoft 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 and test attestation (Preview) features, 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 then 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 and test attestation (Preview) solution settings fields, and then select Add. Users that have the Return to the Workplace - Verifier role (Preview) should be added under this profile.

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

  6. Under membership, select Users and select Add.

  7. Select the users that require read access to the vaccination and test attestation (Preview) solution settings fields, and then 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: Create connections and update connection references

The following connections are needed to enable the Microsoft Return to the Workplace cloud flows:

  • Microsoft Dataverse: Used for connecting to Microsoft Dataverse data.
  • Office 365 Outlook: Used for sending emails. You might need multiple copies of this connector to scale the send email flows.

After you've created these connections, you need to update the connection references in Microsoft Return to the Workplace to point to these connections.

To create connections:

  1. Sign in to Power Apps and select the environment where you deployed the solution.

  2. In the left pane, select Data > Connections, and then select New connection.

  3. Search for Microsoft Dataverse and select it from the list by selecting the plus sign (+).

    New connection 1.

  4. On the next screen, select Create, and then type or select the credentials to connect to your Microsoft Dataverse environment. After successful authentication, your connection will be added in the connection list.

  5. Select New connection to add another connection.

  6. Search for Office 365 Outlook and select it from the list by selecting the plus sign (+).

  7. On the next screen, select Create, and then type or select the credentials to connect to your Microsoft 365 instance. After successful authentication, your connection will be added in the connection list.

Next, you need to update the connection references used by Microsoft Return to the Workplace to point to these connections.

  1. In Power Apps, select Solutions in the left pane, create or update an existing solution to add the following existing connection references to the solution:

    • Common Data Service (current environment)
    • Common Data Service (current environment)
    • Office 365 Outlook
    • RTW Dataverse Connection
    • [RTW Portal] Office 365 Outlook
    • [RTW Portal] Common Data Service (current environment)

    Connection references to be added to solution.

  2. Select Common Data Service (current environment), and then select Edit on the toolbar.

  3. In the edit screen, make sure that you select the Microsoft Dataverse connection that you created earlier in the Connection list, and then select Save.

    Select connection.

  4. Repeat the same for the following connection references:

    • Common Data Service (current environment)
    • RTW Dataverse Connection
    • RTW Portal Common Data Service (current environment)
  5. Edit Office 365 Outlook, select the Office 365 Outlook connection that you created earlier as the connection, and save.

  6. Repeat the same for the following connection reference:

    • RTW Portal Office 365 Outlook

Your Cloud flows can now use your connections.

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.

Step 11: Enable flows

Prior to enabling the flows, ensure that the connection references described in Step 10 are updated.

  1. Sign in to Power Apps. Select the Environment where you deployed your solution from the upper-right corner of the screen.

  2. On the left pane, select Solutions.

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

  4. Select the Send Email (Share guest attestation/registration) flow and select Turn on. Make sure to turn this flow first as other flows call this child flow.

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

    • Share Guest Registration - email
    • Share Guest Attestation - email
    • Contact - Create portal invitation (portal solution)
    • Notification - Send as email (if utilized 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 to show that 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 in AppSource

  2. Select GET IT NOW to install the portal 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: Validate website bindings and 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 the Return to the Workplace website, and then change the Primary domain name to the URL that you created in Step 1-3 earlier. (For example, contoso.powerappsportal.com.)

  3. Select Save and Close.

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

  5. In the Portal settings pane on the right, select Administration to open the portal administration.

    Portal administration

  6. Navigate to Portal Details > Update Portal Bindings. Validate the website record selected is the Return to the Workplace website. If not, update it to Return to the Workplace and click on the Update button.

    Portal bindings.

  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 government community cloud (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