Advanced sync setup: Difference between revisions

Jump to navigation Jump to search

Advanced sync setup (view source)

Revision as of 11:19, 9 January 2020

9,158 bytes added ,  9 January 2020
→‎Custom upload order: new functionality January 2020
(→‎Custom upload order: new functionality January 2020)
Line 242: Line 242:
</SESetup></syntaxhighlight>
</SESetup></syntaxhighlight>


== Custom upload order ==
You can use advanced sync setup to modify the order, in which the client changes are uploaded to the server. This functionality was introduced in a bugfix release in January 2020 (release 12.3.1).
=== Default behavior ===
Let's start by explaining how MCRM uploads user changes.
# MCRM starts by collecting entities with changed records.<br>Changed records are uploaded entity by entity. It cannot happen that, e.g. uploaded accounts would be intermixed with uploaded contacts.
# Next, MCRM decides about the upload order, i.e. which entity is uploaded first, which one comes next, etc. The decision is based on these goals:
#* Parent record (quote, invoice) are uploaded before child records (quotedetail, invoicedetail). See also note below.
#* Minimize forward references. In other words, the lookup target record should be uploaded before the lookup source record. (To avoid lookups pointing to records which were not uploaded yet.)
#* The following entities are uploaded at the very end: ''businessprocessflowinstance'' (entity used for business process modelling; Dynamics only) and ''resco_mobileaudit'' (entity storing MCRM audit information).
The upload order can be checked in the sync log. (You need to enable sync details in [[configuration]] of your app project.)
{{Note|You can influence the upload order by defining child-parent relations. In Woodford, edit the app project, select the child entity from the '''Project''' menu, select the lookup that points to the parent record, and on the '''Properties''' pane check '''Mark as Parent'''.}}
In most scenarios, the default order is good enough. However, there are situations when an optimal upload order does not exist, typically when there are circular references between changed records. In these cases, MCRM attempts other strategies, for example, partial uploads. A detailed explanation is beyond the scope of this document.
Moreover, there are situations that cannot be solved on the client side, e.g. when the server uses a plugin that requires a specific order of uploaded entities.
=== Custom order ===
To address the problems related to the upload order MCRM allows specifying a custom upload order. Custom upload order consists of commands (instructions) that are applied after the upload entities were sorted by the default algorithm.
In particular, you can specify:
* Which entities are uploaded at the beginning (FirstEntities) and which entities are uploaded at the end (LastEntities) of the upload process.
* The order of two or more entities (Sequence).
* Any number of statements of the type "Entity A should be uploaded before Entity B" (Relations).
If your custom commands contradict each other, some are silently ignored.
It is not necessary to define the order of all entities. Usually, it's better if you only set the order of those entities which you want to manage.
=== Technical details ===
The order of application of custom commands:
;(1) FirstEntities
* Only one <FirstEntities> element is allowed, but it may contain any number of entities.
;(2) Sequence
* Only one <Sequence> element is allowed, but it may contain any number of entities.
* Unknown entities (or entities which do not have any changes) are eliminated; remaining Sequence elements (if any) are respected.
;(3) Relations
* Only one <Relations> element is allowed, but it may contain any number of relations.
* Invalid relations (either source or target is an unknown entity) are ignored.
* Remaining relations are interpreted one by one in a cycle.
* The whole cycle is repeated several (but finite number of) times until all relations are fulfilled. (If possible.)
;(4) LastEntities
* Only one <LastEntities> element is allowed, but it may contain any number of entities.
Understand the difference between '''Sequence''' and '''Relations'''. For example:
:<syntaxhighlight>
Sequence: Entity1 < Entity2 < Entity3
Relations: Entity1 < Entity2, Entity2 < Entity3
</syntaxhighlight>
It may look like the two rules above have the same effect, however, there is a difference in the transitivity.
If Entity2 does not exist (or has no changes), then we are left with this:
:<syntaxhighlight>
Sequence: Entity1 < Entity3
Relations: - (nothing)
</syntaxhighlight>
Another important difference between above rules is that '''Sequence''' can't express multi-child relations, e.g.
:<syntaxhighlight>
Relations: Entity1 < Entity3, Entity2 < Entity3
</syntaxhighlight>
=== Examples of custom upload order ===
<syntaxhighlight lang='xml'>// Simple custom order, where we only specify that account entity should be uploaded at the very end after all other entities (if any) are uploaded.
// Note the syntax - <SyncDownloaderSetup/> is omitted. (This node is optional.)
<SESetup Version='1'>
<UploadOrder>
<LastEntities>
<Entity>account</Entity>
</LastEntities>
</UploadOrder>
</SESetup>
</syntaxhighlight>
<syntaxhighlight lang='xml'>// Complex example, where we specify which entities should be uploaded at the start, resp. at the end.
// Additionally, we use Sequence to specify sort order of some of the remaining entities.
<SESetup Version='1'>
<SyncDownloaderSetup>
<Setup Platform='Desktop WinRT WinUWP' DownloadCacheSize='1000' DownloadPageSize='5000' />
</SyncDownloaderSetup>
<UploadOrder>
<FirstEntities>
<Entity>entity8</Entity>
<Entity>entity9</Entity>
</FirstEntities>
<Sequence>
<Entity>entity7</Entity>
<Entity>entity6</Entity>
<Entity>entity5</Entity>
<Entity>entity4</Entity>
<Entity>entity3</Entity>
<Entity>entity2</Entity>
</Sequence>
<LastEntities>
<Entity>entity0</Entity>
<Entity>entity1</Entity>
</LastEntities>
</UploadOrder>
</SESetup>
</syntaxhighlight>
<syntaxhighlight lang='xml'>// Another relatively complex example.
// entityX denotes entity, which is omitted from the client customization.
// This is no error - MCRM simply ignores such entities. (This provides more flexibility when writing custom orders.)
<SESetup Version='1'>
<SyncDownloaderSetup/>
<UploadOrder>
<Sequence>
<Entity>entity8</Entity>
<Entity>entity2</Entity>
<Entity>entityX</Entity>
<Entity>entityX</Entity>
<Entity>entityX</Entity>
</Sequence>
<LastEntities>
<Entity>entity1</Entity>
</LastEntities>
</UploadOrder>
</SESetup>
</syntaxhighlight>
<syntaxhighlight lang='xml'>// Example illustrates a specific upload order, where we define the order of all entities.
// This is a risky setup (you have to analyze all lookups), but if you know what you are doing, the option is here.
<SESetup Version='1'>
<SyncDownloaderSetup/>
<UploadOrder>
<Sequence>
<Entity>entity9</Entity>
<Entity>entity8</Entity>
<Entity>entity7</Entity>
<Entity>entityX</Entity>
<Entity>entity6</Entity>
<Entity>entity5</Entity>
<Entity>entity4</Entity>
<Entity>entity3</Entity>
<Entity>entity2</Entity>
<Entity>entity1</Entity>
<Entity>entity0</Entity>
</Sequence>
</UploadOrder>
</SESetup>
</syntaxhighlight>
<syntaxhighlight lang='xml'>// Example illustrating another possibility of how to influence the upload order:
// This time we specify that entity A should be uploaded prior to entity B plus a similar instruction for entity C and entity D.
// You can specify any number of such relations, just make sure they do not contradict each other.
<SESetup Version='1'>
<SyncDownloaderSetup/>
<UploadOrder>
<Relations>
<Relation Entity='entityA' Before='entityB' />
<Relation Entity='entityC' Before='entityD' />
</Relations>
</UploadOrder>
</SESetup>
</syntaxhighlight>
<syntaxhighlight lang='xml'>// Complex example, where we use several mechanisms to adjust the upload order.
<SESetup Version='1'>
<SyncDownloaderSetup/>
<UploadOrder>
<Sequence>
<Entity>entity7</Entity>
<Entity>entity6</Entity>
<Entity>entity3</Entity>
</Sequence>
<Relations>
<Relation Entity='entity8' Before='entity0'/>
<Relation Entity='entity9' Before='entity0'/>
<Relation Entity='entity5' Before='entity4'/>
</Relations>
<LastEntities>
<Entity>entity2</Entity>
</LastEntities>
</UploadOrder>
</SESetup>
</syntaxhighlight>
<syntaxhighlight lang='xml'>// Last example is here to demonstrate one formal aspect: Order of XML nodes is not prescribed.
<SESetup Version='1'>
<SyncDownloaderSetup/>
<UploadOrder>
<LastEntities>
<Entity>entity2</Entity>
</LastEntities>
<Relations>
<Relation Entity='entity0' Before='entity3'/>
<Relation Entity='entity9' Before='entity0'/>
</Relations>
<Sequence>
<Entity>entity7</Entity>
<Entity>entity6</Entity>
</Sequence>
</UploadOrder>
</SESetup>
</syntaxhighlight>
=== Sync log notation ===
Information about the used custom upload order can be found in the sync log in the <UploadOrder> node, as shown in the example below. Note that this information is omitted if there are no changes to be uploaded to the server.
<syntaxhighlight lang='xml'>
SyncStart:2020-01-02 14:29:46+01:00
<UploadOrder>
    <FirstEntities> entity1 entity2</FirstEntities>
    <LastEntities> entity3</LastEntities>
</UploadOrder>
Date:2020-01-02 14:30:16+01:00
Org:...
</syntaxhighlight>


[[Category:Synchronization]]
[[Category:Synchronization]]
Retrieved from "https://docs.resco.net/wiki/Special:MobileDiff/1619"

Navigation menu