A vital part of the implementation process is locking down your process forms, to ensure users can’t do anything they shouldn’t and enforce a smooth flow. It can be a cumbersome task however, and done improperly can cause issues further down the line.
For my last few projects I’ve been working on a new way of discussing, documenting and implementing form controls.
This includes restricting allowed state transitions, mandatory fields, read-only fields, button / control visibility, and any other required core logic to enforce a process in-tool.
The old way
Most projects look at ACLs, controls and form layout in an extremely granular way. These examples may be familiar :
- A Story logged to add a field. This describes when the field should be editable and by whom. The developer implementing this story creates ACLs and UI policies specific to this field. When they get to the next story, they rinse and repeat.
- A story describes a workflow which moves the process between states but
the related form controls or UI actions don’t allow the user to progress through the workflow. The UI actions and the workflow are described in separate stories and don’t line up.
- Process Experts request the addition of a new field because they know they need it – they never request the removal (hiding) or a field because they don’t know it’s even there to trip them up!
- A related list is added to connect to another table, but the default format allows the user to create new records in that table as well as linking to existing records. This can bypass controls in the process supporting that table and expose default ACLs which might not be expected to be so open.
- Workshops tend understandably focus on new requirements and not reviewing / controlling the out of the box.
- Implementation stories too often viewed in isolation – causes inefficiency for the developers, particularly in larger teams, and the resulting configuration will be harder to understand and maintain in future
- Hard to document coherently. Requirements and documentation of how requirements were implemented is scattered throughout hundreds of stories
- Complicates formal testing due to granular implementation – this results in huge sprawling test sets which rapidly become outdated and must be rewritten
The new way
I’ve been working on a new Design Document based workshop format. The ‘Process Implementation’ document is created for each distinct ITSM process and exists in three stages:
- Current Environment
- Agreed Changes
- Final Build
Stage 1 – Current Environment
The first version of the document contains the following sections to accurately summarise the current state of play:
- State Transitions – a matrix of possible states in the process and which transitions are allowed. This can include annotations about how this happens – automatically, by direct access to the State field, or by UI actions for example.
- ACL Overview – this summarises at a high level who can ‘edit a ticket’ at each state. This references business roles/functions/concepts as well as the actual system roles which are used to implement this. This doesn’t go to field level – just a conceptual level which is aligned to the row-level ACLs.
- UI Actions. A list of the available UI actions, where they appear, when they appear, and what they do. This includes which users / roles etc. are able to see them.
- Forms. This large section includes screenshots of each form section at each stage in the process. Quick and easy to build this shows the current state. Screenshots can be annotated where, for example, certain form sections depend on a role or appear based on other data elements being set.
Stage 2 – Agreed Changes
The document produced in Stage 1 is then reviewed in a workshop. The act of creating the Stage 1 document often reveals many minor issues with permissions and layouts, and these are discussed. Changes to the forms are made in the document using Word objects to overlay and annotate. As standard I add a transparent red rectangle to fields to say they should become mandatory, add a crossed-out rectangle to show fields which should be removed from the form, and simply draw in new fields which should be added.
After the workshop all agreed changes can be summarised at the end which will then provide a to-do list (or skeleton draft for new stories) to hand to the development team.
Stage 3 – Final Build
This final stage is quick and easy – simply tidy the document, update the screenshots, and remove the narrative around changes required. As such this provides a great point-in-time review of how the process has been built, what it looks like, and how it works.
This document can then be used as the basis for training material which can easily re-use much of the content.
When do we do this?
There’s no right answer here. If you are going for a green-field build then this process can start on day 1 – but the three stage process of ‘Current – Changes – Final’ will need adjusting as there’s no point documenting the out of the box layouts in that much detail!
Generally this style works best after the primary development – it acts as a process implementation review, assists with quality control, and provides a structure for finalising the build and tidying up those loose ends.
- Promotes discussion on the user roles and assists with turning access control into a straightforward BAU function.
- Creates a strong audit trail in easy to maintain documents: Version 1 (current state of play, Version 2 (workshop output), and Version 3 (Production ready).
- Assists testing by providing Version 3 document stating the system user types (actors) and forms showing what each actor can and cannot do.
- Improves implementation / code quality by providing each developer with a bigger view of the permissions required – encouraging effective end to end permissions and not point solutions for each field / button etc.
Bite-Size Take Away
- The out of the box forms are unrestricted and grant most users access to everything
- Users discussing the implementation don’t know to ask for things to be hidden or disabled – they need guidance
- Documenting an entire process as it is implemented in the tool is in conflict with a granular agile approach to implementation
- Formalising the user interface controls and permissions in this way brings together users and developers and provides a solid foundation for future changes
Happy Documenting, and thanks for reading.