Notification Flows

Whenever GBDS performs enrollment and update operations, notifications are sent to designated endpoints to inform its result. The entity responsible for this flow is called Notifier.

This document describes some of the notification flows during enrollment and update operations.

For further information about the notification flows during sequence and quality control, see the Sequence and Quality Control documentation.

Any notification sent by the Notifier is an HTTP POST to a configured endpoint (http://<address>:<port>) containing a JSON object. The JSON model for each notification is shown below.

The endpoint to receive notifications must be individually implemented for any system.

The notifier only accepts 200 as an OK response.

Transaction Accepted

All asynchronous transactions received will be enqueued. After processing, a notification is sent informing that the operation was completed.

The notification message will be as the following example:

{
	"operation": "<operation>",
	"tguid": "<tguid>",
	"status": "<status>"
}

The possible operations in this step are: ENROLL, UPDATE, or SEARCH.

The notifier may return diferent statuses according to the operation being performed. The possible final statuses are:

Operation	Status
Enroll/Update	ENROLLED, FAILED
Search	MATCH, NOT_MATCH, FAILED, PERSON_NOT_FOUND

The FAILED status occurs whenever a transaction is aborted or can't be finished.

The PERSON_NOT_FOUND status occur when a 1:1 search is requested, but the reference profile does not exist for the provided key.

In some cases, GBDS identifies a transaction that could not be finished and requires further action. These scenarios generate different statuses and are described in the following sections.

Transaction Sent to Manual Review

In cases where the GBDS identified issues related to sequence or quality control and the transaction was sent to manual review for corrections, a notification will be sent informing that the enrollment is pending, as shown in the following example:

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "PENDING"
}

For further information about the notification flows during sequence and quality control, see the Sequence and Quality Control documentation.

See the MIR Manual for further information about how to deal with transactions sent to manual review.

Transaction with Biometric Exception

If an exception is generated while processing the transaction, the entrant transaction will be sent to exception treatment for analysis. In this case, a notification is sent informing that the transaction incurred into an exception, as shown in the following example:

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "EXCEPTION"
}

Notifications generated by Update operations will not differ the “operation” field, then the "operation": "ENROLL" field will be equal for both operation types.

See the ETR Manual for more information about how to treat exceptions.

Exception Treatment

The exception treatment process will generate different notifications based on the decision provided, the notification flows for each decision will be presented in this section.

Enrollment Exception - Same fingers

This decision confirms that the biometrics in both registers are from the same person, hence the entrant transaction fails the enrollment and is discarded. The notification endpoint, in this case, will receive a notification describing the exception treatment operation followed by another one, indicating the failed enrollment, as shown below:

{
	"operation": "TREAT_EXCEPTION",
	"tguid": "<tguid>",
	"status": "OK",
	"treatment": "SAME_FINGERS"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "FAILED"
}

Enrollment Exception - Different fingers

This decision denotes the match was a false-positive, so the entrant and the reference register contain different biometric sets. In this case, the enrollment must be accepted, and the notification describing the exception treatment operation will be followed by another one, indicating the successful enrollment, as shown below:

{
	"operation": "TREAT_EXCEPTION",
	"tguid": "<tguid>",
	"status": "OK",
	"treatment": "DIFFERENT_FINGERS"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}

Enrollment Exception - Merge transactions

This option confirms that the biometrics in both registers are from the same person, but decides for unifying the registers with both's biometric and biographic data. In this case, the entrant transaction must be accepted, so the notification describing the exception treatment operation will be followed by another one, indicating the successful enrollment, as shown below:

{
	"operation": "TREAT_EXCEPTION",
	"tguid": "<tguid>",
	"status": "OK",
	"treatment": "MERGE_TRANSACTIONS"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}

Enrollment Exception - Recollect

This decision implies that there is an error in the entrant enrollment, and the biometrics must be recollected. In this case, the entrant transaction will fail, and the notification describing the exception treatment operation will be followed by another one, indicating the failed enrollment, as shown below:

{
	"operation": "TREAT_EXCEPTION",
	"tguid": "<tguid>",
	"status": "OK",
	"treatment": "RECOLLECT"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "FAILED"
}

Update Exception - Same fingers

This decision denotes the no-match was a false-negative, and the biometrics in both registers are from the same person, hence the entrant transaction is successfully enrolled. The notification endpoint, in this case, will receive a notification describing the exception treatment operation followed by another one, indicating the successful enrollment, as shown below:

{
	"operation": "TREAT_EXCEPTION",
	"tguid": "<tguid>",
	"status": "OK",
	"treatment": "SAME_FINGERS"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}

Update Exception - Different fingers

This decision confirms that the biometrics in both registers are not from the same person, hence the entrant transaction fails and is discarded. The notification endpoint, in this case, will receive a notification describing the exception treatment operation followed by another one, indicating the failed enrollment, as shown below:

{
	"operation": "TREAT_EXCEPTION",
	"tguid": "<tguid>",
	"status": "OK",
	"treatment": "DIFFERENT_FINGERS"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "FAILED"
}

Update Exception - Recollect

This decision implies that there is an error in the entrant enrollment, and the biometrics must be recollected. In this case, the entrant transaction will fail, and the notification describing the exception treatment operation will be followed by another one, indicating the successful enrollment, as shown below:

{
	"operation": "TREAT_EXCEPTION",
	"tguid": "<tguid>",
	"status": "OK",
	"treatment": "RECOLLECT"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "FAILED"
}

Update Exception - Incorrect Enroll

This decision implies that there is an error in the reference enrollment, so the profile must be discarded. In this case, the entrant transaction will succeed and replace the reference one. The notification describing the exception treatment operation will be followed by another one, indicating the successful enrollment, as shown below:

{
	"operation": "TREAT_EXCEPTION",
	"tguid": "<tguid>",
	"status": "OK",
	"treatment": "INCORRECT_ENROLL"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}

Unsolved Latent Match

Whenever performing a search against the unsolved latents database, if there is a match, the notification endpoint will receive an enrollment notification containing the reverse latent match description and pointing the UGUID of the matching UL. After that, the transaction will continue to a normal enrollment process, that will generate another enrollment notification containing the result for the search against the normal reference database, being it a successful enrollment or an exception, as shown below (for a successful enrollment):

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "REVERSE_LATENT_MATCH",
	"uguid": "<uguid>"
}

{
	"operation": "ENROLL",
	"tguid": "<tguid>",
	"status": "ENROLLED"
}