Rebase Client Configurations¶

Client configurations are changes made to the current application core layouts. In this sense the current client core metadata revision is the baseline for the configuration. I.e. the actual configuration is the difference between the baseline and the configuration. When the application is updated and updated revisions of client core metadata is deployed, then the configuration is no longer the same. In this case the baseline is now behind core and the configurations needs to be verified and uplifted to the new core. This is referred to as rebasing the configurations.

Rebase, is the process of investigating the differences between current core and a configuration baseline, decide what should be included and saving the updated configuration.

Architectural design and definitions¶

Client Model¶

IFS Cloud client layouts are grouped into different client models. This is the same as the server entity sets and actions are grouped into projections. In fact, there is a 1 to 1 relationship between a client model and a projection. Each client model is related to one projection and the way to grant access to pages is to grant access to the projection.

Artifacts¶

The client model is made up by a set of layout elements which is a logical layout item. Lists, groups, commands, charts are examples of elements. An element can be a container for other elements where the element reference other elements, e.g., Pages and Tabs.

Layout: {
   ...,
   Pages: {
      MyPage: {
         Name: ‘MyPage’,
         ...,
         Content:[
            {
               List: MyList
            }
         ]
      }
   },
   Lists: {
      MyList: {
         Name: ‘MyList’,
         ...
      }
   }
}

In the model design storage, each layout element is stored separately, and in this form, they are referred to as artifacts. An artifact is stored as a serialized JSON object that contains all metadata attributes that define the artifact. References to other elements are stored within the referencing artifact as a named reference, but the definition of the referenced artifact is stored as a separate artifact.

Layout configurations are layered revisions of an artifact. I.E., a page configuration is changes to one or more elements, and stored as layered revisions of the corresponding artifacts.

A published configuration will override the core layer artifact when client model is constructed in runtime. Similarly, when a configured artifact is unpublished or removed the original core artifact once again come into use.

A configuration, a change to any aspect of an artifact, will result in a copy of the original artifact being saved including the changes. This gives some implications when updating the environment, as updates to core artifacts are overridden by the configured artifact. Think of this as if the core artifact were stored as a document named doc. When a configuration is made it is stored as doc(1). Both documents are stored in the model storage and as long as the (1) revision exists, that is the one used. Hence updates to doc trough an update will not be used as doc(1) is still in use and it is still a copy of the original doc.

Baseline¶

The revision of the core artifact used as template for and saved together with a configuration is here referred to as baseline.

The model design storage also keeps track of the baseline in combination with the configuration. This is how our tools, e.g., Page Designer, displays the configuration changes. Even if the environment has been updated, Page Designer displays the differences between the baseline and the configured revision of the artifact.

Behind¶

A diff between the core artifact and a configuration baseline can occur. This happens when an application update introduces changes to the core artifact that is currently baseline to a configuration.

This situation is referred to as the configuration being behind. The configuration was made for a specific core revision and now core have moved forward. This also means that the configuration may be obsolete or even faulty combined with the updated core.

After an upgrade both Page Configurations admin overview and Page Designer tool will indicate where configurations are behind and needs to be rebased.

Identifying affected client configurations¶

In Page configurations page the baseline status is shown both on client model and artifact level

Baseline status on client model is an aggregation of the child artifact states. While the client model details display baseline status for each artifact.

In Page Designer the baseline being behind is indicated as a warning icon in the main toolbar command. This is also the command that when executed will open the Rebase Dialog.

Rebase Dialog¶

The rebase dialog is provided to make it possible to rebase configurations. I.e., re-apply configurations on top of updated core artifacts. In this tool the user is presented with the changes between core and baseline to the left and configurations to the right.

The rebase process is about processing (removing) all baseline changes. One start on the left side with choosing to apply baseline changes at some level in the tree. Adjust the configurations accordingly and save. Then repeat the same steps until all baseline changes are removed.

Baseline Changes (left side)¶

On the left side is baseline changes. The changes that are made to core after the configuration was initially created. For the rebase process the left side can be viewed as a task list. The configurations are rebased when there are no more changes displayed on the left side. Now the configuration baseline is up to date.

Note: Only changes to artifacts that have configurations are displayed. I.E., other artifacts may have been changed by the update, but those changes will not show here.

Icon	Description
	This indicator indicates that a node, attribute, or a child of a node has changes.
	This indicator indicates that a node, attribute, or a child of a node has conflicting changes. At some level the same attribute value that is configured has also been changed in core.

Configurations (right side)¶

The right tree displays the current configurations in the same way as the page designer.

Commands¶

The command in the designer is found both in toolbar and on the nodes and attributes. All commands will affect the level to which it is executed and entire child structure. This means that the user needs to choose the level from which to invoke different actions. Depending on the wanted outcome.

Icon	Description
	Start rebasing by applying baseline. This is the start command for one or several rebase activities needed to complete the rebase.
	Mark as rebased - This command bluntly updates the current configuration baseline to current baseline. This means that any baseline changes introduced will be ignored. This command is not intended as part of the normal rebase process but only to be used in situations where one is stuck for any reason. All changes may have been rebased but the rebase status still say "behind". In such a case the resolution is to use this command to force a completion.
	Save changes
	Undo
	Join disconnected item This is a command that is used to fix the broken link between items in the layers that are compared.
	Publish result When a rebase is completed then the configuration draft is rebased to the new core baseline. If the configuration was published to begin with, then the rebased draft needs to be published.

Join disconnected item¶

Parts of the client metadata are arrays. Arrays do not have unique attribute identifiers, only array position numbers. These identifiers will change once an item is added to or removed from the array. The way our tools keep track of changes baseline and configurations is to store a hash of the original array item together with the configured one. When to display configuration changes the hash is used to map the configuration to the correct original array item.

When core updates make changes to an array item the hash calculated for the updated item will no longer match the stored configuration hash, hence it is no longer possible to match the items. The configuration item is now disconnected. In the page designer or rebase dialog where there should have been a modified item, it will now show one deleted and one added item. The deleted item as there is a baseline item with a hash that does not exist in core. The added item because there is a core item with a hash that does not exist in baseline.

When this happens, the disconnected item can be manually connected again.

On the disconnected item click the join disconnected item command.
From the dropdown select the correct item to join with.

It is not possible to undo a join action. It is possible to close the rebase dialog without saving and start over again. But the undo command will not undo a join operation. Make sure that the correct items are joined. Sometimes this can be a bit tricky if several items are named / displayed similar. Or when labels have been changed as part of the update so two fields have different labeling. It is recommended to expand the two items and compare child attributes to make sure that there is a match

Just because an item displays the join command, it does not mean that this item is disconnected. The command is displayed for all added items in an array if there exists any deleted. This combination means that there could be disconnected items, without stating that these are.

Rebase process¶

Backup¶

Back up configurations prior to rebasing. Some of the actions performed during this process is finite. If things get out of hand. It is good to have ACP exports at hand that can be imported to give another chance.

These exports should be done after the application upgrade but before manually rebasing configurations. Client configurations are part of an application upgrade, during which, configuration stored content may be altered by upgrade scripts. This means that ACP exports taken prior to an application upgrade may be partially obsolete after the upgrade.

Unpublish¶

Before starting to rebase a configuration, any published configurations should be unpublished. Later versions of the tool will not even open if there are published content. If running a version where it is possible, remember to unpublish before. This will decrease the complexity of the two-way merge UI.

Base process¶

Here the process is described in a simple step to step process. In practice a rebase will be more complex and the described process may need to be applied several times and on different levels in the structure. So multiple passes may be required, but the base process for each pass will contain these simple steps.

Choose an area to work with. This is at a position where the tool displays baseline changes with Usually this would be an artifact. E.g., list, group, page. It can also be smaller area like a field in a list. Depending on the complexity between baseline changes and configurations it may be easier to do things in smaller steps.
Start by joining any disconnected items If the area that you intend to include in your rebase action contains disconnected items, you should connect items prior.
Start a rebase operation. In the left tree with the baseline changes, on a node or attribute that indicate changes, execute the “Start rebasing command”. This will update the configuration baseline for the node as well as overwrite the current configurations if any.
Choose between baseline changes and configuration. In step (3) existing configurations are overwritten by baseline. In the right tree (configurations) go trough and undo all applied baseline changes for the configurations that should be kept.
Save When saved the baseline change indicator is removed and the selected area is now resolved.

To complete a rebase of a client model. Repeat steps 1-5 until all the baseline change indicators are removed.

Publish¶

When all configurations are rebased, then finished result, can again be published.

For non-global configurations one needs to know that a custom context uses any existing published global as baseline. This means that global configurations should be rebased first. The global rebased configurations should then be published before custom context configuration can be rebased. If this is not done, then the custom context configuration will be rebased with core as baseline. Only to once again end up as behind once the global configuration is later published.

Scenarios & Practical Examples¶

This section contains a number of practical examples with step-by-step instructions on how to handle them in the Rebase Designer.

Simple core attribute change¶

In this example there is a configuration on a page artifact for which an update introduces a small unrelated attribute change. In this scenario the administrator wants to include the change into the configured artifact.

Existing config have removed one group from the page content.
In the update the label of the page has been changed to "Overview Persons". After the upgrade the configuration is flagged as behind. Indicating that the baseline has now changed since the configuration was created.
The administrator is opening the Rebase Designer by clicking on the flag. Expanding the structure indicated as being behind, the attribute change is found and can be reviewed. I.e., is this a change that should be included/merged to existing configuration or omitted.
The administrator want to include the label change into the configuration and start with applying baseline update.
The core label change is applied to the configuration and synchronized with the config baseline.
In this scenario the core change should be merged to the configuration so the current state is the wanted one and the administrator is saving the change. After saving the configuration is updated with core label change and there are no more behind indicators left. This means that the rebase process for this client file is finished.
After closing the Rebase Designer the "behind" flag is removed while the publish command is enabled. It is the draft layer that is rebased and to publish the rebased result, the changes must be published.

Simple core attribute change to configured attribute¶

This scenario is same as the above with the difference that in this case, the label is already configured by the customer. The label change introduced with the upgrade is not wanted. The rebase process is still the same with the addition that the existing label should be preserved.

At the start the customer now have a configuration for the label "Customer Persons"
Opening the Rebase Designer, the baseline change indicators are now orange. This is because they indicate that there are conflicting changes between configuration and the core changes.
Even if the goal is to preserve the configuration. The rebase process always start by applying the baseline change. This synchronizes the core change into the configuration baseline as well as applying it to the configuration.
After applying baseline updates. If there is a configuration that should be preserved. Then the administrator should undo the change that is done to the configuration, before saving. This way the configuration baseline is updated while the configuration is kept unchanged.
When the update is saved the Rebase Designer have no more behind indicators to handle and the rebase process is finished. Close the Rebase Designer and publish the result.

Merge and preserve removed items¶

When there are items in the core metadata that has been removed. These changes are handled in much the same way as for attribute changes. In this scenario some fields are removed from a list. The administrator wishes to merge one of the removals and preserve the other field. Note: this scenario assumes that core is removing the field from the list element, but the connected attribute is still present in the core entity. If this is not the case, the administrator would end up with a configuration that throw an error in runtime. This scenario starts with the Person List containing one configuration where the customer has removed the "Alias" field from the list.

After upgrading the application the page designer indicates that the configuration is behind and needs to be rebased. Opening the Rebase Designer it turns out that the "Nick" and "Weight" field has been removed from the core list.
In this case the administrator decides to go along and merge the removal of the "Nick" field but want to preserve the "Weight" field. Start by applying baseline update for the removed fields
Then undo the configuration change for the "Weight" field to preserve the field in the list. Note that it is possible to preserve a value like this even if it was not a configuration to begin with.
After saving these operations the result is now that there is a new configuration in place. The "weight" field that was preserved during rebase will now be an added field in the configuration. Preserving the field that is removed gives the same outcome as if the administrator would have added a field that was not there to begin with.
There are no more behind indicators so the rebase process is finished. Rebase designer can now be closed, and the result published.

Added field¶

In the case where there are added array elements to the baseline, e.g., fields to a group or a list. Then it is not as straight forward as to cherry-pick only the changes. The Rebase designer does not currently support picking of added or re-arranged items in an array. E.g., content items. In this case the rebase action (apply baseline) must start on the array itself.

In this scenario we start out with the result of the previous where there is a configuration to the "Person List" where "Alias" field is removed, and "Weight" field is added.

The upgrade now introduce the "Nick" field and that field shows up in the Rebase Dialog as a baseline change. In this case the indicators up to and including Content is shown as "conflict". This is because with the added items both baseline content and configured content are changed.
Hovering on the added item itself is not enabling a rebase action command. This is because the Rebase designer is currently not supporting cherry-picking of added or re-arranged items. Instead, where there are added or re-arranged items one need to start the action on the actual collection item that contains the item. In this case "Content"
Start the rebase action on the "Content" will mean that all configurations in that collection and its children are set to baseline. Any configuration in this collection that should be preserved needs to be reverted before saving.
The administrator decide to preserve the configurations as the where and undo applied changes for the "Alias" and "Weight" field.
After the undo actions the "Nick" field is merged to the configured "Content" collection and can be saved.
After save there are no more baseline changes to handle. The administrator closes the Rebase Designer and publish the result.

In cases where there are several changes from core in a combination with several configurations, above process can become a bit complex. Once the start rebase command is executed the distinction between baseline changes and configurations is to some extent lost. To overcome this possibly overwhelming situation one can follow this procedure.

Start to pick and rebase all none added elements and child details separately.

As a last step, execute the start rebase command for the array node.

Undo changes for all elements except for the added one

If some added element should not be included, delete it

Save

This process will still overwrite all configurations in step 2 with baseline. The difference is that because all the details has already been sorted in step 1, it is much less complicated to distinguish between configurations to be undone and the added items.

Join disconnected items¶

In this scenario an application upgrade contains child changes to several fields in a list. A change to a child of an item located in an array result in that the connection between the original and the configured item is lost. See detailed information in the section Join disconnected item. In practice this means that the disconnected items need to be re-connected as part of the rebase process.

Administrator opens the Rebase Dialog box and find that there are some filed changes in the "Person List". Note that there seems to be duplicates of the "Alias" and "Last Name" fields.

If the removed "Last Name" fields are expanded in the baseline tree the field is also expanded in configuration side. This indicates that the designer regards these two versions of the field are connected. This while the other version of the "Last Name" field is unconnected. The value that is changed in the update "Max length" is found in the now not connected version of the field. This is also what happens when an item becomes disconnected. The reference to the original item that the configuration holds is a hash value of the item. When the item is changed the hash changes and the reference is broken. The item is disconnected.
- The field version that exists in the configuration baseline, can't be matched to the changed one in updated core and because of that is displayed as if the update deleted it.
- The field that was updated can't be matched to an existing baseline item and because of that is displayed as if the update is adding the field.
- The configuration is matching the config baseline item and because of this the deleted item is connected to the configured item on the right.
Before the baseline change can be applied. The disconnected item needs to be connected. I.e. refresh the reference between the configuration configuration baseline and core item. The administrator does this by clicking "Join disconnected item" on the disconnected item and then select the item that it should be connected to.
When the item has been connected then the field is displayed in the baseline side as the original field with a change to be handled. The administrator is now applying the core change as for any other attribute change. Can just apply to merge core or decide to preserve the configuration with the current value.
Another field "Alias" is also disconnected containing changes. In the configuration this field is removed from the list. Even if the goal is to preserve the deletion the rebase process is the same. The administrator needs to handle to handle the baseline change. And start out with connecting the disconnected item. When the item is connected, the administrator choose to preserve the deletion and only merge the updated value into the deleted baseline.
When saved the baseline change indicator is now removed and the configuration shows that the deleted "Alias" field equals the new baseline. (rebased)
Last item to connect is an item where a change to the label is introduced. This is a situation that highlights the importance to be careful with connecting items. It is not always straight forward. The administrator is not sure. The situation could be that there is an added "Duration" field and "Length" is actually removed. By looking at the field "Attribute" attribute the administrator concludes that this is actually an update of the label for the "Length" field, and it is really disconnected.
After connecting "Duration" and "Length" field the administrator goes ahead and applies the baseline change.
Now all the baseline changes are handled, and the configuration is fully rebased on top of the upgraded core baseline. The administrator can now close the rebase dialog and publish the result.

Re-arranged array items¶

Arrays where the order of the items has been altered are handled in the same way as added items. This could for example be the content attribute of a list where all the fields are array items. Here the order matters and some fields may have been moved to other location. Here the rebase operation needs to start on the array node as the order of items is owned by the array not individual items.

In the same way as for the added items. It is a good idea to resolve conflicts for array children before rebasing the actual array. This makes it easier to keep track of what is what.

If baseline changes introduce an un-wanted item order. Then the items can be re-arranged in the right tree before saving.

In this scenario the configuration has a label change for "Last Name" as well as changed the order of "First Name" and "C-Last Name". The core upgrade introduce a new field to the same list.

The "Nick" field is added so the administrator have to start applying changes on the parent "Content". This operation overwrites all configurations with current core. Both order and label change is at this point reverted.
The administrator wants to preserve the configurations as they where, and starts by undoing the applied label change for "Last Name"
When applying baseline changes the designer does not support cherry-picking of added or re-arranged items. It is the same with undoing changes. It is not possible to undo a re-arrange directly on the items. This also has to be done on the parent. Something of a catch-22 as that would undo the added "Nick" field. In this case the administrator will have to re-apply the configuration manually. He can do that directly in the configurations pane of the designer by drag-n-drop the items to the wanted positions.
When the re-positioning is done the result is the wanted. At this point the administrator saves the changes, closes the rebase designer and publish the result.