Friday, April 09, 2021

My Analysis Toolkit

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

 

 

DM-4.1

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

SR1.1

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

Oh the unadulterated pleasure of having to do a mapping document! Okay...overly dramatic intro complete.  This is where you map data coming from a source system into your system and (most likely) output to a destination system.  They are not particularly difficult, but can be tedious.  This format is one that has been useful for me.


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.