Integrate with the Camera Registry

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 InitializeUpload, a single endpoint for any job type.

Calling this endpoint will provide the Agent three 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
-The Uri, which contains the SAS token, specifying where to upload the file

Next, the Agent will encrypt the file and upload it using the key and the uri provided in the InitializeUpload response.

The encryption data then needs to be added to the file storage as a metadata, using "encryptiondata" as the metadata key and a serialized version of the EncryptionDataModel used to encrypt the file.

Once the file is uploaded, the Agent will call the CompleteMedia/CompleteDiscovery/CompleteThumbnail, according to the job type.

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.

EncryptionDataModel

/// <summary>
/// Data used for the encryption of the content and the key
/// </summary>
public class EncryptionDataModel
{
    /// <summary>
    /// Encryption IV used for the encryption of the content
    /// </summary>
    public byte[] ContentEncryptionIV { get; set; }

    /// <summary>
    /// Encryption information of the content
    /// </summary>
    public EncryptionDataAgentModel EncryptionAgent { get; set; }

    /// <summary>
    /// Encryption information of the key used to encrypt the content
    /// </summary>
    public EncryptionDataContentKeyModel WrappedContentKey { get; set; }
}

public class EncryptionDataAgentModel
{
    /// <summary>
    /// Encryption algorithm used for the content
    /// </summary>
    public string EncryptionAlgorithm { get; set; } = "AES_CBC_256";
}

public class EncryptionDataContentKeyModel
{
    /// <summary>
    /// Algorithm used to encrypt the content encryption key
    /// </summary>
    public string Algorithm { get; set; } = "RSA-OAEP";

    /// <summary>
    /// Encrypted content encryption key 
    /// </summary>
    public byte[] EncryptedKey { get; set; }

    /// <summary>
    /// Encryption key id
    /// </summary>
    public string KeyId { get; set; }
}

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.