I'm using usync to handle deployments between our test and production Umbraco sites. I've managed to build a functioning workflow for doing this automatically, using the usync API from within the Umbraco-site, triggered by an external web call.
However, I have a couple of question concerning Usync and the API
The Import() method takes an argument "force". What does this bool signify? If this is documented somewhere that I simply haven't found, please refer me to this document.
How will the Import() function handle potential conflicts? Will it throw exception Immediately or simply import what it can? If the latter is true, how to you check on a uSyncAction whether a conflict occur. Is this what the "Success" property is for? See example below:
var actions = uSyncBackOffice.Report("groupName", "folder");
if (actions.Any(x => !x.Success))
{
//ABORT!
return;
}
uSyncBackOffice.ImportAll();
What's the difference between Report() and ImportReport()? What are the "groupname" and "folder" parameters for?
Is there any point in calling Report() prior to an Import() to check for conflicts, assuming that you'll always want to import as much as you can from the content in your usync-folder.
Should I use Import() or ImportAll()? I realize the ImportAll() options imports everything regardless if there is a change or not, so it would seem that Import() is safer, although most code samples I found use ImportAll(). Is ImportAll() considered best practice when handling Usync?
And sort of related:
Is it advisable to, rather than syncing directly against the production site, synchronize a staging umbraco database and then simply restoring the production umbraco database from the staging one? Are there any potential mismatch that can occur between content and what's in the database if you do the latter? I realize this is more of a general best practice question than a specific usync question but I'd appreciate some advice nonetheless.
The force tag forces the import even if uSync things there are no pending changes.
During an import - uSync first generates an xml element of the current node in umbraco and compares this to the one on disk (removing some id values that are specific to the instance). If these files are the same then uSync will not (normally) perform an import and you will get the action change action NoChange back from the report (this also sets x.Success == true).
uSync will import everything it can - If it hits a conflict or change then that is reported for that item, in the result. so if Success != true, you should also see the ChangeDetail and Message elements of a action give you more details as to what went wrong.
ImportAll is the wrapper for Import and will just use the usync config - you only need to call import if you are planning on change the handler groups (see below) or you want to always specify the folder.
x.Success is only true when things have either been imported successfully, or no change was required (so no import happened).
If you want to do full transaction style importing (so import and if there are errors, rollback). Then uSync doesn't do this out of the box : but you could implement something by first performing an export to a temp folder, doing the import and if there are any errors, performing a roll back import from the temp folder. but it's quite a bit of faff for very little gain to be honest. if your imports are not working there is likely a bigger issue at play.
ImportReport is the simpler wrapper for Report, as you point out report takes the handlerGroup Parameter:
as mentioned above you don't need to call Report before doing an import, the import functions do the report checks before they perform a report, with force = false - importing will only happen where there is a change to be made.
But If you want to sanity check your usyncfiles / structure then a report before import would capture any corrupt files on disk - but its not until an actual import is attempted that you will find out if there are unrecoverable issues in the install.
Syncing another DB:
if you are 100% sure the stage db is the same as the live one before you start this can be done - taking a backup of live, running the sync and swapping to that instance as live (e.g with deployment slots in azure) would work like this.
Thanks for the clarifications! I think you answered all of my questions actually.
I do however have another follow up questions regarding the ImportAll(), feature; will Usync ever delete files if it detects files in the database that are not in it's Usync-folder when executing an Import?
Also, which are the circumstances (assuming no parameters are provided) where ImportAll() or ReportImport() might throw an exception?
PS: I have another question regarding Usync ContentEdition but I will post that in a separate thread as it is another type of issue.
Some Usync API questions
I'm using usync to handle deployments between our test and production Umbraco sites. I've managed to build a functioning workflow for doing this automatically, using the usync API from within the Umbraco-site, triggered by an external web call.
However, I have a couple of question concerning Usync and the API
The Import() method takes an argument "force". What does this bool signify? If this is documented somewhere that I simply haven't found, please refer me to this document.
How will the Import() function handle potential conflicts? Will it throw exception Immediately or simply import what it can? If the latter is true, how to you check on a uSyncAction whether a conflict occur. Is this what the "Success" property is for? See example below:
What's the difference between Report() and ImportReport()? What are the "groupname" and "folder" parameters for?
Is there any point in calling Report() prior to an Import() to check for conflicts, assuming that you'll always want to import as much as you can from the content in your usync-folder.
Should I use Import() or ImportAll()? I realize the ImportAll() options imports everything regardless if there is a change or not, so it would seem that Import() is safer, although most code samples I found use ImportAll(). Is ImportAll() considered best practice when handling Usync?
And sort of related:
Thanks in advance!
Hi
lots of questions, hope i can answer them all :
The
forcetag forces the import even if uSync things there are no pending changes.During an import - uSync first generates an xml element of the current node in umbraco and compares this to the one on disk (removing some id values that are specific to the instance). If these files are the same then uSync will not (normally) perform an import and you will get the action change action NoChange back from the report (this also sets x.Success == true).
uSync will import everything it can - If it hits a conflict or change then that is reported for that item, in the result. so if Success != true, you should also see the ChangeDetail and Message elements of a action give you more details as to what went wrong.
ImportAll is the wrapper for Import and will just use the usync config - you only need to call import if you are planning on change the handler groups (see below) or you want to always specify the folder.
x.Success is only true when things have either been imported successfully, or no change was required (so no import happened).
if you want more detail you can get it from the Change value on the action (see https://github.com/KevinJump/uSync/blob/Dev-v7_4/Jumoo.uSync.Core/SyncAttempt.cs#L120)
If you want to do full transaction style importing (so import and if there are errors, rollback). Then uSync doesn't do this out of the box : but you could implement something by first performing an export to a temp folder, doing the import and if there are any errors, performing a roll back import from the temp folder. but it's quite a bit of faff for very little gain to be honest. if your imports are not working there is likely a bigger issue at play.
ImportReport is the simpler wrapper for Report, as you point out report takes the
handlerGroupParameter:Handler groups are new ( http://usync.readthedocs.io/handler-config/ ) and allow you to define what handlers run during your import, so by default all handlers run, but if you where to put a new handler group in the usyncbackoffice.config file. then you could call that and say have a handler group that only imported dictionary items. the repo is slightly ahead of the current release but you can see that in the config here https://github.com/KevinJump/uSync/blob/Dev-v7_4/Jumoo.uSync.BackOffice/Config/uSyncBackOffice.Config#L57
as mentioned above you don't need to call Report before doing an import, the import functions do the report checks before they perform a report, with force = false - importing will only happen where there is a change to be made.
But If you want to sanity check your usyncfiles / structure then a report before import would capture any corrupt files on disk - but its not until an actual import is attempted that you will find out if there are unrecoverable issues in the install.
Syncing another DB: if you are 100% sure the stage db is the same as the live one before you start this can be done - taking a backup of live, running the sync and swapping to that instance as live (e.g with deployment slots in azure) would work like this.
Thanks for the clarifications! I think you answered all of my questions actually.
I do however have another follow up questions regarding the ImportAll(), feature; will Usync ever delete files if it detects files in the database that are not in it's Usync-folder when executing an Import?
Also, which are the circumstances (assuming no parameters are provided) where ImportAll() or ReportImport() might throw an exception?
PS: I have another question regarding Usync ContentEdition but I will post that in a separate thread as it is another type of issue.
is working on a reply...