This question comes up so very often that although documented we've decided to create this Knowledge Module to answer all possible angles of this question.

 For example you need to create an attribute called MyNewAttr in the BMC.CORE:BMC_Monitor and you want this attribute to be visible in the AST:Monitor Asset View.

Although the BMC Remedy Action Request System 7.6.04 Form and Application Objects Guide documents this on page 122 (see excerpt below), there is more to it when it comes to the BMC CMDB.

You may also see errors in logs after an upgrade that talk about field count being out of sych with ARS: 

BMC.CORE:BMC_ComputerSystem
390600 : The form definition field count does not match the number of fields in the database. (ARERR 9912)

.... and other issues.

Legacy ID:KA380649

Let's start by stating couple facts or requirements (expectations):

 - Changes to CMDB classes should be only made through the Class Manager or cmdbdriver. These updates the metadata and makes any changes to the underlying ARSystem forms.  Changes in the CDM that are done this way are preserved. This is important during CMDB upgrades and hence there is no need to use overlays to preserve these customizations.

 - It is never recommended to make changes to the BMC.CORE forms via Remedy Developer Studio if the changes can be made in the CMDB UI.  The only exception is if the view is modified to customize the presentation layer of AST (Asset Management) forms, which does not change the functionality.

- BMC.CORE Classes and Relationships should not be overlaid for any functional changes.  Note that this applies particularly for ARsystem 7.6.04.  In ARSystem 8.1, granular overlays potentially allow more specific customizations but earlier versions overlay the entire form.

- CMDB to Asset Synch (a.k.a cmdb2asset or SynchUI) creates only classes and attributes that are present within the class structure under BMC.CORE:BMC_BaseElement. This conversion utility is Overlay agnostic. BMC.CORE:BMC_BaseElement is the top (master) class. Only the CMDB SynchUI API will propagate CDM changes to all child classes. Dev Studio does not.

- Most common issues seen with the CDM, AST views and Overlays are that CMDB administrators are creating overlays directly on the BMC.CORE schemas.

- Although the SynchUI record is saved and the SynchUI process seems to have been completed, but CDM updates and SynchUI activities are not instant. They take a while (5 - 20 minutes) to complete. BMC Software development has not equipped the UI with a progression bar because this action is expected be done by CMDB Administrators who should be familiar with the process.

BMC.CORE Classes and Relationships can not be overlaid!

Let me add some history behind the CMDB CDM. The BMC.CORE Common Data Model reflects the DMTF (http://dmtf.org/standards/cim/cim_schema_v282) which is a loosely followed standard of data structures for Distributed Management from which the BMC CMDB definition was derived.
This data structure features inheritance of the class BaseElement and relationship BaseRelationship and has been licensed under the trade mark of BMC.CORE. These are the BMC.CORE master classes. As a side note, any class that is created at the same tier as BMC.CORE:BMC_Base* class is considered outside of BMC realm of support. All BMC API's only cater to the BMC.CORE:BMC_Base* tree of classes.

All classes and relationships that are used within the scope of the AtriumCore CMDB application are BMC.CORE. This means that creating a class that is not a child of BaseElement or BaseRelationship classes results in loss of support by BMC Software. 
It also means that the (CMDB2Asset)SynchUI would not push these classes to the AST namespace. Only classes that are children of BMC_BaseElement and their comprised attributes will be synched. However this does not mean that attributes with different namespace will not be considered. As long as they are somewhere in the hierarchy of the BMC.CORE master classes then they will be synched.

One of the features that specifically impacts overlays is the cdm2html conversion utility. It will convert your current CDM into an HTML formatted reference. It is not designed to include overlays. Similarly API's that are built for CMDB management such as CMDBDRIVER are also not designed to handle overlays.
 

What is an overlay?

Overlay (simplified) is a view that is created in the BMC ARS Development Studio while in the Best Practice Mode. Base Editing mode does not create overlays and must also not be used to modify BMC.CORE forms. You can think of an overlay as a glass top that has been laid over a geographical map that must not be altered. On this glass surface you could draw circles and connections from one place to another, but if you were to lift the glass then the map would remain unmarked. This feature was introduced to preserve out of the box conditions of all BMC Remedy applications that have historically caused upgrade issues with the CMDB. Most schemas in the ARSCHEMA database can be overlaid but certainly not those related to the CMDB CDM. Upgrading to 9.x version of AtriumCore will require you to remove them before proceeding.

 CMDB to Asset Synch (a.k.a cmdb2asset or SynchUI) creates only classes and attributes that are present in the CDM (Common Data Model).

CMDB core forms need more user friendly representation when used in other applications. The most significant consumer of the CDMB data structure is BMC Asset Management. However, Asset is a consumer of the CDM and not a manager. It uses views of the BMC Core forms and these views are presented with expectations to be friendly to the Asset data operators. These expectations are coded into the CMDB2Asset SynchUI utility and transformed by a trigger that triggers the synchronization in the background. AST views are then generated or updated with changes to the CDM. Commonly these are extensions that Asset operators need to see for their daily business activities. You may create an overlay on the AST views, but SynchUI will not touch them.

Most common issues seen with the CDM, AST views and Overlays are that CMDB administrators are creating overlays directly on the BMC.CORE schemas.

Issues arise in many cases where empowered CMDB administrators not trained by BMC educational services, documentation or those that were not aware of the above specifics on BMC.CORE and the DMTF standard, create overlays on the BMC.CORE forms. This in effect disables workflow that was not designed to handle overlays to begin with.

Although the SynchUI record is saved and the SynchUI process seems to have been completed, but CDM updates and SynchUI activities are not instant.

Although the SynchUI utility gives the impression that the synchronization has completed when the Synch button is clicked and the record saved, the actual process that completes the synchronization is running much longer than just the few seconds it takes to click and save the HasAssetUI = Yes. In fact it could take 20 minutes or even longer. It depends on the resources of the system that can be committed to this operation, data size and database.

So, what is the best practice on extending classes and synching them with the Asset views?

1. Make one change at a time. One class or one attribute, let the background processing finish before adding more.

2. Always use the Class Manager module in the Atrium Console (or the cmdbdriver utility) to create the class or attribute.

3. Never create a class that is a master class of BMC.CORE. Make sure the class is a child of BaseElement. Unless you really really really have a good reason for an attribute that would fit all child classes of BaseElement.

4. Only synch to asset after the class or attribute is no longer in Change Pending status.

5. Only create an overlay on AST form once the synch is complete.

1. Best Practice:

- Make one change at a time. One class or one attribute, let the background processing finish before adding more.

Make sure that the system is not busy with Reconciliation, Normalization or data transfer jobs (AIE, AI, Data Import). This is best done during a maintenance cycle when no other users are on working on it. This includes server group systems as the database is shared amongst all of them and you are making changes to the data structure after all.

- Open class manager and add your class (for details please see BMC AtriumCore Administration User Guide). Save the change and check OBJSTR:Class to see if it is now Active.

- If the class is still in Change Pending, then copy the Pending ID and use the CMDBDRIVER (for details please see BMC AtriumCore Administration User Guide) to sync the change.

- The command is "sync" and it will prompt you for the Pending ID. Paste it in and press Enter. The synch could take several minutes, but one way or another CMDBDRIVER will return the prompt with a status message. Allow up to 2 hours for this to complete. Expected time to complete is about 5 minutes, but CMDB data structure that holds millions of records can take a while to complete.

- If CMDBDRIVER returns with OK status and return code of 0 without any errors then you may still need to wait couple minutes before the change appears in the AR User Tool or Midtier. In some cases midtier may need to be restarted after Cache Flush and cmdb-cache clean up.

- You can also check the Attribute or Class status using the CMDBDRIVER and AR DRIVER. CMDBDRIVER uses the Attribute Name and AR DRIVER uses the Field ID for lookup.

CMDBDRIVER: 

Command: ga
GET ATTRIBUTE
Class Name
   Namespace (): BMC.CORE
   Class name (): BMC_Monitor
Attribute Name (): MyNewAttr

   CMDBGetAttribute  results
Attribute Info:
   Attribute Name:  MyNewAttr
   Attribute Id:  OA-725004C40EFF11E293CF0050569D0043
   Data Type:  4
   Attribute Type:  3
   Attribute Base Class
     Namespace  :  BMC.CORE
     Class Name :  BMC_Monitor
   Field Id:  536871927
...

AR DRIVER:

Command: gsf
GET FIELD
Schema name: BMC.CORE:BMC_Monitor
Field id (1): 536871927

   ARGetField  results
ReturnCode:  OK
Field name:  MyNewAttr
Field mapping:
   Field type:  JOIN
   Schema Index:  0
   Field Id : 536871927
Datatype:  4
...

 These are the types of results expected when the attribute has been activated and you can synch it with the SynchUI utility.

 Go ahead and make sure that the ARS is not about to hit the ceiling with memory and CPU utilization by checking the Task Manager in Windows or "top" in Unix/Linux. The operation will require extra RAM to complete and you want to make sure it does so.
Once you've clicked the SynchUI button, you will need to check CMDBSynchronizeUI.log which should be found in the ATRIUMCORE_HOME/Logs dir. The log must have "Application UI synchronization completed" at the bottom and time stamp being post the synch trigger.

NOTE(!): 7.6.04 AtriumCore and patch 1 and 2 have had hotfixes releases after the version was made available to customers. If the CMDBSynchronizeUI.log is still being created in the ARSystem\DB directory, then you do not have the hotfix. Please see KA 000095070 for reference. The hotfix is patch & version specific and can not be used with patches that do not match the same patch revision.

Important question to ask before extending classes: Is it ready to accept data? 

In some cases the propagation of the data structure change can take some time to be update the views in the Midtier. Even though you can see the the field with DRIVER and CMDBDRIVER and no Attribute or Class is in Change Pending status, Midtier may still not show the new field.
Here is how you can find out with the same AR DRIVER utility. You need to use AR DRIVER for this because CMDBDRIVER has already synched this change.

First you need to create an instance. You may do so with the AR User Tool, Midtier or AR Driver(*advanced). Open the form, create or update a CI and put a test value into the new field. Now lets test it.

AR DRIVER(*Advanced skill required)

Command: gle
GETLIST ENTRY
Schema: AST:Monitor
Qualifier Struct:
None, And, Or, Not, Relop or From Field (0, 1, 2, 3, 4, 5) (0):
Number of query list fields (0):
Number of sort fields (0):
First Retrieve (0):
Maximum number of entries to retrieve (500):
Get number of matches? (F):
Use Locale for search? (F):

   ARGetListEntry  results
ReturnCode:  OK
Entry List List : 6 items
Entry List Struct:
   Entry Id : 000000000000001|000000000000021|000000000000001|000000000000021
   Short Description : TESTCI                                      Deployed            Hardware            Processing Unit     Other Type of Proces
 

 In the above result please note the "Entry Id" multipart value. You will need it for the next "ge" command where we can test the new attribute for data content:

 Command: ge
GET ENTRY
Schema: AST:Monitor
Number of Items in EntryId ? (1): 4
Entry Id: 000000000000001
Entry Id: 000000000000021
Entry Id: 000000000000001
Entry Id: 000000000000021
Ids of fields to retrieve:
   Number of ids (0): 2
   Id (1): 7
   Id (1): YOURFIELDCUSTOMID

Where YOURFIELDCUSTOMID matches the one in the Attribute Definitions record for the attribute. For example lets use 501230123

The result shold then be:

 ARGetEntry  results
ReturnCode:  OK
Field Value List : 2 items
Field Value Struct:
   Field Id : 7
   Value:  (enumerated)   3
Field Value Struct:
   Field Id : 501230123
   Value:  (char)   TESTCI

Status List : 0 items
 

OK, now that you have verified that ARSCHEMA has stored this value in your custom field you should see it in the Midtier views.

If you do not, then do this: 

- Flush the cache on the midtier server and stop the service.

- Find directory "cmdb-cache"  ( i.e. /opt/apache/tomcat6.0/temp/cmdb-cache) and delete contents of that dir.

- Start the midtier. Clear out your Internet Explorer Temporary files and relogin to the midtier. The field should now be visible in AST forms.

1. BMC Atrium Integration Engine
2. BMC Atrium Configuration Management System Essentials for Outsourcers