Migrating from v1 to v2


Introduction 

v2 improves Kloudless’s support for new APIs, features as well as authentication mechanisms. Support for v1 will be removed on February 28, 2020.

This migration guide provides an overview of backwards incompatiblities that require changes to be made to your application when migrating from v1 to v2.

Here is a summary of the backwards-incompatible changes described below:

  • raw_id has been moved to the raw object’s id attribute.

  • Meta tokens have replaced Developer Keys.

  • Some Account properties have been renamed.

  • New Events format and Audit Event API.

  • cursor format and value changes in Events API.

  • Folder structure changes in the following services:

    • Dropbox
  • New Calendar Event format:

    • Deprecate reminder in favor of reminders and use_default_reminder.
  • Raw CRM data not returned by default.


New location for Raw IDs 

Previously, file metadata and other objects would include the raw_id attribute. This has been moved to the raw object’s id attribute instead.

For example, here is the format in v1:

{
        "raw_id": "ABCDEF-123"
        "raw": {
            "object": { ... raw data ... },
        }
    }

Here is the equivalent format in v2:

{
        "raw": {
            "id": "ABCDEF-123",
            "object": { ... raw data ... }
        }
    }

Developer Keys replaced with Meta tokens 

Meta tokens (OAuth 2.0 Bearer Tokens) have replaced Developer Keys. Meta tokens are automatically created when a user signs up and are used to authorize access to your Kloudless developer account and information associated with it.

Authorization: Bearer {token: string}

__NOTE__: DeveloperKey authorization available in v1 has been deprecated in
favor of Meta Bearer tokens. All existing Developer Keys have been transitioned
to Meta Bearer tokens and can be used with the "Bearer" Authorization scheme
immediately.

All existing DeveloperKey keys have automatically been transitioned to Bearer tokens and will work with the Bearer Authorization type.


Some Account properties have been renamed. 

The attributes below have been renamed to avoid confusion, but their values remain the same:

  • active is now known as enabled

  • deactivation_code is now known as disable_reason


Events 

  • cursor: Is now always returned as string and should not be treated as integer as it can vary. If there is no cursor (eg. because no events have been collected yet), the cursor will be null instead of -1 or 0.

Audit Events 

The new Event format provides more detailed information on activity in connected accounts, including unified data on the cause of an event, metadata associated with the action, and the target of the action.

Several new unified event categories and types have been introduced. Check out the v2 Events API here.

In addition to new attributes that provide more granular and accurate event data, the remaining attribute is no longer present due to limitations with accuracy and performance.

The older Event format has been maintained below for reference.

v1 Audit Event Types and Format

While most audit data is presented as received via the Kloudless Event’s raw attribute, Kloudless maps recognized events to known event types and formats. Here are the possible event types Kloudless provides:

  • unknown: This is the default event type for an event that is not mapped to a Kloudless Audit Event type specified in this list. The raw data for the event object will provide access to the original event received from the third-party service for further analysis.

  • login: A user successfully logged into the account

  • login_failed: A user failed to log into the account

  • logout: A user successfully logged out of the account

  • share_link: A link to a resource was shared

  • unshare_link: A shared link to a resource was removed

  • share_update: A shared link to a resource was modified

  • collaboration_add: A collaborator was added to a resource

  • collaboration_invite: A collaborator was invited to a resource

  • collaboration_accept: A collaborator has accepted the invite to a resource

  • collaboration_delete: A collaborator was removed from a resource

  • collaboration_update: The resource’s collaborators were updated

  • view: The resource was viewed

  • download: The resource was downloaded

  • user_invite: A user has been invited

  • user_add: A new user was created

  • user_delete: A user was deleted

  • user_update: A user was updated

  • group_add: A new group was created

  • group_delete: A group was deleted

  • group_update: A group was updated

  • group_add_user: A user was added to a group

  • group_delete_user: A user was removed from a group

Audit Event objects may also have the fields below in lieu of metadata and previous_metadata. They may either not be present or default to {} where unavailable or not applicable.

  • user: Information on the user associated with the event. e.g.: The user that was created, or the user a resource was shared with.

  • previous_user: The previous user data that was modified.

  • group: Information on the group associated with the event.

  • previous_group: The previous group data that was modified.

  • link: Metadata on a shared link. Includes the link’s URL.

  • login: Metadata on a login or attempted login.

  • collaboration: Metadata on a collaboration

See the Team endpoints for more information on user and group objects.


Folder Structure Changes 

A few changes have been made regarding the folder structure in the services below.

Dropbox

Folder creation and file uploads with parent_id set to root will now create/upload the resource under under the shared root folder for the Dropbox Business Organization instead of the private Home folder of the connected account. The root folder of the Dropbox Business Organization is the folder shown in the Files tab in the left-hand side navigation menu of the Dropbox Web UI.

Files and folders in the root folder can be accessed by the team, and are not private like data in the Home folder. Please ensure that all new folders created and files uplaoded to the root folder are intended to be shared.


Calendar Event format changes 

The attribute reminder has been replaced by reminders, which provides more information such as the reminder name and mechanism.

The new attribute use_default_reminder has been added to indicate whether to use the default reminder or not. Only supported for google_calendar.

For example, here is the format in v1:

{
    "reminder": 30
}

Here is the format in v2:

{
    "use_default_reminder": false,
    "reminders": [{
        "minutes": 30,
        "message": "popup"
    }]
}

See the Calendar Event Docs for more information on reminders and use_default_reminder.


Raw CRM data not returned by default 

All CRM API endpoints now only return raw upstream data if the X-Kloudless-Raw-Data: true header was included in the API request. This is consistent with the behavior of other API endpoints. Previously, some CRM accounts defaulted to returning raw upstream data along with the unified response. This was the case with developers using Kloudless prior to 2019 with Salesforce, Dynamics, Oracle, and Pipeliner.