View source for Guides on Power Platform

{{Guides TOC}}
Traditionally, end users of Resco Guides consume guides in [[Resco mobile apps]]. Since [[Releases/Summer 2023|Release 16.1 (summer 2023)]], guides can also be used in various components of the Microsoft Power Platform: Power Apps and Power Pages.

As your backend server, use Microsoft Dataverse - with or without extra Dynamics features. In this configuration, you also don't need to install Woodford.

== Prerequisites ==

Here's a high-level overview of steps to prepare your environment:
# Go to https://make.powerapps.com/.
# Install the Resco Guides managed solution. ([[Guides#Installing_the_guides_solution|How?]]) Requires release 16.1 or later.
# Optionally, define some N:N relationships between the Guides table and other tables (if you want to have guides related to other records). ([[Guides#Defining_N:N_relationships|How?]])
# Optionally, define some guide categories. ([[Guides#Dataverse|How?]])
# Use [[Guides library]] to create and publish at least one guide.

== Guide views and Guide Player ==

Once you install Resco Guides in your environment, you can use our predefined views for the Guide table, as well as the Guide Player, which is a web resource that replaces the default form. You can use the views and the player on the Power Platform.

== Power Apps ==

The Guide table can be easily integrated into your Power Apps with only a few clicks. Treat Guide just like a standard Dataverse table, with the Guide Player replacing the standard table form.

=== Create a model-driven app ===

# Go to https://make.powerapps.com/ (Power Apps home).
# Ensure you are in the environment with the Resco Guides solution installed.
# Optionally, go to (or create) a solution to keep your work organized. (Solutions are particularly useful if you want to transfer all your customizations to a different environment.) 
# Edit a model-driven app, or create a new one.
# Click '''Add page''' and select '''Dataverse table''', then click '''Next'''.
# Select the "Guide" table and click '''Add'''.
# Save all changes, publish the app, then click '''Play''' to run it.

[[File:Designing-power-app-with-guides.png|alt=Designing power app with guides|600px]]

{{Note|If you see the standard form for guides, rather than the Guide Player, you are probably not using the latest Resco Guides solution.}} 

=== Configuring Power Apps ===

If you know Guides from Resco mobile apps, you are probably aware of the Guides configuration page in Woodford. Guides on Power Apps are blissfully ignorant of any settings in Woodford. Fortunately, similar settings are available on Power Platform.
# Go to https://make.powerapps.com/ (Power Apps home).
# Ensure you are in the environment with the Resco Guides solution installed.
# Select '''Solutions''' from the menu, then select the '''Default Solution'''.
# Select '''Settings > Setting environment values''' from the list of objects.
# Click '''New > More > Setting > Setting environment value''' and find one of the Guides settings in the list (you can search for "rh").
# Select the value and click '''Add'''.
# In the sidebar, click '''+ New environment value''', select a new value, and click '''Save'''.

[[File:Configuring-guides-on-power-platform.png|alt= Configuring guides on power platform step 5|600px]]

Use '''Enable step feedback''' to allow users to comment on any guide step (default: no).

Use '''Enable usage logging''' to record statistical information about reading guides in the app (default: yes). This information is then made available to guide editors.

Use '''Guide feedback timeout''' to set how many seconds users must read a guide before they can rate it (default: 10 seconds).

=== Offline mode ===

Before enabling offline mode for an app, you must create an offline profile, listing the tables necessary in the offline mode.

# Go to https://admin.powerplatform.microsoft.com/ and select '''Environments''' from the menu. 
# Click the ellipsis button next to your environment to display all environment actions and select '''Settings'''.
# Expand '''Users + permissions''' and click '''Mobile Configuration'''.
# Click '''New profile''', name it, then click '''Create'''.<br>[[File:Create-offline-profile-in-power-platform-admin.png|alt=Guides: Offline mode: Create offline profile in power platform-admin|600px]]
# Click the newly created profile.
# Click '''Add table''', select "Guide", then click '''Next'''. Select '''All rows''' (or create a custom filter), then click '''Save'''.<br>[[File:Add-tables-to-offline-profile.png|alt=Guides: Offline mode: Add tables to offline profile|600px]]
# Add four more tables to the offline profile. Only related rows are necessary. Find the suggested relations in the table below.<br><table class="wikitable"><tr><th>Table</th><th>Relation</th></tr><tr><td>Guide Category</td><td>Guide table, column name Category</td></tr><tr><td>Guide Feedback</td><td>Guide table, column name Regarding</td></tr><tr><td>Note</td><td>Guide table, column name Regarding</td></tr><tr><td>User</td><td>Guide table, column name Created By</td></tr></table>
# Publish the offline profile.

With the offline profile ready, follow the procedure for enabling an app for offline use described in the [https://learn.microsoft.com/en-us/power-apps/mobile/setup-mobile-offline#enable-your-app-for-offline-use-preview Power Apps documentation]. A quick overview of the steps is listed below for your convenience:
# Edit your app in Power Apps.
# Click '''Settings'''.
# On the '''Features''' tab, enable '''Offline setup from the app designer'''.
# On the '''General''' tab, enable '''Can be used offline''' and select the '''Mobile offline profile'''.
# Save all changes and publish the app.

You're now ready to test your app on your phone.
# Download the Power Apps app from the store.
# Sign in with your user name.
# Find the published app and start it. The app downloads data for the offline mode.
# Once the download is complete, you are ready to go offline. Good luck.

== Power Pages ==

Microsoft Power Pages is a platform for creating, hosting, and managing websites. The following example explains how to include Guide Player in such a webpage.

=== Create a Power Page ===

# Go to https://make.powerpages.microsoft.com/ (Power Pages design studio).
# Ensure you are in the environment with Resco Guides solution installed.
# Create a new power page or edit an existing one.
# Go to '''Pages''' and select the page where you want to add the Guide Player.
# Insert an iframe to the page, then switch to '''Edit code''' and use the following code to define the iframe content:<br><code><nowiki><iframe frameborder="0" src="/_webresource/rh_rescoplayer/index.html?id=6b9021ba-6495-4207-9e9c-9d6a4aa8219b&data=endpoint%3DPortalWebApi"></iframe></nowiki></code>
# Save the modified code, return to Power Page design studio, and click '''Sync''' to retrieve the latest code.

{{Note|The id in the iframe represents the id of the guide. Replace the id with a guide id that exists in your environment.}}

=== Set up table permissions ===

While editing your site, go to '''Security > Table permissions''' and add permissions for 7 tables:

* Six tables required to run the Guide Player (rh_guide, rh_guidecategory, rh_tag, rh_feedback, systemuser, and annotation).
* Web Resource table.

Read privileges should be sufficient. For the sake of demonstration, you can grant it to all users/roles. In production, you should probably evaluate the permissions more carefully.

[[File:Grant-table-permissions-for-power-page.png|alt=Grant table permissions for power page|600px]]

=== Set up web API access ===

# Return to the Power Pages home page (list of your sites).
# On the tile of your site, click the ellipsis button and select '''Power Pages Management''' (originally called '''Portal management''').
# Select '''Website > Site Settings''' from the menu.
# For each of the six Guide Player tables (rh_guide, rh_guidecategory, rh_tag, rh_feedback, systemuser, and annotation), create two new site settings:
#* Enable the web API for this table.
#* Set up fields that should be available via web API (or use asterisk for all).

[[File:Guides-in-power-pages-portal-management-site-settings.png|alt=Guides: power pages portal management site settings|600px]]

=== Preview the web ===

If everything works as planned, your Power Page site now includes a guide.

{{Note|During the design phase, your Power Page may say "Access Denied" instead of showing a guide. Preview the webpage to see the guides.}}

[[File:Sample-power-page-with-guides.png|alt=Sample power- page with guides|600px]]

You can change the displayed guide in the iframe with simple Javascript. All you need to do is change the iframe src="" with the URL containing a different guide id. E.g., change to source on button click. 

<syntaxhighlight lang="js">
<button onclick="changeIframeSource()">Change iframe source</button> 
  <script> 
    function changeIframeSource() { 
      var iframe = document.getElementById("guidePlayerResource"); 
      iframe.src = "/_webresource/rh_rescoplayer/index.html?id=e193fe3e-937f-4abe-9512-0a067f8009f1&data=endpoint%3DPortalWebApi"; 
    } 
  </script></syntaxhighlight>

=== (Optional) Allow users to report issues ===

If you want to allow your readers to report issues in your guides, you need to perform a few extra steps:
# Modify the iframe URL. Add <code>%26enableStepFeedback%3Dtrue</code> at the very end. For example:<br><code>iframe.src = "/_webresource/rh_rescoplayer/index.html?id=e193fe3e-937f-4abe-9512-0a067f8009f1&data=endpoint%3DPortalWebApi%26enableStepFeedback%3Dtrue";</code>
# Grant your users the '''Append''' permission for the table '''rh_guide'''.
# Grant your users the '''Append To''' and '''Create''' permissions for the table '''rh_feedback'''.

Users can then use the '''Report issue''' button to add comments. See [[Guides_feedback_and_statistics#Leave_comments_on_questions|Guides feedback and statistics]] for more information.

[[File:Report-issue-in-a-guide-step.png|alt=Report issue in a guide step|600px]]









{{Feedback}}
[[Category:Guides]]