Guides

From Resco's Wiki
Jump to navigation Jump to search

Guides are an optional component of the resco.ServicePlatform that allows you to create step-by-step instructions that your technicians in the field can follow to solve a problem.

Features

  • Guides: Step-by-step instructions that combine text content, images, videos, and PDF attachments that are related to a particular record (for example, a piece of machinery) that users of Resco mobile apps can display in their apps.
  • Guides editor: A web application accessible from the Resco Cloud landing page and Dynamics which allows you to create, modify, and publish guides.
  • Feedback: App users can rate the guides and provide feedback to the guide editors in the back office.
  • Guides harvesting: App users can quickly collect simple guides from the field (take/upload photos and add comments) if they identify missing processes. Guide editors in the back office can then standardize the guides, add proper language and associations, and then publish them to make the information available to all users in the field (knowledge decentralization from experts to the entire organization).

Prerequisites

Configuring in Woodford

Enabling guides
  1. Edit an app project in Woodford.
  2. Select Settings > Guides from the Project menu.
    1. Select Enable Guides.
    2. Select the entities for which you want to define guides. For example, if you want guides for your products, select the Product entity. You can add multiple.
      Notes:
      • Once guides are enabled for an entity, they cannot be disabled.
      • On Dynamics, you need to create an N:N entity before you can enable guides for an entity.
    3. Select Enable Feedback and set the delay after viewing a guide when a feedback form appears.
  3. Click Save.
  4. Optionally, click Add To Home if you want to add the Guides view as the last item on your home screen.
  5. For manager/admin projects that should have access to the Guides Editor, click Add Editor To Home.
    Enable Guide.png
Adding guides to entity forms
The home screen item lists all guides. Alternatively (or in addition) to the home screen button, you can add a list of related guides to an entity form. Users that display a record can then see the list of relevant guides.
  1. Edit an entity form.
  2. Click Add List and select "Guides List".
  3. Optionally, set up a filter, for example, Status Reason Equals Published.
  4. Save all changes.

Setting up Dynamics

Before you can use Guides on Dynamics, you have to:

  • Install the Guides solution to your Dynamics
  • Create N:N entities between the Guide entity and entities that need access to guides.

Installing the Guides solution

  1. Download the Guides solution file from Resco web.
  2. Log in to Dynamics as a system administrator.
  3. Go to the Solutions section of your server settings.
  4. Click Import and select the downloaded solution file.
  5. Finish the import wizard.
  6. Publish all customizations.
  7. Reload the Dynamics webpage (often, this can be accomplished by pressing F5).

Once installed, you can find Resco Guides in the list of published apps.

Resco suite app.png

Defining N:N relationships

On the Dynamics backend, before you can associate a guide with another entity in Woodford, you must create an N:N relationship on Dynamics.

  1. Go to the Settings > Customizations and click Customize the System. A new window opens.
  2. In the left panel, expand Entities and find Guide.
  3. Expand Guide and click N: N Relationship.
    N N relationship.png
  4. Click New Many-to-Many Relationship and fill Other Entity information.
  5. Click Save & Close.

Adding guide categories

Resco Cloud

Guides that you create can belong to a category. To keep your guides organized, create guide categories that are suitable for your organization.

  1. Start the Admin Console.
  2. Select Data > Manage Data.
  3. Scroll down to the Guide Category entity and open it.
  4. Click New and enter a category, for example, "Maintenance" or "Repair", and save it.
    Guide category.png

Microsoft Dynamics

  1. Start Resco Guides > Categories from the left panel.
  2. Click New in the tool bar and fill in the information.
    Categories.png
  3. Click Save & Close.

Guides editor

Guides editor or library is web application for creating, updating, and publishing guides. To start the editor, log in to your organization:

The editor screen offers several functions that should make your work a pleasant experience:

  • Filters in the left pane allow to you quickly locate what you need. You can filter guides according to their category, status, associations, authors and tags.
  • Sort by: Select how should the displayed guides be ordered in the top row.
  • View as: Switch between grid and list view.
    Working with guides.png

To work with a particular guide, do one of the following:

  • select it and use the top row buttons.
  • hover over a guide and use the buttons that appear.

The following functions are available:

  • Edit
  • Duplicate (clone) (not supported on Dynamics)
  • Archive
  • Import
  • Export
  • Share: Available for published guides. Displays a QR code that you can scan on your phone to open the guide. Also displays a link that you can use in the Questionnaire Designer to link the guide from a questionnaire.
  • Preview
  • View feedback
  • Publish or unpublish

Manage guides in bulk

You can check multiple guides (up to 10) to select them. The following bulk actions are available:

  • Export
  • Archive
  • Publish and unpublish (requires that all selected guides are in a suitable state)

I don't see guides editor

If you are using a resco.FieldService or resco.Inspections organization with a custom manager's landing page, there's no Guides Editor link on it by default. You can add it in the Guides configuration in Woodford: click Add Editor To Home.

Creating a new guide

  1. On the list of guides, click New Guide.
    Houston blank library.png
  2. In the Media library pane, click the plus button and upload images or PDF that you plan to use in the guide.
  3. Drag an image from the Media library pane to the central pane. You can then click Edit to crop the image or annotate it with text, arrows, or similar effects. Remember to save changes.
    Houston image editing.png
  4. Enter a title and description for your guide.
  5. In the Steps Explorer pane, add a new step.
  6. Just like for the cover page, drag an image from the library and enter a title and a description for the step. You can add more descriptive paragraphs, tips, or warnings as needed.
    Houston guide editing.png
  7. Continue adding steps until the guide is complete. You can reorder steps on the Steps Explorer pane by dragging them to the right location.
  8. Switch to the Associate tab to edit guide properties.
    Houston guide properties.png
  9. Save all changes and publish your new guide.

Using the media library

The media library within the guide editor is the place where you store files that are or can be used in a guide. The following media types are supported:

Images
  • You can edit the images directly in the media library, resizing them, cropping them, adding text or arrows, etc.
  • You can also set up how to scale images.
    Image display options.png
PDF documents
Videos
  • When harvesting guides in the field, users can record video on device (limited duration)
  • In the guide editor, users can embed YouTube videos and/or include local videos (limited size)
Note Videos recorded on some Android devices are by default saved in the webm format. Unfortunately, iOS devices often don't support this format. As a workaround, a guides administrator can download the video from the guide using the guide editor, convert it to mp4 format using a third-party tool, then upload it back to the guide.
Gallery
  • Each guide step can contain multiple images/videos/PDF documents in a gallery. Up to 5 documents can be used. Multiple documents are not available on the cover page.

Media are saved as notes. Databases often have limits on how large a note attachment can be. The maximum allowed size in the library is 10 MB, but your backend might have a lower limit. Your backend admin might be able to increase the limit.

Using guides in the app

In the app, you can find guides in three places:

On the home screen - all guides (if you used the Add To Home button in Guides configuration)

Guides on the home screen.png

On the entity form - related guides (if you added the related guides list to the form)

Guides on a form.png

In a questionnaire (if you added the guide as a static component of the questionnaire)

Guides from inspections.png

Tap the guide that interests you to display it.

Houston9.png Houston10.png

Harvesting guides from the app

You can also create new draft guides:

  1. On the home screen, tap Guides.
  2. Tap the plus button in the top right corner.
  3. Add a title, description, steps, and photos.
  4. Save the guide.
  5. Synchronize the app to make the guide available in the Guides Editor (status = "collected").
    Creating a new guide.png

Leave comments, provide feedback, gather usage data

Guides offer multiple ways to improve documentation.

  • Users can leave comments for each question.
  • Users can provide feedback after reading a guide.
  • Users are tracked when they open and read guides.
  • Editors can display and process comments in the library.
  • Editors can check guide feedback in the library.
  • Editors can switch to the statistics page of the library to see collected usage data.

Enable feedback and usage logging

Guide feedback and logging.png

These features are configured in Woodford:

  1. Go to the Guides configuration in Woodford.
  2. To enable feedback, and select Enable Feedback.
  3. To enable comments on step level, select Allow users to report step issues.
  4. To enable statistics, and select Enable Usage Logging.
  5. Save changes and publish the app project.

Rate guides and view feedback

Users can rate the guides and provide feedback to the guide editors.

Guide feedback.png

The option to leave feedback is displayed after closing the guide preview. Users must spend at least 10 seconds in the guide to leave feedback. The minimum time spent viewing the guide can be configured in the Guides configuration (Time) or in the project configuration (Guide Feedback Timeout).

Editors in the back office can then view user feedback in the Guide Editor and use it to improve the guides.

Guideeditor feedback.png

Leave comments on questions

Users can report issues for individual steps when viewing a guide.

Guide editors see a red flag on their guide. They review the issues, perform changes in the guide, and mark issues complete.

Report issue for a particular step.png Red flag means open issues.png Accept or decline comments in the guide editor.png

Usage statistics

The information on how many times a particular guide was opened is available in the guides library:

Guides statistics.png

To see more detailed statistics switch to the Statistics tab of the library.

See also

Retrieved from "https://docs.resco.net/mediawiki/index.php?title=Guides&oldid=8584"