Skip to main content
June 8, 2025
Solved

Forms Event Handler

  • June 8, 2025
  • 1 reply
  • 2 views

Hi everyone,

I’m looking for some guidance or references regarding the Forms Event Handler. I would really appreciate it if anyone could help with the following:

  • any  documentation or examples for using Forms Event Handlers
  • any sample implementations or best practices shared by the community
  • How to use Forms Event Handlers 

If there’s any downloadable content (like a sample/snippet), or even just some insights from your experience, that would be a great help.

Thank You.

Best answer by MarcusH

There is an example of FormsEventHandler in GolfStream (or at else there is in my copy)' It doesn't do much except check a user's security:

Namespace OneStream.BusinessRule.FormsEventHandler.FormsEventHandler
	Public Class MainClass
		Public Function Main(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal api As Object, ByVal args As FormsEventHandlerArgs) As Object
			Try
				Dim returnValue As Object = args.DefaultReturnValue
				args.UseReturnValueFromBusinessRule = False
				args.Cancel = False				

                Select Case args.OperationName
					Case Is = BREventOperationType.Forms.CompleteForm
						Dim cubeName = brapi.Workflow.Metadata.GetProfile(si, si.WorkflowClusterPk).CubeName
						If (cubeName = "CCR") Then
							If Not BRApi.Security.Authorization.IsUserInGroup(si, "WF_CCR_All_Approver") Then
						    ' Do nothing
							
							Else
								If BRApi.Security.Authorization.IsUserInGroup(si, "WF_CCR_All_Approver") And Not BRApi.Security.Authorization.IsUserInGroup(si, "Administrators") And Not BRApi.Security.Authorization.IsUserInGroup(si, "WF_CCR_All_Preparer")Then
									If (args.IsBeforeEvent = False) Then	
										Throw (New XFUserMsgException(si, Nothing, Nothing, "Security Access Error. Only preparer can execute the current workflow step"))
									End If
								End If
							End If
						End If

				End Select
				Return returnValue
			Catch ex As Exception
				Throw ErrorHandler.LogWrite(si, New XFException(si, ex))
			End Try
		End Function
	End Class
End Namespace

I did some examination of how FormsEventHandler works a while back and the object you need to look at (as always) is args. args.inputs contains 3 records:
args(0) contains the form definition in XFFormPK format:
  ProfileKey (32677076-d62d-4eca-8157-c8b1153cf3f9), ScenarioKey (7340033), TimeKey (2021009000), , FormTemplateID: 83f99e91-fb2f-4c5a-ac42-5f62d6861822
args(1) contains the list of changes to be saved as a list of DataCellEx:
  System.Collections.Generic.List`1[OneStream.Shared.Wcf.DataCellEx]
args(2) contains:
  OneStream.Shared.Wcf.DataEntryAuditItem

The DataCellEx object holds the POV information for the data cell like this:

[, 0, , 8388904, , -1, , 45, , 7340033, , 2021009000, , 3, , 513, , 1048595, , -28, , -999, , 2097515, , 3145831, , 4194305, , -999, , -999, , 5243021, , -999, , -999, -77.00, IsRealData, Input]

Every other cell is blank (I don't know why). I use constants to identify the dimension member:

Public Const cARGS_ACCOUNT_ID As Integer = 15
Public Const cARGS_FLOW_ID As Integer = 17
Public Const cARGS_ORIGIN_ID As Integer = 19
Public Const cARGS_IC_ID As Integer = 21
Public Const cARGS_UD1_ID As Integer = 23
Public Const cARGS_UD2_ID As Integer = 25
Public Const cARGS_UD3_ID As Integer = 27
Public Const cARGS_UD4_ID As Integer = 29
Public Const cARGS_UD5_ID As Integer = 31
Public Const cARGS_UD6_ID As Integer = 33
Public Const cARGS_UD7_ID As Integer = 35
Public Const cARGS_UD8_ID As Integer = 37

And then I process the changed cells like this:

If (args.IsBeforeEvent = False) AndAlso (args.OperationName.Equals(BREventOperationType.Forms.SaveForm, StringComparison.InvariantCultureIgnoreCase)) Then
	' Get a list of cells being updated in the form from the input parameters
	Dim dataCells As List(Of DataCellEx) = args.inputs(1)
	' Check each updated cell.
	For Each dCell As DataCellEx In dataCells
		' Get the POV being updated. Set to True to add the member IDs
		Dim CellToSave As String = dCell.DataCell.GetCSVString(api, True)
		Dim cellList() As String = CellToSave.Split(",")

		Dim AccountID As Integer = CType(cellList(cARGS_ACCOUNT_ID).trim, Integer)
		Dim AccountName As String = BRApi.Finance.Members.GetMemberName(si, DimType.Account.Id, AccountID)
		Dim FlowID As Integer = CType(cellList(cARGS_FLOW_ID).trim, Integer)
		Dim FlowName As String = BRApi.Finance.Members.GetMemberName(si, DimType.Flow.Id, FlowID)
		.....
	Next
	
End If

 

1 reply

MarcusHAnswer
June 9, 2025

There is an example of FormsEventHandler in GolfStream (or at else there is in my copy)' It doesn't do much except check a user's security:

Namespace OneStream.BusinessRule.FormsEventHandler.FormsEventHandler
	Public Class MainClass
		Public Function Main(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal api As Object, ByVal args As FormsEventHandlerArgs) As Object
			Try
				Dim returnValue As Object = args.DefaultReturnValue
				args.UseReturnValueFromBusinessRule = False
				args.Cancel = False				

                Select Case args.OperationName
					Case Is = BREventOperationType.Forms.CompleteForm
						Dim cubeName = brapi.Workflow.Metadata.GetProfile(si, si.WorkflowClusterPk).CubeName
						If (cubeName = "CCR") Then
							If Not BRApi.Security.Authorization.IsUserInGroup(si, "WF_CCR_All_Approver") Then
						    ' Do nothing
							
							Else
								If BRApi.Security.Authorization.IsUserInGroup(si, "WF_CCR_All_Approver") And Not BRApi.Security.Authorization.IsUserInGroup(si, "Administrators") And Not BRApi.Security.Authorization.IsUserInGroup(si, "WF_CCR_All_Preparer")Then
									If (args.IsBeforeEvent = False) Then	
										Throw (New XFUserMsgException(si, Nothing, Nothing, "Security Access Error. Only preparer can execute the current workflow step"))
									End If
								End If
							End If
						End If

				End Select
				Return returnValue
			Catch ex As Exception
				Throw ErrorHandler.LogWrite(si, New XFException(si, ex))
			End Try
		End Function
	End Class
End Namespace

I did some examination of how FormsEventHandler works a while back and the object you need to look at (as always) is args. args.inputs contains 3 records:
args(0) contains the form definition in XFFormPK format:
  ProfileKey (32677076-d62d-4eca-8157-c8b1153cf3f9), ScenarioKey (7340033), TimeKey (2021009000), , FormTemplateID: 83f99e91-fb2f-4c5a-ac42-5f62d6861822
args(1) contains the list of changes to be saved as a list of DataCellEx:
  System.Collections.Generic.List`1[OneStream.Shared.Wcf.DataCellEx]
args(2) contains:
  OneStream.Shared.Wcf.DataEntryAuditItem

The DataCellEx object holds the POV information for the data cell like this:

[, 0, , 8388904, , -1, , 45, , 7340033, , 2021009000, , 3, , 513, , 1048595, , -28, , -999, , 2097515, , 3145831, , 4194305, , -999, , -999, , 5243021, , -999, , -999, -77.00, IsRealData, Input]

Every other cell is blank (I don't know why). I use constants to identify the dimension member:

Public Const cARGS_ACCOUNT_ID As Integer = 15
Public Const cARGS_FLOW_ID As Integer = 17
Public Const cARGS_ORIGIN_ID As Integer = 19
Public Const cARGS_IC_ID As Integer = 21
Public Const cARGS_UD1_ID As Integer = 23
Public Const cARGS_UD2_ID As Integer = 25
Public Const cARGS_UD3_ID As Integer = 27
Public Const cARGS_UD4_ID As Integer = 29
Public Const cARGS_UD5_ID As Integer = 31
Public Const cARGS_UD6_ID As Integer = 33
Public Const cARGS_UD7_ID As Integer = 35
Public Const cARGS_UD8_ID As Integer = 37

And then I process the changed cells like this:

If (args.IsBeforeEvent = False) AndAlso (args.OperationName.Equals(BREventOperationType.Forms.SaveForm, StringComparison.InvariantCultureIgnoreCase)) Then
	' Get a list of cells being updated in the form from the input parameters
	Dim dataCells As List(Of DataCellEx) = args.inputs(1)
	' Check each updated cell.
	For Each dCell As DataCellEx In dataCells
		' Get the POV being updated. Set to True to add the member IDs
		Dim CellToSave As String = dCell.DataCell.GetCSVString(api, True)
		Dim cellList() As String = CellToSave.Split(",")

		Dim AccountID As Integer = CType(cellList(cARGS_ACCOUNT_ID).trim, Integer)
		Dim AccountName As String = BRApi.Finance.Members.GetMemberName(si, DimType.Account.Id, AccountID)
		Dim FlowID As Integer = CType(cellList(cARGS_FLOW_ID).trim, Integer)
		Dim FlowName As String = BRApi.Finance.Members.GetMemberName(si, DimType.Flow.Id, FlowID)
		.....
	Next
	
End If

 

ShivangiAuthor
June 9, 2025

It’s working for me, Thank You!

However, I do have one question: I tried to utilize this for the 'SaveForm' event and noticed that it doesn’t seem to trigger when the form is accessed via Dashboards (only Complete/Revert form events triggered). Is this the expected behavior? I would appreciate your guidance on this.