SuccessFactors: Importance of documenting and defining a naming convention for SuccessFactors Business Rules
This blog is co-authored by Gobinder Sandhu (https://people.sap.com/gobi.sandhuFormer Memberand Stéphanie Bourgault-Mongeau (https://people.sap.com/stephanie.bourgault)
Business rules in SuccessFactors make it possible to implement client-specific system behaviors and functionalities in SuccessFactors Employee Central, in MDF Object used in other SuccessFactors Modules and in Custom MDF Object.
Business rules are simply great (and can be highly fun to implement!) allowing the system to become highly flexible to meet very specific client, industry or country needs and making SuccessFactors unique for every client. But with uniqueness comes complexity.
In addition, business rules are not part of any configuration workbooks. There is no rule amount limitation. Some rule can be simple and understandable in a glimpse of an eye; some can be highly complex using a mixture of available rules’ functions. Two business rules could sometimes conflict with one another and can produce unwanted result which are difficult to trace. In short, as useful as the business rule tool is, it is even more important that these are well managed within the system.
Let’s face it, right now, we, SuccessFactor implementers, are quite lucky implementing in brand new fresh client instances. However, it will come the time that we will be asked to do improvement projects on existing instance and if we do not do a good job documenting and naming the rules in the effective manner, it will be a nightmare later for the folks supporting and enhancing the solution. (That will also mean more support tickets to SAP).
In this blog entry and subsequent updates to it based on our experiences, let’s device a mechanism towards the naming convention for business rules. For the continuous improvement in this area your feedback in the comment section is paramount. Please do not hesitate to criticize and suggest your way of naming the business rules. About time to do some mutual learning and set some standards!
Documenting Business Rules
There are 3 areas that we can use to document our business rules in the system: The Rule Name / ID, the Rule Type and the rule Description.
Figure 1 – Business Rules
Not that the naming convention being proposed in this blog is perfect, but in recent implementations it was deemed very useful from maintenance and housekeeping perspective. Here are the general guidelines:
Rule Name / Rule ID values
- Business Rule Name/ID should identify where the rule will be affecting the system (where is the “change” is happening).
- Business Rule Name/ID should stay basic and simple but be meaningful and must follow a pattern for easier assimilation by somebody who reads through the rule name/id list
- Business Rule Name/ID should all follow the same convention for all modules, consultants on the project. Once we decide on the convention, it should be documented as naming standards and be explained when a new admin/implementer resources join the project
- Business Rule Name/ID should help identify quickly the rules used in the instance and the default rule provided by SF that aren’t necessarily used in Date Model/Objects
- Business Rule Name/ID convention should be able to evolve with time. I’m hopeful that someday all modules of SF will be able to incorporate Business Rules and therefore, our naming convention should be able flexible for when this time comes!
Rule Type value
- Rule Type picklist should be up to date with your configuration and maintained for your Business Rule. Based on what is enabled and configure in the system, whenever the implementation guide specifies to add a value to the Rule Type picklist it should be done and used.
Rule Description value
- I use the rule description box to specify the Rule Event (onInit, onView, onValidate, onSave, onPostSave, saveAlert, delete, onChange of field X) and I add a small description of the rule. You need to be concise here as the description box is limited to 128 characters.
Rule Name / Rule ID Proposed Convention
Here is the generic format of proposed naming convention for the Business Rule. Please note that each of the entity in naming is separated by a hyphen for easy read. Significance of each of the entity is explained later in the blog.
|Company Short Name||Modules||Type (module specific)||Object/Portlet/Purpose||Description|
|Following are the Examples based on the format above :|
|XYZ||–||EC||–||EDM||–||RecPayComp||–||Create Pay Scale Component|
|XYZ||–||EC||–||EDM||–||RecPayComp||–||Delete Pay Scale Component|
|XYZ||–||EC||–||EDM||–||JobInfo||–||Default Probation End Date|
|XYZ||–||EC||–||EDM||–||PersonalInfo||–||Initialize Preferred Name At Hire|
|XYZ||–||EC||–||EDM||–||JobInfo||–||Default Position In JobInfo|
|XYZ||–||EC||–||OBJ||–||Position||–||Default Job Class On Position|
|XYZ||–||EC||–||EDM||–||OEB||–||Daily Pay Scale Increase|
|XYZ||–||EC||–||EDM||–||Alert||–||Work Permit Expiration|
|XYZ||–||EC||–||EDM||–||Alert||–||Probation End Date|
|XYZ||–||RC||–||FORM||–||Requisition||–||Default Requisition Template From Position|
|XYZ||–||RCM||–||FORM||–||Requisition||–||Default Requisition Fields From Position|
|XYZ||–||COMP||–||FORM||–||CompWorkSheet||–||Eligible for Compensation Cycle|
Company Short Name
In order to differentiate, the client specific rules to the default SF rules available, we must add the company name abbreviation (in the following example company is XYZ), It can be 3 or at the most four characters:
Other way is to start the business rule name with “Z_” but in case of more than one company or multi-country system adding company short name makes sense.
Module here means the short name of SuccessFactors system where the business rule will be triggered or is related to:
- EC for Employee Central
- RCM for Recruiting Management
- COMP for Compensation.
- So, on and so forth
(I’m quite hopeful that all modules will be able to use the business rule engine someday)
Type (Module Specific)
Within the module, the business rule is impacting various objects or areas. For example, within EC the business rule may be related to Employee File or Foundation/Generic Objects:
- EDM (Employee Data Management)
- OBJ (Object related could be Foundation Object or Generic Object)
These abbreviations come handy in clear differentiation and investigations.
This part of the naming helps to identify the Object/Portlet/Purpose prefix. Obviously, this will change as new functionality emerge from SuccessFactors. At the end, it is just about making sense and easy for a consultant to understand when they read the names:
|Is it a rule that trigger a Workflow||WF|
|Is it a rule that trigger an Alert||Alert|
|Is a rule for Off Event Batch Cycle||OEB|
|Otherwise, if Employee File related (EDM), identify the portlet affected:||PortletName|
|Otherwise, if Object related (OBJ), identify the name of Object affected:||ObjectName|
From personal experience, when it is Employee File related, I specify where the rule will change data. It is not necessarily the base object of the rule (as this is already identified by the rule base objects field) but rather where the rule will change the system. For example, when we use Pay Scale Level to create automatically create the Pay Component line, the rule use the Job Information base object, however, in my naming convention, I prefer to specify that in impact the Recurring Pay Comp portlet rather than Job Info:
A brief description, cryptic it may be, but always will help especially when the list of rule is revisited for maintenance purpose.
So, what will be Advantage of the proposed guidelines?
Advantage of strictly following a naming convention is well known and proven methodology. In case of business rules, if not done so, it can become cumbersome to understand the dependencies between various business rules, written by somebody else or even by you after a time gap. Unless these guidelines are adhered to, the only option remains. Is to open all business rules one by one or business configurations for individual portlet to know what goes where.
Another advantage is resolving support tickets quickly which seems like has become norm in the industry today. A consultant is expected to know it all from word go.
It also, helps in avoiding regression defects and helps in providing holistic picture about all the rules and their nature being triggered for a specific object.
To give example, let’s say, I have to debug some Pay Component that should be generated automatically, I just check RecPayComp related rules and I know where to start my investigation. Good head start isn’t it?
It is also easier for the support organization or system administrators to get ramp up more quickly when they are supporting the system after go live. And also, useful for post EC implementations, for example the Onboarding consultant can search more easily and try to find out if rules are overwriting his ONB to EC mapping if we make it more easy for him to navigate the rule list!
And above all, your client appreciates the work you have done for them after you are long gone.
I hope that you have like reading about this topic. This is mostly about the documentation and it may not be the most interesting topic to read about but for sure the better governance around the SuccessFactors system configuration is necessary and in our best interest as implementers.
So, stay organized and for my curiosity please share your experience and improvement points in the comment section of this blog.
Hi Stéphanie & Gobinder,
Thanks for this wonderful and very helpful guideline. I hope we can adapt to something similar and this should help alleviate the need to dig in to all the rules when debugging.
Thank you Harshal, please let us know how it goes!