View source for Deploy UI Customizings (Client)

As a crucial part of the {{UBIK}} client, it is often the case that a set of UI customizings, once finished, is needed on multiple devices. Therefore, the deployment is an important step.

== Location of UI customizing ==
UBIK clients use the same <code>[CurrentUserFolder]\AppData\Packages\AugmensysGmbH.UBIK.[ClientType]\LocalState\XAML</code> folder as the root of all UI customizings.
* [CurrentUserFolder] is something like "C:\Users\UserName";
* [ClientType] is either UWP or Xamarin.

=== Profile specific customizing {{Version/XamarinSince|1.2}} ===
In some scenarios, a user might want to switch between two different sets of UI customizings depending on the selected profile. To achieve this, the customizing files need to be deployed accordingly.

Every profile has a field called "Name", which not only decides how it's displayed, but also tells the client under which sub folder it should look for profile specific customizings. Imagine a profile named "Demo_V3", the client first tries to find a "Demo_V3" sub folder under the [[#Location_of_UI_customizing|root XAML folder]]. If it finds none, it then uses those under the root.

{{Hint|There's also another field called "Customizing" in a profile. If specified, it overrules the "Name" field when it comes to the profile specific customizing folder. This is usually only used if you want different profiles to share the same set of customizings.}}

== Manual deployment ==
This is an obvious approach of deploying UI customizings. From a {{UBIK}} perspective, this can be
* Manually copying/pasting the UI customizing files (XAMLs, images, etc.) to the desired devices;
* Other 3rd-party (e.g. customers' private rollout infrastructure) automated deployment systems.

=== Import UI customizing ===
Since it's impossible to copy/paste files to the app data folder with UBIK.Xamarin for Android and iOS, those clients provide an alternative option to "Import Customizing" in the general settings.
* You can import a single XAML file which then ends up under the [[#Location_of_UI_customizing|root XAML folder]];
* You can also import a zip archive of many XAML files at once.
** With a zip archive, its content (files and folders) is unpacked under the [[#Location_of_UI_customizing|root XAML folder]] '''with the folder structure of the archive preserved'''. This is important because of the [[#Profile_specific_customizing|profile specific customizing]] feature.


== {{UBIK}} server deployment ==
{{Version/WinXSince|3.7}} {{Version/XamarinSince|1.1}} {{UBIK}} provides a new solution where UI customizings can be deployed from {{UBIK}} servers to the clients the same way content can be fetched.

=== Technical concept ===
The UI customizings are delivered from {{UBIK}} servers to clients in the form of [[SYSCLS_UI_CUSTOMIZING|archive documents]] which contains the following.
* The archive files containing the packed UI customizing files;
* The version of the UI customizings.

=== Client scenario ===
Once a {{UBIK}} client connects to a server and downloads such a customizing archive, it unpacks the archive file the same way it does during a [[#Import_UI_customizing|manual import]].
* If a folder or a file at the root level of the archive already has a same-named counterpart in the client's XAML folder, the existing one is first removed before the one from the archive gets unpacked;
** {{Version/WinXSince|4.7}} {{Version/XamarinSince|4.7}} A copy of the zip archive will be saved to the Documents/UIArchive folder.
* Once the archive is unpacked, the client tries to reload the UI customizings. If a set is found for the currently selected profile, one should see the changes in the UI;
* Most likely, you would want to include a certain folder structure in the archive to achieve [[#Profile_specific_customizing|profile specific customizing]].

=== Some other details ===
* The download of a document file is not always automatically done in {{UBIK}} clients.
** If the archive document is a part of the infrastructure objects, its file is automatically downloaded during login (as long as the client is in online/auto sync mode);
** Otherwise, one has to either navigate to that document or download a branch containing that document.
* One can deploy multiple sets of UI customizings in a single archive document by placing them under corresponding folders. Theoretically, it's okay to configure and deliver multiple archive documents to the clients since the content will be unpacked just the same. However, it's our recommendation to use a single archive document not only because it's simpler, but also see below;
[[File:UI_WinX_Customizing_Version.png|thumb|alt=Customizing Version|Customizing Version]]
* The version information of the UI customizings is available on the archive document and is displayed together with the client version at the bottom of the login page. Currently there's no additional UI to display a list of versions, so the version of a randomly chosen archive will be displayed in case multiple are present. Also, the version information only becomes available after a user logins in (which grants access to the content).

=== Known Issues ===
Sometimes, unpacking UI customizing archives might fail because the app cannot overwrite some files which are being used in the current UI. A typical example of this is related to using the Image control.
In the example below, an image file "UBIK.png" under the "Demo" customizing folder is referenced by an Image control. If such a control is displayed while an archive containing a set of UI customizings with the same name "Demo" is received on the client, the unpacking will fail because the UI is still holding onto the file, which blocks the unpacking.
<syntaxhighlight lang="xml">
<Grid>
    <Image ...
        Source="ms-appdata:///local/xaml/Demo/Images/UBIK.png" />
</Grid>
</syntaxhighlight>
This tends to happen with image files used in the login/home page since that's where users are most likely at when UI customizing archives are received. In such cases, one can use the following converter technique so that the image files can be safely deleted even when they are being displayed.
<syntaxhighlight lang="xml">
<Grid>
    <Grid.Resources>
        <x:String x:Key="logo">ms-appdata:///local/xaml/Demo/Images/UBIK.png</x:String>
    </Grid.Resources>
    <Image ...
        Source="{Binding Source={StaticResource logo}, Converter={StaticResource PathToImageConverter}}" />
</Grid>
</syntaxhighlight>
{{Attention|The converter essentially creates a copy of the image file in the device memory. While solving the deletion problem, it does add up the memory consumption. So one should be cautious about using this converter too much especially when the images are relatively large.}}
{{Hint|An easy way to verify whether the failing of unpack is related to the deletion is to check in Windows Explorer whether there are files that can not be manually deleted in the target unpakcing folder before closing the {{UBIK}} app. If that's the case, please check the customizings and see if there's any reference to those files that can not be deleted. When the problem is not solvable with the above mentioned technique, please [https://support.augmensys.net/scp/index.php create a ticket with sufficient details] or manually delete the files after closing the app.}}


== Delete UI customizings ==
In UWP, customizing files can be deleted manually in the app data folder.

Similar to the importing scenario, it's impossible to delete customizing files from the app data folder with UBIK.Xamarin for Android and iOS, those clients provide an alternative option to "Delete Customizing" in the general settings (not yet available on UWP).
* {{Version/XamarinSince|4.7}} All customizing files for all users will be cleared.
* Versions before 4.7: to properly clear all customizing related files it is necessary to "Delete files" additionally to "Delete Customizing" (Note: with "Delete files" all online documents will be cleared).

[[Category:Client|Deploy UI Customizings (Client)]]
[[Category:WinX|Deploy UI Customizings (Client)]]
[[Category:Xamarin|Deploy UI Customizings (Client)]]