HowTo: Extend GAM entity properties

Official Content

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

The purpose is to allow 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

GAMPropertyObject

Suppose the case of 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, which Id will be "Main Page" and its value will be the name of the web page which 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 "chanel 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 if he / she belongs to a specific branch of the company. Besides checking that the user is allowed to perform certain actions, you need to check if this Permission is allowed for the branch where the user works. In this case you would define an additional property for the Permissions entity, which Id would be "branch of the company" and its value is the name of the branch. When checking the User Permissions you need to check programatically the property ""branch of the company"" of this Permission before taking a decision on to allow or deny the user to perform an action.

Examples

Here we use the Role entity 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 we scan the Role's extended properties. 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
EndFor

2. Insert or update extended properties

The way to add dynamic properties is by adding the property to the collection, and executing save() method and 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
&Role.Properties.Add(&RoleProp)
&Role.Save()
For &Error In &Role.GetErrors()
  msg(&Error.Message + !"(GAM" + &Error.Code.ToString().Trim() + !")")
EndFor
If &Role.Success()
  Commit
EndIf

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