Enable "locking" library templates

[Ig-Rebollo]

1: Allow owners/editors to "lock" a template 2: Questions in locked templates can be set to “core” to prevent users [who create new surveys from this template] from [in the surveys they create]

• Removing "core" questions
• Editing the name of a variable (unique question name)
• Modifying calculations
• Adding new questions
• Editing any existing labels

[Ig-Rebollo]

@tinok @jnm

This is the initial attempt to incorporate all the requirements and comments from the previous calls into a coherent design. I will have to create additional mockups to show the implications for the library view, the project sections, etc. but this gives you a first idea of how it could work if we work on a GUI for this feature.

First, the editor would create a normal template

The form builder would now include an icon to access a new modal for locking the template. This icon only shows up when creating a template, not for a regular form.

The template would then be locked, though the template owner can of course continue to edit

When another user creates a project from that template, it would become a 'locked project', and they would see this:

Let me know what you think and I'll continue expanding on it.

[tinok]

@Ig-Rebollo, I think the direction looks great. My only concern is that I found the pin vs asterisk icons confusing. We use asterisk for mandatory questions elsewhere. After discussing with John we'll have more than one "locking" level that users can define. So (visually) there will be two statuses per question:

• Unlocked: Maybe an open padlock?
• Fully locked: Closed padlock

[Ig-Rebollo]

Thanks @tinok

Re-icons. The problem is that we were already using the lock icon for encrypted projects, hence why I thought it might be best to avoid it. However we could also consider using the lock for this and changing the icons for the encryption.

In the original mockups pinned='unlocked' and core=locked. The reason I did not want to call it 'locked/unlocked' is that the 'unlocked' might be misleading, because you can still not edit it in any meaningful way, just remove it (hence the pinned, though I'm open to better options). The language we use should reflect that.

I also see you edited the original comment (I received the original comment in the email notification). Does that mean we keep the per-question locking in the new modal, or do you still would rather having it in each question? I simply thought it would be easier to implement in the modal, and both options should work equally well. But happy to change it.

[jnm]

Hey @tinok @Ig-Rebollo, let's skip over (temporarily!) the entire discussion about having a UI for administering the locking settings. This won't be in scope for the initial UNICEF work. We can concentrate our GUI efforts on what the country director sees in the form builder while editing a survey created from a locked template. From our 12/16 call notes:

the experience they overwhelmingly care about is the country director's, not the HQ admin's [provided that the submission data arrives back to HQ intact]

The initial release will require the HQ admin to configure the template locking solely within XLSForm. Certainly, this deserves UX consideration in its own right: @tinok and I have tried to outline how this might work; we'd like to present it to you, @Ig-Rebollo, and get your input. Ideally, we'd rope in @magicznyleszek for a call as well, and development could progress along the lines of:

1. We figure out the XLSForm workflow and write a sample template that uses all locking features
2. I create a mock JSON structure from that XLSForm
3. In parallel:
   1. The back-end team works on making our importer understand this new XLSForm and create the appropriate JSON structure
   2. The form-builder changes are made:
      1. The UI design is completed
      2. The front-end team implements the UI design using my mock JSON as a stand-in for the back end's output

I'll start a thread in Zulip about scheduling a call.

[jnm]

'unlocked' might be misleading, because you can still not edit it in any meaningful way, just remove it (hence the pinned, though I'm open to better options).

Agreed. I know we'll go over this on a call, but to whet your appetite: let's consider that there might be an "unlocked" state (i.e. the only state we have right now) plus a variety of partially or fully "locked" states (not just one or two). We could provide a default "locked" state where all actions are disabled (like UNICEF's "core") but also allow the template author to name and define other states that restrict only some actions. There's quite a lot of actions available for questions and groups:

• Delete question
• Edit question labels
• Edit choice labels
• Change choice order
• Edit question settings
• Edit skip logic
• Edit constraint
• Add question to group
• Remove question from group
• Delete entire group
• Edit group labels
• Change question order within group
• Edit group settings
• Edit skip logic
• Child questions can be removed
• (more?)

There are other actions at the form level:

• Add question
• Change question order
• Add translation
• (more?)

Initially, all this would be configured only in the XLSForm of the template—but the consequences would be seen in the form builder UI when editing a survey created from that template.

[Ig-Rebollo]

That will certainly give a lot more flexibility to everybody, so this feature doesn't adapt only to the needs of UNICEF but any other organization. On the downside, it will make the feature significantly more complex and difficult to understand at first.

For instance, where would I define those custom partially locked states? In a modal, question by question, or maybe somehow in the project view beforehand, so I can then apply predefined custom locks in the form builder?

I'm thinking if providing flexibility is the key priority, probably the settings of each question is the way to go. If discoverability is the priority, the modal might be better. Probably a combination of both might work best.

[jnm]

That will certainly give a lot more flexibility to everybody, so this feature doesn't adapt only to the needs of UNICEF but any other organization. On the downside, it will make the feature significantly more complex and difficult to understand at first.

Exactly, and of course with all respect to their foresight, our friends at UNICEF may change their requirements over time as well. My hope is that we can have this flexibility without steepening the learning curve too badly, perhaps using the default "locked" state that I mentioned. This ought to make it comparatively easy to block all actions without having to get into the nitty-gritty, granular settings at all.

For instance, where would I define those custom partially locked states? In a modal, question by question, or maybe somehow in the project view beforehand, so I can then apply predefined custom locks in the form builder?

For the first iteration, everything's in XLSForm-land. Tino and I spoke about defining the custom states in the settings sheet, or perhaps a new sheet, and then referencing them question-by-question (row-by-row) from within survey. It'll be revealing, though, to see how much that makes sense from your perspective—and with an eye toward making this configurable in the UI.

[Ig-Rebollo]

@jnm @tinok

Including here some updated mockups with a slightly revised version of the country manager view of the template/project.

It uses the same icon (a lock) but changing colours to indicate the two types. Red would mean total lock (UNICEF's core question), while the yellow ones mean partial lock (which would be any customization of that full lock, for example, any of the items from the list john mentioned above)

I also decided to keep every icon/button on the side of each question. Whatever can't be clicked would simply be reduced in opacity. If it has full opacity, then it can be clicked (like the remove icon in partial lock questions). Labels can be clicked on and edited.

[magicznyleszek]

My notes from the meeting today :)

The locking profiles and settings are stored with the asset. When the asset type is template, the locking settings are editable, but when it is survey you can't change locking settings.

There are locking rules that could be set for:

1. group - visible as icon next to question row
2. question - visible as icon next to group row
3. template - visible somewhere in the sidebar's "Layout & Settings" ❓

We will have locking profiles:

• "Kobo Locked" - built in, "no" to everything
• "Kobo Unlocked" - "yes" to everything - and it's basically having no profile set ❓
• Custom Profiles - here UNICEF will define for themselves their "core" and "flexible"

There is an idea to have a small UI (a switch) that will set "Kobo Locked" to everything (all groups, all questions and the template) with then possibility to go through each item and set locking profile to something different (custom or no profile).

The problem with Custom profiles in the context of UNICEF is that it would be nice if custom profiles could be distinguishable in the Form Builder UI (each row has an icon meaning what locking profile is set to it). In current design there is one icon for "Kobo Locked" (red) and one for Custom Profile (orange). Some ideas how to distinguish Custom Profiles:

1. Somehow use the first letter from the profile name in the icon (e.g. "🔒" for "Kobo Locked", "🔒F" for "Flexible" Custom Profile, "🔒C" for "Core" Custom Profile)
2. Have a predefined list of colors for Custom Profiles. E.g. ["violet", "purple", "pink"], and then "Flexible" will be violet and "Core" will be purple.
   • A risk here is that we will have a limited number of predefined colors, and somoene could have more Custom Profiles defined and we will reuse the same color for different ones
   • A (small) risk here is that someone will get used to seeing violet "Flexible" and purple "Core", but a change in the order of definitions would make the colors change
3. Instead of icon use profile name - this would require changing how we show rows locking profiles

We could mix these ideas and have:

• red 🔒 for built-in "Kobo Locked"
• violet 🔒F for "Flexible"
• purple 🔒C for "Core"
• pink 🔒U for "UNICEF Profile Added in the Future"

[Ig-Rebollo]

@magicznyleszek @jnm

Based on the brainstorming and conversations from our previous calls and some discussions with @tinok, I put together two options on how we could approach this. They are practically the same, but they have a key difference: the number of locking levels we allow.

Option 1:

In this version, we would cap the number of locking levels allowed. The specific number could be discussed, but it would have to be limited somehow. Each level could be customized as the template designer wants. UNICEF could use it to create a profile with 'Core' and 'Flexible' locking levels, but maybe UNHCR wants to create 'Essential', 'Important' and 'Relevant' levels.

Each level would get a colour assigned. This is why there has to be a limit. At some point, too many colours will become irrelevant. In the example below, there are three colours:

• Grey = 100% locked, no options available (this would be the default KoBo lock)
• Red = 1st level customizable. In this case, it represents 'Core'
• Orange = 2nd level customizable. In this case it represents 'Flexible'
• No colour = Fully editable.

If a given user wanted to create more levels, we could add a few more colours, but I wouldn't add more the 1 or 2 on top of the previous list. Alternatively, we could use a change in the icons instead of colours (for example, a 'X', a '!', and other symbols representing a warning/restriction). This could give us a few more options than the colours, but again, the less they are, the more relevant it will be.

The form level restrictions would be displayed in a banner on top of the form, and question options could be displayed when hovering the lock icons of each questions.

The user could also give a name to each level, which would be shown on hover over the icon (in this case, 'core' and 'flexible')

Option 2:

In this version, the only significant change is that there are no defined locking levels. The only difference is between a fully locked question, and a question with any type of customized locking. Using the same UNICEF example as before, with this approach all their questions would look yellow, regardless of whether they are 'Core' or 'Flexible'.

Note that on hover, they do not say 'core' or 'flexible' anymore, but simply 'Editing restricted'.

The key advantage here is that the template manager could create infinite number of locking levels, without any restrictions. Country officers would simply hover or click on the lock icon to see what options are available in each question. Additionally, locked and unlocked functions could also be displayed in the questions settings:

Ultimately, it is a trade off. Option 2 sacrifices a small part of the user experience on the country officer side for a lot more flexibility for the template creator. Option 1 on the other hand prioritizes the experience of the country officer but might be more restrictive.

[Ig-Rebollo]

@magicznyleszek @jnm @tinok Here is the latest iteration of the locking feature, incorporating the last few exchanges we had on this.

In the end the decision has been to simplify, minimizing the display of icons and colours to allow as much customization as possible without making the feature confusing:

Latest version as of Mar 11, 2021

There will be a default kobo locking profile that simply locks every functionality. This type of lock will work slightly different from the others, as it will not only show an icon but also add a light grey background to the question, highlighting the fact that it cannot be edited in any way.

There can be as many custom profiles as the template owner needs, however, these profiles will only be visually distinct up to 3 levels. From that point forward, the icon will look exactly the same.

On hover, these icons will display the name of the profile as assigned in the xlsform. Below this name it will say 'partially locked question' as opposed to the default kobo lock, which will display 'fully locked question'.

A full list of the functionalities blocked can be found in the settings of each question, though users will be able to easily see what is blocked as the affected buttons and functions themselves would be removed (or in some cases greyed out). Note: or

As in the previous versions, the form level locking would be displayed in the banner on top, though it would not show a legend of the icons, simply focusing on describing the form level restrictions:

In the library view, locked templates would appear with a lock icon attached to the template icon. For the time being though, since these icons don't use colours, we will not make a distinction between fully locked and partially locked visually, but simply with the notification on hover (one would say locked template and the other partially locked template on hover, even though the icon would look exactly the same)

I will post soon a list of buttons, icons and sections of the formbuilder, describing how each should behave when locked (be removed, greyed out, or changed)

Let me know if you have any comments or questions!