Collections

It is useful to aggregate Persons in your organization into groups.

Whether the groups are departments, sub-divisions, or even your own customers, groups are helpful to stay organized.

In our parlance, a group of persons in called a Collection

Let us now create a Collection

Create a Collection

A Collection has a name and a description. It also has an id, but that is auto-assigned by the system.

Let's create a new Collection with the name My Groovy Collection, and with the description Groovy or Boring:

from opencv.fr.collections.schemas import CollectionBase
my_collection = CollectionBase("My Groovy Collection", "Groovy or Boring")
my_collection = sdk.collections.create(my_collection)
print(my_collection)
print(my_collection.id)

If you enter the above in a cell in your notebook (or a Python command line), and execute it, a Collection should be created. You're on your way to more impressive feats!

List Collections

The proof of the pudding is in its eating. Yes!, you created a Collection but how will anyone ever know you did so?

Our SDK allows you to list all collections you ever created. To do so, you can execute the following code in your next adventurous exploration:

all_collections = sdk.collections.list()
print(all_collections)

This should give you a result like the following:

{
        'count': 1, 
        'collections': [
                {
                        'id': '59939f5a-08dc-4769-bd5d-2aa41bcfb80f', 
                        'name': 'My Groovy Collection', 
                        'description': 'Groovy or Boring', 
                        'count': 0, 
                        'create_date': '2022-07-12 11:02:52.860200', 
                        'modified_date': '2022-07-12 11:02:52.860203'
                }
        ]
}

There are a couple of things going on here.

First, the count tells you that there are a total number of 1 collections in your database. The next attribute collections shows you the actual collections (as a list). Each collection has its own count which indicates how many persons are members of the collection.

When you print any of the objects in this SDK, it looks like a dictionary. However, these are actual objects and you can access their properties.

As an example, I can print the total count as follows:

print(all_collections.count)

Filtering Collections

In the previous example, we called sdk.collections.list() without specifying any qualifiers.

Certainly, it's good to see that we actually created a collection, but, if we have many of them, then listing all of them, at the same time, might not be such a good idea would it?

That is why our API allows additional parameters to filter collections!

Here is the full documentation of our sdk.collections.list() function:

def list(self, skip:Optional[int]=0, 
         take:Optional[int]=20, 
         order:Optional[SortOrder]=SortOrder.ASC, 
         search:Optional[str]=None) -> CollectionList:
        """Get a collections list 

        :param skip: skip the specified number of initial rows, defaults to 0
        :type skip:Optional[int]
        :param take: get the specified number of rows, defaults to 20
        :type take:Optional[int]
        :param order: order ascending(SortOrder.ASC) or descending(SortOrder.DESC)
        :type order:Optional[SortOrder]
        :param search: a search string to filter collections by name/description
        :type search:Optional[str]

        :raises API.ApiError: an API error if unsuccessful

        :return: a CollectionList object
        :rtype: CollectionList
        """

The skip parameter tells the system to skip the specified number of records from the beginning of matched records.

The take parameter tells the system to get the specified number of records from the skip position. if take is 20, then the system will return 20 records (unless there are less than 20 from the skip position).

The order parameter specifies an order (ascending or descending).

The search parameter filters collections that contain the search string in either their name or description.

These parameters can help developers implement paging and sorting in a front end application.

Getting a specific Collection

You can get a collection by its id:

my_collection = sdk.collections.get(my_collection.id)
print(my_collection)

Updating a Collection

You can update a Collection either after creating it, or after getting it (through sdk.collections.get() or through sdk.collections.list()):

Create:

from opencv.fr.collections.schemas import CollectionBase
my_collection = CollectionBase("My Groovy Collection", "Groovy or Boring")
my_collection = sdk.collections.create(my_collection)

Get:

my_collection = sdk.collections.get(my_collection.id)

As long as my_collection is a valid reference to a collection, you can update it like so:

my_collection.name = "My Speedy Collection"
my_collection = sdk.collections.update(my_collection)
print(sdk.collections.list())

Adding and removing multiple persons from a specific Collection

Given a list of person ids that you would like to add to or remove from a specific collection id, the following code can enable you to do so:

from opencv.fr.collections.schemas import UpdateCollectionRequest
update_collection_request = UpdateCollectionRequest()
update_collection_request.collection_id = my_collection.id
update_collection_request.new_person_ids = [my_person1.id]
update_collection_request.removed_person_ids = [my_person2.id]
update_collection_response = sdk.collections.update_collection_persons(update_collection_request)

The code will add my_person1 to the collection and my_person2 will be removed from the collection.

Deleting a specific Collection

If you know the id of a collection, you can delete is like so:

sdk.collections.delete(my_collection.id)
print(sdk.collections.list())