Who is this article for?

Users submitting tickets, projects, or proposals

No elevated permissions are required.

The configuration of a business process depends on the requirements provided by a customer. The quality and thoroughness of these requirements impact various aspects of a project or support request such as timeliness, testing, overall quality, potential costs, and customer satisfaction.

This document aims to assist customers in crafting comprehensive and high-quality requirement documentation.

Requirements start with a business need and transition to functional requirements 
Business Need: "The product owner needs to share the implementation completion rates with stakeholders." Functional Requirement: "The completion of the implementation task needs to be tracked and reportable."

Hurdles and solutions

Writing thorough requirements can be difficult for a few reasons:

1. You don't know what you don't know: Individuals tasked with writing requirements don't always know what is possible
2. The underlying business process may not be fully defined: It is common for companies to use requirement writing to document or change a business process
3. There are multiple stakeholders, each with their own opinion: When multiple individuals provide conflicting requirements it can become time-consuming, expensive, and stressful for all parties involved

There are solutions to these hurdles:

1. Know what is possible: The main purpose of the Writing Requirements documentation is to educate the reader about module development capabilities, making it easier to understand the possibilities
2. Start by writing out the process as it works today: The business process is already being followed and partially documented
   • Workflow: The work begins with some trigger, progresses through a workflow, and then closes. During this time various data elements (fields) are captured, updated, and used to make decisions
   • Business Logic: The workflow and fields follow business logic to identify which fields are required, which fields are non-modifiable, which workflow steps or tasks within the workflow steps can be skipped and when, etc.
   • Reporting: Consider required data and reporting needs
3. Appoint an authorized project owner: Successful projects include opportunities for invested parties to participate
   • The customer should formally appoint and authorize an owner to be the individual with the final say on requirements, functionality, and testing
   • Identify contributors and stakeholders
   • Take time to formalize the project requirements, testing, and iteration process before the project begins

Benefits

Thorough requirement gathering allows an organization to reap the following benefits:

• Reduced project/implementation duration: A new application, or changes, can be moved to production sooner, rather than later
• Reduced cost (potentially): If fewer hours are required to plan, design, test, and implement an application, then fewer hours are billed for time and expenses
• Improved internal alignment: Internal requirement gathering plans and defined procedures for requirement alignment disputes help avoid costly iteration delays
• Improved testing: Test scripts that reflect thorough requirements are easy to validate
• Improved quality: Implementing requirements from a clear set of thorough requirements means fewer iterations and changes and leads to a higher-quality product

Requirements fundamentals

Writing effective and easy-to-understand requirements involves an understanding of topics discussed in Course 1000 Lessons. Additional answers to questions can also be found in the Module Developer Guide which is used by module developers to design modules.

The following are some of the primary requirements gathering elements to consider:

• Modules: It is important to know that multiple modules may be used in a business process. For instance, an incident management business process may require corrective action modules, effectiveness review modules, and management of change modules, these requirements should be included in the requirement documentation and task associated to those processes outlined.
• Fields: Fields are used to collect individual pieces of data within a module. Multiple rules and behaviors can be applied to a field at once. In addition to rules and behaviors, fields can also have properties that aren’t dependent on rules.
• Rules and Behaviors: Rules can, and often do, have many associated behaviors. It is important to identify field rules behaviors that may affect the workflow of the business process.
• Calculation: A calculation uses DXL to set the value of a field. Calculations are initiated from a rule. Calculations can also be used on child levels to add or remove line items. Examples of requirements that are fulfilled by using a calculation are:
  • Default the RA (reporting authority) field of an object
  • Display instructions based on workflow tasks
  • Default the “Date Implementation Completed" field to ‘Today’ when “Date Implementation Completed" is null and the workflow task equals Implementation
  • Calculate the number of comments or attachments in an object
• Roles: In a module, the actions a user can take are influenced by their assigned roles. Users have the flexibility to hold multiple roles. While it's possible to define several roles within a module, usually only a handful are necessary. The same role can be used across different modules. Although permissions for each role can vary from one module to another, it's advisable to keep them consistent. Common roles and their associated permissions are:
  • Participant (All users)
    • Initiate new objects/records
    • Act on records assigned to them
    • Roll back (reopen) an assigned record to a prior workflow task
    • Search for and view (read only) all records
  • Coordinator (Named coordinators - per application)
    • Everything a Participant can do
    • Open any record and act as the assignee
    • Reassign at any workflow task
    • Cancel records (at Initiate only)
  • Administrator (Named administrators - per application)
    • Everything a Coordinator can do
    • Reopen closed records
    • Manage reference data that is not hard-coded
    • Manage Teams
• Attachment and Prints: Identify and outline limitations regarding attachment types and sizes and include print requirements.
• Object Layout: Ensure that the object layout accurately reflects workflow steps and critical information.
  • Consider the use of a Model Template to improve collection of data.
  • Will a workflow step need to be viewed on a small screen?
• Workflows: Modules with workflows can have an unlimited number of Steps, and each Step can have an unlimited number of Tasks.
  • The first Step is always Initiate, and the last Step is always Close.
    • Every Step must have at least one Task.
    • Parallel steps or tasks are not supported but can be met by applying child-level actions that must be completed before an object can advance to the next workflow step/task.
• Workflow Behaviors: Behaviors that always apply to Tasks, not Steps.
  • The default behaviors for Workflow Tasks are:
    • No task can be skipped
    • All browser windows remain open to the user after clicking submit
    • All tasks can be rolled back
    • No tasks can be canceled
    • No task guidance is displayed
  • If any behavior besides the default is required then one or more of the follow Module Builder behaviors will need to be applied, for each task. The following behaviors are controlled by rules.
    • Skip task
    • Complete task
    • Prevent rollback
    • Update task
    • Update current task
    • Allow cancellation
    • Completion rules
  • The following workflow behaviors are not controlled by rules. They are either on or off.
    • Return on complete: Closes the browser tab and returns the user to the previous screen when the task is successfully completed
    • Task guidance: Used to display instructions, per workflow, which can be displayed on-screen and within assignment emails
• Workflow Task Assignments: A key requirement of any workflow-based module is to define task assignments. The assignment of each task can be to a User or a Team.
  • Considerations when determining task assignments:
    • Q: If the default assignment is to an individual user and that person is no longer with the company?
      • A: If an additional assignee were defined, such as a team supervisor, the assignment would route to the supervisor.
    • Q: Should a catch-all assignee be defined as if all other assignment rules failed to determine a valid assignee?
      • A: The catch-all assignee could be an Administration team that will always have at least one member.
  • The time to plan for these scenarios is now, not when the employee departs the company. If an alternate assignee is not defined and the only assignee is not valid, the object will not be allowed to advance to the next task.

Security and confidentiality

Keeping our customers' information safe and secure is our company's number one priority. Identifying requirements for a project or support request can also involve security best practices. 

As described above in Behaviors, by default, all users can see all data (read-only). Using rules, roles, and behavior it is possible to hide fields from certain users. Hiding fields in this manner only hides what is visible on the screen, it does not prevent the user from searching for and seeing this information in search results.

To completely prevent users from being able to see controlled information it is necessary to implement other controls.

• Reporting Authorities segregate data at the object/record level
  • If a user doesn't have access to a particular reporting authority, they will not be able to see or search for any objects in that reporting authority
• Record Access Control is a more granular method of limiting users to specific objects

Test scripts

Write test scripts to help define requirements

Test scripts evaluate if requirements have been met. Test scripts are an ordered list of actions and associated expectations. Here is an example:

*When gathering requirements, it was not considered what the value of the "Building" field should be if it was previously set but then the "Area" field was modified.

Do you want to write better requirements? Write some test scripts.

Don't wait to write test scripts. The process of writing out the actions and expected results can help highlight missing requirements.

Test scripts should also account for the following scenarios:

• Users clicking the wrong buttons or doing something incorrectly
• Rollbacks
• In-flight testing on open items and how they are affected by the planned changes
• What affect does a role have on a business process
  • Can an administrator see fields that a standard user cannot
  • Is a participant able to access areas they shouldn't have access to

Allocating sufficient time to develop comprehensive requirements and formulate test scripts diminishes the number of iterations and expedites the overall implementation timeline.

The configuration of a module is inherently iterative.

Requirements are collected and communicated, after which the business process is configured and subsequently tested.

Should further requirements be identified during the testing phase, additional configuration will take place, followed by further testing, continuing in this manner until testing is validated and accepted.

Helpful tools

Additional documentation may also help you with writing requirements when you understand recommended client configuration tips and know how to prepare for the deployment of a project.

To begin writing requirements it might be helpful to populate a spreadsheet listing the various workflow steps, workflow tasks, fields, roles, logic, etc. that will make up the requirements. 

The following are some suggested templates and examples to help you start this process. 

• The Project Requirement Template is a great tool for applications owners to download
• Also consider downloading and reviewing this Project Requirement Example
• For small module enhancements, the Request Checklist will list requirements to consider and prompt questions to ask