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 incompatibilities 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.

  • Subscription-based activity monitoring via the new Activity API deprecates the Events API.

    • The Event objects in the Events API are now Activity objects.
  • The format and value of cursor changes in the Activity API.

  • cursor format and value changes in Activity 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.

  • Raw type not included in the CRM Schema raw response data.


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 API -> Activity API 

The Events API has been deprecated and is now known as the Activity API, with support for Subscription objects. This change has been implemented in part to help avoid further confusion with the Calendar Events API.

Event objects have been renamed to Activity objects.

Here are some of the major updates to be aware of:

  • The cursor returned is always returned as a string and should not be treated as an integer as it can vary. If there is no cursor since no activity has been collected yet, the cursor will be null instead of -1 or 0 as before.

  • The /events/latest endpoint is no longer necessary since the Subscription object contains the data it used to provide.

The older Events API endpoints are listed below for reference, with some details on the changes above.

List Events 

list eventsGET /accounts/{account_id}/events{?cursor,page_size,from,until}

Events are retrieved using this endpoint similar to the Activity API endpoint to list events for a Subscription. In this previous format, an account essentially only has a single implicit subscription that events are retrieved through.

The query parameters and the response object format are the same as in the new Activity API, except for the api and type attributes, which indicate the new API and object type respectively.

    Retrieve Latest Cursor 

    Retrieve Latest CursorGET /accounts/{account_id}/events/latest

    This returns the latest cursor that is available. This makes it easier to start fetching new events immediately, rather than making a potentially large initial request to retrieve all data from when the account was connected.

    This returns an object with the following fields:

    • cursor: The most recent cursor for this account.

    • upstream_cursor: Cursor from the upstream service. This indicates that the upstream event stream can be directly queried.

    Either cursor can be used in the cursor parameter when retrieving events.

    The v2 Activity API makes information on the latest cursor available through the Subscription object’s upstream_checkpoint attribute, for the upstream_cursor, and last_activity attribute, for the cursor.

    Example Request:

    curl -H 'Authorization: Bearer [TOKEN]' \
        'https://api.kloudless.com/v2/accounts/123/events/latest'
    • Response  200Toggle
    • Headers

      Content-Type: application/json

      Body

      {
        "cursor": 29,
        "upstream_cursor": "1veNDdHe2_99qcndJ6cId",
        "type": "cursor",
        "api": "events"
      }

    Audit Activity 

    The new Activity format provides more detailed information on activity in connected accounts. This includes unified data on the action/cause of an activity, metadata associated with said action, as well as the action’s target.

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

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

    The older Activity format has been maintained below for reference.

    v1 Audit Activity Types and Format

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

    • unknown: This is the default activity event type for an activity that is not mapped to a Kloudless Audit Activity event type specified in this list. The raw data for the activity object will provide access to the original activity 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 Activity 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 activity. 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 activity.

    • 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.


    Raw type not included in the CRM Schema response 

    Use the new service_object_name and service_field_name attributes to determine the raw object and field names respectively in the CRM Schema response, rather than checking the raw data for this information. The raw data continues to include the schema data provided by the upstream service, but this is not the same type as the actual object it is describing, so the raw->type attribute is excluded in v2 onwards for consistency.


    Webhooks available with JSON payloads 

    Previously, Kloudless sent webhooks to your server with a URL-encoded body data. However, a JSON payload is more extensible and enables Kloudless to include additional information about the new activity available. Kloudless therefore introduced webhooks that transmit JSON payloads. The v2 API and above require using this new format.

    Here are two ways to migrate legacy webhooks to new webhooks that include JSON data:

    1. Update your existing webhook endpoints to accept both content types (application/x-www-form-urlencoded and application/json). Then click the “Migrate” button on the “Legacy Webhooks” section of the Events Configuration page for each of your Kloudless apps.

    2. Add new webhooks to each of your apps’ Events Configuration pages. This will create new webhooks that receive JSON payloads instead. After you confirm your servers successfully process this JSON data, click the “Delete All” button in the “Legacy Webhooks” section to delete all legacy webhooks.

    See the Webhooks API reference for more information.