Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Data Field Mapping Reference

During migration, all fields building up a Backend Services content type item are migrated to corresponding Kinvey collection entity fields. Every effort has been made to keep the entity structures and functionality as similar as possible. Dissimilarities, where they exist, are listed as specifics under the reference tables.

All Content Types

Consult the following table to learn how each Backend Services item field maps to the respective Kinvey entity field during migration. The table includes fields common to all content types. Fields specific to built-in content types like Users and Files are listed in the next sections.

Backend Services field name Kinvey field name Value Description
Id _id1 ID Unique ID of the item.
CreatedAt _kmd.ect DateTime String representation of the date and time when the item was created, in ISO 8601 format.
ModifiedAt _kmd.lmt DateTime String representation of the date and time when the item was last modified, in ISO 8601 format.
Owner _acl.creator2 ID ID of the user who holds the "Owner" role for the item or an empty GUID if the "create" operation was executed with master key privileges. Usually this is the same value as "CreatedBy" if not changed subsequently. Not migrated in the case of the Users content type due to limitations.
CreatedBy CreatedBy3 ID ID of the user who created the item or an empty GUID if the "create" operation was executed with master key privileges.
ModifiedBy ModifiedBy3 ID ID of the last user who modified the item or an empty GUID if the operation was executed with master key privileges.
_ACL _acl Object An object that holds the definition of the item-level permissions.
_ACL.EveryoneCanRead _acl.gr Boolean Gives read permission to all user accounts.
_ACL.EveryoneCanUpdate _acl.gw4 Boolean Gives update permission to all user accounts.
_ACL.EveryoneCanDelete _acl.gw4 Boolean Gives delete permission to all user accounts.
_ACL.UsersCanRead _acl.r Array of user IDs Gives read permission to the specified user accounts.
_ACL.UsersCanUpdate _acl.w5 Array of user IDs Gives update permission to the specified user accounts.
_ACL.UsersCanDelete _acl.w5 Array of user IDs Gives delete permission to the specified user accounts.
_ACL.RolesCanRead _acl.roles.r Array of role IDs Gives read permission to the specified security roles.
_ACL.RolesCanUpdate _acl.roles.u Array of role IDs Gives update permission to the specified security roles.
_ACL.RolesCanDelete _acl.roles.d Array of role IDs Gives delete permission to the specified security roles.
MyCustomFieldName1 MyCustomFieldName1 Any All custom fields are migrated to the Kinvey entity "as-is".
FileRelationId-FieldName FileRelationId-FieldName6 FileID The ID of an associated file entity.
LocationFieldName _geoloc7 Geo Point A definition of a geographic coordinate.

Due to a flaw in the migration procedure, items migrated from Backend Services before April 19, 2018, 15:00 Coordinated Universal Time (UTC), will have their "_kmd.ect" value set to the value of their "ModifiedAt" field in Backend Services (instead of the value of the "CreatedAt" field). This affects the Users, Files, and all user-defined content types. If you need to keep the creation date accurate in the migrated data, locate the collection in Kinvey, delete the previously migrated item(s), and then migrate the data for the collection once again using the migration tool.

Specifics:

  1. The Id of the data items in Backend Services has a default value set to a globally unique identifier (GUID), for instance, "998d4118-8707-45bc-a327-3e39e423b4d1". This value is preserved as the _id of the Kinvey entity when the items are migrated from Backend Services to Kinvey. Newly-created data entities in Kinvey will have their _id value set by default to a MongoDB ObjectId, for instance, "507f191e810c19729de860ea". Normally, there should not be any implications from that difference for your apps but you may need to handle that case when working with the collectionAccess module from the Kinvey Business Logic layer and using its findById/findOne methods. Depending on the value format of the _id you are searching for (GUID or ObjectId), you have to either cast or not the string value to an ObjectId. For more information, see the ObjectID warning section.

  2. When the value of the Backend Services item Owner is an empty GUID ("00000000-0000-0000-0000-000000000000"), the Kinvey entity _acl.creator is set to the current Kinvey App Key (for example, kid_ABCDEF1234) for consistency with normal Kinvey behavior.

    The Owner field value is lost during migration for items of the Backend Services Users content type. The _acl.creator field of the user account in Kinvey is always set to the Kinvey _id of the user account entity.

  3. The Backend Services CreatedBy and ModifiedBy fields are transferred during the migration but Kinvey will not automatically update them from then on. If you want to continue using them, you need to populate them programmatically during the creation/update of the item. Note that most of the time you can use the Kinvey _acl.creator field in the same way as CreatedBy.

  4. The Kinvey entity is set to "globally writeable" (by setting _acl.gw to true) only if both EveryoneCanUpdate and EveryoneCanDelete are true. Otherwise _acl.gw is set to false.

  5. Only these users from the UsersCanUpdate and UsersCanDelete arrays that are allowed to both Update and Delete the item according to the ACL definition are populated in the _acl.w array. User IDs on one of the lists only are not migrated to the ACL definition of the Kinvey entity, which means they lose their respective Update or Delete rights for the entity.

  6. All data items that contain a File relation field (as defined in the Backend Services content type structure) are migrated according to the Kinvey-specific structure for handling file relations as explained here. Example:

    // in Backend Services
    "PictureId": "my-file-id" 
    
    // in Kinvey 
    "PictureId": {"_type": "KinveyFile", "_id": "my-file-id"} 
    
  7. The first item field of type GeoPoint (as defined in the Backend Services content type structure) is migrated as a _geoloc field which is the Kinvey entity field designated to holding the geographical coordinates definition. If your Backend Services data item contains multiple Geo Point fields, only the first is converted to _geoloc. The remaining are migrated "as-is" (object or array depending on how you save your GeoPoints) and you will not be able to execute geoqueries on these fields.

Files

Consult the following table to learn how each Backend Services Files item field maps to the respective Kinvey entity field during migration. These fields are in addition to the common content type fields described in All Content Types.

Backend Services field name Kinvey field name Description
Filename _filename The file name set at the time of creating the file.
ContentType mimeType The Multipurpose Internet Mail Extensions (MIME) type of the file as specified at the time of creating the file.
Length size An integer specifying the file size in bytes.
Uri N/A1 Not migrated to Kinvey. Use the _downloadURL field of the file entity in Kinvey after the migration. The Uniform Resource Locator (URL) referencing the physical content of the resource on the Telerik Platform content delivery network (CDN). Example:https://bs2.cdn.telerik.com/v1/abcdefg123456/fb40aef1-54c3-11e7-9021-04ac21c10e6
Storage N/A2 A system-set property not needed in Kinvey. Not migrated to Kinvey.
N/A _public3 Always set to true.
N/A _downloadURL4 The Uniform Resource Locator (URL) referencing the physical content of the resource on a Kinvey CDN. Use this field after the migration instead of the Uri field of the Backend Services file metadata. Example:https://storage.googleapis.com/29e1ba7e957c4e7b9f6ce51819ae9835/ff6375ed-e1ec-3b72-681e-3660bb98b5b1/myawesomepicture.jpeg

Specifics:

  1. The Uri field that used to hold the path to the file resource on the Telerik Platform Backend Services content delivery network does not make sense in Kinvey and is not migrated. Instead, the Kinvey file entity receives an automatically-populated _downloadURL field. Use this field to access the file content.

  2. The Storage system field is not migrated.

  3. Migrated files are always set to _public which means that the web address of the resource on the CDN will be visible to anyone who has the link. This choice preserves the backwards compatibility as well as the familiar behavior from the Telerik Platform CDN. After the migration, you can update the file metadata and set the CDN link to private.

  4. Use the _downloadURL field of the Kinvey file entity to access the file content.

Users

Consult the following table to learn how each Backend Services Users item field maps to the respective Kinvey entity field during migration. These fields are in addition to the common content type fields described in All Content Types.

Backend Services field name Kinvey field name Description
Id _id, _acl.creator1 Unique ID of the user account. Creator of the user account.
Username username Username chosen at registration time.
Email email2 The user's email address required for uniqueness and operations relating to email notifications.
IsVerified _kmd.emailVerification.status3 Migrated only in case the field value is true in which case the value is migrated as confirmed. Not migrated if the user account is not verified. See Specifics below for an example.
IdentityProvider N/A Not migrated due to inapplicability.
Role _kmd.roles[{"roleId": "role-id-here"}]4 Identifier(s) of the role(s) that the user is assigned.
VerificationCode N/A Not migrated due to inapplicability.
Owner N/A1 Not migrated due to technical limitations.

Specifics:

  1. In addition to being used as a basis for the Kinvey user account's _id filed, the Backend Services user account Id is copied to the Kinvey _acl.creator field in case of users. Note that this differs from other entities migrated to Kinvey where the creator is set to the Owner of the Backend Services item. The Users item owner is lost during migration because the _acl.creator field of the user accounts in Kinvey is by design set to the _id of the user account.

  2. The email field in Kinvey is not required to be unique and multiple user accounts can have the same email address.

  3. When the IsVerified field for the user account in Backend Services is set to true, it is migrated to the following structure as supported in Kinvey:

    {
      // ommitted for brevity
       "_kmd":{
          "lmt":"2018-01-04T10:20:27.743Z",
          "ect":"2018-01-04T10:20:27.743Z",
          "emailVerification":{
             "status":"confirmed",
             "lastStateChangeAt":"2018-01-08T12:38:06.874Z",
             "lastConfirmedAt":"2018-01-08T12:38:06.874Z",
             "emailAddress":"email@example.com"
          }
       }
      // ommitted for brevity
    }
    

    The lastStateChangeAt and lastConfirmedAt dates are set to the value of the CreatedAt field of the source entity.

  4. The user account's Role field is migrated as a more complex structure in Kinvey, as shown below. The grantDate value is set to the moment in time when the user was assigned the role, which in this case is the user account creation time during the migration. Note that due to technical limitations the roleId is not preserved, even though the migrated role wears the same name as in Backend Services.

    "_kmd": {
      // ommitted for brevity    
        "roles": [
            {
                "roleId": "8f489c82-6a9d-4318-8ebb-d581482c9275",
                "grantedBy": "kid_HJWVDV4MZ",
                "grantDate": "2018-01-12T15:14:35.110Z"
            }
        ]
    }
    

Social Users

Consult the following table to learn how each social-related Backend Services Users item field maps to the respective Kinvey entity field during migration.

Backend Services field name Kinvey field name Description
Identity _socialIdentity1 Object containing the definition of the linked third-party social account.
Identity.<provider-name> _socialIdentity.<provider-name> Identifier of the source third-party provider. Example: _socialIdentity.facebook

Specifics:

  1. The _socialIdentity field in Kinvey holds user information coming from the linked social account. The first part of the example below shows a Backend Services user account before the migration while the second depicts how it is transformed to become a Kinvey user account. Note that normally Kinvey only maintains a selected set of the social provider account attributes and subsequent users created in Kinvey may differ from the migrated social users. User accounts created from Google may also have a different structure for their social identity field given that the authentication in Kinvey is based on the Google access_token as opposed to the usage of the Google id_token in Backend Services.

    Backend Services user account created from Facebook:

    {
        "IsVerified":true,
        "IdentityProvider":"Facebook",
        "Identity":{
            "Facebook":{
                "id":"facebook-id",
                "first_name":"First",
                "last_name":"Last",
                "age_range":{
                    "min":21
                },
                "link":"https://www.facebook.com/app_scoped_user_id/facebook-id/",
                "gender":"male",
                "locale":"en_US",
                "picture":{
                    "data":{
                        "height":50,
                        "is_silhouette":false,
                        "url":"https://scontent.xx.fbcdn.net/...",
                        "width":50
                    }
                },
                "timezone":2,
                "updated_time":"2016-10-26T13:27:16+0000",
                "verified":true,
                "email":"email@example.com",
                "name":"First Last"
            }
        },
        "Email":"email@example.com",
        "DisplayName":"First Last",
        "Role":"2c8f3c10-fcee-11e7-a16f-af67d810ff27",
        "CreatedAt":"2018-01-22T12:24:36.121Z",
        "ModifiedAt":"2018-01-22T12:24:36.121Z",
        "CreatedBy":"00000000-0000-0000-0000-000000000000",
        "ModifiedBy":"00000000-0000-0000-0000-000000000000",
        "Owner":"35721090-ff6f-11e7-9d61-13ebb7e1f954",
        "Id":"35721090-ff6f-11e7-9d61-13ebb7e1f954"
    }
    
    

    Corresponding Kinvey user account after the migration:

    {
        "_id":"35721090-ff6f-11e7-9d61-13ebb7e1f954",
        "DisplayName":"First Last",
        "CreatedBy":"00000000-0000-0000-0000-000000000000",
        "ModifiedBy":"00000000-0000-0000-0000-000000000000",
        "_kmd":{
            "ect":"2018-01-22T12:24:36.121Z",
            "lmt":"2018-01-22T12:24:36.121Z",
            "roles":[
                {
                    "roleId":"2563a140-857a-4862-bb8c-dcbacf66c638",
                    "grantedBy":"kid_ABCDED123456",
                    "grantDate":"2018-01-22T12:24:36.121Z"
                }
            ],
            "emailVerification":{
                "status":"confirmed",
                "lastStateChangeAt":"2018-01-22T12:24:36.121Z",
                "lastConfirmedAt":"2018-01-22T12:24:36.121Z",
                "emailAddress":"email@example.com"
            }
        },
        "email":"email@example.com",
        "_socialIdentity":{
            "facebook":{
                "id":"555075051352852",
                "first_name":"First",
                "last_name":"Last",
                "age_range":{
                    "min":21
                },
                "link":"https://www.facebook.com/app_scoped_user_id/facebook-id/",
                "gender":"male",
                "locale":"en_US",
                "picture":{
                    "data":{
                        "height":50,
                        "is_silhouette":false,
                        "url":"https://scontent.xx.fbcdn.net/...",
                        "width":50
                    }
                },
                "timezone":2,
                "updated_time":"2016-10-26T13:27:16+0000",
                "verified":true,
                "email":"email@example.com",
                "name":"First Last"
            }
        },
        "username":"3621be0d-df3d-463a-896a-2e848ec278dd",
        "_acl":{
            "creator":"35721090-ff6f-11e7-9d61-13ebb7e1f954"
        }
    }
    
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2018, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.