Tag Archive for: requirements specification

Check Security Authorization

/in /by

Because each system we build has custom security requirements, there is no way to implement one security model and apply it to all systems.  Instead the framework supports extensibility points as part of the command and query architectures.

But before you go there, you’ll need to flesh out the requirements for security and build the necessary database tables.

Some important questions to answer regarding security requirements:

  • What are the roles?
  • Do users need to be granted/denied access to specific types of data? (i.e. can all users access all entities)
  • Do users need to be granted/denied access to specific data (e.g. have access to one division, but not another division)
  • What are the different rights that can be assigned to each role (very convenient if you can associate them one-to-one with biz commands)
  • Do different roles need to be disallowed from different client apps?
  • Who will manage security roles?  How will they do this?
  • Who will manage rights?  How will they do this?

After understanding that, the next step would be to create the necessary database tables to support those requirements, populate them with data, and build some queries or stored procedures to allow you to ask the necessary questions of the security system.  After all that, then we can wire up to the security system in the command and query architecture.

There are two different ways to apply security.

  1. Apply security on a per command basis
  2. Apply security on a per entity basis

Apply security on a per command basis

For Add, Edit, and Delete operations you will apply security on a per command basis.  In this case you want to check security ONCE per command execution.

For each of your commands that need security do the following:

public override bool CheckSecurity()
{
}

Fill in the method guts with a query that checks whether the user has permission to execute this command OR has permission to execute this command on this entity.  For example, you might have a system that allows for deleting of users.  In one scenario, only admins can delete users.  In that case, simply check whether the currently logged in user is an admin in the CheckSecurity method.  In another scenario, only the user can delete themselves.  In that case, check whether the user that is about to be deleted is the currently logged in user.  In both scenarios we are checking security ONCE per command execution.

In theory you could apply this type of security checking on Get methods too since they operate on exactly one entity, however, see below for a better option.

Apply security on a per entity basis

For Get and GetAll, we are performing read operations on 1 or more records in the database.  It is not efficient nor practical to do that checking in the command layer.  Instead, checking is done in the query layer.

You will need to extend the code generated queries using partial classes.  These partial classes should be placed in the /Queries/Extended folder in the Model project.  You will typically override the GetAll method to include filters that apply security correctly.  Note, that the Get method internally calls the GetAll method so you can limit your security settings to a single location and read security will be applied in a uniformed way everywhere.

 

 

Story Points

/in /by

Don’t use hours to estimate a requirement or feature.  Your estimate will be wrong, but you’ll be held to it.  Instead let’s use story points.  Story points are values that only have meaning within a given team.  That meaning is developed, learned, and refined over time.

 To understand story points, let’s look at something similar that we all understand.

Restaurants are rated on a scale of 1 to 5.  That star rating conveys a lot of information.  With that star rating you know the following:

  • Quality of food
  • Attire
  • Price
  • Wait time for food
  • Will there be valet parking?
  • Will there be a waiter or do I order at the counter?
  • How customizable will the meal be?
  • How knowledgeable will the staff be?

If I tell you we are going to a 5 star restaurant, I bet you could answer all of those questions with a high degree of confidence.  You would not know precisely how much it will cost, but you’ll have a ballpark feel for it.  If tell you we are going to a 2 star restaurant, again, I bet you have a pretty clear expectation.

If instead of the star rating, I just told you that the food was really good, would you know how to dress?  If I just told you that it was very reasonably priced, would know if you were ordering at the counter or talking to a waiter.  If told you that meals were $50 a plate, you might guess that it was a 4 or 5 star restaurant.  But in reality it could be a 3 star tourist trap on an island that has only 1 restaurant and has to fly all of their food in from the mainland.  The point being is that knowing only one dimension can sometimes you get close to the right answer, but can also be quite misleading and dangerous.

Story points allow you to embed information from lots of dimensions into the numeric value.  We might embed the following dimensions into our story points:

  • Coding effort
  • Complexity
  • Risk
  • Knowledge of technology
  • Quality of the domain expert
  • Platform
  • Usability requirements

So maybe we can setup story points like the following:

Example:

  • 1 point = easy, straightforward feature
  • 2 points
  • 3 points = moderate, somewhat complex feature or contains some moderate risk
  • 4 points
  • 5 points = hard, complex feature, that may contain high risk

These are just guidelines to get started.  Story points develop meaning over time.  Just as with restaurants, it took experience with restaurants before you understood the rating system.

In that one number you can embed any additional information or padding that you may need.  If you estimate everything in hours you will be challenged by people who don’t know better.  If you assign story points to things, you can use your intuition or any other knowledge to pad your estimate without getting into a debate with those who don’t understand.

Each developer will bring a different intuition to assign story points.  Some will be junior developers who spend most of their time focused on technology challenges.  Others will be senior architects who are assessing risks and future complexities far outside the experience of the junior developer.  Story points serve to normalize those large differences in experience and perspectives across the team.

Story points are a tool.  When used incorrectly you will get bad results.  Story points only work when the project is being managed in the Scrum (or similar) methodology. They work with time boxed sprints and user stories.  If you are doing time boxed sprints and user stories, then you may not get the desired results.

User Stories

/in /by

What is a user story?

A user story is one or more sentences describing what a end user needs.  It is expressed in everyday language or the business language of the user.  A user story is NOT intended to capture ALL knowledge required to implement a given feature.  User stories facilitate conversations between customer and developer.  The details required to implement the story are acquired overtime via these conversations.  

Why user stories?

  • Verbal communication – yields greater knowledge and understanding
  • Comprehensible (non technical)
  • Right size for planning
  • Work well with iterative development
  • Encourage deferring detail
  • Opportunistic development
  • Participatory design (between developers and customer)
  • Build up tacit knowledge

Structure of a User Story

As a {user role} I want to {do something} so that {reason} 

  • User Role = Who
  • Do Something = What
  • Reason = Why

 NOTE: we are not talking about HOW to implement it.

The structure of the sentence forces us to talk about requirements and NOT design.  This prevents us from short-circuiting the analysis and design phases.

Attributes of a good user story

Very good blog explaining the important attributes of a user story

http://agilesoftwaredevelopment.com/blog/vaibhav/good-user-story-invest

Just think of INVEST to remind you of the attributes of good user story.

  • Independent – loose coupling between user stories.  Makes planning much easier.
  • Negotiable – don’t design a solution or specify so many details that you paint yourself into a corner.  We should always be free to change our mind on HOW to implement the given requirement at a later time.
  • Valuable – must be a value to the end user
  • Estimable – must be able to put an estimated number of hours or days
  • Small – less than a week
  • Testable – so we know when we are done.

A useful tool for ensuring that user stories adhere to INVEST is to either break a user story apart into smaller user stories.  Occasionally, the opposite might be true (combine many smaller use stories), especially in support of Independent.

Drawbacks to User Stories

  • Difficult to understand relationship between stories
  • May require augmenting them with additional documentation if traceability is a mandate
  • May not scale well to large teams (too much conversation and too many pathways)

Guidelines for Good Stories

  • Start with Goal Stories – why is user using the system?
  • Slice the Cake – slice up large stories in way that the user can actually accomplish something (not part of something).  e.g. 1) collect data 2) write to database.  That is bad.  Good would be to 1) collect basic information, 2) collect detailed information
  • Write closed stories – don’t write a story that will never complete.  e.g. A user can manage his projects.  instead, breakup into smaller chunks that can be completed.  e.g. A user can add and remove team members from a project.
  • Put constraints on cards
  • Size the story to the horizon – stories you are going to tackle sooner need more precision.  Stories far in the future don’t need same level of precision.
  • Keep the UI out as long as possible – that’s a design task, not a requirements task
  • Some things aren’t stories – if it does not fit in a user story, use a different method.  Use this is a last resort, not as a cop out to learning how to write good user stories.
  • Include user roles in stories
  • Write for one user
  • Write in active voice
  • Customer writes – ideally, but requires training and discipline on the part of the customer
  • Don’t number story cards – tempting, but pointless overhead.  Short title is better.
  • Don’t forget the purpose – to remind you to discuss the feature

Final Thoughts

User stories are a TOOL.  They are a great tool that every software developer should master.  But like any tool, it can be misused and thus not yield the desired results.  Also, like any tool, it is not appropriate for every job.  Before you try to use this tool, I highly recommend reading some books, reading blogs of those who have had success, and start small.

Books

 

Collecting Requirements

/in /by

Any stakeholder can specify requirements.  Obviously the requests by users and project sponsors carry the most weight, however stakeholders such as developers, system administrators, and quality assurance personnel need to have a say since they usually have the best ability to manage the quality, cost, and time dimensions.

A requirement is usually a textual specification of the form “The system shall…”  But beyond just documenting WHAT the system should do, you should also document WHY the system must conform to the requirement.  This is helpful when developers interpret the requirements.  It is also helpful when trade-offs need to occur between conflicting requirements.

Where possible, it helpful to express requirements in numerical terms, for example, the “The system shall return results to the users within 3 seconds, given a maximum of 100 records per result set and a maximum of 40 simultaneous users.”  A requirement at this level of detail is helpful to developers, project sponsors, quality assurance personnel, database administrators, and system administrators.  In that example, the technical stakeholders have some pretty concrete metrics to work with and the project sponsor has a reasonable way to verify the fulfillment of the requirement.

Warning.  Stakeholders don’t always ask for what they really need.  They make requests.  It is your job to figure out what the real need is.  You should ask yourself, “What is driving this request?”  Requests provide context for needs.  Is there a marketing reason for this request?  Is there business process reason?  Is there a compliance or legal reason?  Is there a political reason?

Warning. Stakeholders quite often express their requirement in terms of features they have previous experience with.  For example, “I would like a system that can handle email attachments”.  In reality, what they want is a way to transfer files from one user to another, but if the only way they have ever done this is via email, they will explain their requirement in the only language they know.  This represents a different form of thinking for the stakeholder.  Instead of expressing WHAT they need, they are expressing HOW it should perform.  Depending on the sophistication of the stakeholder, this may or may not be misleading.  It is your job to translate “feature speak” back into needs, then recommend features that fulfill those needs.

 

Non-Functional Requirements

/in /by

When we talk about requirements, we are almost always talking about functional requirements.  i.e. the features.  Features deal with WHAT the application is supposed to do.  However, there is another classification of requirements called non-functional requirements.  These fall into the following categories:

  • Usability – the human factors such as aesthetics, ease of learning, ease of use, and consistency of the user interface.
  • Reliability – frequency and severity of failure, recoverability, predictability, and accuracy.
  • Performance – transaction rate, speed, availability, accuracy, response time, recovery time, or memory usage.
  • Supportability – testability and maintainability.  This is important to Quality assurance personnel and system administrators.

NOTE: The actual categorization is not important when documenting non-functional requirements.  For example, there is not much use in debating whether a requirement is a reliability or performance requirement.  The list simply exists as a mental check list of perspectives to keep in mind when looking for requirements.

Unfortunately, these non-functional requirements are rarely considered in estimates.  Exploring non-functional requirements is just as important as exploring functional requirements and can sometimes affect the cost and effort required by orders of magnitude.  For example, if a server needs to have 99.9% uptime the cost is substantially less than a server that needs to be up 99.999% of the time.  Instead of thousands of dollars per year, you may need to be spending hundreds of thousands of dollars per year.

Here are some examples of non-functional requirements

  • System must support up to 100,000 total users
  • System must support up to 1,000 simultaneous users
  • System must support up to 1,000 tasks per user (100 million total tasks)
  • System must support up to 100 projects per user
  • System must support up to 1,000 tasks per project
  • System must be accessible on desktop and mobile devices
  • System must be understandable and usable by users without any documentation or training
  • System must respond to user requests in 2 seconds or less
  • System must be hosted on Rackspace (production)
  • System must run on exactly one VM (to reduce operations costs)
  • System must work on 90% of all browsers used in the U.S.
  • System must be up 99.9% of the time (normal operation and maintenance)
  • System must support disaster recovery of no more than 1 day of downtime
  • System must be easily supported.  No more than 1 FTE support personnel
  • System must be easily maintainable.  Respond to most feature requests in less than 1 week and bug fixes in less than 2 days.