CRM Online (Carina) API Enhancements Highlights

As an ongoing concern CRM architects and developer should continue to review the latest features and capabilities of the platform. Keeping up to date on exactly what is new or changed is not an easy task as there is no official “checklist” for what’s new when upgrading to a new version of the platform. This blog is especially for anyone that wants to be able to know about the latest platform enhancements especially targeted at data migration and integration concerns. The following are what you should consider when reviewing your customizations for CRM 2015 Carina or CRM 2016 Ara.

Data migration and integration is a major part of any enterprise CRM implementation. The most recent API enhancements are primarily targeted at data migration/integration scenarios with improvements in available SDK messages and/or feature enhancements. Common data integration scenarios include the following pushing legacy data into CRM, updating CRM from offline data and synchronizing CRM to an external data store. The following enhancements should help make some dramatic improvements.

• Alternate Keys Feature Enhancement
  • As of CRM 2015 (Carina) the platform will implement the concept of alternate keys
    • Implementing an integration pushing legacy data to CRM can require a significant amount of chatter with the sever because records need to be looked up by keys found in other systems and CRM only understands Guid’s
  • An alternate key can be defined against an entity so that it can be queried directly as opposed to having to use retrieve multiple queries to find the desired record
  • An alternate key can be made up of one or more fields on an entity and must be unique
  • There is a new key attributes collection that can be populated when making a calls to the server that will contain the key fields defined for the entity
  • Behind the scenes the platform creates a unique key on the defined alternate key fields. This will enforce a unique constraint for non-null fields.
  • For example, when making an update to an entity the alternate key can be used versus having to first find out the Guid of the CRM record. This allows for a direct reference between an external data store key such as an ERP system and the data within CRM.
• Upsert Request
  • Send UpsertRequest with enough data for a create or an update
  • CRM will determine if the record exists, and call create or update as needed
  • Works great with alternate keys
  • The Upsert request is a pure wrapper message. It determines up front before entering the CRM pipeline if the operations is going to be an insert or an update.
  • For plugins, if the record will be inserted the operation will run through the create pipeline and for an update it will run through the update pipeline.
• Special Fields Feature Enhancement
  • Owner, BU, Manager, State and Status fields all require unique API calls today to modify
  • Steepens the learning curve for new developers
  • Leads to more complex code
  • Introduces additional costly round trips to the service
  • Update: Assign and SetState will be changeable through a standard updates
    • Works for owner, state, status, business unit and manager fields
    • Since special fields will now be updatable via normal update operations developers will need to be careful to analyze any existing plugins that trigger on assign or set state events because these will not fire
    • The correct way to for example determine if the owner of a record has changed is to watch for an update and check the owner field. In this scenario the code will work normally after changing existing code to directly update the owner of a record.
• Transactional Batching
  • Execute multiple was introduced to help reduce the number of call that needed to be made to the server. This worked well for the most part, but alone it didn’t always meet the need because after making the request you would be notified of which requests were successful or not but they weren’t treated as a single unit
  • There are scenarios where it may be desirable for the request to act as a transaction where all requests succeed or they a fail.
  • Introducing the ExecutionTransaction request
    • Submit a collection of requests messages
    • Executed in sequence in a single transaction
    • All succeed or all are rolled back
    • A new API called Execute Transaction allows a developer to create a transaction for a given set of request messages.
    • It should be used for scenarios where you want to keep logical consistency
    • Constrained by the same limits as ExecuteMultiple for maximum batch size and concurrent batch execution
    • Can be composed with ExecuteMultiple
      • ExecuteMultiple can contain ExecuteTranscation items
      • Batch size is calculated by total of all individual items
      • Long running transactions can block other requests so use with care.
• External Data Store Synchronization
  • Scenarios include reporting/analytics, related applications like portals and master data flows
  • The basic question that needs to be answers is what has changed
  • Introducing the change tracking capability
    • Enabled at the entity level
    • Use new RetrieveEntityChanges SDK message
      • Returns records that have been created or updated, or deleted since the last request
      • Used for server data sync, not offline clients
      • Requires caller to have “root read” privileges on the requested entity
      • Delete history available for 90 days
      • Allows caller to retrieve changes to an entity
      • Designed for use in server to server data synchronization scenarios
    • Without the change tracking feature developers may use the last modified date to determine what has changed since a specific date and time, but the fallback of this approach is that it will not return deleted records
    • In practice developers would write their own plugins to track deleted records, but the change tracking feature will do this more efficiently for you
    • When you receiving a list of deleted records all you will get is the list of Guid’s so if you are syncing deleted records to another system you have to store the Guid’s in order to find the records to be deleted
• Optimistic Concurrency
  • As of today CRM has a policy of the last update to a record wins even in scenarios where a precious update will be lost
  • RowVersion returned with each retrieve entity
  • Concurrency behavior can be set with each UpdateRequest or DeleteRequest
    • AlwaysOverwrite (default) or IfVersionMatches
  • When IfVersionMatches requested, Update or Delete will fail if record has been updated since it was retrieved
  • API support only – not used by CRM clients
  • With the new optimistic concurrency option (called a Concurrency Behavior) CRM can keep track of the version numbers of records for entities. Two or more users may retrieve a record but if an update happens and another user attempts to save the record without the latest changes then the user will be presented with an error.