Risk Management - API Design

Challenge Objectives

 

• Design API specification (Swagger)

 

Project Background

 

We’re building a Risk Management tool. Intended app workflow is fairly simple - admin users define risk matrix and risk register and regular users use it to track risks for an activity and they can add actions to mitigate risk and get the final remaining risk number. Even though the workflow is simple, there are a lot of configurable options both on the admin and user side and making the tool flexible to support all those options is a high priority for the tool

 

This challenge is building the api specification and followup challenges will focus on building the backend, frontend and integration.

 

Technology Stack

 

• Swagger Open API Specification

• ERD

• Relational Database - PostgreSQL

Individual requirements

 

We’re aiming to create two things in this challenge:

• REST API specification document (swagger)

• Database structure - ERD

 

Application wireframes are provided in the forums and your task is to build an api and db structure to support all the features in those wireframes. See below for a short description of the app features.

 

There are two types of users in the app: admin and regular user.

 

User authentication is out of scope and will be developed in the future (or the app will be integrated with external authentication service), so for now just add a simple POST /login?username=xx that returns a jwt token for a user with username xx (and we can have several test users [username, role, id, externalParentId] configured in the backend) - this jwt token should be used for all other api calls.

 

Admin user is first defining a risk matrix - wireframe pages 34-54, and a risk register for that same matrix - wireframe pages 55-59

Risk matrix has the following properties (see wireframes page 37-38):

• Name (string)

• Type (string)

• Matrix size - X and Y dimension (positive integers)

• Labels for X and Y axis

• Sorting order for both axes

• Additional criteria columns (X axis columns)

• Additional criteria rows (Y axis columns)

• Short title for each criteria column

• Title for each criteria column

• Text for each combination of criteria column and each row (Y axis dimension)

• Name of each row (number of rows is equal to Y axis dimension)

• Name of each column (number of columns is equal to X axis dimension)

• Text for each combination of criteria row and each column (X axis dimension)

• Value for each combination of row and column (actual risk values)

• Risk categories definition (wireframe page 40) - ordered list:

  • Risk level range (ex 1-3)

  • Risk level label (ex II - see page 47)

  • Qualitative evaluation

  • Description

  • Color 

Those are just the underlying data attributes for defining a risk matrix. Additionally, each matrix should store presentation configuration attributes:

• Location of X and Y axis labels (start, middle, end) - two attributes, one for each axis

• Width of each criteria column (we’ll leave the interpretation of these attributes to frontend - just save a string value here - it’s up to the frontend developers to save either absolute width here or percentages)

 

Once a risk matrix is set up, the admin user has to configure a risk register for that matrix (matrix without a risk register won’t be used anywhere).  Risk register is a table with lots of configuration options that tracks risk changes for a particular activity. Admin users should configure it, and regular users will fill in the actual rows. Risk register has the following columns:

• RiskNo, HazardId, RiskType, Category, Reference that are all mandatory columns

• Risk Code, Risk Code 2, Event, Cause, Consequence - default columns that can be hidden 

• Initial risk section - for each value of “additional columns” in the risk matrix, user should enter value for X axis, value for Y axis, and risk (this will be auto calculated).

• Actions column, Status, Responsible, DueDate

• Remaining risk - similar to initial risk section - holds the information on the risk remaining from initial risk after taking the actions from “Actions” column

• Final Risk

• Comments

• Type (specific or generic)

• Additional columns

 

Admin can add additional columns to risk register and each of those columns has these attributes:

• Label 

• Filter enabled flag

• Type: Picklist, Text, Date

• Allowed values in case the type is picklist

 

Admin users can also choose which columns will be visible for the end user. All columns except for mandatory columns and final risk can be hidden. Finally, column width can be saved for each column for presentation purposes (same behavior as criteria columns - just save a string value and let the frontend handle the interpretation)

 

Now let's move on to the actual user of the risk matrix and risk register. Those are wireframe pages 9-32. Pages 6-9 are for illustrative purposes only and out of scope for this challenge (they are meant to associate risk assessments to different external objects like wellbores, designs, projects and we will work on that later on). 

 

Users will be entering data for a risk register table and that data is called risk assessment - essentially it’s just rows for the configured risk register table. Each risk assessment record will need to save values for each column defined in the risk register, plus the following data:

• Multiple actions can be saved for a risk assessment record and that will require saving multiple values for action, status, responsible and due date columns

• Flag that indicated weather the record is in the library or not

When risk assessment is saved, final risk will be calculated and stored - see the wireframes 27-29. Risks that are saved to the library will need to be searchable.

 

Your task is to design the API specification (swagger) and provide implementation notes for the followup challenge for each of the defined endpoints (no need to go into too much detail, just mention what the endpoint is doing and if there is any custom logic that needs to be implemented)

 

To accommodate integration into a larger system, backend will store additional info for all entities:

• externalParentId (ex projectId)

• externalType (ex ‘well bore’, ‘design’, ..)

• externalId (ex id of externalType stored in the larger system)

This will allow convenient data level access for multi-tenancy (assume JWT token will have externalParentId that the current user has access to) and grouping of risk assessments at different levels.

All entities should have timestamps (createdAt, updatedAt) and createdBy and updatedBy fields.

 

Followup tasks will be available for the challenge winner to define the relations of risk matrices/registers/assessments with external data (projects, sites, designs), and to create a mapping of api endpoints to wireframe screens.

What To Submit

 

Submit a Swagger API specification, ER diagram and any other documents that you think will better illustrate your api design.

Final Submission Guidelines

See above