Hidden Seek Operation in the Scribe Connector for Dynamics 365/CRM
Overview of the SeekUnder Operation
The Scribe Connector for Dynamics 365/CRM leverages a feature called Seek Under to allow users to configure more natural match criteria. This feature allows Scribe users to configure target operations that require a lookup (Update, Update/Insert and Delete) with match criteria other than the primary key. The Dynamics 365 API requires a primary key for these operations. When using a one of these target operations, the Scribe Connector performs a Seek behind the scenes to automatically retrieve the primary key, removing the need to explicitly configure the primary key retrieval and related link in the Map. We refer to this operation and corresponding feature, as a “SeekUnder.”
Previous SeekUnder Implementation
In earlier versions of the Connector, prior to the Fall 2017 release (v.1.5), this SeekUnder occurred every time one of the specified operations was executed. In the Fall 2017 release, we introduced some SeekUnder optimizations, which have implications that are not immediately obvious, but are useful for designing more efficient integrations.
SeekUnder Implementation Changes
Default Behavior on Update and Update/Insert Operations
- Update and Update/Insert operations execute the SeekUnder operation by default to support customers’ existing Maps.
Default Behavior on Delete Operations
- For standard processing, Delete operation always perform the SeekUnder operation to maintain backward compatibility with a feature that returns all values from the deleted record prior to deletion. Users can then log successfully deleted records to an external data store.
- For bulk or batch processing, Delete operations perform the SeekUnder if no primary key is provided in the match criteria and skip the SeekUnder if the primary key is provided in the match criteria.
The SkipSeekUnder Option
As of the Fall 2017 release, the Connector has a new virtual Boolean field, SkipSeekUnder, for Update and Update/Insert operations. The field is exposed on Delete operations but is not functional. Deletes behave as described in the Default Behavior section above in all cases.
Option Behavior on Update and Update/Insert Operations
If the SkipSeekUnder field is set to true, the SeekUnder operation is skipped if the match criteria include either a single standard GUID or a complete alternate primary key.
- The SeekUnder is executed to retrieve a unique primary key if the match criteria include either of the following:
- More than one primary key.
- An incomplete multi-segment alternate key.
- Even if the match criteria on the block is a single standard GUID or a complete alternate primary key, Scribe overrides this setting and the SeekUnder is executed in the following scenarios:
- You have mapped an OwnerId field without mapping the OwnerIdType field. Scribe interprets that the intention is to leave the Type field untouched in the existing record and so does the SeekUnder to obtain the current value. The recommended best practice here is to always provide links to both the Entity Reference Id and Type fields.
- You have mapped a value to either State or Status or both. Scribe executes the SeekUnder because certain actions require specific SetState calls that may require comparisons of the values you have linked to existing values.
Upsert Operation Changes for Alternate Key Support
Overview of the Upsert Operation
The Upsert operation has been available in the Connector for Dynamics 365 for some time, but with this release we have implemented wider support for alternate keys. That means some changes to the way you work with the Upsert operation. First a quick overview of the differences between Update/Insert and Upsert.
Most Scribe Connectors expose an Update/Insert operation. Any entity that can support both the Update operation and the Create operation can support the Update/Insert operation. This is because the Update/Insert operation is just an attempt to execute each operation in sequence. Like an Update block, you define the match criteria and, if the update fails, Scribe then attempts an Insert.
When you see an Upsert operation in a Scribe Connector, it indicates that the API itself provides this capability and performs similar logic to our Update/Insert except that it is all done by the API, on the application server side. This means Scribe is only executing a single operation. It also usually means, as is the case with the Upsert available through the Dynamics 365 API, that the match criteria are not defined separately. The operation requires a key to be passed in as a linked field and uses that key to find a match for updating.
Previous Upsert Implementation
In the past, the Upsert operation in Dynamics 365 was pretty straightforward, if you did not provide the standard GUID primary key for the entity, the Upsert operation was not valid and you received an exception indicating that the primary key was required.
Upsert Implementation Changes
With the new support for alternate keys, the Upsert operation now has a way to specify which key to use as the match criteria via the new AlternateKeyName virtual field. When the AlternateKeyName field is populated, the named key is used as the match criteria if the fields that make up that alternate key are also linked. If the AlternateKeyName field is not populated, the standard GUID primary key is used as the match criteria and must be linked. If all are linked, the alternate key takes precedence.
- The AlternateKeyName field is populated with a valid alternate key name, but the alternate key fields are not all linked.
- The AlternateKeyName field is populated with an invalid alternate key name.
Neither the AlternateKeyName field nor the GUID primary key fields are linked.