NexJ Logo

Creating new subject areas and extending default subject areas

As of the Data Bridge 3.3 release, you can create and extend subject areas for Data Bridge, and then load these model changes at run time.

Creating new subject areas

You can create additional subject areas for view definitions. Subject areas are defined in individual .json files and should be located in the directory specified by the "dng.sarea.location" environment file flag.

To create a new subject area:

  1. Using any text editor, create a new file.
  2. Specify the required properties in JSON format:
    1. Specify the"name" of the subject area using the following syntax:
      "name": "{prefix:value}"

      Out-of-the-box subject areas use "dataengine:" as a prefix that is included in the name of the subject area. As a best practice, a different prefix should be used in the new subject area to differentiate it from out-of-the-box subject areas.
    2. Specify the "$class" property using the following syntax:
      "$class": "{CRM Class}"
    3. Specify the "icon" property, which is the material design icon displayed for the subject area in the Data Bridge user interface. For example, you could specify "icon”: “icon:\\uf137” .
  3. Specify the following:
  4. Save the file as a .json file.
  5. If the file is not located in the directory specified by "dng.sarea.location", then it should be moved to that directory.

Subject area attributes

Attribute nameRequired?DescriptionExample

name

Yes

The unique name for the subject area.

“name”: “Custom:Address”
$classYesThe name of the NexJ CRM class that this subject area is for.“$class”: “Address”
iconYesThis attribute is the material design icon displayed for the subject area in the Data Bridge user interface. You can use any of the icons available in the maticons or mdicons font files in the <AFL_project>/mod/fonts folder. For more information about icons, see Adding and updating icons.“icon”: “icon:\\uf137”
nameAttributeNoThis attribute determines the value that will show in the UI grid for each instance of a subject area. If not specified, the nameAttribute of the JSON class model will be used.“nameAttribute”: “address”
iconColorIndexNoThe color code for the subject area icon. If not set, 1 is used as a default value.“iconColorIndex”: 2
captionNoThe caption that will be shown in the UI for the subject area. The value can be an “ids.*” string or the caption value.“caption”: “Addresses”
enabledNoControls whether the subject area is enabled. By default, the subject area will be enabled.“enabled”: true
baseNoThe name of the subject area from which to inherit all overrides.“base”: “EntityCollection”

attributes

NoContains a list of attribute overrides. Overridden attributes must be primitives and must exist in the class model. For more information, see the Adding attribute overrides to subject areas and subject area augments.


“attributes”: [
   {
      “name”: “address”,
      “caption”: “description”,
"filterable": true
    }
]
associationsNoContains a list of associations that should show in the subject area. Association paths specified here must be valid with respect to the class model. For more information, see Adding associations to subject areas and subject area augments.


“associations”: [
   {
      “name”: “Company”,
      “path”: (@ entity company)
   }
]

Example subject area

The following code shows an example subject area file:

{
   "$class": "CallRecord",
   "name": "dataengine:CallRecords",
   "caption": "ids.subjectArea.CallRecords",
   "iconColorIndex": 1,
   "icon": "icon:phone",
   "enabled": false,
   "attributes": [
      {
         "name": "title",
         "navigable": true,
         "filterable": true
      }
   ],
   "associations": [
      {
         "base": "dataengine:Contacts",
         "name": "For",
         "path": "(@ entityParticipants entity)"
      },
      {
         "base": "dataengine:Users",
         "name": "AssignTo",
         "path": "(@ userParticipants entity)"
      },
      {
         "base": "dataengine:Contacts",
         "name": "Author",
         "path": "(@ author)"
      },
      {
         "base": "dataengine:Users",
         "name": "Creator",
         "path": "(@ creator)"
      },
      {
         "path": "(@ campaign)",
         "name": "Campaign"
      },
      {
         "base": "dataengine:Contacts",
         "name": "BookedByEntities",
         "path": "(@ bookedByEntities)"
      },
      {
         "base": "dataengine:Contacts",
         "name": "Clients",
         "path": "(@ clients entity)"
      },
      {
         "base": "dataengine:Contacts",
         "name": "Contacts",
         "path": "(@ contacts entity)"
      },
      {
         "path": "(@ folder items)",
         "name": "Folder"
      },
      {
         "base": "dataengine:Activities",
         "name": "FollowUps",
         "path": "(@ followUps)"
      },
      {
         "base": "dataengine:Activities",
         "name": "ParentActivity",
         "path": "(@ parent)"
      },
      {
         "base": "dataengine:Opportunities",
         "name": "RelatedOpportunity",
         "path": "(@ opportunity)"
      }
   ]
}

Extending default subject areas using augments

You can modify existing subject area behavior using subject area augments. Subject area augments are defined in individual .json files and should be located in the directory specified by the "dng.sarea.augment.location" environment file flag.

To extend an existing subject area:

  1. Using any text editor, create a new file.
  2. Specify the required properties in JSON format:
    1. Specify the "for" property using the following syntax:
      "for": "<name of existing subject area>"
      For example, you could specify "for": "dataengine:Activities").
    2. Specify the "icon" property, which overrides the icon of the subject area with the specified icon. For example, you could specify “icon”: “icon:\\uf137 .
  3. (Optional) Specify optional properties. For more information, see Subject area augments.

  4. Specify any attribute overrides. For more information, see Adding attribute overrides to subject areas and subject area augments.
  5. Specify additional associations and association overrides. For more information, see Adding associations to subject areas and subject area augments.
  6. Save the file as a .json file.
  7. If the file is not located in the directory specified by "dng.sarea.augment.location", then it should be moved to that directory.

Subject area augments

Attribute nameRequired?DescriptionExample
forYesThe name of the subject area that the augment is for.“for”: “Custom:Address”
iconYes

Overrides the icon of the subject area with the specified icon. icon is the material design icon displayed for the subject area in the Data Bridge user interface. You can use any of the icons available in the maticons or mdicons font files the <AFL_project>/mod/fonts folder. This value is required. For more information about icons, see Adding and updating icons.

“icon”: “icon:\\uf137”
nameAttributeNoOverrides the name attribute specified in the subject area. This attribute determines the value that will show in the UI grid for each instance of the subject area.“nameAttribute”: “description”
iconColorIndexNoOverrides the icon color for the icon associated with the subject area.“iconColorIndex”: 2
captionNo

Overrides the caption that will be shown in the UI for the subject area. The value can be an “ids.*” string or the caption value.

“caption”: “Home Address”
enabledNoOverrides whether the subject area is enabled. Only enabled subject areas will show in the UI.“enabled”: true
baseNoOverrides the base field. The name of the subject area from which to inherit all overrides.“base”: “EntityCollection”
attributesNoContains a list of attribute overrides. Overridden attributes must be primitives and must exist in the class model. Attribute overrides specified here will override those in the subject area.
“attributes”: [
   { 
      “name”: “address”,
      “caption”: “title”
   }
]

associations

NoContains a list of associations that should show in the subject area. Association paths specified here must be valid with respect to the class model. Association overrides specified here will override those specified in the subject area.
“associations”: [
   { 
      “name”: “Company”,
      “caption”: “Employee Company”
   }
]

Example subject area augment

The following example shows how to create a subject area augment:

{
   "for": "dataengine:CallRecords",
   "caption": "ids.subjectArea.CallRecords",
   "nameAttribute": "text"
   "enabled": true,
   "attributes": [
      {
         "name": "text",
		 "caption": "notes"
      }
   ],
   "associations": [
      {
         "base": "dataengine:Contacts",
         "name": "For",
         "path": "(@ entityParticipants entity)"
      }
   ]
}

Adding attribute overrides to subject areas and subject area augments

You can add attribute overrides to subject areas and subject area augments.

Attribute nameRequired?DescriptionExample
nameYesThe name of the attribute. This should be valid with respect to the class model."name":"description
typeNoThe type for the attribute. By default, this will be the type that the attribute has in the class model. The specified type must be valid with respect to the original type of the attribute."type":"decimal"
captionNoThe caption for the attribute that will be shown in the UI."caption":"Address Description"
excludedNoSetting this to true will hide this attribute in the UI."excluded":true

filterable

No

Indicates whether the attribute can be used as a filter. If excluded is set to true, this attribute is ignored.

Supported in version 3.7.0 and later versions.

"filterable": true

Adding associations to subject areas and subject area augments

You can add the following associations to subject areas and subject area augments.

Attribute nameRequired?DescriptionExample
nameYesA unique name to identity the association in the context of the subject area. If an association with this name exists, the existing association is modified. If an association with this name does not exist, the new association is added.“name”: “Entity”
captionNoThe field name that will display in the Data Bridge user interface.“caption”: “Client”
pathYes

It defines how to get to the association from the subject area's class model. Specify the path if you are adding a new association. Do not enter a path for an existing association.

“path”: “(@ entity)”
baseNoThe name of a subject area from which attribute and association overrides will be applied.

“base”: “dataengine:Contacts”

Loading model changes at run time

After you have created new subject areas or extended existing subject areas, you should load these model changes.

To load model changes at run time:

  1. Navigate to the Data Bridge URL: {<hostname>:<port>/nexj/ui/bridge}.
  2. Navigate to the Global Settings workspace, and select the Subject Area Configuration tab.
  3. The Dynamic Metadata Loading card displays the following information:

    If the following fields are not set, they will display “(Loaded from JAR),” which means that the files will be loaded from the project’s JAR files.

    • Metaclass Path – This refers to the file path from where the data engine metaclass is being loaded. If the dng.model.location path is set in the environment file, then it will initially show its value.
    • Subject Area Path – This refers to the file path from where the subject areas are being loaded. If the dng.sarea.location path is set in the environment file, then it will will initially show its value.
    • Subject Area Augment Path - This refers to the file path from where the subject area augments are being loaded. If the dng.sarea.augment.location path is set in the environment file, then it will initially show its value.

  4. Click Load Metadata. If the new metaclasses are loaded successfully, the following dialog displays:
    Metadata update completed successfully example
    The Loaded Subject Areas card updates to display the list of metaclasses that are currently loaded. You can click on a metaclass to view additional attributes information for the class.

    If a user has made changes in NexJ CRM that invalidate view definitions in Data Bridge then metaclasses will not load successfully when you click Load Metadata and the following will display:

    • An error dialog displays that lists invalid views or error messages. For example:
      Metadata update completed with errors dialog
    • The View Explorer displays an error icon in the Snapshot Enabled and Streaming Enabled columns in the views data table for invalid views.
    • The banner in the View Details pages for invalid views displays "Invalid View Definition."
    • If a field attribute has not been found in the model for a view, a related error message displays on the Create View page for the view, in the Data Selection tab, and in the Fields section.

    A view is determined by Data Bridge to be invalid if it contains a grid attribute or filter attribute that is either no longer part of the JSON metaclass, is excluded from the subject area, or points to an association that is part of a disabled subject area. A view that is marked as invalid is disabled for real-time streaming and snapshot exports.

    You can change the view from an invalid to a valid state if you remove all attributes that are causing the view to be invalid. Only then can you re-enable the view to allow real-time streaming and snapshot exports. If you try to re-enable the view without fixing all of these attributes, the view will stay in a disabled state.

  5. Refresh the UI.

Troubleshooting errors

The following table lists the error messages that you may encounter in the Metadata update completed with errors dialog and describes how to resolve them:

Error messageCauseFix
Attribute "name" not specifed in subject area file "[Path To File].json"The subject area specified in the given file does not specify a "name" property.Add a unique "name" property to the given subject area file.
Unknown class {Metaclass} referenced by subject area {SubjectArea}The subject area is referencing a metaclass that does not exist.Check to makes sure the JSON Metaclass is in the location specified by "dng.model.location". If it is not there, then it should be added. If the class should not be there, then the subject area should be removed or should point to a different class that does exist.
Duplicate definition of subject area {SubjectArea}Two or more subject areas are using the same "name" value.Ensure all subject areas have a unique "name" property defined.
Name attribute "{attribute}" in subject area {SubjectArea} does not exist in the metaclass {Metaclass}The "nameAttribute" property in the specified subject area does not match any attribute specified in the corresponding Metaclass.Make sure the "nameAttribute" property exists in the subject area's JSON metaclass. If it does not, then a different attribute should be specified.
Unknown subject area "{SubjectArea}" referenced by augment file "{SubjectAreaAugment}"The "for" property in a subject area augment JSON file points to a subject area that does not exist.Make sure the subject area specified in the "for" property exists in the "dng.sarea.location". If the subject area should not be present, the subject area augment file should also be removed.
Property "name" not specified for attribute in Subject Area "{SubjectArea}"An "attribute" within the attributes collection in the subject area or its augment does not specify a "name" property.Specify the "name" property for the attribute in the subject area or subject area augment JSON file.
Unknown attribute {Attribute} in metaclass {Metaclass} within the attribute list in subject area {SubjectArea}An "attribute" within the attributes collection in the subject area or its augment references an attribute name that does not exist in the JSON Metaclass.Make sure the attribute exists in the JSON metaclass. If the attribute should not be present in the JSON Metaclass, then it should be removed from the subject area and subject area augment files.
Duplicate attribute {Attribute} in subject area {SubjectArea}Two or more "attributes" within the attributes collection in the subject area or its augment share the same "name" value.Consolidate duplicate definitions of the attributes into a single definition.
Duplicate caption for attribute {AttributeOne} and {AttributeTwo} in subject area {SubjectArea}Two "attributes" within the attributes collection in the subject area or its augment share the same "caption" value.Make sure the attributes have different "caption" values.
Missing associated subject name in subject area {SubjectArea}An "association" within the associations collection specified in either the subject area or its augment does not specify a "name" property.Specify the "name" property for any associations that are missing them within the subject area and subject area augment JSON files.
Missing path in associated subject area {Association} in subject area {SubjectArea}An "association" within the associations collection specified in either the subject area or its augment does not specify a "path" property.Specify the "path" property for any associations that are missing them within the subject area and subject area augment JSON files.
Duplicate definitions of associated subject {Association} in subject area {SubjectArea}Two or more "associations" within the associations collection in the subject area or its augment share the same "name" value.If both associations have the same "path" value, then they should be merged. If both reference different "path" values, then unique names should be assigned to both.
Duplicate associated subject area caption for association {AssociationOne} and {AssociationTwo} in subject area {SubjectArea}Two or more "associations" within the associations collection in the subject area or its augment share the same "caption" value.Make sure the associations have different "caption" values.
Path {AssociationPath} in associated subject area {Association} in subject area {SubjectArea} is invalidThe path from the subject area's class to the final attribute specified in the "path" attribute of the subject area or its augment points to an association type that is invalid.Make sure the "path" value of the given association is referencing a JSON metaclass that exists in "dng.model.location" and is not a primitive.
Name Attribute {Attribute} in association {Association} in subject area {SubjectArea} does not exist in the metaclass {Metaclass}The association specified in the error has a "nameAttribute" value that references an attribute, which does not exist in the metaclass JSON file.Change the "nameAttribute" value of the association to an attribute that does exist in the given metaclass JSON file.
Unknown subject area "{SubjectAreaOne}" referenced in base property of association "{associationName}" of subject area "{SubjectAreaTwo}"The "base" property of the association in SubjectAreaTwo is pointing to a SubjectArea that does not exist.Remove the "base" property of the problematic association or change its value to a subject area that does exist in the model.
The name attribute "{nameOfAttribute}" is not defined in the class model "{Metaclass}"The "nameAttribute" property is referring to an attribute that is not part of the class model.Regenerate the class model so that the nameAttribute property is pointing to an attribute that is part of the model.
Attribute "{attributeName}" in metaclass "{MetaClassOne} is of type "{MetaClassTwo}" which is not part of the class modelThe attribute referenced in Metaclass one is of a class type that is not present in the model.Metaclass two should either be added or removed from the bridge-admin UI and the model should be regenerated.