CaseFu Documentation

Learn how to write functional specification with CaseFu

Contents:

Installation

Prerequisites

To start using CaseFu, you will need the following:
  1. Node.js. Go for the latest LTS version. You may want to install it via a version manager, like NVM.
  2. A plain text file editor. vi (or Notepad) will do just fine, but you will enjoy an editor with support for Markdown and HTML syntax highlighting much more.

Project setup

  1. Create a new Node project (unless you already have one you can embed the FSD into):

    mkdir my-new-fsd
cd my-new-fsd
npm init

    and confirm (or answer) all the questions.

  2. Install the CaseFu CLI module:

    npm i casefu-cli --save-dev

  3. Add npm scripts. Add the following 2 rows into the scripts section of the package.json file:

    "scripts": {
  "build": "casefu build --sources fsd/**/*.md --target build/index.html",
  "serve": "casefu serve --sources fsd/**/*.md --target build/index.html --port 8080"
}

    The parameters above contain the default values. You can either omit them if you are happy with the default values, or you can tweak them to your liking.

  4. Create an fsd sub-directory (or your custom one if you have changed the default --sources parameter), the first source file Overview.md within it and put the following into the file:

    # My new system

Building the FSD

To build the output FSD, execute:

npm run build

The FSD is then available at build/index.html.

Writing the FSD

To continuously re-build the FSD whenever any source file changes, execute:

npm run serve

Then open a browser window and navigate to the URL given at the terminal.

As you write into the files in the fsd/ directory and save a file, the FSD output in the browser gets automatically refreshed.

System

Start with naming the system that you want to specify.

Add a description of the system and starting points into the FSD.

# systemName

...put system description here...

...put entry points into the documentation here...

Example FSD introduction:

# Acme Ordering system

This is the Functional Specification Document
for the Ordering system in Acme, Ltd.

## Menu
...

Sample Sample source file

Data model

Specify the system's data model.

Entities

Define an entity:

## Entity: Entity name `EntityCode`

### Attributes:

...attribute definitions go here...
where:
  • Entity name is the name of the entity.
  • EntityCode can be used to link to this entity. The EntityCode is by convention in PascalCase. The EntityCode is optional, if omitted, it is derived from the entity name.

Example entity definitions:

## Entity: Customer

## Entity: Order

### Attributes:
...put Order attribute definitions here...

## Entity: Order item `OrderItem`

Sample Sample source file

Attributes

An entity consist of attributes:

...entity definition...

### Attributes:

- Attribute name `attributeCode` (attributeStatus attributeDataType): exampleValue - attributeDescription
- ...another attribute here...
where:
  • Attribute name is the name of the attribute.
  • attributeCode can be used to link to this attribute. The attributeCode is by convention in camelCase. The attributeCode is optional, if omitted, it is derived from the attribute name.
  • attributeStatus is one of:
    • APK, autoGeneratedPrimaryKey: primary key generated automatically by the database
    • NPK, naturalPrimaryKey: natural (business) key of the entity that serves also as its primary key
    • FPK, foreignPrimaryKey: foreign key that is at the same time the primary key
    • PK, primaryKey: primary key
    • FK, foreignKey: foreign key
    • OFK, optionalForeignKey: optional foreign key
    • NK, naturalKey: natural key (same as business key), uniquely identifies the instance (unique and immutable)
    • BK, businessKey: business key (same as natural key), uniquely identifies the instance (unique and immutable)
    • U, unique: unique value
    • OU, optionalUnique: optional unique value
    • M, mandatory: mandatory value
    • V, version: version for optimistic locking, mandatory
    • S, status: entity status, mandatory
    • C, conditional: conditional value (optional or mandatory depending on other attribute values)
    • O, optional: optional value
    • RO, readOnly: read-only value
    • A relation cardinality, e.g. 1:1, 1:N, etc. More formally, it is composed of 2 relation-side cardinalities separated by colon :, where a relation-side cardinality is one of:
      • 1
      • 0..1
      • 1..1
      • N
      • 0..N
      • 1..N
      The N code can also be written as n or *. An M:N relation cardinality is also supported.
  • attributeDataType is the data type of the attribute. You can put anything here.
    • For primitive types, you might want to follow the data types of your database.
    • You can put a link to another entity here when the attribute is a relation or a foreign key.
    • To indicate a fixed list of allowed values use a supported prefix of enum: (including the space at the end) followed by the list of values separated by commas.
  • exampleValue is an example of a value that the attribute may hold. Providing an example value aids the reader in better understanding the attribute.
  • attributeDescription is an optional description of the attribute.

Example attribute definitions:

## Entity: Customer

### Attributes:

- Name
- Tax number `taxNo` (M varchar(14)) - The tax identification number of the company.
- Mobile (O varchar(30))
- Status (S enum: created, approved, disabled)
- Created by (n:1 `#User`)

Sample Sample source file

Screen mockups

Create mockups of the screens of the system you are building.

Screens

Define a screen:

## Screen: Screen name `/screen/code`

...put screen content here...
where:
  • Screen name is the name of the screen.
  • /screen/code can be used to link to this screen. The /screen/code is by convention in the form of URI-like /‑delimited path. The /screen/code is optional, if omitted, it is derived from the screen name.

Example screens:

## Screen: Create order `/orders/create`

...put Create order screen content here...

## Screen: Orders

...put Orders screen content here...

## Screen: Order detail `/orders/detail`

...put Order detail screen content here...

Sample Sample source file

Forms

A screen consists of forms and tables. To define a form use:

### Form: Form name

...form's fields go here...

or:

### ReadOnlyForm: Form name

...form's fields go here...
where:
  • The form keyword defines the default status of its fields.
    • Form: - fields are by default optional
    • ReadOnlyForm: - fields are by default read only
  • Form name is an optional name of the form.

Example form definition:

### Form: Customer

...put form fields here...

Sample Sample source file

Fields

A form consists of fields.

Define a field as follows:

...form defined here...

- Field name (fieldStatus fieldType: fieldTypeValue, fieldTypeValue, ...): fieldValue, fieldValue, ... - fieldHint
- ...another field here...
where:
  • Field name is the name of the field.
  • fieldStatus is one of:
    • R, required: field is marked with a red asterisk
    • O, optional
    • RO, readOnly: field is not editable
  • fieldType is one of:
    • text: plain text field
    • password: text field with the value hidden
    • date: field is marked with a calendar icon
    • time: field is marked with a clock icon
    • multiLine: multi-line text field
    • checkbox: a checkbox field, value is boolean (true or false)
    • select: a dropdown / combobox field that lets the user select a single value from a list of available values
    • typeAhead: a text field that lets the user type in any value, but suggests values from a list of available values
    • radios: list of radio buttons to select a single value from a list of fixed values
    • multiSelect: a dropdown / combobox field that lets the user select multiple values from a list of available values
    • checkboxes: list of checkboxes to select multiple values from a list of fixed values
  • For field types select, typeAhead, radios, multiSelect and checkboxes specify the field type values / options that will be available in the widget. The values are separated by comma ,.
    When the field type value for a select or multiSelect consists only of dashes -, it will produce a non-selectable "separator".
  • fieldValue is the value to pre-fill into the field. For field types multiSelect and checkboxes there can be multiple field values separated by comma ,.
  • fieldHint is a hint to be displayed below the field for the user of the system.

Example field definitions:

### Form:

- First name
- Last name (required text)
- Birth date (R date) - Format DD/MM/YYYY.
- Gender (radios: Male, Female)
- Country (select: USA, Canada, UK, Germany, France): USA
- I agree with terms and conditions (R checkbox): true - Agreement is mandatory to proceed.
- Registered (RO): 6/7/2016 12:34

Sample Sample source file

Field sets

You can wrap a set of fields into a card to put them visually together. To define a field set use:

...form defined here...

- FieldSet: Field set name

    - ...field-set fields defined here...

- ...other form fields defined here...
where:
  • Field set name is an optional name of the field set.

A field set can be used in any place a field could be used. This also means that field sets can be nested.

Example field set definition:

### Form: Order

- Order number

- FieldSet: Customer
    - Name
    - Tax number

- FieldSet: Contact
    - Name
    - E-mail

Sample Sample source file

Tables

A screen consists of forms and tables. To define a table use:

### Table: Table name

...table's columns go here...
where:
  • Table name is an optional name of the table.

Example table definition:

### Table: Order items

...put table columns here...

Sample Sample source file

Columns

A table consists of columns. Define a column as follows:

...table defined here...

- Column name (fieldStatus fieldType: fieldTypeValue, fieldTypeValue, ...)

    - columnValue
    - columnValue
    - ...

- ...another column here...

where fieldStatus, fieldType and fieldTypeValue are defined in the Fields section above.

Example column definitions:

### Table: Order items

- Product (R text)
    - Cigar
    - Pabst Blue Robot beer 6-pack
    - BendërBrau ColdFusion Stream Beer Premium
- Unit price (R)
    - 2.35
    - 3.24
    - 3.49
- Quantity (R)
    - 8
    - 1
    - 4
- Item total
    - 18.8
    - 3.24
    - 13.96

Sample Sample source file

System functionality

Functional notes in screens

Within screen mockups you can create notes that specify the functionality of the system. To distinguish them from the regular screen mockup itself, use block-quotes. Start the row with greater-than character >:

> System functionality specification.

The functional notes are displayed with yellow background.

Example link reference definitions:

...an action button is defined here...

> On pressing this button
> the system will perform such and such action.

Sample Sample source file

Actors

To create an actor:

## Actor: Actor name `ActorCode`

...actor description and goals specification go here...
where:
  • Actor name is the name of the actor.
  • ActorCode can be used to link to this actor. The ActorCode is by convention in PascalCase. The ActorCode is optional, if omitted, it is derived from the actor name.

Example actor definitions:

## Actor: Sales
### Goals
- [Create order](#OR-100)
- [List orders](#OR-110)

## Actor: Shipping
...goals of Shipping actor go here...

Sample Sample source file

Use cases

To create a use case:

## UC: `Use-case-code` Use case name

- Actors: linksToPrimaryActors
- ...other use case properties

### Main success scenario:

1. Step.
2. ...other steps...

### Extensions:

- Extension:
    - Extension step.
    - ...other extension steps...
- ...other extensions...
where:
  • Use-case-code can be used to link to this use case. The Use-case-code is by convention dash-separated. The Use-case-code is optional, if omitted, it is derived from the use case name.
  • Use case name is the name of the use case.
  • linksToPrimaryActors list the primary actors of the use case.

Example use case definition:

## UC: `OR-100` Create order

- Actors: `#Sales`
- Level: User goal

### Main success scenario:

1. User enters order data.
2. User enters order item data.
3. System calculates the `Item total` for each item
    and `Invoice total` for the whole order.
4. User saves the order.
5. System validates the data.
6. System creates new `#Order`.

### Extensions:

- 2a. User wants to order more than 1 item:
    - 2a1. User adds more item rows and fills them in.
- 2b. User wants to remove an item from the order:
    - 2b1. User deletes the item row.
- 5a. [Due date](#Order.dueDate) is in past:
    - 5a1. System displays error: Must be in future.

Sample Sample source file

References

References to other items of the FSD can be created via links and buttons.