➡️ Migrations

➡️ Migrations#

Upgrade to V2#

Note

This page lists all non-backward compatible changes made by version 2 of the framework. It is important to read it in its entirety to update your configurations and your code when upgrading from any version 1.X.X to 2.0.0 or higher.

Python#

OlvidClient#

Configuration#

The configuration of different Olvid clients has been standardized. This may result in changes to environment variables in docker-compose.yaml files, in .env files, or during instantiation of the OlvidClient and OlvidAdminClient classes.

  • The environment variables DAEMON_HOSTNAME, DAEMON_PORT and OLVID_DAEMON_TARGET have been removed in favor of the OLVID_DAEMON_URL variable. The new variable corresponds to the daemon’s full access URL.

OLVID_DAEMON_URL=http://daemon:50051

Note

The OlvidClient attribute daemon_target has also been renamed to daemon_url.

  • The configuration files .client_key and .admin_client_key are no longer supported, please use a .env file instead, with the following variables:

OLVID_CLIENT_KEY=00000000-0000-0000-0000-000000000000
OLVID_ADMIN_CLIENT_KEY=00000000-0000-0000-0000-000000000000
Methods#

  • the methods add_command and remove_command are replaced by add_listener and remove_listener.

from olvid import OlvidClient, datatypes, listeners

async def help_cmd(message: datatypes.Message):
    await client.message_send(discussion_id=message.discussion_id, body="Help")

client: OlvidClient = OlvidClient()
client.add_listener(listeners.Command(handler=help_cmd, regexp_filter="!help"))

  • normalization of method names that use files, involving renaming some methods.

from olvid import OlvidClient, datatypes, listeners

client: OlvidClient = OlvidClient()

async def change_identity_photo(photo_path: str):
    await client.identity_set_photo_file(file_path=photo_path)

async def change_group_photo(group_id: int, photo_path: str):
    await client.group_set_photo_file(group_id=group_id, file_path=photo_path)

OlvidBot#

The OlvidBot and OlvidClient classes have been merged, you can replace all uses of the class OlvidBot with OlvidClient.

from olvid import OlvidClient, datatypes

class Bot(OlvidClient):
    @OlvidClient.command("!help")
    async def help_cmd(self, message: datatypes.Message):
        await self.message_send(discussion_id=message.discussion_id, body="Help")

datatypes#

Certain methods associated with objects from the datatypes module now take an instance of the class OlvidClient as a parameter. Here are some NON-EXHAUSTIVE examples of changes.

from olvid import OlvidClient, datatypes

class Bot(OlvidClient):
    async def on_message_received(self, message: datatypes.Message):
        await message.reply(client=self, body=f"**{message.body}**")
        await message.react(client=self, reaction="🪿") 
    
    async def on_discussion_new(self, discussion: datatypes.Discussion):
        await discussion.post_message(client=self, body="Welcome !")

tools#

Removal of classes tools.AutoInvitationBot, tools.DiscussionRetentionPolicyBot, tools.SelfCleaningBot and tools.KeycloakAutoInvitationBot. The OlvidClient class now includes methods for configuring daemon behavior.

from olvid import OlvidClient

async def main():
    client = OlvidClient()
    # replace tools.AutoInvitationBot()
    # accept any invitation
    await client.enable_auto_invitation(accept_all=True)

    # replace tools.SelfCleaningBot() and/or tools.DiscussionRetentionPolicyBot()
    # keep only 20 messages by discussion, delete messages older than one day and delete messages in locked discussions
    await client.set_message_retention_policy(existence_duration=60*60*24, discussion_count=20, clean_locked_discussions=True)

    # replace tools.KeycloakAutoInvitationBot()
    # for keycloak bots only: invite every new user on your keycloak instance
    await client.enable_keycloak_auto_invite(auto_invite_new_members=True)

Listeners#

The concept of listeners has evolved to use the notification filtering mechanism introduced in version 1.4.0. The following changes stem from this desire for standardization with other clients. To learn more about using listeners, click here.

  • removal of the concept of checkers, use filters instead.

  • removal of the priority parameter.

  • The parameter count is now strictly positive, you must now use the value 0 for an infinite listener (and no longer -1).

Javascript#

Configuration#

The configuration of different Olvid clients has been standardized. This may result in changes to environment variables in docker-compose.yaml files, in .env files, or during instantiation of the OlvidClient and OlvidAdminClient classes.

  • The environment variable OLVID_DAEMON_TARGET has been replaced by the variable OLVID_DAEMON_URL. The new variable corresponds to the full access URL of the daemon.

OLVID_DAEMON_URL=http://daemon:50051

Note

The OlvidClient attribute serverUrl has also been renamed daemonUrl.

Protobuf#

The version of the protobuf library has been updated in the npm packages @olvid/bot-node and @olvid/bot-web. This impacts the usage of generated code. For more information on these changes, please refer to the bufbuild migration guide.

The main change concerns the creation of new protobuf objects

import {OlvidClient} from "@olvid/bot-node";
import {create} from "@bufbuild/protobuf";

let messageFilter = create(datatypes.MessageFilterSchema, {location: datatypes.MessageFilter_Location.HAVE})}

tools#

Removal of classes tools.AutoInvitationBot, tools.DiscussionRetentionPolicyBot, tools.SelfCleaningBot and tools.KeycloakAutoInvitationBot. The OlvidClient class now includes methods for configuring daemon behavior.

from olvid import OlvidClient

async def main():
    client = OlvidClient()
    # replace tools.AutoInvitationBot()
    # accept any invitation
    await client.enable_auto_invitation(accept_all=True)

    # replace tools.SelfCleaningBot() and/or tools.DiscussionRetentionPolicyBot()
    # keep only 20 messages by discussion, delete messages older than one day and delete messages in locked discussions
    await client.set_message_retention_policy(existence_duration=60*60*24, discussion_count=20, clean_locked_discussions=True)

    # replace tools.KeycloakAutoInvitationBot()
    # for keycloak bots only: invite every new user on your keycloak instance
    await client.enable_keycloak_auto_invite(auto_invite_new_members=True)

datatypes#

The shortcut methods associated with objects from the datatypes module have been moved to a separate helpers module. Here are two examples with the Message.reply and Discussion.postMessage methods, but these are not the only affected methods.

import {OlvidClient, datatypes, helpers, onMessageReceived, onDiscussionNew} from "@olvid/bot-node";

class ExampleBot extends OlvidClient {
    @onMessageReceived()
    async messageReceived(message: datatypes.Message) {
        // replace: await message.reply(this, "pong")
        await helpers.message.reply(this, message,  "pong")
    }

    @onDiscussionNew()
    async discussionNew(discussion: datatypes.Discussion) {
        // replace: await discussion.postMessage(this, "Welcome !")
        await helpers.discussion.postMessage(this, discussion,  "Welcome!")
    }
}

Daemon#

The following changes in the daemon API may affect all clients. Therefore, it is necessary to check for each change if your code is impacted.

Backups#

Version 2 introduces Olvid’s new backup system. Backups are now stored on our server and you only need to store the associated encryption key to recover your daemon.

As in v1, the backups folder of the daemon contains everything needed to restore a backup. If you were already backing up its contents, no changes should be necessary, but we still recommend checking that everything is working correctly.

For more information on setting up backups.

Commands#

MessageCommandeService#

  • messageSendVoip: Removal of the command, use the callCommandService instead.

from olvid import OlvidClient

client = OlvidClient()
async def call(discussion_id: int):
    client.call_start_discussion_call(discussion_id=discussion_id)
AttachmentOrderService#

(from version 2.0.1)

  • attachmentDelete: removal of the delete_everywhere parameter that did not work.

from olvid import OlvidClient

client = OlvidClient()
async def delete_attachment(attachment_id: int):
  # replace: client.attachment_delete(attachment_id=attachment_id, delete_everywhere=True)
  client.attachment_delete(attachment_id=attachment_id)
IdentityOrderService#

  • keycloakBind and keycloakUnbind: moved within the keycloakCommandService

from olvid import OlvidClient

client = OlvidClient()
async def bind_to_keycloak(configuration_link: str):
    # replace: client.identity_keycloak_bind(configuration_link)
    client.keycloak_bind_identity(configuration_link=configuration_link)
DiscussionCommandService#

  • discussionEmpty: removal of the delete_everywhere parameter which no longer worked (it was no longer possible to remotely delete other people’s messages).

from olvid import OlvidClient

client = OlvidClient()
async def empty_discussion(discussion_id: int):
    # replace: client.discussion_empty(discussion_id=discussion_id, delete_everywhere=True)
    client.discussion_empty(discussion_id=discussion_id)

  • discussionSettingsGet and discussionSettingsSet: moved within the new service settingsCommandService

from olvid import OlvidClient

client = OlvidClient()
async def get_discussion_settings(discussion_id: int):
    # replace: client.settings_discussion_get()
    client.settings_discussion_get(discussion_id=discussion_id)

Notifications#

GroupNotificationService#

  • GroupUpdateInProgress and GroupUpdateFinished: removal of obsolete notifications (group updates have been made synchronous and wait for the group to become available).

Admin#

IdentityAdminService#

  • identityNew: removal of the api_key parameter, use the command identitySetApiKey once the identity has been created.

Datatypes#

Identity#

  • removed the field invitation_url, instead use IdentityGetInvitationLink or IdentityAdminGetInvitationLink commands.

Invitation#

  • removal of the status STATUS_GROUP_INVITATION_FROZEN, which has become unnecessary.

Discussion#

  • moved the protobuf message DiscussionSettings from discussion.proto to settings.proto, but it remains in the datatypes module, so this should not affect the code.

MessageFilter#

  • renamed of the field reactions_filter to reaction_filters to follow the convention used elsewhere (from version 2.0.1)

N8n#

Warning

The n8n Olvid nodes have been deeply reworked and may therefore not be backward compatible. We recommend you to backup your existing flows before updating the package.

Credentials#

The Olvid credentials have been updated. If your nodes can no longer find their credentials, you will need to add new ones and update the credentials used by each Olvid node. To create your new credentials, go to the section Configurer le nœud Olvid.