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 / Examples¶

Simple attribute change¶

In this example a field in a list have one attribute configured while another attribute is updated in core. The core change result in configuration becomes behind and needs to be rebased. Simple additions like this are easy to rebase as they can be picked one by one directly.

Expand baseline tree all the way down to the updated attribute.
Execute the start rebase command for the attribute
Save

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 to pick only that change. Rebase designer does not support picking, of separate added elements. In this case, the rebase action needs to be started for the parent array itself. This means that all configurations on any of the array elements are Initially overwritten with the baseline content.

On the content array node, execute the start rebase command
Go through all updated changes and undo changes to configurations to keep as they were
Save

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, there is no need distinguish between baseline changes and configurations, as this is already done. That way, it becomes quite simple to just undo every change except for added elements.

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.

Known Limitations¶

Currently no known limitations that needs explanation.