Xrm.Mobile.offline (client-side reference)

  • Article

 

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.

Note

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

Important

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.

In This Topic

isOfflineEnabled

createRecord

retrieveRecord

retrieveMultipleRecords

updateRecord

deleteRecord

isOfflineEnabled

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.

createRecord

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.

retrieveRecord

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)

    Tip

    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.

retrieveMultipleRecords

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.

updateRecord

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.

deleteRecord

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.

See Also

Write and debug scripts for Dynamics 365 for phones and tablets
Client-side programming reference

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright