Intro
I was recently asked how I go about gathering requirements and creating functional designs. Today I'm going to show you my favorite tools that help me go about doing that.
Requirements Gathering
I like 1-on-1 sessions. A full house JAD (Joint Application Design) session is fine and you can learn a lot from people relaying stories about the pain points they experience. But, 1-on-1 sessions allow people to let down their guard in a way that a large setting may not allow. They feel more free to speak up about certain things when they are in a conversation with a co-worker or consultant and know that the information won't go any farther than that. This goes back to being able to be a trusted advisor to your client (internal or external)--be trustworthy, keep their secrets secret and allow yourself to be a sounding board. Above all else, let them know that you are there to help.
Use Case Diagrams
Breaking domains down into use cases is paramount to drilling down to needs and wants. You start at a 10,000 view and dig down to sea level.
Recently, I interviewed a client about issues they were having with auditing (use case). We spoke about some of the issues and determined that the reason that they were having issues was because they files that they were basing their audits on weren't always available. Next of course, why are the files available? Because they based the audit process on message queues, not actual physical files. These queues were not always readily available, resulting in an inability to sync with other systems. Don't be afraid to ask a question that you think may be "stupid". If you don't know, you don't know and it is a far cry better than making an incorrect assumption and finding out you were incorrect after money and resources have been committed. JUST ASK!
Activity Diagrams
These are one of my favorite tools. They offer a little more flexibility than flowcharts in my opinion. Always review your activity diagram with a group. Key point here...If you have a large, complicated activity diagram, don't try to cram an activity diagram with a lot of detail, just to get it on one page. You WILL lose your audience if you present them with an activity diagram that has too many points on one page. Less is more. The diagram below is relatively simple and describes what should happen when we receive a file from one of our vendors. Make liberal use of the 'Notes' as they can help clarify the activity boxes without you having to place a lot of detail in the box (the reason for keeping the text in the boxes short is that it helps when detailing the activity in your text-based/textual use cases).
Textual Use Cases
I use my text-based use cases to follow my activity diagrams. Each activity is broken down into individual steps. Before you call me out for using implementation language in my diagrams and use cases, these examples are for Functional Design, not requirements. But, I'm sure you can see how useful this approach could be for requirements also.
|
Project Name: |
|
|
NC5208: State Health Plan |
|
|
Use Case: |
|
|
Feature 180 Company Processing – Daily Maintenance File
Processing |
|
|
Pre-Condition(s): |
|
|
File is sent to BCNC |
|
|
|
|
|
Actors: |
|
|
Vendor_1 |
|
|
Company |
|
|
Vendor_2 |
|
|
|
|
|
Functional Requirement(s) Satisfied: |
|
|
834 File Transmission.001.001 |
|
|
834 File Transmission.001.002 |
|
|
834 File Transmission.001.003 |
|
|
834 File Transmission.001.007 |
|
|
834 File Transmission.002.001 |
|
|
834 File Transmission.002.005 |
|
|
834 File Transmission.003.005 |
|
Daily Maintenance flow
|
Step |
Actor(s) |
Action |
Input |
Output |
Expected
Outcome |
Applicable
Rule |
Functional
Req’s Met |
|
Pre
Condition |
Vendor_1 |
Send file to {File
Location-TBD} |
Batched Enrollments |
Vendor_1 file |
File is available for
processing |
|
|
|
DM-1 |
Company |
Retrieve File |
Vendor_1 File |
File Type |
If File received prior to 6pm: ·
Go to Step DM-2
If file received
prior to 6pm, but is for a prior date: ·
Go to Step DM-2
If File received after 6pm: ·
Go to DM.1.1 |
|
834 File Transmission.001.003
834 File
Transmission.001.002 834 File
834 File Transmission.001.002
|
|
DM.1.1 |
Company |
Store Transaction for Next Day
Processing |
Late File |
N/A |
Go To DM-End |
|
834 File Transmission.003.004 |
|
DM-2 |
Company |
Determine File Type |
File Type |
|
If Daily: Go To DM-3
If Monthly: Go to Alternate Flow: AF-2 |
|
834 File Transmission.001.001
834 File Transmission.002.001 |
|
DM-3 |
Company |
Send Acknowledgement receipt of
Daily File |
Vendor_1 834 Change File |
Acknowledgement |
SR1.3 |
834 File Transmission.001.007 |
|
|
DM-4 |
Company |
Convert file from 834 to Keyword File |
Vendor_1 834 Change File |
·
Vendor_2 Keyword File ·
Record Count Report(s) |
Successful Conversion: ·
HIPAA Checks Performed ·
SNIP Level 6 checks performed ·
Go to Step DM-5 Record Level Error
Found: ·
Go to 4.2 Unsuccessful Conversion: ·
Go to 4.1 |
Loaded with issues SR2.1 SR2.2 SR2.3 Not Loaded SR1.1 SR1.2
|
|
|
Company |
Notify
Business |
Vendor_1
834 Change File |
·
Email File Level Error Report |
Notification/Email
sent to business Go to
Step DM-4.2 |
|
|
|
|
DM-4.2 |
Company |
Generate
Error Report |
Vendor_1
834 Change File |
·
TA1/999 ·
Email Record Level Error Report |
File
Level Error: ·
Return Original file to Vendor_1 ·
Provide Vendor_1 with TA1 and Error
Report ·
Go To DM-4.3 Record
Level Error: ·
Produce 999 error ·
Add error detail to LDNS report ·
Go to DM-5 |
|
|
|
DM-4.3 |
Company |
Return
File to Vendor_1 |
Vendor_1
834 Change File |
·
Original File ·
Error Report |
Go To
DM-End |
|
|
|
DM-4 |
Company |
Generate Record Count Reports |
Vendor_1 834 Change File |
999 and LDNS report |
Go to Step DM-5 |
|
See Company250-FDD for details |
|
DM-5 |
Company |
Send File to Vendor_2 |
Keyword File |
N/A |
Successful Transmission: Go to Step DM-End Unsuccessful Transmission: Go to Step DM-5.1 |
|
|
|
DM-5.1 |
Company |
Retry File Transmission |
Keyword File |
N/A |
·
Rule
##: If Vendor_2 server is down/file cannot be received on Vendor_2 side,
resent file after ## tries or after ## minutes. If Unsuccessful ·
Go to Step DM-1.1 If Successful ·
Go to DM-End |
|
|
|
DM-END |
End of Processing |
||||||
Alternate Flow
|
Step |
Actor(s) |
Action |
Input |
Output |
Expected
Outcome |
Applicable
Rule |
Req’s
Met |
|
AF-2 |
Company |
Send Acknowledgement of Receipt
of Audit file |
Vendor_1 Audit File |
N/A |
|
|
Retiree Audit: 834 File Transmission.002.005
Active Member Audit: Transmission.003.005
|
|
AF-3 |
Company |
Convert file from 834 Audit to Keyword File |
Vendor_1 Audit File |
· Vendor_2 Keyword File ·
Record Count Report(s) |
Successful Conversion: Vendor_2 Keyword File Record Count Reports Go To AF-4 Unsuccessful
Conversion: Email Error Report Go to AF-3.1 |
Loaded with issues SR1.4 SR1.5 SR1.6 Not
Loaded SR1.1 SR1.2
|
|
|
AF-3.1 |
Company |
Notify Business of File failure |
Vendor_1 834 File |
·
TA1 ·
Email File Level Error Report |
Email sent to business Go to Step AF-3.2 |
SR1.1 SR1.2
|
|
|
AF-3.2 |
Company |
Generate Error Report |
Vendor_1 834 File |
·
999 ·
Email Record Level Error Report |
File Level Error: Return Original file to Vendor_1 Provide Vendor_1 with TA1 and Error Report Go To DM-3.3 Record Level Error: Add error detail to LDNS report Go to DM-4 |
|
|
|
AF-3.3 |
Company |
Return File to Vendor_1 |
Vendor_1 834 File |
· Original File · Error Report |
Go To AF-End |
|
|
|
AF-4 |
Company |
Generate Record Count Reports |
Vendor_1 834 File |
999 and CSV/HTML report |
Go to Step AF-5 |
See Feature 250 FDD |
|
|
AF-5 |
Company |
Send Keyword File to Vendor_2 |
Keyword File |
Send with filename ??? to
indicate SHP Retiree Audit File Send with filename ??? to
indicate Active Audit file |
Successful Transmission: Go to Step 5 Unsuccessful Transmission: Rule ##: If Vendor 2 server is down/file cannot be received on Vendor_2 side, resent file after ## tries or after ## minutes. Go To Step 5 |
Rule ##: If Vendor_2 server is
down/file cannot be received on Vendor_2 side, resent file after ## tries or
after ## minutes. |
|
|
AF-END |
End of Processing |
||||||
System Rules
|
System Rule # |
Name |
System Rule |
Design
Considerations |
Level |
|
SR1.1 |
File
arrived after cut off time |
If the file is received from the enrollment vendor, after 6pm,
store file and process on the next business day |
Store and process next business
day |
File |
|
No Records Found |
The 834 Files received from Vendor_1 contains zero records. |
Return to Vendor |
File |
|
|
SR1.2 |
Percentage/Count of records exceed threshold for number
of SNIP 1-6 Errors |
The 834 Files received from Vendor_1 contain one or more file-level
HIPAA SNIP 1-6 errors. |
Return to Vendor |
Record |
|
SR1.4 |
Subscriber Name contains a number |
A Subscriber record is received on the 834 File
where any of the following data elements contains a number: 1) Subscriber First Name 2) Subscriber Last Name 3) Subscriber Middle Name |
Send with Warning |
Record |
|
SR1.5 |
Member Name contains a number |
A SHP Dependent record is received on the SHP 834 File
where any of the following data elements contains a number: 1) Dependent First Name 2) Dependent Last Name 3) Dependent Middle Name 4) Custodial Parent First Name 5) Custodial Parent Last Name 6) Custodial Parent Middle Name |
Send with Warning |
Record |
|
SR1.6 |
SSN is invalid |
A Dependent record is received on 834 File where
any of the below individual data element does NOT meet the character limits
for the following field: SSN |
Send with Warning |
Record |
Decision Tables/Matrix Diagram
These are my go-to tool for particularly tricky logic issues. These can be easily read an comprehended by business people and developers. They allow you to break a task down to simple yes or no, go or no-go scenarios. Always cover every scenario even if the scenario is impossible. The point here is to cover every possibility. This is especially useful when you have largely unimaginative developers. Some developers will be fine with an activity diagram and your textual use cases. However, lazy or inexperienced developers will rely solely on your logic to implement theirs. People may disagree with me on this point, but that is my opinion. When I was a developer we did not have the luxury of having an Analyst to tell us the logic we should follow and hence did not have someone to blame when we didn't fully think through our logic. And, trust me, your developers will attempt to throw you under the bus for something they missed or should have known. "I was just following the Functional Design" or "I thought the Functional Design Document had something different" will come out of their mouths whether it is valid or not. That is the nature of today's developers. Just being real with you.
The following is an example of a decision table or matrix diagram.
Mapping Documents
Conclusion
These are MY favorite tools for requirements and functional design. It's all about what you feel comfortable with. I happen to like the above tools because it is complete and leaves very little to developers imagination--very little they can "miss" and blame on you.
