1. Introduction

BCC Services is a software component used for biometric capture. The application is used to collect biometric images but does not automatically send them to the server. You can see how to send a capture to the GBDS in the Enrolling in the GBDS section.

Important

BCC Services do not save the collected biometrics and only maintain it in RAM while active. Restarting or shutting down the computer or closing BCC Services will result in the loss of the collections.

This manual describes the standard BCC Services biometric capture workflow and troubleshooting. See the BCC Services API specification for further information on the API calls.

This manual is updated to the BCC Services version 2.8.8.

2. Capture Workflow

This section will describe the capture workflow and the options of biometric captures you can perform with BCC Services. An example of the endpoint calls and responses can be seen in the Capture Workflow Example.

To start a capture, you need to call one of the Biometric Capture endpoints. Those are:

• Irises Capture
• Palm Capture
• Signature Capture
• Fingerprint Capture
• Newborn Palm Capture
• Face Capture
• Auxiliar Image Capture
• Full Profile Capture

Those captures can return one of two responses:

• 200, for OK
• 400, for ERROR

The 200 status will have a tguid field that you must save. Each Biometric Capture call will have its unique ID, regardless of how many captures are performed in the same call. i.e., you can perform the Fingerprint Capture call to collect all ten fingers, generating one tguid for all captures, or using the same endpoint ten times, generating a tguid for each fingerprint.

The Biometric Capture spawns a capture window. To get the capture status, perform the status call. This endpoint will return the capture status, the sensor informations and a partial information of what biometrics are captured.

You need to perform the status call until the status field value is captured. This will indicate that the capture is complete. Other statuses could be seen if the capture is incomplete, such as capturing if the capture window is still open or closed if the capture window was closed without finishing the capture.

When you get the captured status, you need to perform the getProfile call. This call response contains the .wsq and the .jpeg images. Those are in the buffer and converted-buffer field, respectively, as base64 bytearrays.

After a capture is finished, we recommend to save the images in a local database until you send them to the servers.

Danger

BCC Services saves the capture in RAM. Exiting BCC Services, shutting down or restarting the computer without persisting the transaction data will result in data loss.

After all needed captures are done, restart BCC services using the restartBcc call.

Warning

Restarting BCC Services will clean all transactions data in RAM. Guarantee that your data is saved before restarting BCC Services.

The restartBcc call will shutdown BCC Services and reopen it automatically. To guarantee that the software is running after the restart, perform a serviceStatus call and verify that the serverState field value is running.

2.1. Reopen incomplete capture window

If the user closed a capture window without finishing the capture, the status will return the status value as closed. You can continue an interrupted capture with the openCapture call passing the tguid provided by the Biometric Capture call. Doing so will maintain the capture progress.

2.2. Recovering TGUID

If you lost a transaction GUID for any reason, you can recover the tguid using the listCaptureInstances call. Inside the instances array field, you can find every biometric capture performed while BCC Services was active (if the transaction history was not cleaned). It will list in the execution order, the first one will be the first Biometric Capture called and the last will be the last Biometric Capture called. A response example is shown below.

{
    "result": "OK",
    "instances": [
        {
            "tguid": "F1F14ADA-6A00-4A67-B887-F574764ECC77",
            "type": "FINGERPRINT"
        },
        {
            "tguid": "DD08CEAA-B508-421D-8484-717DF01C0C55",
            "type": "SIGNATURE"
        },
        {
            "tguid": "EB321A10-F2B2-46DB-9479-8A6E5A1A485D",
            "type": "PROFILE"
        }
    ]
}

3. Troubleshooting

BCC Services have some troubleshooting calls that you can make to guarantee things are running correctly, your types of equipment are being identified, and the software version is known by you and the support team that may help you with your problem. Those calls are presented below.

3.1. Version

Checking the software version is essential to the troubleshooting scenario. To check BCC Services version, perform the version call.

3.2. Running

To verify if the program is running, use the serviceStatus call endpoint and look at the serverState field value.

3.3. Devices

BCC Services offers an option to show all devices that are connected with it. To display the device list, perform the deviceStatus call.

4. Shutdown

To shutdown BCC Services, call finishService

5. Capture Workflow Example

In this example, we will describe how to perform the calls for a register of a rolled capture of all left-hand fingers.

First, perform the Fingerprint Capture call with the following query:

Note

“captureMode” field do not affect the behaviour of BCC Services capture. This field is used to identify the operation in BCC application.

{
    "captureMode": "REGISTER",
    "notifyUrl": "",
    "theme": "DARK",
    "captureType": "ROLLED",
    "type": "FINGERPRINT",
    "sequenceControlType": "NONE",
    "indexes": [
        {
            "index": "LEFT_LITTLE"
        },
        {
            "index": "LEFT_RING"
        },
        {
            "index": "LEFT_MIDDLE"
        },
        {
            "index": "LEFT_INDEX"
        },
        {
            "index": "LEFT_THUMB"
        }
    ],
    "exceptionSetType": "SIMPLIFIED",
    "functions": [
        {
            "type": "RESET",
            "enabled": true
        },
        {
            "type": "CONFIG",
            "enabled": true
        },
        {
            "type": "CLEAR",
            "enabled": true
        },
        {
            "type": "CAPTURE",
            "enabled": true
        },
        {
            "type": "CANCEL",
            "enabled": true
        },
        {
            "type": "CAPTURE_NEW_IMAGE",
            "enabled": true
        },
        {
            "type": "IMAGE_PREVIEW",
            "enabled": true
        },
        {
            "type": "NEXT",
            "enabled": true
        },
        {
            "type": "OK",
            "enabled": true
        },
        {
            "type": "UPDATE_IMAGE",
            "enabled": true
        },
        {
            "type": "REMOVE_IMAGE",
            "enabled": true
        },
        {
            "type": "LIVE",
            "enabled": true
        },
        {
            "type": "ACQUIRE",
            "enabled": true
        },
        {
            "type": "SAVE",
            "enabled": true
        },
        {
            "type": "IMPORT",
            "enabled": true
        }
    ]
}

If the screen is successfully open, you will receive this JSON:

{
        "result": "OK",
        "tguid": "F1F14ADA-6A00-4A67-B887-F574764ECC77"
}

Copy this TGUID and start calling status. until you receive the captured status.

Important

Remember that other statuses, as closed, can also be returned if the operator does not complete the capture.

If no fingers were captured, the response should be:

{
    "result": "OK",
    "tguid": "F1F14ADA-6A00-4A67-B887-F574764ECC77",
    "type": "FINGERPRINT",
    "status": "CAPTURING",
    "operation": "INIT",
    "command": "INIT",
    "profile": {},
    "profileMetadata": {
        "profileVersion": "GBS BCC profile v2.8.7",
        "appName": "GBS BCC",
        "macAddress": [
            "08-62-66-80-D5-5C",
            "42-E2-30-11-DB-15",
            "42-E2-30-11-D3-15",
            "08-62-66-80-D4-94",
            "40-E2-30-13-F7-8A",
            "40-E2-30-11-D3-15"
        ],
        "softwareStatus": {
            "vendor": "Griaule Biometrics Ltda.",
            "version": "2.8.7.10805",
            "name": "GBS BCC Service"
        },
        "fingerprintPluggedDevices": [],
        "fingerprintStartedDevices": [],
        "faceDevice": {
            "productName": "OBS Virtual Camera",
            "serialNumber": "N/A",
            "firmwareVersion": "N/A"
        },
        "bodyDevice": {
            "productName": "OBS Virtual Camera",
            "serialNumber": "N/A",
            "firmwareVersion": "N/A"
        },
        "signatureDevice": {
            "serialNumber": "N/A"
        },
        "irisDevice": "IRITECH",
        "fields": [],
        "fingerprints": [],
        "palms": [],
        "bodyImages": []
    },
    "windowInfo": {
        "x": 683.0,
        "y": 237.0,
        "width": 685.0,
        "height": 579.0,
        "state": "NORMAL"
    }
}

If some fingers were captured, but the capture is not finished, status will respond with the partial capture information, as shown:

{
    "result": "OK",
    "tguid": "F1F14ADA-6A00-4A67-B887-F574764ECC77",
    "type": "FINGERPRINT",
    "status": "CAPTURING",
    "operation": "INIT",
    "command": "INIT",
    "profileMetadata": {
        "profileVersion": "GBS BCC profile v2.8.7",
        "appName": "GBS BCC",
        "macAddress": [
            "08-62-66-80-D5-5C",
            "42-E2-30-11-DB-15",
            "42-E2-30-11-D3-15",
            "08-62-66-80-D4-94",
            "40-E2-30-13-F7-8A",
            "40-E2-30-11-D3-15"
        ],
        "softwareStatus": {
            "vendor": "Griaule Biometrics Ltda.",
            "version": "2.8.7.10805",
            "name": "GBS BCC Service"
        },
        "fingerprintPluggedDevices": [],
        "fingerprintStartedDevices": [],
        "faceDevice": {
            "productName": "OBS Virtual Camera",
            "serialNumber": "N/A",
            "firmwareVersion": "N/A"
        },
        "bodyDevice": {
            "productName": "OBS Virtual Camera",
            "serialNumber": "N/A",
            "firmwareVersion": "N/A"
        },
        "signatureDevice": {
            "serialNumber": "N/A"
        },
        "irisDevice": "IRITECH",
        "fields": [],
        "fingerprints": [
            {
                "index": "LEFT_LITTLE",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left little",
                "image": {
                    "resolution": 500
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 96
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 72,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_RING",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left ring",
                "image": {
                    "resolution": 500
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 98
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 66,
                "captured": false,
                "extracted": true
            }
        ],
        "palms": [],
        "bodyImages": []
    },
    "windowInfo": {
        "x": 683.0,
        "y": 237.0,
        "width": 685.0,
        "height": 579.0,
        "state": "NORMAL"
    }
}

After the capture is finished, the status field will change to captured and the status call will answer with the following response:

Important

The “BYTEARRAY” values are strings in base64 format.

{
    "result": "OK",
    "tguid": "F1F14ADA-6A00-4A67-B887-F574764ECC77",
    "type": "FINGERPRINT",
    "status": "CAPTURED",
    "operation": "INIT",
    "command": "NONE",
    "profileMetadata": {
        "profileVersion": "GBS BCC profile v2.8.7",
        "appName": "GBS BCC",
        "macAddress": [
            "08-62-66-80-D5-5C",
            "42-E2-30-11-DB-15",
            "42-E2-30-11-D3-15",
            "08-62-66-80-D4-94",
            "40-E2-30-13-F7-8A",
            "40-E2-30-11-D3-15"
        ],
        "softwareStatus": {
            "vendor": "Griaule Biometrics Ltda.",
            "version": "2.8.7.10805",
            "name": "GBS BCC Service"
        },
        "fingerprintPluggedDevices": [],
        "fingerprintStartedDevices": [],
        "faceDevice": {
            "productName": "OBS Virtual Camera",
            "serialNumber": "N/A",
            "firmwareVersion": "N/A"
        },
        "bodyDevice": {
            "productName": "OBS Virtual Camera",
            "serialNumber": "N/A",
            "firmwareVersion": "N/A"
        },
        "signatureDevice": {
            "serialNumber": "N/A"
        },
        "irisDevice": "IRITECH",
        "fields": [],
        "fingerprints": [
            {
                "index": "LEFT_LITTLE",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left little",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 96
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 72,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_RING",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left ring",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 98
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 66,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_MIDDLE",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left middle",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 98
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 76,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_INDEX",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left index",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 100
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 71,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_THUMB",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left thumb",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 100
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 70,
                "captured": false,
                "extracted": true
            }
        ],
        "palms": [],
        "bodyImages": []
    },
    "windowInfo": {
        "x": 683.0,
        "y": 237.0,
        "width": 1000.0,
        "height": 579.0,
        "state": "NORMAL"
    }
}

Note

After a complete transaction, the status call answers with the .jpeg images.

Now it is time to perform the getProfile call. This call will answer with the images in .wsq and .jpeg images. The buffer field contains the .wsq images while the converted-buffer field contains the .jpeg images.

{
    "result": "OK",
    "tguid": "F1F14ADA-6A00-4A67-B887-F574764ECC77",
    "type": "FINGERPRINT",
    "status": "CAPTURED",
    "operation": "INIT",
    "command": "NONE",
    "profile": {
        "fingerprints": [
            {
                "index": "LEFT_LITTLE",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left little",
                "image": {
                    "buffer": "BYTEARRAY",
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "buffer": "BYTEARRAY",
                    "quality": 96
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 72,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_RING",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left ring",
                "image": {
                    "buffer": "BYTEARRAY",
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "buffer": "BYTEARRAY",
                    "quality": 98
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 66,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_MIDDLE",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left middle",
                "image": {
                    "buffer": "BYTEARRAY",
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "buffer": "BYTEARRAY",
                    "quality": 98
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 76,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_INDEX",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left index",
                "image": {
                    "buffer": "BYTEARRAY",
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "buffer": "BYTEARRAY",
                    "quality": 100
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 71,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_THUMB",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left thumb",
                "image": {
                    "buffer": "BYTEARRAY",
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "buffer": "BYTEARRAY",
                    "quality": 100
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 70,
                "captured": false,
                "extracted": true
            }
        ]
    },
    "profileMetadata": {
        "profileVersion": "GBS BCC profile v2.8.7",
        "appName": "GBS BCC",
        "macAddress": [
            "08-62-66-80-D5-5C",
            "42-E2-30-11-DB-15",
            "42-E2-30-11-D3-15",
            "08-62-66-80-D4-94",
            "40-E2-30-13-F7-8A",
            "40-E2-30-11-D3-15"
        ],
        "softwareStatus": {
            "vendor": "Griaule Biometrics Ltda.",
            "version": "2.8.7.10805",
            "name": "GBS BCC Service"
        },
        "fingerprintPluggedDevices": [],
        "fingerprintStartedDevices": [],
        "faceDevice": {
            "productName": "OBS Virtual Camera",
            "serialNumber": "N/A",
            "firmwareVersion": "N/A"
        },
        "bodyDevice": {
            "productName": "OBS Virtual Camera",
            "serialNumber": "N/A",
            "firmwareVersion": "N/A"
        },
        "signatureDevice": {
            "serialNumber": "N/A"
        },
        "irisDevice": "IRITECH",
        "fields": [],
        "fingerprints": [
            {
                "index": "LEFT_LITTLE",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left little",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 96
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 72,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_RING",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left ring",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 98
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 66,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_MIDDLE",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left middle",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 98
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 76,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_INDEX",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left index",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 100
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 71,
                "captured": false,
                "extracted": true
            },
            {
                "index": "LEFT_THUMB",
                "type": "ROLLED",
                "typeIndexKey": "ROLLED-left thumb",
                "image": {
                    "resolution": 500,
                    "converted-buffer": "BYTEARRAY"
                },
                "height": 480,
                "width": 320,
                "template": {
                    "quality": 100
                },
                "captureType": "FLAT",
                "nfiq": 1,
                "contrast": 70,
                "captured": false,
                "extracted": true
            }
        ],
        "palms": [],
        "bodyImages": []
    },
    "windowInfo": {
        "x": 683.0,
        "y": 237.0,
        "width": 685.0,
        "height": 579.0,
        "state": "NORMAL"
    }
}

After the capture is done, you can send the images to the server. To understand how to enroll the captured biometrics in the GBDS, proceed to the next section.

5.1. Enrolling in the GBDS

Call the enroll endpoint if you want to enroll the previously captured images to the GBDS.

In the payload you need to insert the keys information, the biographics. Inside the biometric array, you will need to insert the data from BCC Services getCapture endpoint.

The buffer field value on BCC Services needs to be placed on the content field value in the JSON payload to the GBDS.

See also

For more information about operations on GBDS, see the GBDS Integration Manual.

The example payload to perform the enrollment is shown below:

{
        "meta":{
        "priority":"DEFAULT_PRIORITY",
        "timeout":"-1"
    },
    "data":{
            "keys": [
    {
        "id": "CPF",
        "value": "618.323.606-44"
    }
    ],
    "biographics": [
    {
        "id": "name",
        "value": "John Doe"
    }
    ],
"biometric": [
        {
        "source": "ORIGINAL",
        "type": "FINGERPRINT",
        "format": "WSQ",
        "properties": {
            "width": 0,
            "height": 0,
            "resolution": 500,
            "ratio": 0.0,
            "matcherId": 0,
            "extractorId": 0
        },
        "index": 0,
        "content": "BYTEARRAY"
        },
        {
        "source": "ORIGINAL",
        "type": "FINGERPRINT",
        "format": "WSQ",
        "properties": {
            "width": 0,
            "height": 0,
            "resolution": 500,
            "ratio": 0.0,
            "matcherId": 0,
            "extractorId": 0
        },
        "index": 1,
        "content": "BYTEARRAY"
        },
        {
        "source": "ORIGINAL",
        "type": "FINGERPRINT",
        "format": "WSQ",
        "properties": {
            "width": 0,
            "height": 0,
            "resolution": 500,
            "ratio": 0.0,
            "matcherId": 0,
            "extractorId": 0
        },
        "index": 2,
        "content": "BYTEARRAY"
        },
        {
        "source": "ORIGINAL",
        "type": "FINGERPRINT",
        "format": "WSQ",
        "properties": {
            "width": 0,
            "height": 0,
            "resolution": 500,
            "ratio": 0.0,
            "matcherId": 0,
            "extractorId": 0
        },
        "index": 3,
        "content": "BYTEARRAY"
        },
        {
        "source": "ORIGINAL",
        "type": "FINGERPRINT",
        "format": "WSQ",
        "properties": {
            "width": 0,
            "height": 0,
            "resolution": 500,
            "ratio": 0.0,
            "matcherId": 0,
            "extractorId": 0
        },
        "index": 4,
        "content": "BYTEARRAY"
        }
]
}
}