Customising step instructions in UPK

Whenever you record an action within a UPK capture, it uses a template to determine how to describe each action you complete. You can customise this template text so that steps are presented in a language and format that best fits your requirements. Your customisations are then automatically applied across all your published outputs: simulations and documentation.

Note this topic explains how to change the standard text for all steps, and all captures. If you just want to make a one-off edit to the text in a single step you can make your life easier by just editing it directly. Just click the Insert template text as user text button in the frame properties and edit away.

How template files are organised and applied

UPK provides separate template files for each language. To find the current files for your required language open your library and navigate to System > Templates. The template files are organised in separate folders for each language:


For most of the languages (although from here on we’ll focus on English), UPK comes with two default templates: Standard and Microsoft. UPK by default uses Standard – English.

I’ve been unable to find any documentation that quantifies the differences between the two; however a quick side-by-side review would suggest Microsoft are more a fan of “Click [it]”, whereas the UPK standard template has an occasional preference towards “Press [it]”.

The default template selected for each new capture is recorded in the UPK options (Tools > Options), under General. You can modify this at any time to have a different template selected for all new captures.

Changing this setting does not affect existing captures.

If you want to apply, or change the template for an existing capture you need to change it within the Properties pane (choose View > Properties from the menu), also under General.

Note there’s no way to quickly/easily review all your processes and confirm which template has been selected for each. You need to highlight each in turn and view the setting within the Properties pane.

How to customise template text

It’s a simple three step procedure to customise the template text for your UPK efforts:

  1. create your own template file
  2. edit the template text to match your requirements, then
  3. apply the template to your capture(s).

(1) Create your own template file

Instead of editing one of the existing templates it is recommended that you copy the provided one (choose the Standard or Microsoft as base depending on your preference) and create/save your own template file:

  • Open the appropriate template folder (Library > System > Templates > [language])
  • Right-click on the existing template and choose Copy
  • Right-click anywhere in the folder and choose Paste

Interestingly UPK will let you paste your template copy into the folder with the same name as the original. Use the file date to determine which is the copy, right-click on it and choose Rename, then give it a name that represents your project or organisation.

Note: Other than keeping your edits separate (and allowing you to rollback quickly if getting into trouble), another reason to create your own template file is that anytime you upgrade UPK it will overwrite the standard templates. You could therefore lose all your edits if not maintaining a copy outside of UPK.

(2) Edit the template text

Once you have your own template to edit you can start to make the text changes you require. The good news is UPK is shipped with a template editor to make this easier. The bad news is the editor is not really that integrated with UPK itself, hence using it is a bit convoluted. This is the best process I could determine.

Double-click your template in UPK to open it. It will open in a new UPK tab, showing it contains three separate files; we’re only interested in the middle one: template.xml.

  1. Drag template.xml from the UPK tab to your desktop (or anywhere on your computer
    where you can save it and edit it).
  2. Open the UPK Template Editor: Start > Programs > User Productivity Kit > Template Editor
  3. In the editor, select File > Open from the menu and choose the template.xml file you saved earlier.

UPK template editor is not very object-oriented (so you cannot select your template file and choose Open With). You always need to open the editor first, and then choose File > Open to get to your content.

You get a bit closer in Windows 7 than in XP, as in the former you can double-click on template.xml inside UPK and the editor will open. However it still did not open the file to be edited, so you still have to do as above and first copy it out of UPK and to your computer.

Once you’ve opened the template file you’ll see it’s contents, ready to start editing.

When you’ve finished all your edits in template.xml, save the file. To update UPK then drag that file back into the UPK template tab to overwrite the existing template.xml. You should get a confirmation dialog (“This folder already contains a file called template.xml”); click Yes to upload your changes. Then close the template tab to save the changes.

Making changes using the editor

In the editor the key items you need to work with are the classes (at the top), and the events (down the left-side). To make any changes you:

  1. select the class (i.e. Pushbutton)
  2. select the event (i.e. LClick1 = single left click), and
  3. modify the text definition for that combination.

The definition is constructed from a collection of elements, including static text, field names, types, etc. Double-click on any element to edit, or choose from the menu above the definition to add, remove or re-order the existing items. Then use the Preview window at the bottom of the screen to check your edits have the desired effect.

Tip: Keep an eye on punctuation. Use the Preview window to check you start and end your sentences correctly, as well leave appropriate spaces between elements.

Local vs. remote templates

In the list of events shown on the LHS some will appear in bold and some not.

If in bold that means the definition displayed for that event is specific to the chosen class. If you edit it then only the text for the current combination is changed. if the text is not bold, then the definition is common, and every class/event that has the same unshaded value will use your corrected text.

This may explain why, after making changes for some action in your capture, the same language suddenly starts to appear in other, unrelated steps.

To make a local template for the current class, right-click on the event and choose Add Local Template. Then your changes will only apply to the current class. To remove your local instance and revert to the default/global value, right-click and select Remove Local Template.

Mapping template elements to UPK frame actions

Oftentimes you only realise you need to change template text when viewing the text as generated for a specific step in your process capture. If that’s the case it’s quite easy to locate the appropriate definition within the template file based on the frame properties.

To locate the appropriate template entry for a step in your process:

  1. view the current step in UPK Developer and view the frame properties.
  2. in the properties check the current values for the action (an unlabelled dropbox in the bottom section of the properties pane) and the Object type.
  3. Now open your template file in the template editor.
  4. Select the class where the List Name matches the Object type noted in the frame properties
  5. Select the event that matches the action also noted from the frame.

The definition you have selected is the one that is being used to generate the text for the current step. Any edits you make in the template will be reflected in the step once the template file is saved and updated.

Before diving into the template and editing your definitions, check that UPK has correctly identified the Object Type. Sometimes UPK does pick the wrong type, and changing this selection can immediately improve the template text used to describe the action.

What to change?

You should make changes in accordance with your own internal documentation standards. And for bonus points you should document those standards separately and independently (so other resources can be produced in accordance with them.

As an example, the following table shows the first round of changes we made to the Standard – English template.

Element/Action Change from Change to
Pushbutton / left-click Click the [] button. Click [].
Menu entry / left-click Click the [] menu. Select [].
Editfield / string input Enter the desired information into the []
field. Enter [].
Enter the required information in the [] field. For this scenario, enter [].
Listbox item / left-click Click the [] list item. Select [] from the list.
Combobox / left-click Click on the [] list. Click on the [] dropdown list.

Editfield complications

The only complicated template edit is the Editfield / string input combination. This is because it includes a further level of definition to support the different simulation modes. It allows you to fine-tune how explicit your steps are to be and/or how much scope is to be given in what is presented as an acceptable input value.

For example consider a step to enter an account number. In training you may want to explicit present a value to be used. In production however (i.e. if using Do It mode), you don’t want to give a specific value, but instead instruct the user to enter any valid value, perhaps then using your training value as an example. The StringInputExtension elements allow you to support this flexibility by defining optional text such as “for example”. You can also have that text automatically adjust whether multiple values are acceptable, or just “any” value.

For these fields, use the options alongside the Preview text to fine-tune the requirements. Or,
if you’re not using Do It then remove the complications and simplify the template across all your processes.

(3) Apply the template

Once you’ve created and saved your template you can add it to your simulations.

  1. You can set it as the default for all new captures (Tools > Options), or
  2. You can apply it to an existing capture (Properties > General).

Note if you’ve already applied it a process (ie you’ve just edited an existing template, yours or standard) then the changes are automatically applied when the process is edited or published.

No template

One possible issue you may come across when working with templates is a missing one. If you try and edit or publish a capture with a template that cannot be found, you’ll see the following:

  • Steps will appear with the text “NO TEMPLATE” instead of meaningful
    instructions, and
  • the chosen template file in the capture properties will appear as a very
    long string of gibberish.

To resolve both these issues you simply need to edit the capture properties to choose a template that exists in the local installation.

A common cause for this issue is moving (import/export) process captures from one developer installation to another. Template files are not included in the document import/export. You need to move them separately.

Conclusion

UPK’s template approach gives you complete flexibility to tailor the language used across all your capture simulations and documentation. Understanding how to make changes gives you a valuable tool for fine-tuning your captures and further reducing production overhead in developing content that meets your organisational needs.

2 thoughts on “Customising step instructions in UPK

  1. pauline bennett

    I am using UPK for E-Learning resources.
    The FRAME numbering is driving me to distraction – it is all over the place numerically and I cannot find where the Frame ID. Number is generated.

    If in each Module I hae 70 frames – i need to navigate them numberically – but at present there is chaos in the numbering sequence. For. Eg. added new Frames today and the numbering sequence was going up by 2 for each frame: 98, 100, 102, etc.
    in the midst of 304 and 111 sequence!!
    Can you help me out? thanks Pauline

    Reply
    1. steven Post author

      Very interesting Pauline. Until your comment I never noticed that frame numbers are variable. Quick check of my last capture and the steps are 8-10-12-23-16-7!

      I cannot find any kind of “renumber” function. So question is why does it matter that they are sequential and/or logical? Since only developers will ever get to see them can’t they get used to the (dis)order?

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>