Deltanji 6.0 Documentation
System Manager Guide

Controlling an Ensemble Production Class

Home > System Manager Guide > Controlling an Ensemble Production Class

The definition of an Ensemble production is stored in a class, where Deltanji can manage it as a CLS type component. However to date (Ensemble 2015.1) this class is changed via Portal regardless of its source control status. For example, changes to settings on configuration items in the production will be filed in an XData block in the class even when not checked out. From Ensemble 2012.1 onward Deltanji is capable of tracking such Portal changes. Two techniques are available, as follows. Implement one or the other, not both.

Technique #1: Snapshot Every Applied Change

With this technique, every time the Apply button is pressed in Portal after production settings have been changed on a checked-in class, a new version of the Deltanji object is stored in the repository. This results in maximum audit of changes, at the expense of creating more versions.

1. Define a suitable transfer route.

  • Function code SNAP, with no function caption so as to prevent its routes being offered for direct use in the transfer dialog.
  • From each location in which you want Portal changes to result in a snapshot when applied to a class that is not checked out.
  • To your multi-version repository location, e.g. Library.
  • Create new version.
  • Activate +%FROM,+%TO plus at other appropriate locations (e.g. Latest).
  • Set master to %TO.

2. Override the OnConfigChange method of your production class. Suitable method code for the production class would be as follows:

ClassMethod OnConfigChange(pProduction As Ens.Config.Production, pItem As Ens.Config.Item)
{
 Try {
  s sc=$classmethod("VCmStudio.SourceControl.Ensemble","vcmOnConfigChange",pProduction,pItem,"Library")
  i $$$ISERR(sc) $$$LOGWARNING("OnConfigChange Deltanji snapshot not taken: "_$system.Status.GetErrorText(sc))
 }
 Catch ex {
  If "<CLASS DOES NOT EXIST<METHOD DOES NOT EXIST<"'[($p(ex.Name,">")_"<") Throw ex
 }
}

3. Register the class.

4. Check it in.

5. Create a Change Request whose name matches the production class name (omitting the .cls extension).

6. Using Portal, change a setting on a configuration item of your production. Apply the change. Review Deltanji audit and object history to confirm that a new version has been created as a snapshot.

Notes on this technique:

  1. A snapshot is only attempted if all of the following conditions are true:
    • The production class is being updated by Portal in a namespace that uses VCmStudio.SourceControl.Ensemble (or a subclass) as its source control class.
    • The Studio add-in called Deltanji Configuration has been used to configure settings for the namespace.
    • The production class is already registered and checked in.
    • The class contents have changed compared to the the copy of this version that is already at the destination of the SNAP route.
  2. In the example code above the call made to the vcmConfigChange method in the VCmStudio.SourceControl.Ensemble class assumes the existence of a route with function code SNAP to Library from any Deltanji-controlled namespace in which the production settings will be changed. If your multi-version repository location is not called Library, amend the method argument. Consult the vcmConfigChange method documentation for more information about its arguments.
  3. If you already use a SNAP function code for other purposes, create another one for use here and pass it as an extra argument on the $classmethod call.
  4. The method call also assumes the existence of a Change Request whose name matches the name of the production class (excluding the .cls extension). Alternatively, hard-code a CR name into the $classmethod call.
  5. The example code logs failures as warning-level Ensemble events. This is optional.

Technique #2: Automatic Checkout When First Change Applied

As an alternative to snapshotting every applied change, the mechanism can be used to perform a checkout whenever a change is applied via Portal to a checked-in production class. This technique produces fewer versions and less audit information, depending on how frequently the class is subsequently checked in.

There are two variants of the technique. Pick only one.

Variant A: Reflexive Checkout

An advantage of this variant is that Deltanji updates its comments at the top of the production class, making these show the correct version number.

A drawback of this variant is that Deltanji updates the timestamp on the production class, which causes a reload alert in Portal.

1. Define a suitable transfer route.

  • Function code SNAP, with no function caption so as to prevent its routes being offered for direct use in the transfer dialog.
  • From each location in which you want Portal changes to result in a checkout when applied to a class that is not checked out.
  • To the same location.
  • Create new version.
  • Activate +%TO.
  • Set master to %TO.

2. Override the OnConfigChange method of your production class. Suitable method code for the production class would be as follows:

ClassMethod OnConfigChange(pProduction As Ens.Config.Production, pItem As Ens.Config.Item)
{
 Try {
  s sc=$classmethod("VCmStudio.SourceControl.Ensemble","vcmOnConfigChange",pProduction,pItem)
  i $$$ISERR(sc) $$$LOGWARNING("OnConfigChange checkout not performed: "_$system.Status.GetErrorText(sc))
 }
 Catch ex {
  If "<CLASS DOES NOT EXIST<METHOD DOES NOT EXIST<"'[($p(ex.Name,">")_"<") Throw ex
 }
}

3. Register the class.

4. Check it in.

5. Create a Change Request whose name matches the production class name (omitting the .cls extension).

6. Using Portal, change a setting on a configuration item of your production. Apply the change. Review Deltanji audit and object history to confirm that a new version has been created and is checked out at the location.

Variant B: Checkout to Null

An advantage of this variant is that no reload warning is triggered in Portal.

A drawback of this variant is that the Deltanji comments at the top of the production class are not updated to reflect the new version number.

1. If you do not already have a location, e.g. Null, that maps components nowhere, define one.

2. Define a suitable transfer route.

  • Function code SNAP, with no function caption so as to prevent its routes being offered for direct use in the transfer dialog.
  • From each location in which you want Portal changes to result in a checkout when applied to a class that is not checked out.
  • To your null-mapped location.
  • Create new version.
  • Activate +%FROM.
  • Set master to %FROM.

3. Override the OnConfigChange method of your production class. Suitable method code for the production class would be as follows (substitute the name of your null-mapped location as the final classmethod argument):

ClassMethod OnConfigChange(pProduction As Ens.Config.Production, pItem As Ens.Config.Item)
{
 Try {
  s sc=$classmethod("VCmStudio.SourceControl.Ensemble","vcmOnConfigChange",pProduction,pItem,"Null")
  i $$$ISERR(sc) $$$LOGWARNING("OnConfigChange checkout not performed: "_$system.Status.GetErrorText(sc))
 }
 Catch ex {
  If "<CLASS DOES NOT EXIST<METHOD DOES NOT EXIST<"'[($p(ex.Name,">")_"<") Throw ex
 }
}

4. Register the class.

5. Check it in.

6. Create a Change Request whose name matches the production class name (omitting the .cls extension).

7. Using Portal, change a setting on a configuration item of your production. Apply the change. Review Deltanji audit and object history to confirm that a new version has been created and is checked out at the location.