Surplus National Workforce

Overview

Problem

In a high level, SNW is a web app that is built for PDO to solve the problem of matching employees of expiring contracts with other active contracts. The current process, which takes time, is done manually by the Emdad team. We want to build the web app to:

1. Automate the process of redeploying employees
2. Be used by Emdad team, contract holders, subject matter experts, and training institutes

There are 2 isolated flows in SNW, which are:

1. Redeployment flow
2. Training programs flow

Redeployment flow

The redeployment flow is the main one, which is concerned about redeploying employees for expiring contracts. Here is a look at the flow's happy path:

1. Read provided data views

Note that:

• contracts.is_extended field is only needed initially (when we get the data), but it's not needed afterwards since CH/Coordinators will set contract statuses in SNW.
• contracts.status is not needed since those statuses represent something else in the data source (MARS). The contracts status in SNW is different than the contract status retrieved from MARS. We are supposed to care about contracts that have the status approved in MARS.

The flow starts from the data provided by the Emdad team. Here is what is provided (the structure of the views is not confirmed yet):

the data in our database uses pgsodium to row encrypt specific confidential columns:

• contract holder email
• contract holder name
• civil IDs
• compensation per hour the encyrption is done using pgsodium. This uses Server Key Managment loads an external secret key into memory that is never accessible to SQL. SNW also uses Transparent Column Encryption to automatically encrypt and decrypt the columns. Each row uses its own key and nonce so no two rows use the same key.

2. Identify expiring contracts

The core of SNW is matching employees with new contracts, but before we do that, we want to identify the employees we want to redeploy. And in order to identify those employees, we want to look at the contracts.

If a contract is going to expire within a year, the contract holder will need to take action, otherwise, no action is needed.

3. Take action on expiring contracts (Contract Holders or Coordinators)

Note that:

• Contract statuses are:
  • Redeploy: means work is not done yet, but the contract will expire, hence, redeploy employees
  • Transfer: means work is not done yet, but transfer the contract to another company
  • Extension: the contract is extended
• Employee statuses are:
  • Redeploy: means we want to redeploy this employee to another contract
  • Retire: means the employee will retire (or is retired)
  • Retain: means the employee will stay in the same company

The steps for this stage are:

1. Send an email to CH notifying them a contract is expiring
2. They should select the contract's status. If transfer or extension, don't do anything. Otherwise, continue flow
3. If the status is redeploy, the CH will have to ensure the contract has an assigned coordinator.
4. The assigned coordinator will select which employees are redeployed/retired/retained.
5. The CH can then review the selection made by the coordinator. They can approve or reject the employee status chosen. Or they can select a new status, overwritting the coordinator.
6. Then, create a list of employees to be redeployed (with status redeploy), and continue the flow.

Note that if the CH didn't assign a coordinator to the contract then the redeployment flow will be halted, until a coordinator is assigned to handle redeployment.

4. Review employees to be redeployed (Emdad users)

After list of employees are chosen by the Coordinator and approved by the CH, Emdad users should approve each employee status. Any employee approved by EMDAD will go to the matcher, otherwise the declined employees will go back to the CH.

5. Matching process (AI)

This is the core of the application. The AI algorithm will take the list of employees to be redployed and suggest best contracts for each employee based on certain parameters/features, which are:

1. Employee's position (sub-category), qualification and category
2. Omani or Expat? If a contract contains a lot of expats, we should try to fill it with more Omanis
3. Same department

It will also take into account past manual assignments by emdad, and past actions of CH if they accept/decline.

6. Review Suggested Employees (Assigned Contract CH)

Contract Holders will go over the suggested employees for their contract and will:

1. Approve the employees they see are a good fit
2. Approve and Upskill, this means the employee is approved but with a training program assigned to them
3. Decline unfit employees.

Note that:

1. All CH's that own a contract with suggested employees (suggested by the matcher) will be notified to take action (every 2 weeks)
2. If CH/Coordinator didn't respond within 2 months, the tool will assume that they declined.
3. EMDAD will be notified when the employees are approved/declined.

Training programs flow

Gaining Access To SNW

• SNW is only accessible through PDO's Azure AD using SSO
• All users that enter SNW will automatically have a user role of none
• The emdad admin must assign the role of the users from their custom dashboard
  • The first emdad admin will be created by Rihal
• When a CH logs in SNW will automatically detect they are a contact holder and assign them with their role. This is the only user role thats automatically assigned. As the views provided by PDO have all the CH's already.

Contribution

Prerequisites

Before contributing (or running) this project, make sure that you have done the following:

1. Set up ~/.netrc file to pull rihal.tech/foundation library. Click here for instructions.
2. Set up ~/.npmrc file to pull private npm packages. Click here for instructions.

Running the web app for the first time

Run the following command from the root of the repo:

docker-compose up --build
# or
make dev-run

The --build flag will build server docker image, which is necessary to be built at first because it uses reflex package for live reloading.

After that, you can run the same command without --build flag.

Populating the db

To populate the db with dummy data, run the following command from the /server directory:

go run main.go populate

Which will populate the db without clearing it. Pass --clear to clear the db first (i.e. truncate tables).

List of flags:

Usage:
  serve populate [flags]

Flags:
      --clear                     If true, all tables will be cleared before population
      --contract_holders int      Number of contract holders (default 10)
      --contractors int           Number of contractors (default 3)
      --contracts int             Number of contracts (default 100)
      --db_host string            db hostname (default "localhost")
      --employees int             Number of employees (default 500)
  -h, --help                      help for populate
      --seed int                  Seed value that is used for generating random values (default 1656247840906441074)
      --training_institutes int   Number of training institutes (default 20)
      --training_programs int     Number of training programs (default 30)
      --users int                 Number of users (default 1000)

Note: make dev-run will run the containers then populate the db. It's been added for convenience.

Sample users

Sample users were added to make testing and development easier. The usernames are:

• contract_holder
• coordinator
• emdad_admin
• emdad_user
• training_institute
• cfdh

The password for all users is snw.

Note:

• contract_holder user is given ch_email_1@test.com. This user will be assigned contracts when the db is populated. However, make sure to upsert the user first, i.e. send a request to /api/user/login.

API endpoints docs

All API endpoints are added to the SNW collection in Postman. To view the documenation and examples of response/request bodies, contact one of the developers working on the project to share the collection with you.

SMTP client

We use mailhog as an SMTP client for development. To check emails sent by the server, go to http://localhost:8025