Legacy Camera Registry Integration

🚧

This page refer to an old API documentation

The integration to the registry uses a specific Agent protocol that is compatible with either a Cloud service or an on-premise implementation. The concept of the protocol is an agent-based job processing framework where agents (your integration) act as a client that communicates via REST with the Clearance Registry Agent service (the Registry). The Agent pool the service for available job to complete. Once a job is available the agent must lock the job and process it. Once the process is complete, it must complete the job with the service.

This document goes through the various functionalities that your agent must implement to properly integrate to the registry.

The integration to the registry allows you to display proprietary camera in the Clearance registry user interface and it also allows the automatic extraction of media from the external system to Clearance based on requests in the registry.

The full api documentation is available at https://cc-proda-api.clearance.network/agentservice/swagger

There are currently 3 types of job that the agent can do:

  • mediarequest : This job's objective is to extract a media file from the external/proprietary system.
  • discovery: This job's objective is to discover the available device in the external/proprietary system.
  • thumbnail: This job's objective is to extract a thumbnail image from the device in in the external proprietary system.

The authentication mechanism is the same across all Clearance APIs as explained in Authentication

Media Request Job

The first call the agents have to make is to get the jobs that are available for their agent.
If no jobs are returned, then there is nothing for the agent to do at this time. The agent should poll this endpoint at regular intervals to see if a new job has been posted.
Once the agent has a list of available jobs, he can chose, based on his own criteria which one he will take.
Once a job is selected, the agent will lock the job to avoid 2 agents working on the same job.
(Optional) The agent can report the progress of his work by updating the job. This is done by providing a « taskProgress » and a « taskTotal ». The progress will be divided by the total to obtain a progress percentage.
(Optional) The agent is also responsible for renewing his lock if the lock gets close to the expiration date provided. If the job is not renewed it will again be made available to be picked up and the progress will be lost.
Once the job is finished, the agent can complete the job with a state (Completed/PartiallyCompleted/Failed).

The actual processing of the job is explained in the 'Uploading the job result' section below.

Device Discovery Job

The process of discovering devices or thumbnails starts the same way as a media requests. A discovery-type job will be posted. The agent will poll for jobs. Once the job is available, the agent can chose to pick this job and lock it.

(Optional) The agent can provide updates on the progress of this job.

(Optional) The agent can renew the lock on the job if it gets close to the expiration time to avoid losing the lock and the progress on the current job.

Once the work is done, the agent will complete the job, similar as in a media request.

The actual processing of the job is explained in the 'Uploading the job result' section below.

Thumbnail Job

The process of the thumbnail job starts the same way as a media request job. A thumbnail-type job will be posted. The agent will poll for jobs. Once the job is available, the agent can chose to pick this job and lock it.

(Optional) The agent can provide updates on the progress of this job.

(Optional) The agent can renew the lock on the job if it gets close to the expiration time to avoid losing the lock and the progress on the current job.

Once the work is done, the agent will complete the job, similar as in a media request.

The actual processing of the job is explained in the 'Uploading the job result' section below.

Uploading a job result

After locking a job, the Agent knows he’s responsible for providing the requested files. To do so, the Agent will use the File APIs.

First, the Agent will call the InitializeMediaUpload/InitializeThumbnailUpload/InitializeDiscoveryUpload according to the job type.

Calling this endpoint will provide the Agent two important details:
-The file ID used when calling the API endpoints
-The JsonWebKey used to encrypt each block of the file that is being uploaded

Next, the Agent will start encrypting the file to send by blocks of 4 MB using the key provided and upload them to the upload endpoint. When calling this endpoint, each block will need to be identified by a block ID chosen by the Agent. All the block IDs will be needed at the end to complete the file upload.

Once all the blocks are uploaded. The Agent will call the complete endpoint with the list of block Ids in the order in which they should be read to form the file. The encryption metadata needs to be provided here.

Once the file upload is complete, the Agent can upload other files for the same job. If there was only 1 file, he can proceed to complete the job as shown in the previous diagrams.

Cancelling a job

If the agent cannot fulfill a job for any reason. He can choose to cancel it. The job will be cancelled and will not be made available again.

Releasing a job

If the agent cannot fulfill a job at this point in time but will be able to fulfill the job later. He can chose to release a job, this will make the job available again to be picked up by another agent. The agent will be free to choose which job he wants to take in the list of available jobs again.

Code sample

A code sample is available for download at this link but require a connection string provided by Genetec on request.