Skip to main content

v10

help center
Submit a request
Submit a request
  1. Total Compensation Management
  2. Technical admin
  3. Process

Configuring the process budget widget

Nolwenn Marjou
  • Last updated:

Configuring the process budget widget

The budget widget, which can be used in process grids in the beqom application, is a tool targeted at managers. Located above the process grid, it enables the user to view a budget and keep track of the allocated or remaining budget, based on the values of a given column in the process.

The widget is typically used for the distribution of bonuses or the evaluation of base salaries, but can be used with any column of type SUM.

The main difference between the process budget widget and an SSRS report attached to a process grid is that the process widget values are refreshed in real time, at every change to the related column in the process grid (whereas SSRS reports cannot display values dynamically).

This article describes the steps required to configure the widget for a given process.

Roadmap

The following table outlines the steps to be performed to set up the process budget widget.

Budget widget configuration roadmap
Step# Description
1. Register the process as an object.
2. Create the widget and grant it the "budget" type.
3. Link the widget to the process.
4. Grant permissions related to the use of the widget.
5. Configure the budget widget tabs.

Registering the process as an object

To register the process as an object in the database, you need to use the synchronization API method, as described in the table below:

This is an note/information message.

To use this method, you need to have previously retrieved the ID of the process you want to synchronize

Process registration method
Service Action Endpoint Body
Gateway POST /api/Admin/SynchronizePlanById
Copy
{
    "idProcess": "integer",
}

Creating the widget

The second step of the configuration the process budget widget is to create the widget with the "budget" type. This operation is performed using the following API method, with the parameters described in the table below:

Widget creation method
Service Action Endpoint Body
Object POST /api/widgets
Copy
{
    "name": "string",
    "extendedProperties": "string",
    "extendedConfiguration": "string",
    "type": 0
}

The following table details the parameters passed in the body of the widget creation method:

Parameter Description
Name Name of the widget
extentedProperties Empty
extendedConfiguration
Copy
[
    {"key":"idProcess","value":Integer}},
    {"key":"idIndicator","value":integer},
    {"key":"idField","value":integer},
    {"key":"storedProcedureName","value":"string"}
]

Example:

Copy
[
    {"key":"idProcess","value":3}
    {"key":"idIndicator","value":54}
    {"key":"idField","value":57}
    {"key":"storedProcedureName","value":"SP_Widget_Budget"}
]
Type

1 : Widget

2 : Widget Insight

3 : Widget Content Html

4 : Widget Analytics

5 : Widget Budget

 

In the extended configuration, you need to map the process indicator field needs to be used to automatically calculate the budget value. This is done using "key":"idProcess", "key":"idIndicator", and "key":"idField".

Using the parameter "key":"storedProcedureName", you can specify the stored procedure that needs to be executed in order to calculate the budget value.

This method will give you the widget UID. This API call requires to use the Swagger URL of the object.

Mapping the process and the widget

Use the following method to map the process and the widget:

Process mapping method
Service Action Endpoint Description Body
Object POST /api/objects/{id}/relation {id}: UID of the widget
Copy
{
    "uidObject": "ProcessObjectUID",
    "uidObjectRelated": "WidgetUID",
    "uidRelationTypeId": "73D5BCB9-FA21-436D-8582-6A4FFB33E179",
}

Granting access to the widget

The final step in the configuration consists in granting profiles access to the budget widget.

To do so, start by checking the uid_profile value of the profile to which you want to grant access to the widget in the k_profiles table.

Then, you need to execute the following API method:

Service Action Endpoint Description Body
Object POST /api/objects/{id}/access

{id}: UID of the widget

Profile UID to be retrieved from the k_profiles table
Copy
{
    "name": "string",
    "profile": "ProfileUID",
    "role": "CF42837A-B509-4542-8FEC-08AE7DBA42C3",
}

Best practices for configuring the stored procedure

There are three important areas of concern when configuring the stored procedure that will be used to calculate the budget, as outlined below.

Security

The security of the budget widget is solely depending on Stored Procedure. You need to make sure that the stored procedure is secured using the uidUser and uidProfile parameters. These parameters are retrieved depending on the context; therefore, they cannot be changed by end-users.

If the stored procedure does not consider these parameters, then every authenticated user in the tenant can see the same data (provided that they know the correct parameters). It is therefore very important to implement the stored procedure in such a way that it will use user and profile information to limit the amount of data to which users have access. It is also possible to use a hierarchy security ID to leverage a hierarchy security definition.

Parameters

While it is possible to ignore parameters send to the stored procedure, each time a filter is ignored, the budget widget will not show the actual values. As a result, it is your responsibility to decide how accurate the budget values must be.

The following table lists all the parameters that can be configured in the stored procedure:

List of stored procedure parameters
Parameter Data type Description
idProcess INT ID of the process
idIndicator INT ID of the indicator
idField INT ID of the field
idTree INT ID of the hierarchy
idTreeSecurity INT ID of the hierarchy security
idNodeManager INT ID of the selected node in the hierarchy
levels NVARCHAR(max) Hierarchy level filters
startDate DATETIME Start date filter
endDate DATETIME End date filter
isSelf INT Self appraisal filter
infoFilters NVARCHAR(max)

Information field filters

This is an attention message.

beqom recommends to use this parameter in the stored procedure with the infoFiltersVariables and infoFiltersVariableTypes parameters.
indicatorFilterFields NVARCHAR(max)

Indicator field filters

This is an attention message.

beqom recommends to use this parameter in the stored procedure with the indicatorFieldFiltersVariables and indicatorFieldFiltersVariableTypes parameters.
infoFiltersVariables NVARCHAR(max) List of variables for information field filters (e.g. @P0_715 = N'Abril', @P1_719 = N'1')
infoFiltersVariableTypes NVARCHAR(max) Types of variables for information field filters (e.g. @P0_715 nvarchar(511), @P1_719 int)
indicatorFieldFiltersVariables NVARCHAR(max) List of variables for indicator field filters
indicatorFieldFiltersVariableTypes NVARCHAR(max) Types of variables for indicator field filters
workflowStepFilters NVARCHAR(max) Workflow step filters
idProfile INT ID of the user's current profile
idUser INT ID of the user

Example of stored procedure:

Copy
CREATEPROCEDURE [dbo].[SP_Widget_Budget]
(
    @idProcessint,
    @startDatedatetime,
    @endDatedatetime,
    @isSelfbit,
    @idIndint,
    @idFieldint,
    @idTreeint,
    @idTreeSecurityint,
    @idNodeManagerint,
    @levels nvarchar(max)='-1',
    @infoFilters nvarchar(max)=' ' (to be used with@infoFiltersVariablesand@infoFiltersVariablesTypes),
    @indicatorFieldFilters nvarchar(max)=' ' (to be used with@indicatorsFieldsFiltersVariablesand@indicatorsFieldsFiltersVariablesTypes),
    @infoFiltersVariables nvarchar(max)='-1',
    @infoFiltersVariablesTypes nvarchar(max)='-1',
    @indicatorsFieldsFiltersVariables nvarchar(max)='-1',
    @indicatorsFieldsFiltersVariablesTypes nvarchar(max)='-1',
    @workflowStepFilters nvarchar(max)=' ',
    @idUser uniqueidentifier =' ',
    @idProfile uniqueidentifier =' '
)
AS
BEGIN
IFOBJECT_ID('tempdb..#Steps') ISNOTNULLDROPTABLE#Steps
CREATETABLE#Steps
(
idStep    INT,
idPayee INT
);
-- REGION START PARAMETERIZED QUERY
DECLARE@SQL nvarchar(max)
DECLARE@ParamDefinition  nvarchar(max) ='@idProcess int, @startDate datetime, @endDate datetime';
DECLARE@Params  nvarchar(max) ='@idProcess  = '+CONVERT(nvarchar(10), @idProcess)
+', @startDate = '''+CONVERT(nvarchar(10), @startDate, 105) +''', @endDate = '''+CONVERT(nvarchar(10), @endDate, 105) +'''';
SET@SQL=
'select ps.id_step, ps.id_payee from ['+@nameTable+'] ic
inner join k_m_plans_payees_steps ps on ps.id_plan = @idProcess and ic.idPayee = ps.id_payee and @endDate > ic.start_date_histo and @startDate <= ic.end_date_histo
where 1=1 '+@infoFilters+' '
IFNULLIF(@infoFiltersVariables, '') ISNOTNULL
ANDNULLIF(@infoFiltersVariableTypes, '') ISNOTNULL
BEGIN
SET@ParamDefinition  =@ParamDefinition+','+@infoFiltersVariableTypes;
SET@Params=@Params+','+@infoFiltersVariables;
END
SET@SQL=  N'exec sp_executesql N'''+@SQL+''' ,N'''+@ParamDefinition+''','+@Params
INSERTINTO#Steps
EXECUTE sp_executesql @SQL
END

Displaying the "Allocated" and "Remaining" tabs

The following table describes the principles that apply for the display of the Allocated and Remaining tabs in the budget widget:

Allocated and Remaining tabs display principles
totalAmount spendAmount showRemainingAllocated
Not provided Not provided False
Not provided Numeric False
Numeric (0 or NULL accepted) Not provided False
Numeric (0 or NULL accepted) Numeric (0 accepted) True

This is an note/information message.

  • If both totalAmount and spendAmount are provided in the stored procedure, then the Remaining and Allocated tabs are displayed

  • If neither totalAmount nor spendAmount are provided in the stored procedure: the Remaining and Allocated tabs are not displayed

Displaying the "Average" tab

The following table describes the principles that apply for the display of the Average tab in the budget widget:

Average tab display principles
averageAmount totalStepCount averageAmount showAverage
Not provided Not provided NULL False
Not provided Integer (greater than 0) NULL False
Numeric Not provided NULL False
Numeric Integer (0 or lower) NULL False
Numeric Integer (greater than 0) Integer True

This is an note/information message.

  • If both totalStepCount and averageAmount are provided in the stored procedure, thenthe Average tab is displayed

  • If neither totalStepCount nor averageAmount are provided in the stored procedure, or if totalStepCount is NULL or 0, then the Average tab is not displayed

Process data

In order to use actual amounts, beqom recommends to use a SUM of the data in k_m_values. However, it can be difficult to find the payee steps to aggregate. Therefore, the following filters must be applied before retrieving data from k_m_values:

  • Apply hierarchy security using the tree security ID, the tree ID and the definitions

  • Apply infoFilters by joining the process template view and the indicatorFieldFilters by joining indicator/fields

  • Apply levels

  • Apply process filters such as start/end date and workflow step

Is it possible to configure multiple budgets in the widget?

Depending on the requirements, it can be useful to have several budgets configured in your budget widget. In order to do so, repeat the previous steps to create a new budget and assign it to the same process. In that way, the new budget will be accessible in your process as shown in the following figure:

Budget widget with multiple budgets

Attachments
Was this article helpful?
0 out of 0 found this helpful
Return to top