Guides
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
- Resco Cloud – Release 15.0 (spring 2022) or later
- Microsoft Dynamics 365 – Release 15.1 (summer 2022) or later
Configuring in Woodford
- Enabling guides
- Edit an app project in Woodford.
- Select Settings > Guides from the Project menu.
- Select Enable Guides.
- 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.
- Select Enable Feedback and set the delay after viewing a guide when a feedback form appears.
- Click Save.
- Optionally, click Add To Home if you want to add the Guides view as the last item on your home screen.
- For manager/admin projects that should have access to the Guides Editor, click Add Editor To Home.
- 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.
- Edit an entity form.
- Click Add List and select "Guides List".
- Optionally, set up a filter, for example,
Status Reason Equals Published
. - 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
- Download the Guides solution file from Resco web.
- Log in to Dynamics as a system administrator.
- Go to the Solutions section of your server settings.
- Click Import and select the downloaded solution file.
- Finish the import wizard.
- Publish all customizations.
- 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.
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.
- Go to the Settings > Customizations and click Customize the System. A new window opens.
- In the left panel, expand Entities and find Guide.
- Expand Guide and click N: N Relationship.
- Click New Many-to-Many Relationship and fill Other Entity information.
- 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.
- Start the Admin Console.
- Select Data > Manage Data.
- Scroll down to the Guide Category entity and open it.
- Click New and enter a category, for example, "Maintenance" or "Repair", and save it.
Microsoft Dynamics
- Start Resco Guides > Categories from the left panel.
- Click New in the tool bar and fill in the information.
- 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:
- On the Resco Cloud landing page, select Guides Editor.
- On Dynamics, start to the Resco Guides app and select Guides.
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.
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
- On the list of guides, click New Guide.
- In the Media library pane, click the plus button and upload images or PDF that you plan to use in the guide.
- 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.
- Enter a title and description for your guide.
- In the Steps Explorer pane, add a new step.
- 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.
- Continue adding steps until the guide is complete. You can reorder steps on the Steps Explorer pane by dragging them to the right location.
- Switch to the Associate tab to edit guide properties.
- 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.
- 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)
On the entity form - related guides (if you added the related guides list to the form)
In a questionnaire (if you added the guide as a static component of the questionnaire)
Tap the guide that interests you to display it.
Harvesting guides from the app
You can also create new draft guides:
- On the home screen, tap Guides.
- Tap the plus button in the top right corner.
- Add a title, description, steps, and photos.
- Save the guide.
- Synchronize the app to make the guide available in the Guides Editor (status = "collected").
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
These features are configured in Woodford:
- Go to the Guides configuration in Woodford.
- To enable feedback, and select Enable Feedback.
- To enable comments on step level, select Allow users to report step issues.
- To enable statistics, and select Enable Usage Logging.
- Save changes and publish the app project.
Rate guides and view feedback
Users can rate the guides and provide feedback to the guide editors.
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.
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.
Usage statistics
The information on how many times a particular guide was opened is available in the guides library:
To see more detailed statistics switch to the Statistics tab of the library.