Defining a step

Flow based user journeys are composed of one or more steps. All steps are located in the steps directory.

Schema

Steps are implemented as javascript objects and registered as part of a journey. To create a step, export a javascript object from the steps directory that implements the following schema:

Property	Type	Description
path	string	Path for the last segment of the URL (prefix with /)
template	string	name of the template to render the step
next optional	(req) => string	A function that takes an Express JS request object and returns the path for the next step in the journey
sanitize optional	(config, journey, step) => Express middleware	Middleware for sanitizing the incoming request
validate optional	(config, journey, step) => Express middleware	Middleware for validating the incoming request
pageContent	({ translate }) => {}	A function that takes a translation function and returns an object. All properties in the object are available in the step template
behaviourForGet optional	(config, journey, step) => Express middleware	Middleware that runs when a GET request is sent for the step
behaviourForPost optional	(config, journey, step) => Express middleware	Middleware that runs when a POST request is sent for the step
isNavigable optional	(req) => boolean	A function that takes an Express JS request object and returns a boolean to determine if the step can be navigated to
contentSummary optional	(req) => { key: string, value: string }	A function that takes an Express JS request object and returns a summary of the step used when rendering /check-answers
requestBody optional	(session) => {}	A function that takes the active session and returns key value pairs to be appended to the request to the claimant service
toggle optional	string	A key for feature toggling the step
shouldInvalidateReview optional	(claim) => boolean	A function that takes the claim object stored in session and returns a boolean to determine if the application state should be set to IN_PROGRESS

next

By default a journey will determine the next path in a journey based on the order of the steps. The next property provides the option to override this default behaviour e.g:

{
  ...
  next: req => req.session.colour === 'red' ? '/red-step' : '/green-step'
}

sanitize

Enables sanitizing the incoming request before validation or persisting data to the session. Takes the format of a function that returns Express JS middleware, giving access to config, the active journey and the active step e.g:

{
  ...
  sanitize: (config, journey, step) => (req, res, next) => {
    req.body.email = req.body.name.trim()
    next()
  }
}

validate

Enables validation of the incoming request. Takes the format of a function that returns Express JS middleware, giving access to config, the active journey and the active step.

The application assumes that express-validator is used for validation e.g:

{
  ...
  validate: (config, journey, step) => [
    check('firstName').isLength({ max: FIRST_NAME_MAX_LENGTH }),
    check('firstName').not().isEmpty()
  ]
}

N.B. it is valid to return an array of middleware functions

pageContent

Provides content that is accessible in the template defined on the step. The function takes a translate argument to facilitate string internationalisation e.g:

{
  ...
  pageContent: ({ translate }) => ({
    title: translate('myStep.title')
  })
}

isNavigable

By default a step is navigable by a user as long as the appropriate previous steps have been completed. Sometimes there is a requirement to enable or disable a step based on data set at another point of the journey lifecycle.

isNavigable enables more control over when a step can be accessed. If a step's isNavigable function returns false then it is omitted from the journey for that particular request e.g:

{
 ...
 isNavigable: req => req.session.name === 'Fred'
}

contentSummary

Returns an object with key and value properties used for rendering the claim summary on the /check-answers page e.g:

{
  ...
  contentSummary: req => ({
    key: 'name',
    value: req.session.claim.name
  })
}

requestBody

Returns an object with key value pairs to be appended to the request body that is sent to the claimant service at the end of the journey e.g:

{
  ...
  requestBody: session => ({
    name: session.claim.name
  })
}