The Metadata Framework functionality gives SuccessFactors users the capacity to build end-to-end applications to meet business-specific requirements not available in an out-of-the-box system. This includes the ability to create their own rules, validations, and business logic to both standard and custom objects. The functionality is primarily available in Employee Central, but is also partially available in the Succession and Compensation modules as of now.
We provide further insight into the flexibility of the Metadata Framework. We also take a look at the Advanced Reporting tool’s capabilities using the objects created via the Metadata Framework. In this article, we use an example of creating this custom functionality in SuccessFactors and displaying it in the users’ portals.
Scenario: Create Custom Functionality from Scratch in SuccessFactors and Display It in the Portal
In this scenario, the HR department is looking to develop an end-to-end warning process for the organization that captures and tracks the warnings issued to employees as part of its HR records. You also need to include a workflow mechanism before a warning letter is issued to the employee.
This end-to-end process requires the following steps:
- The manager of the employee initiates the process
- The HR manager and further up-line managers approve or reject the request
- On approval, the record becomes part of the employee record
There is no out-of-the-box solution in SuccessFactors to meet this requirement. However, the Metadata Framework functionality can be used to meet the business necessity and enhance the return on investment (ROI) as the business is able to leverage their investment in SuccessFactors by adding custom functionality at no extra licensing cost.
To address this requirement, the following steps need to be taken to set up the system:
- Configure the Metadata Framework objects
- Define the user interface (UI) object
- Attach the UI to the employee files
- Assign the role for the Metadata Framework object
- Define the workflow
Step 1. Configure the Metadata Framework Objects
To configure the two objects, follow menu path Admin Center > Company Settings (Figure 1). Select Configure Object Definitions and the screen in Figure 2 opens.
The initial admin tools screen for creating and defining new objects
Define a new object
Select Object Definition from the Create New field options. This opens the screen in Figure 3.
The new Object Definition screen
Perform the following steps:
- Code field: Provide a unique name for the custom object.
- Label field: Provide the name that needs to be associated with the object for display purposes.
- Fields section: Here you add fields that are required for the custom object. The externalCode field has to be defined as a data type user. This ensures that when the object is attached to the employee files, the object is associated with a unique user (employee). In this example, we define two fields: Warning Reason and Detailed Description.
- There are other system generated fields such as mdSystemLastModifed that are present by default and should be retained. These can be used for audits and general reports (e.g., all records modified by a particular user ID or after a particular date can be fetched in Online Report Designer (ORD) reporting using these fields as filters).
On the same screen at the bottom, security needs to be enabled by making the following entries:
- Secured: Yes
- Permission Category: MDF Foundation Objects
- RBP [Role Based Permissions] Subject User Field: Enter the value externalCode (this means that the user, defined in the first custom field, defines the authorization of the object).
This configuration ensures that all the fields on the document can be controlled for view, update, and delete access using Role Based Permissions (described later in this article). Finally, save the newly defined object by clicking the Save button at the bottom of the screen (not shown).
Step 2. Define the UI Object
Now that you have defined the object that holds the data, let’s define the Metadata Framework UI to display these objects together in a UI screen. This Metadata Framework is then associated with a portlet.
Follow menu path Admin Center > Employee Files > Manage Configuration UI (Figure 1). In the screen that opens (Figure 4), click the Create New button to create a new configuration UI object.
Create a new UI object
In the next screen that opens (Figure 5) provide the following details:
- Id field: Enter the ID of the UI object. All the UI objects are to be uniquely defined in the system so that they can be inserted in the employee’s file portlets.
- Select Base Object field: Select the already defined object (Figure 3) to be associated with the UI. In this case, it is a Warning Letter.
Enter the UI definition for the warning object
(Note: By default the Warning Reason and Detailed Description custom fields appear in the Manage Configuration UI screen along with the effective date (Date of Warning) and external code fields.)
Once you’ve made your entries, click the OK button to save your new UI object.
Step 3. Attach the UI to the Employee Files
To display the UI object (i.e., the Warning Letter) in the portal as a portlet option, you need to attach it to the employee’s file. To set up the UI to achieve this, follow menu path Admin Center > Employee Files > Configure Employee Files (Figure 1).
In the screen that opens (Figure 6), attach the UI to the employee files so that the user can access it from the front end. To do this, click the Add New View button.
Add a new view (for the employee’s file portlet)
In the screen that opens (Figure 7), give the new dashboard a relevant name (in this case, Warning Letter), and then click the Insert Portlet button under User Elements on the left.
Define the new view (for the employee portlet)
This expands the screen with the available options, shown in Figure 8. Select the Create & Add button on the left in the Live Profile MDF Metadata Information row.
Add a new metadata profile portlet
In the screen that opens (Figure 9), select the Metadata Framework UI object (in this example, Warning Letter) from the MDF Screen ID field drop-down options. Then click the Save button.
Create the new Metadata Framework portlet
A new entry, Warning Letter, is created at the end of the Design Employee Files Layout (Figure 10).
The new Metadata Framework profile View Name is displayed in the options
Step 4. Assign the Role for the Metadata Framework Object
In this step, you define the authorization of the custom object (created in step 1) to users based on the role assigned to them. Go to Admin Center > Set User Permission > Manage Permission Roles (Figure 1), and the screen in Figure 11 opens. Click the Permission Role to be updated; in this case, start with the Manager Role and update its permission settings. Repeat the same steps for Employee Self Service and the HR Role, setting up access based on the business requirements.
Select the role(s) to be updated
Click the Permission… button (not shown) and, in the screen that opens (Figure 12), click the Employee Views link. In the list of employee views that opens on the right, select the Warning Letter check box. This makes the view visible in the layout of employee’s file.
Update the permissions for the role
While in the same pop-up window, in the User Permissions section (on the left) scroll down to the MDF Foundation Objects option and select it (Figure 13). In the screen that expands on the right, which lists the defined custom objects, select the permissions to be granted. When you’ve made your required selections, click the Done button. The pop-up screen closes, and, in the next screen that opens (not shown) click the Save Changes button.
Set field-wise permissions for the custom object
The Warning Object is now defined. Next, the workflow needs to be set up so that the manager can initiate the request and the HR manager and any up-line managers will have the workflow routed to them.
Step 5. Define the Workflow
First, you need to define the workflow to meet the requirement of the two levels of approval. Define the workflow by following this menu path in Figure 1: Admin Center > Employee Files > Manage Organization, Pay and Job Structures. In the screen that opens (Figure 14), select Workflow from the Create New drop-down options.
Create a new workflow for the Warning Letter object
In the screen that opens (Figure 15) define the following:
- Workflow ID: It has to be a unique alphanumeric text to each workflow.
- Name: The label for the workflow (which shows up in the workflow routings)
- Description: A short description of what this workflow is used for and who participate in it
- Reminder in Days: Here an entry should be made if email notifications are to be sent as a reminder to the individual with whom the workflow is pending.
- For the remaining fields (Is Delegate Supported, Alternate Workflow, and Redirect CC Users, keep the default values).
Define the new workflow
In addition, in the Step 1, 2, and 3 sections of the screen, define the different steps in the workflow, as follows:
- Select Approver Type as Role under Step 1 (since, in this example, workflow is role-based).
- Select the Approver Role (person to perform the action) for all three steps. In this case, Step 1 as the Manager, Step 2 as the Employee HR, and Step 3 as the Manager Manager.
- Context as Source (since all these roles are with respect to the employee’s current [Source] position).
- Set the Edit Transaction field as Edit without Route change (as you want updates to be made without changing the flow of the workflow).
- Set the No Approver Behavior to Skip the step (as you do not want workflow to become stuck if an approver is not available to approve it).
- Set the Relationship to Approver as Employee.
- Set the Respect Permission to Yes (since you are controlling permissioning through Role Based Permissions separately).
After configuring the new Metadata Framework object and its UI, and attaching it to the Employee files, you can access the Warning Letter Metadata Framework object via the Employee Profile (Figure 16).
The Metadata Framework Object (Warning Letter) attached to the employee’s file
In this example, let’s assume that a manager wishes to issue a warning to a direct report. In this case, the portlet appears as shown in Figure 16. The manager has the option to enter the details of the Warning Reason and a Detailed Description.
Once the changes to the portlet have been saved, a workflow is triggered (Figure 17).
Manager Carla Grant initiates a Warning Letter workflow for employee Marcus Hoff
After the manager initiates the Warning Letter workflow, it is automatically routed to the HR Manager (Figure 18).
HR Manager Nancy Nash approves the warning for the employee
Once the HR Manager approves the warning for the employee (Figure 19), it is routed to the up-line manager of the employee (e.g., the employee’s manager’s manager).
The up-line manager approves the warning to the employee
Once all the approvals are in place, the Warning Letter becomes part of the employee’s record and is visible to the employee in the employee portlet (Figure 20).
The approved warning is visible to the employee (Marcus Hoff)
How to Use the ORD Tool to Enable Advanced Reporting and Create Reports
To be able to report on the data captured in custom Metadata Framework objects, the Advanced Reporting option needs to be enabled by the SuccessFactors support team, by raising a request in the SuccessFactors Support portal. Once the Advanced Reporting functionality is enabled, navigate to Home > Analytics (Figure 21). Then select the Analytics tab.
The Analytics tab appears
In the screen that opens (Figure 22) select Detailed Reporting. This opens the Detailed Reporting tool (Figure 23) where you can create a new report.
Select the Detailed Reporting option in the reporting design tool
The Detailed Reporting tab showing the standard- and custom-defined reporting table options
In Figure 23 you can see which Detailed Reporting and Live Data fields are available to be selected. When you click the objects shown in the figure, you can see the tables and columns contained within the respective object (e.g., Personal Information). Then, when you select a table, the standard fields (First names, Surname etc.) are available under the standard table Personal Information (Figure 24). To add fields to the report, select and then drag and drop the desired fields from the left to the right of the screen (i.e., to the canvas).
The standard table’s fields in the Detailed Reporting tool
As shown in Figure 25, the custom Metadata Framework fields (e.g., Warning, Reason for Warning, and so on) are available under the corresponding Metadata Framework object (in this example, Warning).
The list of custom fields from the Metadata Framework object in the Detailed Reporting tool
Once the required fields are dragged and dropped from the left to the right of the canvas, the corresponding column headers (e.g., User, First names, and so on) are displayed in the Analytics report (Figure 26).
The custom column headers for the report are now displayed
Then, once all the required fields have been moved onto the canvas on the right, save the new report by clicking File and then Save from the drop-down options that open. A pop-up window opens that prompts you for the name of the report (Figure 27). You also have the option to create a new folder where the new report can be saved.
Create a folder for the new custom reports
Once you’ve named the report, click the OK button to save it. The report output shows the values in each column (Figure 28). These can then be exported to Excel for further processing by clicking the Excel icon at the top.
Sample custom report output