GAM Events subscription

Official Content
This documentation is valid for:

The purpose of the GAM Events subscription is to allow the automatic trigger of additional (external) code when a GAM event is executed. That is, being able to execute a custom event automatically, after a GAM event executes (i.e: the creation of a GAM user).

Consider a scenario where you have a Users table, and the user information is redundant with the GAM Users table. You need to 
keep the Users table updated, that is, any time a GAM User is updated (created or removed) the Users table should be updated accordingly.

The following pseudo-code would be used in such case. 

&GAMUser.Save()
//Call a procedure to make the necessary changes in the Users table.

To avoid considering this piece of code in every part where you update a GAM User, the code may be automatically triggered immediately after the GAM user is updated.

So the GAM User insert, update, and delete are considered to be events that automatically trigger the piece of code declared to be executed.

In other words, you subscribe some events, so that (external) code can be triggered as any of these events is executed.

Events you may subscribe

  • User_Insert: Insert of a GAM User
  • User_Update: Update of a GAM User
  • User_Delete: Delete of a GAM User
  • User_UpdateRoles: Change of roles of a list of users
  • User_GetCustomInfo    : Get user's information on the server when the GAM Remote login is executed. It's executed when the user logs in to the server, and also in the SSO login (when an app connects from another tab of the browser, and the session already exists so the user doesn't need to login again) 
  • User_SaveCustomInfo : This event is executed on the client when the  GAM Remote login is successfully finished.
  • Role_Insert: Insert of a role
  • Role_Update: Update of a role
  • Role_Delete: Delete of a role
  • Repository_Login: GAM User login (any GAM Authentication Types is supported)
  • Repository_Logout: GAM log out
  • Application_CheckPermissionFail : Failure of a permission verification.

Requirements of a program that subscribes an event

The way to subscribe an event is to configure a program that will be triggered when the event is executed. The configuration may be done using the GAM API(1) or the GAM Web Backoffice(2). We'll go over this topic in more detail below.

The program that considers the GAM events may be developed using GeneXus or not, and it has to fulfill some requirements.

First, the signature of the program has to be:

(in Character &EventName, in Character &jsonIn, out Character &jsonOut)

Where 

  • &EventName: belongs to the GAMEvents Domain.
  • &jsonIN: json string whose format depends on the GAM event that the program is subscribed to (see the table below for more details).
  • &jsonOUT: json string used to print information in the GAM trace (in the case it's enabled)

Secondly, consider how the &jsonIN format should be:

Event GAM object
User_Insert GAMUser (i.e., the jsonIN format is derived from the GAMUser object)
User_Update GAMUser
User_Delete GAMUser
User_UpdateRoles GAMGUID collection representing the list of users whose roles were changed.
User_GetCustomInfo  GAMSession
User_SaveCustomInfo (free format)
Role_Insert GAMRole (i.e., the jsonIN format is derived from the GAMRole object)
Role_Update GAMRole
Role_Delete GAMRole
Repository_Login GAMSession (i.e., the jsonIN format is derived from the GAMSession object)
Repository_Logout GAMSession
Application_CheckPermissionFail GAMSessionLogCheckPermissionFail

Example I

In the following example, we have subscribed the User_Insert event.

In the GAM Web Backoffice(2), go through Settings > Event Subscriptions and define the Event as shown in the following figure.

i2016_10_13_13_43_261_png
Net configuration
i2016_10_24_20_40_561_png
Java configuration (in this example the Java Package Name=com.gameventssubscription)
 
Status It may be {subscribed,unsubscribed}. It has to be subscribed for the procedure to be triggered when the event is executed.
Event

It's a combo box where you can select any of the events available.

image_2017124114711_1_png

File Name The name of the .dll or .class file which listens to the event execution.
Class Name The name of the program including its package.
Method Name The method of the program in GeneXus it's always "execute".

The code of the notifyuserinsert procedure is as follows:

Rules: Parm(in:&EventName, in:&jsonIN, out:&jsonOUT);
&GAMUser.FromJsonString(&jsonIN)

&MyUser.Load(&GAMUser.GUID)  //&Myuser is based on a BC.
If &MyUser.Fail()
    &MyUser = new()    
Endif
&MyUser.MyUserGUID    =&GAMUser.GUID
&MyUser.MyUserEmail    = &GAMUser.EMail
&MyUser.MyUserName    = &GAMUser.FirstName.Trim() +" "+ &GAMUser.LastName.Trim()
&MyUser.Save()
If &MyUser.Success()
    //Ok
Else
    //load &jsonOUT parameter with information about the error.
Endif

Example II

See HowTo: Get user's additional information from the GAM Identity Provider for an example of User_GetCustomInfo and User_SaveCustomInfo events.

(1)   How to subscribe an event using the GAM API

You can define the event subscription as shown in the following example:

&GAMEventSubscription = new()    // &GAMEventSubscription is GAMEventSubscription data type
&GAMEventSubscription.Description =  "Inspecting the User Login"
&GAMEventSubscription.Event       =  GAMEvents.Repository_Login
&GAMEventSubscription.FileName    = "aNotifyUserLogin.dll"
&GAMEventSubscription.ClassName   = "GeneXus.Programs.anotifyuserlogin"
&GAMEventSubscription.MethodName  =  "execute"
&GAMEventSubscription.Save()
If &GAMEventSubscription.Success()
  Commit
  // Subscription activation:
  &isOK = GAMRepository.SubscribeEvent(&GAMEventSubscription.Id, &GAMErrors)
  If &isOK
     Commit
  Endif
Endif

You may define more than one program to be triggered when the event is executed.

Note that the subscription must be activated using the SubscribeEvent method of GAMRepository.

Considerations about the logic transaction

Case 1. The program was developed using GeneXus 

To include the program subscribed to the event in the same LWU (Logical work unit) of the event, include the Commit command after the code that triggers the event (i.e., &GAMUser.save() or &GAMRole.save()).

On the contrary, if you don't want to include the program in the same LWU, just configure Execute in new LUW property = True for the program.

The Repository_Login and Repository_Logout methods execute an implicit commit, so you don't need to execute it.

Case 2. The program was not developed using GeneXus

It will not be in the same LWU. 

 




Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.