Xrm.Mobile.offline (client-side reference)

Dynamics CRM 2016
 

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

The Xrm.Mobile.offline namespace provides methods to create and manage records in the Dynamics 365 mobile clients (Dynamics 365 for phones and Dynamics 365 for tablets) while working in the offline mode.

System_CAPS_noteNote

The Xrm.Mobile.offline namespace was introduced in the December 2016 update for Dynamics 365 (online and on-premises).

These client APIs under the Xrm.Mobile.offline namespace will work only if you are in the offline mode and for entities that are enabled for mobile offline synchronization. More information:  Help & Training: Configure mobile offline synchronization for CRM for phones and tablets

System_CAPS_importantImportant

While creating or updating record in the offline mode, only basic validation is performed on the input data. Basic validation includes things such as ensuring that the entity attribute name specified is in lower case and does exist for an entity, checking for data type mismatch for the specified attribute value, preventing records getting created with the same GUID value, checking whether the related entity is offline enabled when retrieving related entity records, and validating if the record that you want to retrieve, update, or delete actually exists in the offline data store. Business-level validations happen only when you are connected to Dynamics 365 server and the data is synchronized. A record is created or updated in Dynamics 365 only if the input data is completely valid.

Returns whether an entity is offline enabled.

Xrm.Mobile.offline.isOfflineEnabled("entityType")
Parameters

Type: String. The entity type in Dynamics 365. For example: "account". For information about entity types in Dynamics 365, see Web API EntityType Reference.

Return Value

Type: Boolean. True if the entity is offline enabled; otherwise false.

Creates an entity record in Dynamics 365 mobile clients while working in the offline mode.

Xrm.Mobile.offline.createRecord(entityType, data).then(successCallback, errorCallback)
Parameters

Name

Type

Required

Description

entityType

String

Yes

The entity type in Dynamics 365 for which you want to create a record. For example: "account". For information about entity types in Dynamics 365, see Web API EntityType Reference

data

Object

Yes

A dictionary object containing key : value pairs, where key is the property of the entity set and value is the value for the property you want to use for creating entity record. For example, define the following object to create an account:

var myAccount = {};
myAccount.name = "Sample Account Name";
myAccount.accountid = "2724A2AF-697E-E611-80DB-00155DB412B4";
myAccount.parentaccountid = {
    "logicalname": "account",
    "id": "76BE5E4A-5990-E611-80DA-00155DD8BA2D"
};
myAccount.revenue = "60000.00";
myAccount.primarycontactid = {
    "logicalname": "contact",
    "id": "76BE5E4A-5990-E611-80DA-00155DD8BA2D"
};
myAccount.new_customdate = new Date("September 29, 2016 12:00:00");

For information about entity types and their properties in Dynamics 365, see Web API EntityType Reference

successCallback

Function

No

A function to call when a record is created. An object with the following properties will be passed to identify the new record:

  • id: String. GUID of the record that was created.

  • logicalName: String. Logical name of the entity.

errorCallback

Function

No

A function to call when the operation fails. An object with the following properties will be passed:

  • errorCode: Number. The error code.

  • message: String. An error message describing the issue.

  • debugMessage: String. An internal error message that might contain additional details about the issue.

Limitations
  • You cannot create intersect and activity party entities.

  • Only the following attribute types are supported for creating a record in the offline mode: BigInt, Boolean, Customer, DateTime, Decimal, Double, EntityName, Integer, Lookup, Memo, Money, Owner, Picklist, String, State, Status, and UniqueIdentifier.

Retrieves an entity record in Dynamics 365 mobile clients while working in the offline mode.

Xrm.Mobile.offline.retrieveRecord(entityType, id, options).then(successCallback, errorCallback)
Parameters

Name

Type

Required

Description

entityType

String

Yes

The entity type in Dynamics 365 for which you want to retrieve a record. For example: "account". For information about entity types in Dynamics 365, see Web API EntityType Reference

id

String

Yes

GUID of the record you want to retrieve.

options

String

No

OData system query options to retrieve your data. The following system query options are supported: $select and $expand.

  • For using $expand, the related entity must also be offline enabled. For example, to retrieve the contact related to an account record, both account and contact entities must be offline enabled.

  • You specify the query options starting with ?. For specifying multiple query options, use & to separate the query options. For example:

    ?$select=name&$expand=primarycontactid($select=contactid,fullname)
    
System_CAPS_tipTip

As a performance best practice, limit the number of properties you are retrieving by using the $select query option. Otherwise, all the properties will be retrieved.

Also while retrieving related entity property names using the $expand option, simply including the name of the navigation property will return all the properties for related records. You can limit the properties returned for related records using the $select system query option in parentheses after the navigation property name in $expand. More information: Retrieve related entities for an entity by expanding navigation properties

successCallback

Function

No

A function to call when a record is retrieved. An object with the following properties will be passed to identify the retrieved record:

  • id: String. GUID of the record that was retrieved.

  • logicalName: String. Logical name of the entity.

errorCallback

Function

No

A function to call when the operation fails. An object with the following properties will be passed:

  • errorCode: Number. The error code.

  • message: String. An error message describing the issue.

  • debugMessage: String. An internal error message that might contain additional details about the issue.

Limitations
  • Only $select option can be specified within $expand.

  • Only the following attribute types are supported for retrieving a record in the offline mode: BigInt, Boolean, Customer, DateTime, Decimal, Double, EntityName, Integer, Lookup, Memo, Money, Owner, Picklist, String, State, Status, and UniqueIdentifier.

Retrieves a collection of entity records in Dynamics 365 mobile clients while working in the offline mode.

Xrm.Mobile.offline.retrieveMultipleRecords(entityType, options, maxPageSize).then(successCallback, errorCallback)
Parameters

Name

Type

Required

Description

entityType

String

Yes

The entity type in Dynamics 365 for which you want to retrieve records. For example: "account". For information about entity types in Dynamics 365, see Web API EntityType Reference

options

String

No

OData system query options or FetchXML query to retrieve your data. The following system query options are supported: $select, $top, $filter, $expand, and $orderby.

  • For $filter, only the standard filter operators as mentioned under the Filter results section are supported; the standard query functions are not supported

  • For using $expand, the related entity must also be offline enabled. For example, to retrieve the contact for the account records, both account and contact entities must be offline enabled. If you expand on collection-valued navigation properties for an entity to retrieve related entities, a [NavigationPropertyName]@odata.nextLink property will be returned for the related entities. For example if you are expanding on the primarycontactid navigation property, it will return primarycontactid@odata.nextLink. You should use the value of the primarycontactid@odata.nextLink property with a new GET request to return the required data.

  • You specify the query options starting with ?. For specifying multiple query options, use & to separate the query options. For example:

    ?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname)
    

    To specify a FetchXML query, use the fetchXml parameter for specifying the query:

    ?fetchXml=<FetchXML>
    

    Using FetchXml, you can only retrieve base entity attributes.

For example, here is the an example of a retrieve multiple call using the query options:

Xrm.Mobile.offline.retrieveMultipleRecords("account", "?select=name,revenue,&$orderby=revenue&$filter=revenue ne '60000.00'", null)

maxPageSize

Integer

No

Specify a positive number that indicates the number of entity records to be returned per page. If you do not specify this parameter, the default value is passed as 5000.

If the number of records being retrieved is more than maxPageSize, an @odata.nextLink property will be returned, and you can use the value of the @odata.nextLink property with a new GET request to return next set of records. More information: Specify the number of entities to return in a page

successCallback

Function

No

A function to call when records are retrieved. A dictionary containing key : value pairs of data retrieved will be passed to identify the retrieved records.

errorCallback

Function

No

A function to call when the operation fails. An object with the following properties will be passed:

  • errorCode: Number. The error code.

  • message: String. An error message describing the issue.

  • debugMessage: String. An internal error message that might contain additional details about the issue.

Limitations
  • A maximum of 5000 related records can be retrieved when using $expand.

  • Only $select option can be specified within $expand.

  • $skip query option is not supported.

  • Only the following attribute types are supported for retrieving records in the offline mode: BigInt, Boolean, Customer, DateTime, Decimal, Double, EntityName, Integer, Lookup, Memo, Money, Owner, Picklist, String, State, Status, and UniqueIdentifier.

Updates an entity record in Dynamics 365 mobile clients while working in the offline mode.

Xrm.Mobile.offline.updateRecord(entityType, id, data).then(successCallback, errorCallback)
Parameters

Name

Type

Required

Description

entityType

String

Yes

The entity type in Dynamics 365 for which you want to update a record. For example: "account". For information about entity types in Dynamics 365, see Web API EntityType Reference

id

String

Yes

GUID of the record you want to update.

data

Object

Yes

A dictionary object containing key : value pairs, where key is the logical name of the property that you want to update and value is the updated value for the property. Only the properties and values you specify in the dictionary object will be updated for the record. for example:

var myUpdatedAccount = {};
myUpdatedAccount.name = "Changed Account Name";
myUpdatedAccount.revenue = "60000.00";

successCallback

Function

No

A function to call when a record is updated. An object with the following properties will be passed to identify the updated record:

  • id: String. GUID of the record that was updated.

  • logicalName: String. Logical name of the entity.

errorCallback

Function

No

A function to call when the operation fails. An object with the following properties will be passed:

  • errorCode: Number. The error code.

  • message: String. An error message describing the issue.

  • debugMessage: String. An internal error message that might contain additional details about the issue.

Limitations
  • You cannot update intersect and activity party entities.

  • Only the following attribute types are supported for updating a record in the offline mode: BigInt, Boolean, Customer, DateTime, Decimal, Double, EntityName, Integer, Lookup, Memo, Money, Owner, Picklist, String, State, Status, and UniqueIdentifier.

Deletes an entity record in Dynamics 365 mobile clients while working in the offline mode.

Xrm.Mobile.offline.deleteRecord(entityType, id).then(successCallback, errorCallback)
Parameters

Name

Type

Required

Description

entityType

String

Yes

The entity type in Dynamics 365 for which you want to delete a record. For example: "account". For information about entity types in Dynamics 365, see Web API EntityType Reference

id

String

Yes

GUID of the record you want to delete.

successCallback

Function

No

A function to call when a record is deleted. An object with the following properties will be passed to identify the deleted record:

  • id: String. GUID of the record that was deleted.

  • logicalName: String. Logical name of the entity.

errorCallback

Function

No

A function to call when the operation fails. An object with the following properties will be passed:

  • errorCode: Number. The error code.

  • message: String. An error message describing the issue.

  • debugMessage: String. An internal error message that might contain additional details about the issue.

Limitations

You cannot delete intersect and activity party entities.

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Community Additions

Show: