Creating Custom Captions for Interoperability Business Host Settings

When creating custom Business Hosts, it's often necessary to add properties to the class for additional settings that will be used in the initialization or operation of the host. The property name itself isn't always very descriptive, so it's an advantage to have a custom caption display with the field.

In Caché, it was fairly straightforward:

TEST> Set ^CacheMsg("EnsColumns","en-us","<property name>") = "<caption>"

But It involves a bit more effort in IRIS ...

In IRIS, the caption names of business host and production properties are stored in ^IRIS.Msg("EnsColumns"), which is normally mapped from the read-only ENSLIB database.

You won't be able to update them in ENSLIB unless you mount it read-write, but I don't think that's a good idea; any changes there may get wiped on a subsequent upgrade.

However, you can create your own copy of that subscript in a read-write database of your choice, and map it from there:

TEST> merge ^|"^^/isc/iris/db/testdata/"|IRIS.Msg("EnsColumns")=^|"^^/isc/iris/sys/mgr/enslib/"|IRIS.Msg("EnsColumns")

Substitute the paths to the target and source databases for the ones following the "^^" in the example above.

Then change the mapping in the Management Console via System Administration | Configuration | System Configuration | Namespaces, selecting the Global Mappings link for your namespace. Then edit the mapping for IRIS.Msg("EnsColumns"), changing it from ENSLIB to the name of the database to which the subscript was copied:

Click OK, then Save Changes.

Create the entries for your new caption names:

HICG> Set ^IRIS.Msg("EnsColumns","<locale>","property name") = "caption name"

In the US, "<locale>" is "en-us" ... your locale may vary 😉 

Here's an example. Consider this custom property:

/// Facility Code for the Receiving Facility
Property FacilityCode As %String;
Parameter SETTINGS = "FacilityCode:Basic";

In  your production, it would normally appear like this:

To make it more descriptive, set the caption name in ^IRIS.Msg:

TEST> Set ^IRIS.Msg("EnsColumns","en-us","FacilityCode")="Receiving System Facility Code"

You should now see the business host property in your production displayed with the new caption:

IMPORTANT NOTE: The downside of this process is that any new settings added by InterSystems won't show with the new caption data supplied as part of an upgrade, so you'll have to merge from ENSLIB again to update your mapped copy.