7.2. Create missing address process

Name	Create Missing Address Request
Purpose	Allow Editors to add missing addresses to the system, so that they are not blocked during the data ingestion processes.
Linked user stories	4.28. Editor - Create temporary address
APIs used	POST /addresses
Scope	This process only handles the creation of the address in a temporary state. This state will allow the Editors to enter data into the vertical cabling database for that temporary address. The process of validating and approving the temporary addresses is out of the scope of this process.
Roles	Organisation Editor, System
Input	- address (mandatory) - site structure, including site → blocks → units (optional)
Output	- temporary address - the given site structure or the default one if not structure was provided

Detailed Process description

Main process

Step	Description	Actor(s)	Input(s)	Output(s)	Decision points
1	An Editor sends a “create address request”.	Editor	- Address (mandatory) - Site structure (optional)	-
2	The system checks if the address already exists	System	- Address (mandatory) - Site structure (optional)	- yes / no	If the address does not exist: - the ingestion process continues (Step 3) If the address exists: - An error is returned (E.1. Address exists)
3	The system checks if their are high confidence matches (e.g. potential spelling mistakes in the street / locality)	System	- Address	- list of high confidence matches (if any)	If no high confidence matches: - the ingestion process continues (Step 4) If high confidence matches are found: - Matches are returned to the Editor for verification (secondary process: S.1. High confidence address verification)
4	The system creates the address in the database with a flag indicating that it is a temporary address that is not yet validated.	System	- Address (with flag validated=false)	- Newly created address
5	The system checks if a site structure was sent with the “create address request”.	System	- Create address request	- yes / no	If a site structure is provided: - the provided structure is created. If no site structure is provided: - a default structure is created.
6.a	The system creates the provided site structure	System	- Requested site structure	- Newly created site structure
6.b	The system creates the default site structure	System	-	- Newly created default site structure
7	The system returns the created address and the site structure	System	-	- Newly created address and site structure
8	The Editor gets the newly requested address	Editor	-	- Newly created address and site structure

Secondary Processes

S.1. High confidence address verification

Step	Description	Actor(s)	Input(s)	Output(s)	Decision points
1	System returns a list of high confidence address matches	System	-	- list of high confidence matches
2	Editor verifies if the address is present in the list	Editor	- list of high confidence matches	- yes / no	If address not present: - the secondary process continues (S.1. Step 3) If address present: - the ingestion process is canceled (E.2. Address exists)
3	The Editor sends again a “create address request” but this time flags it as forced (force = true)	Editor	- Address (mandatory) - Site structure (optional)	-
4	The system checks if the address already exists	System	- Address (mandatory) - Site structure (optional)	- yes / no	If the address does not exist: - the main process continues (Step 4) If the address exists: - An error is returned (E.1. Address exists)

Error Processes

E.1. Address exists (System error)

Step	Description	Actor(s)	Input(s)	Output(s)	Decision points
1	System returns an error indicating that the address already exists	System	-	Error: Address exists

E.2. Address exists (Editor cancel)

Step	Description	Actor(s)	Input(s)	Output(s)	Decision points
1	Editor finds the address in the high confidence matches returned by the system. The process is canceled.	Editor	-	-

Additional Information

Address matching processes

Exact match (link to algorithm or process)

High confidence match (link to algorithm or process)

Default site structure

If no site structure is sent with the “address creation request”, a default site structure will be created composed of a site, to which one block is linked. No units are created by default, as more information is needed to create the units (floor, identification).

Exceptions

[400 Bad Request] Invalid input:

If mandatory fields are missing or fields are invalid, the system returns an error message.

[409 Already Exists] Address already exists

If the Editor attempts to add an address that already exists, an error is returned.

[300 Similar exists] High confidence matches

If the Editor attempts to add an address for which the system detects high confidence matches and the force flag is set to false, the system return an error 300 and the list of high confidence matches.

[500 Internal Server Error] System Error

If the system fails to save changes due to an internal error, it displays an appropriate message and logs the error for further investigation.