HowTo: Extend GAM entity properties

Official Content

The purpose of this article is to explain the necessary steps to extend the GAM entity properties.

The GAMProperty External Object is part of the GAM Library consolidated when the Enable Integrated Security Property is set to Yes. It defines dynamic properties (OAV Pattern) in several GAM entities, such as RolesApplicationsPermissionsRepositories.

Its purpose is to allow you to model several scenarios where the properties which are pre-defined in these entities are not enough.

Let's start by showing the GAMProperty object properties:

  • Id
  • Token
  • Value


Suppose the case of a GXportal where the main page of the application depends on the Main Role of the User. In this case an additional property needs to be defined for the Role entity, whose Id will be "Main Page" and its value will be the web page's name that is going to be the home page of users with this role. 
In some cases, you may need more granularity, such as specifying the main page for the Main Role for a specific channel. In this case, besides defining the Id and values mentioned above, you need to specify the "channel identification" in the Token property of GAMProperty object.

Another example can be taken from the GAM Permissions entity. Suppose you need to check the Permissions of a user regarding whether they belong to a specific branch of the company. In addition to checking that the user can perform certain actions, you need to check if this Permission is allowed for the branch where the user works.

In this case, it is necessary to define an additional property for the Permissions entity, whose Id would be "company branch" and its value is the name of the branch. When checking the User Permissions, you should check the "company branch" property of this Permission programatically, before making a decision on whether to allow or deny the user to perform an action.


Here, the Role entity is used as an example, but it's the same idea for the rest of the GAM entities.

1. Loop through the entity properties.

In this example, the Role's extended properties is scanned. There is a "Properties" property of GAMRole object which returns a collection of GAMProperty object.

For &RoleProp In &Role.Properties //&RoleProp is GAMProperty data type, &Role is GAMRole data type.
  &RolePropValue = &RoleProp.Value //&RolePropValue is GAMPropertyValue data type
  &PropValueToken = &RoleProp.Token //&PropValueToken is GAMPropertyToken data type
  &PropValueId = &RoleProp.Id //&PropValueId is GAMPropertyId data type

2. Insert or update extended properties

The way to add dynamic properties is by adding the property to the collection, executing ths Save() method and the Commit command afterwards.

&Role.Load(&RoleIdSelected) //&RoleIdSelected is GAMKeyNumLong data type
&RoleProp = New() //&RoleProp is GAMProperty data type
&RoleProp.Id = &PropValueToAdd
&RoleProp.Token = &RolePropToken
&RoleProp.Value = &PropValue
For &Error In &Role.GetErrors()
  msg(&Error.Message + !"(GAM" + &Error.Code.ToString().Trim() + !")")
If &Role.Success()

In order to update a dynamic property, you need to remove it first and then add the property.

3. Remove extended properties

You have to remove it from the collection, performing collection operations as usual.

See Also

Extensibility of GAM entity properties