katxeus/npis-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

new base npis-docs

Browse Source
This commit is contained in:
katxeus
2025-10-16 09:01:38 +03:00
parent 6a64eac91c
commit d2961071d9
62 changed files with 14836 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
docs/user-guide/intro.md Normal file
View File

@@ -0,0 +1,198 @@
---
sidebar_position: 1
label: 'Guides Overview'
---
<!-- import ReactPlayer from "react-player" -->
# Guide Introduction
All user guides documented here, are purposefully to serve as both training manuals and technical proxy (equivalency) to as **User Acceptance Tests (UATs)** for all NPIS use cases as specified in the [Software Requirements Specification (SRS) Document](../project-requirements/SRS#system-users-and-characteristics) for NPIS users to execute all case scenarios for their respective [system roles in the same SRS Document](../project-requirements/SRS#user-roles).
Users reading this guide are to select their respective user group/roles in the sidebar on the left under User Guides to complete these UATs and training by expanding the menu to further reveal a breakdown of all the usecases for the system tasks executable by their user role/group.
## NPIS Design and Features
All system units of functionality for all NPIS documented [system roles in the SRS Document](../project-requirements/SRS#user-roles), were synthesized into a service oriented architectural design that groups related functionality into microservices that are containerized to run indenpendently. The microservices architectural design shown below, allows specific user roles assigned to particular user groups be executable from particular microservices.
<!-- ![NPIS Architecture](/img/npis-microservice-architecture.jpg) -->
![NPIS Architecture](/img/npis_microservice_architecture.jpg)
The designed microservices that make up NPIS are outlined below:
### NPIS-IAM Microservice
All other microservices are configured to point to and be secured by the NPIS-IAM (Identity Access Management). NPIS-IAM uses open protocol standards **OpenID Connect** and **SAML 2.0** to secure other microservices and NPIS in all. NPIS frontend clients (Browser UI and NPIS mobile applications) redirect a user’s browser or app ui from the application to the NPIS-IAM as an authentication provider where they enter their credentials. This redirection is important because users are completely isolated from applications and applications never see a user’s credentials. Applications instead are given an identity token or assertion that is cryptographically signed. These tokens can have identity information like username, address, email, and other profile data. They can also hold permission data so that applications can make authorization decisions. These tokens are also used to make secure invocations on NPIS' REST-based other microservices that execute NPIS business logic.
### Forms Management Microservice
This is designed to incorporate all form designing/building and publishing functionality for licensing, inspection monitoring and enforcement in petroleum supply operations workflows. Also, it handles the versioning, captureing, storage, retrieval and rendering of captured form data.
### BPM Workflow Management Microservices
This microservice is responsible for providing the functionality for modelling or designing business process management workflows, for streamlining the automation of task execution during permits and licensing, volume storage and tracking, pricing, environmental assessment, monitoring and inspection, compliance enforcement, labs and quality assurance, LGP and standards business processes.
### Document Management Microservice
This encampasses all functionality to document genetation from form captured data from petroleum supply operation workflows, these includes: permits, licenses, physical application forms, reports like volumes, financial, etc. The same microservice also handles document digitization that enables migrations of legacy petroleum supply operations data into NPIS.
### Data Analysis Microservice
This microservice is designed to house all functionality to compute petroleum supply operations information insights using data visualization dashboards for policy input and forecasting. This uses regressional models and opion mining of large data volumes using the microservice sentimental analysis engine.
### NPIS Web API Gateway Microservice
This encampasses all units functionality that implements all petroleum supply operations business logic which includes ermits and licensing, volume storage and tracking, pricing, environmental assessment, monitoring and inspection, compliance enforcement, labs and quality assurance, LGP and standards business.
## User Groups
Specific PSD personel designations responsible for executing specific units of functionality (tasks) within NPIS have therefore been categorized into user groups to which roles granted with specific roles and permissions are granted. These are briefly outlined below:
### Administrator
A super user role granted the permissions to execute tasks for bootstraping NPIS from the group up with initial authorization and authentication data like user roles, groups, profiles, credentials, accounts as well as system identity data like mail and domains, plus system security requirements like cryptographic keys, ssl certificates, access tokens, account secrets, etc. Requirement Traceability Matrix (RTM) of the project does reference this requirement from [section 3.0 of the ToR](../project-requirements/ToR#row-one) and [section 10.0 of the ToR](../project-requirements/ToR#10.0).
:::tip[Requirements]
Users assigned to the admin user group are PSD IT personel who are required to be acquianted with system administrative knowledge with regard to, networks, security, databases, and special technical know how on technical standard (IETF RFC 6749 and 6750) known as **OpenID Connect (OIDC)**, an interoperable authentication protocol based on the OAuth 2.0 framework of specifications.
:::
:::danger[Requirements]
Any misconceptions or misunderstandings on this know-how, will result in NPIS improper setup or unusability.
:::
:::info[Learning Resources]
The user guide therefore provides such an introduction to the user in form of a prime, or brief introductory notes on the subject matter. An in the case the where there is more ground to cover beyond the scope of the project, the guide refers the users to curated resources online like links to learning material, standards, or vendor documentation.
:::
Users from this user group should select the admin submenu from the left sidebar for their tutorials and user guides.
### Form Designer
A user role granted the permissions to design and publish forms for all petroeleum supply operations including; petroleum construction permits, (retial or wholesale distribution), transport, storage, operating licenses, as well as enforcement monitoring and regulatory inspections. Requirement Traceability Matrix (RTM) of the project does reference this requirement from [section 6.0 of the ToR](../project-requirements/ToR#6.0)
:::tip[Requirements]
Users assigned to the Workflow modeller user group are PSD IT personel who are required to be acquianted with the [**ISO/IEC 11179-1:2023** ](https://www.iso.org/standard/78914.html) standard, an international standard for standardizing and registering metadata to make data understandable and shareable across different systems. This standard, along with others like [**IISO/IEC 15445:2000 DTD**](https://www.w3.org/People/mimasa/HTML/DTD/ISO-HTML/DTD-TREE.html)and for [HTML form controls](https://html.spec.whatwg.org/multipage/forms.html) elements like text inputs, checkboxes, and radio buttons used within a `<form>` to collect user data. Their functionality is defined by specifications from organizations like the W3C, The International Organization for Standardization (ISO) and the International Electrotechnical Commission (IEC) have specific standards that govern web accessibility and other aspects, which indirectly affect how these form controls are implemented to meet international requirements.
:::
:::danger[Requirements]
Any misconceptions or misunderstandings on this know-how, will result in NPIS forms unusability.
:::
:::info[Learning Resources]
The user guide therefore provides such an introduction to the user in form of a prime, or brief introductory notes on [HTML form controls](https://html.spec.whatwg.org/multipage/forms.html). An in the case the where there is more ground to cover beyond the scope of the project, the guide refers the users to curated resources online like links to learning material, standards, or vendor documentation.
:::
Users from this user group should select the form designer submenu from the left sidebar for their tutorials and user guides.
### Workflow Modeller
A user role granted the permissions to model Business Process Management (BPM) workflows to streamline and automate all petroeleum supply operations including; petroleum construction permits, (retial or wholesale distribution), transport, storage, operating licenses, as well as enforcement monitoring and regulatory inspections. Requirement Traceability Matrix (RTM) of the project does reference this requirement from [section 6.0 of the ToR](../project-requirements/ToR#6.0)
:::tip[Requirements]
Users assigned to the Workflow modeller user group are PSD IT personel who are required to be acquianted with the [**ISO/IEC 19510:2013** ](https://www.iso.org/standard/62652.html) standard for business process management (BPM) workflows which specifies the Business Process Model and Notation (BPMN). BPMN provides a standardized graphical notation for modeling business processes, making them understandable to all business stakeholders, from analysts to developers and managers. This standard, along with others like **ISO 9000**, helps organizations streamline operations, improve efficiency, and manage quality and risk through a process-centric approach.
:::
:::danger[Requirements]
Any misconceptions or misunderstandings on this know-how, will result in unfunctional NPIS workflows or general NPIS unusability.
:::
:::info[Learning Resources]
The user guide therefore provides such an introduction to the user in form of a prime, or brief introductory notes on [Business Process Model and Notation (BPMN) specification](https://www.omg.org/bpmn/). An in the case the where there is more ground to cover beyond the scope of the project, the guide refers the users to curated resources online like links to learning material, standards, or vendor documentation.
:::
Users from this user group should select the workflow modeller submenu from the left sidebar for their tutorials and user guides.
### NPIS Client
A user role granted with filling-out and submission permissions for ***starter forms*** that trigger or initiate petroeleum supply BPM operations workflows. These include; petroleum construction permits, retial or wholesale distribution, transport, storage, operating licenses as well as enforcement monitoring and regulatory inspections workflow forms.
:::tip[Requirements]
Users assigned to the NPIS Client user group are Oil Marketing Companies (OMCs) registered accounts and PSD officers to whom executing petroeleum supply operations workflows involves submitting partial or full forms as part of their composite user group roles.
:::
:::danger[Requirements]
Any misconfigured client roles, will result in unfunctional NPIS client accounts or general NPIS unusability.
:::
:::info[Learning Resources]
The user guide for client user roles will also be made available within client user accounts as quick start guides as sources of information so as client accounts like OMCs can learn how to use the system even if they don't directly have access to the documentation portal.
:::
Users from this user group should select the npis clients ubmenu from the left sidebar for their tutorials and user guides.
### NPIS Reviewer
A user role granted with filling-out and submission permissions for ***user task forms*** that model work or activity that needs to be done by a human actor when automated process execution arrives at their user task in petroeleum supply BPM operations workflows. These include; petroleum construction permits, retial or wholesale distribution, transport, storage, operating licenses review of earlier submitted application ***starter forms*** as well as enforcement monitoring and regulatory inspections workflow forms.
:::tip[Requirements]
Users assigned to the NPIS Reviewer user group are PSD officers to whom executing petroeleum supply operations workflows involves submitting partial or full forms as part of their composite user group roles in for example review of licesing application for say, errors and omissions etc.
:::
:::danger[Requirements]
Any misconfigured reviewer roles, will result in unfunctional NPIS reviewer user group accounts holders or general NPIS unusability.
:::
:::info[Learning Resources]
The user guide for reviewer user roles will also be made available within user accounts as quick start guides as sources of information so as client accounts like petrolem officers, supervising petroleum officers can learn how to use the system even if they don't directly have access to the documentation portal.
:::
Users from this user group should select the npis reviewer submenu from the left sidebar for their tutorials and user guides.
### NPIS Evaluator
A user role granted with filling-out and submission permissions for ***user task forms*** that model work or activity that needs to be done by a human actor when automated process execution arrives at their user task in petroeleum supply BPM operations workflows. These include; petroleum construction permits, retial or wholesale distribution, transport, storage, operating licenses evaluation of earlier submitted application ***starter forms*** or other ***user task forms*** as well as enforcement monitoring and regulatory inspections workflow forms.
:::tip[Requirements]
Users assigned to the NPIS Evaluator user group are PSD officers to whom executing petroeleum supply operations workflows involves submitting partial or full forms as part of their composite user group roles in for example adding an evaluation report of licesing or construction permit application..
:::
:::danger[Requirements]
Any misconfigured evaluator roles, will result in unfunctional NPIS evaluator user group accounts holders or general NPIS unusability.
:::
:::info[Learning Resources]
The user guide for evaluator user roles will also be made available within user accounts as quick start guides as sources of information so as client accounts like supervising or principal petroleum officers can learn how to use the system even if they don't directly have access to the documentation portal.
:::
Users from this user group should select the npis evaluator submenu from the left sidebar for their tutorials and user guides.
### NPIS Approver
A user role granted with filling-out and submission permissions for ***user task forms*** that model work or activity that needs to be done by a human actor when automated process execution arrives at their user task in petroeleum supply BPM operations workflows. These include; petroleum construction permits, retial or wholesale distribution, transport, storage, operating licenses evaluation of earlier submitted application ***starter forms*** or other ***user task forms*** as well as enforcement monitoring and regulatory inspections workflow forms.
:::tip[Requirements]
Users assigned to the NPIS approver user group are PSD officers to whom executing petroeleum supply operations workflows involves submitting partial or full forms as part of their composite user group roles in for example final approval of licesing or construction permit application..
:::
:::danger[Requirements]
Any misconfigured approver roles, will result in unfunctional NPIS approver user group accounts holders or general NPIS unusability.
:::
:::info[Learning Resources]
The user guide for approver user roles will also be made available within user accounts as quick start guides as sources of information so as client accounts like supervising or principal petroleum officers can learn how to use the system even if they don't directly have access to the documentation portal.
:::
Users from this user group should select the npis approver submenu from the left sidebar for their tutorials and user guides.
<!-- <div className="video__wrapper">
<ReactPlayer className="video__player" controls height="50%" src="/videos/Big_Buck_Bunny_360_10s_1MB.webm" width="50%" />
</div> -->
<!-- Adds a import GifPlayer from "react-gif-player"; to the markdown.
Inserts html like <GifPlayer gif="https://media.giphy.com/media/VhiAuDYHkNPydiNnOs/giphy.gif" /> -->