Skip to main content

Migration to Kisi 2.0

You can stop reading this if you’re not a Kisi integration partner, and you don’t have any custom integration built on Kisi.

Quick background

Currently Kisi works according to two models:

  1. the Standard (legacy) model, where the login can be done only through a Kisi user.
  2. the Organizations model, that also offers SSO authentication and SCIM integration with leading identity providers, for example Azure Active Directory

During 2022 we will deprecate the Standard model. This means, all our integration partners and customers currently using the Standard model will be migrated to the Organizations model, also known as Kisi 2.0.

Implications for integration partners and custom integrations

We’re working hard to support all 3rd party integrations on Kisi 2.0. From your side, all you will have to do is follow the steps indicated by our product team.

Below we summarized the most important information you need to know, as well as the steps to take before migrating to Kisi 2.0. Please read carefully.

Important steps to take before the Kisi Places you manage can be migrated to Kisi 2.0.

  • Understand the differences between the Standard and Organizations models and how it affects your Kisi integration, i.e the differences in the scopes of resources, differences in the payloads of requests and responses of endpoints you use, etc.

  • Make sure your system supports the Organizations model. Below is a list of major endpoints and how they are different in the Organizations model:

    EndpointsStandard ModelOrganization Model
    Create login (https://api.kisi.io/docs#/operations/createLogin)domain parameter is not requireddomain parameter is required in the request body
    Create member (https://api.kisi.io/docs#/operations/createMember)place_id is required in the request bodyplace_id is not required. Including a place_id would result in a 422 error
    Fetch shares (https://api.kisi.io/docs#/operations/fetchShares)A place_id query parameter can be included to return all the shares that belong to the placeDon't include a place_id query parameter if you need all the shares that belong to the organization.
    Fetch groups (https://api.kisi.io/docs#/operations/fetchGroups)A place_id query parameter can be included to fetch all groups that belong to the placeDon't include a place_id query parameter if you need all the groups that belong to the organization.
    Fetch events (https://api.kisi.io/docs#/operations/fetchEvents)place_id query parameter is requiredplace_id parameter is ignored. The endpoint would return events for the organization

    Other major endpoints should work the same way they do in the legacy model.

  • Understand what happens during the migration (most importantly, which resources are cloned during the migration) and how it will affect your integration.

    Here is a list of resources that are cloned. This means, their IDs would be different in the Organizations model:

    • Shares
    • Groups
    • Users
    • Members
    • GroupLocks
    • Cards
    • Schedules

    If you save the IDs of any of these resources, you’ll need to update with the new ones after the migration. We have an endpoint that returns a mapping of old resource IDs to the new ones: https://api.kisi.io/docs#/operations/fetchMigrationRecordsMapping. The mapping can be used to replace the old IDs that you save on your end with the new ones.

    Event Webhook integrations (except migration webhooks) are disabled during migration. It may require setting them up again after the migration.

  • To easily automate updating the Kisi resource IDs that you save on your end with the new ones after a migration, we recommend you do the following:

    • Build an event webhook endpoint to handle migration events from Kisi

    • Create an event webhook integration specifically for the migration for each of the Kisi places that are managed by your integration: You can do that via this endpoint https://api.kisi.io/docs#/operations/createIntegration with the following request payload:

      {
      "integration": {
      "name": "Migration webhook",
      "place_id": 0,
      "type": "event_webhook",
      "url": "https://your_migration_web_hook_endpoint",
      "enabled": true,
      "enabled_events": ["place.migrate_to_organization"]
      }
      }
    • Immediately the place is migrated, a post request will be sent your webhook endpoint with an event payload like this:

      {
      "id": 0,
      "actor_type": null,
      "actor_id": null,
      "action": "migrate_to_organization",
      "object_type": "Place",
      "object_id": 0,
      "success": true,
      "code": "000000",
      "message": "The place <place> has been migrated to organization <organization>",
      "created_at": "The time it happened",
      "references": "Some references"
      }

      The object_id in the payload will be the id of the place that was migrated.

    • Your webhook endpoint can handle the event by making a request to https://api.kisi.io/docs#/operations/fetchMigrationRecordsMapping to fetch the records mapping for the migrated place (using the place ID) and make any updates you need to make on your end.

  • When everything has been set up on your end to support the migration, you can create Kisi test places by using this endpoint: https://api.kisi.io/docs#/operations/createPlace Next, integrate them with your app, and set up a migration webhook for them. To make sure the migration runs smooth, we can run a test migration for these test places (when you are ready to do this, please send us an email at support@kisi.io.

  • If the above goes fine, we can go ahead with the migration.

For those who want to use the White labeling in Kisi 2.0

"White label" users are users that will be fully managed by your integration and won't receive any notifications from Kisi, neither need to use the Kisi app.

If you would like to use the White-labeling feature in Kisi 2.0, we have an option to disable all future Kisi email notifications for all existing non-admin users during the migration. However, we advise communicating this option to customers.

You can find information about creating new White label users and how to create logins on behalf of them here: https://docs.kisi.io/for_integration_partners/registration_and_authentication#creating-white-label-users

After the migration

After the migration, we usually keep an old instance for 7 days. Having two instances would create a mismatch since only the new one will be updated with the integration, and some users still might be having access through the old instance.

For Admins, we offer the option to remove the old instance any time earlier than that, but we can also shorten that period for your users. In this case, we recommend having a couple of test runs that guarantee that the integration is functional.

In case you have questions, don’t hesitate to reach out to us at support@getkisi.com