As with SAP ERP HCM, SuccessFactors Employee Central users often need to create and use company-specific objects in their system. Also like SAP ERP HCM, SuccessFactors Employee Central offers users the ability to create these objects (called Generic Objects) and use them within the system through its Metadata Framework functionality. This provides users with some of the extensibility required to support their business processes within Employee Central. In this article, we cover all aspects of creating Generic Objects within SuccessFactors Employee Central using the Metadata Framework.

Concepts of the Metadata Framework

The Metadata Framework is a framework to extend the object model of the SuccessFactors system using metadata. Metadata is simply data that describes data. As part of the Metadata Framework, a single instance of a generic set of components exists within the system that is re-used by multiple objects. Their behavior can be configured using metadata, which means that multiple custom objects can be created or modified in the system without affecting performance or stability. It also means that users can get a great deal of flexibility within the system without compromising operation or upgradability.

The objects created in the Metadata Framework are Generic Objects. Generic Objects are used to store data for a number of use cases, including employee data. They are also leveraged for standard SuccessFactors functionality such as Time Off and Deductions. These differ from Foundation Objects that are cross-organizational and used to set up the organization, job, and pay structures.

Each Generic Object can have up to 200 custom fields added (in addition to the standard fields) and comes with its own generic user interface (UI). Multiple Rules can be assigned at various points in the transaction flow of a Generic Object or to a field of a Generic Object. These points are called Hooks. Rules can be used to define how a Generic Object or field behaves, as data validation, or used to propagate (populate) other fields based on the data selected. Rules are created in the Rules Engine of the Metadata Framework. Like objects in SAP ERP HCM, Generic Objects can have relationships created with other objects. In SuccessFactors these are called Associations.

Generic Objects are created and managed in OneAdmin by an administrator. However, they can also be created and managed by other users through Role-Based Permissions. Before the various Metadata Framework options can be accessed in OneAdmin they must be enabled in Provisioning by an implementation consultant. Then an administrator must grant privileges to enable access to the Metadata Framework activities. The various options are available under Company Settings and Employee Files, which are referenced throughout the article. Some features that are built on the Metadata Framework (e.g., Time Off) have their own options in OneAdmin.

Examples of Generic Objects used by users include Positions, Time Off objects, Competencies, Message Definitions (for Rules), and Work Schedules. In this article we look at creating a Generic Object for a Global Assignment prerequisite. This object is called Global Assgmt PreRequisite.

Creating Generic Objects

The first step in creating a Generic Object is to create the definition, which is done in Configure Object Definitions in OneAdmin. In the Configure Object Definitions screen (Figure 1), select Object Definition from the Create New drop-down field options.

Figure 1

Create a new Generic Object definition

This opens the Object Definition form (Figure 2).

Figure 2

Define the new Object Definition form

The first three attributes – Code, Effective Dating, and Label – define the object ID (i.e., whether the object is effective dated and the name of the object that is displayed to the end user, respectively). By default, the system adds the prefix cust_ to the value that is entered in the Code field. By selecting the globe icon next to the Label field, the label can be entered in each of the languages available in the system.

The following three attributes in Figure 2—Workflow Routing, Pending Data, and Todo Category—define the workflow properties of the object. These define the Workflow configuration to use, whether data subject to a Workflow must be approved before being displayed, and—if Pending Data is set to Yes—in which category on the homepage Todo tile the Workflow should appear.

Ideally the Workflow should be created before the Generic Object is created, although a Workflow can be created and assigned to the Object Definition after the Object Definition has been created.

For the new Global Assgmt PreRequisite object, enter the following details in the fields in Figure 2:

• Code: globalobject
• Effective Dating: Basic
• Label: Global Assgmt PreRequisite
• Workflow Routing: Leave this blank
• Pending Data: No
• Todo Category: Generic Object Change Requests

Under this section you can define any fields for the object. There are several attributes that can be defined for each field. The first three are visible, while the remaining attributes are accessed by clicking the Details hyperlink to the right of the respective field (Figure 3).

Figure 3

Additional attributes available to each field

The attributes are:

• Name: The technical identifier of the field
• Data Type: The type of data to be used in the field, such as String, Number, User, or Foundation Object.
• Maximum Length: The maximum length of the field input
• Valid Values Source: This is used to define the source of the values when the Data Type value is set as Picklist, Generic Object, Foundation Object, or Enum.
• Hide Old Value: This determines whether the old value of a field is displayed with strikethrough (No) or is completely hidden (Yes) when it’s changed
• Decimal Precision: The decimal precision when the field’s Data Type value is Decimal
• Required: Whether the field is required for input or not
• Visibility: Whether the field is displayed and editable (Editable), hidden from display (Not Visible), or displayed but not editable (Read Only)
• Label: The name of the field on the UI
• Field Criteria: Select this to restrict the value of a field dependent on another field
• Rules: Here one or more Rules can be assigned to the object; this is the onChange event that is referred to later in this article.

Like Workflows, Rules can be defined prior to creating the Object Definition or they can be added afterwards.

There are two standard fields on each Generic Object that should not be changed, except for the label of the fields. The standard fields are externalCode and externalName. These refer to the ID and name of each instance of the object.

For this new object you need to configure three custom fields. Configure each of the fields with the values displayed in Table 1. The default value is used for any fields not included in the table.

Note that for your object the following attributes have default values (Figure 4): Maximum Length, Hide Old Value, Include Inactive Users, Visibility, and Rules.

Figure 4

The Generic Object definition for your Global Assgmt PreRequisite object

Once the fields of the object have been defined, there are four other sections of attributes to be defined:

• Associations: Defines any associations between the object and other Generic Objects.
• Searchable Fields: Defines the fields that can be used to search for the object.
• Security: This section defines if the object is subject to Role-Based Permissions and, if so, in which section of the Role-Based Permissions menu the object will be located.
• Rules: This section defines where Rules can be assigned for onInit and onSave events (see below).

For each of these attributes, define the following settings:

• Associations: Your object has a Composite, One-to-Many association with another generic object called Global Contract Data (this is covered in more detail later in this article).
• Search Fields: Leave blank
• Security: Leave blank
• Rules: You want to assign a Rule, but haven’t created the rule yet; leave this field blank and you will come back later to assign your rule to the OnSave event.

Now that your Object Definition is complete, click the Save button. If Security is set to Yes then the object must be permissioned for the relevant Permission Role(s) in OneAdmin in Set User Permissions > Manage Permission Roles > Miscellaneous Permissions.

Adding a View in Employee Files for a Generic Object

Once a Generic Object has been created you may then wish to add a new View in the Employee Files so that records may be displayed and, if required, edited by employees. Figure 5 shows a screenprint of a View that has been added.

Figure 5

A custom View added in Employee Files for your Global Assgmt PreRequisite object

This is the primary method for allowing employees, managers, or administrators to view or edit Generic Object records when the object is created for employee data. Generic Object records can also be created and edited in Manage Data in OneAdmin, although usually most employees would not have access to this screen.

There are a number of steps you need to complete to add a new View. The first step is to create a Config UI in OneAdmin in Employee Files > Manage Config UI. In the Manage Configuration UI screen that results (Figure 6) click the Create New button. This opens an additional row with the Id and Select Base Object input fields. Here you enter the code for the Config UI in the Id field and select your Global Assgmt PreRequisite object as the base object. When the object is selected from the Select Base Object drop-down options, the UI designer is displayed underneath with an auto-generated UI. This is the Global Assgmt PreRequisite Portlet seen in Figure 6.

Figure 6

The UI designer with the auto-generated UI

The auto-generated UI uses the same layout as in View or in Manage Data. Click the Save button to save the configuration UI.

Note
Some aspects of the screen layout and individual fields in the Manage Configuration UI screen can be modified using the Edit Properties button, as seen in Figure 7. This appears once the mouse hovers over the UI. Additional fields or Rules for fields can also be added this way. However, the specifics for doing this are not covered in this article.

Figure 7

The additional properties pop-up

The next step is to create a View and assign the Config UI to it. This is done in OneAdmin in Employee Files > Configure Employee Files. In the Configure Employee Files screen, click the Add New View button at the top of the screen. This opens the screen in Figure 8, where you click the Insert Portlet button (highlighted) on the left in the User Elements section.

Figure 8

Click the left-side Insert Portlet button

In the next screen, scroll down and click the Create & Add button next to the Live Profile MDF Information hyperlink (Figure 9).

Figure 9

The Create & Add button to select the Config UI you created

This opens the Admin Tools screen in Figure 10, where you enter the title of the Portlet in the Portlet Title text box (e.g., Global Assignment Prerequisite). You also enter the name of your Global Assgmt PreRequisite object. An optional Portlet Description also can be added. Select the Config UI from the MDF Screen ID drop-down options; in this case, you select the Config UI that you created earlier. The screen should look similar to the screen in Figure 10.

Figure 10

The Portlet screen showing your configuration

Click the Save button to save the Portlet. This takes you back to the View screen where you enter the name of the View in the Dashboard Name text box (Figure 11). You can also add an optional description in the Description text box.

Figure 11

The View screen showing your configuration

Click the Save Dashboard button to return to the Configure Employee Files screen (Figure 12). Here you check to make sure that the check box is selected in the Show/Hide column for the new View Name and use the up or down arrow icons in the Sort Order to column to change the order that the View is displayed in the Employee Files drop-down. Your new View should display in in a similar way to the screenprint in Figure 12.

Figure 12

The new Global Employee Profile View in the Configure Employee Files screen

Click the Save Changes button at the bottom of the screen (not shown) to save the changes and return to OneAdmin. Now the View needs to be permissioned in Set User Permissions > Manage Permission Roles under the Employee View permissions. Once this is completed, then the View can be accessed from the Global Employee Profile drop-down under Employee Records (Figure 13).

Figure 13

The new Global Employee Profile

By selecting a View from the screen in Figure 13, users can now view or edit records for the Global Assgmt PreRequisite object, depending on the Permissions granted to the user. In Figure 14 the user can view and edit a record for the object.

Figure 14

The new View with a record of the Global Assgmt PreRequisite object

Now let’s look at creating rules and validations using the Metadata Framework’s Rules engine.

Creating Rules and Validations

Now that you’ve created your Generic Object, let’s look at creating and assigning some rules using the Metadata Framework’s Rules Engine. Rules allow business-specific logic to be applied to different field change events, data propagation, warnings and messages to display, and calculate field values on the fly when a page is opened.

There are three different events on which a Rule can be triggered:

• OnInit: Triggers a Rule when the portlet or Add New Employee screen is loaded for the user
• OnSave: Triggers a Rule when the portlet or screen (e.g., Add New Employee, Employment Information, or Personal Information) is saved after the user has modified it
• OnChange: Triggers a Rule when the user changes a field value on the Add New Employee, Employment Information, or Personal Information screen.

It is important to know which event you are going to assign your Rule to and in which screen your object or field appears when creating your Rule. For example, when adding a Rule to the Add New Employee screen, your Base Object must be Employee Information Model.

Rules are defined in a two-step approach using conditions. First, the If condition defines the conditions to trigger the Rule. Then the Then condition defines what actions should be taken when the Rule is triggered. For example, if the If condition Job Code is equal to ENG3B, then set the Weekly Working Hours to 38. It is important to note that the field(s) or object in the Then condition must always refer to fields of the object on which the Rule is triggered. However, the fields used in the If conditions do not need to refer to fields of the same object.

Since you have created a new Global Assgmt PreRequisite object, you now need to apply rules to control its behavior when a record is saved. This is done in Configure Business Rules under Company Settings in OneAdmin. In Configure Business Rules, the user has the option to select an existing Rule from a drop-down or create a new Rule using the Create New Rule button. In this example we are using the option to create a new rule by selecting the Create New Rule button (Figure 15).

Figure 15

Creating the Workers Council Rule in the Rules Engine

Clicking the Create New Rule button opens the Rule Portlet screen. Here you must define four attributes for your new rule:

• Rule ID: The ID of the Rule object
• Rule Name: The identifier of the Rule object
• Base Object: This determines which object (Foundation Object or Generic Object) this Rule must be used for
• Rule Type: The category of the rule has no function in Employee Central, although it is used for other SuccessFactors applications

For a Generic Object the Base Object value is that object, but for other use cases and event types the value may be different. See the summary in Table 2 for more details. 

The Manage Parameters hyperlink next to the Base Object field provides additional options for specific Rule uses, such as Time Off, period-end processing, and accruals. This can be seen in Figure 15.

Since you want your Workers Council Rule to raise a message when the user selects Part Time in the Works Council field, input the following information:

• Rule ID: globalwkcouncil
• Rule Name: Workers Council
• Base Object: Global Assgmt PreRequisite
• Rule Type: Global Assignment

After the Base Object has been selected, the If and Then Portlets appear. Figure 15 shows the configuration for the Rule attributes and the If and Then conditions.

The second part of configuring a Rule is configuring the If conditions that trigger the rule. In the If Portlet, multiple conditions can be set to meet the desired conditions required. The Rule itself can be set to always be true using the Always True check box so that the Then actions are always triggered when the Rule is triggered.

There are a number of options that can be defined for each If condition, such as the field to check, whether the value should be equal to or not equal to, and a value (depending on the data type of the field). There are a number of functions available for number and date fields, such as various arithmetic and date calculation functions. Multiple If conditions can be used with either AND or OR operators.

In our example we are looking for the rule to trigger when the value for the Works Council field in our Global Assgmt PreRequisite is Part Time, so in the If Portlet you enter the information shown in Figure 16.

Figure 16

The If Portlet showing Works Council Member is equal to Part Time

Now that you’ve defined the If conditions, you must define what happens when the Rule is triggered (i.e., if the If conditions are met). This is done in the Then Portlet. The options of the Then Portlet are similar to those in the If Portlet, although in addition it is also possible to raise a message, create a new object instance, or delete an existing object instance.

Select Raise Message and select the messageDefinition object that you created earlier (a messageDefinition object is a Generic Object). The Raise Message condition has a number of severity levels:

• Error: Displays a warning message and does not allow processing to continue
• Warning: Displays a warning message but allows processing to continue
• Info: Displays a message and allows processing to continue

Because there are additional activities required to make changes in the employee’s work schedule after a record has been created, select the Warning condition. Figure 17 shows the configured Then conditions.

Figure 17

The Then Portlet with your message condition configured

Once your Rule is defined, click the Save button to save it. Now that you’ve created your Rule you can assign it to our Global Assgmt PreRequisite object in Configure Object Definitions.

Creating Associations Between Generic Objects

With your fully functioning Global Assgmt PreRequisite object you can now associate it with other objects. Associations define the hierarchical relationship between an object and other objects, similar to SAP ERP HCM relationships. Within SuccessFactors, associations define a parent–child relationship or define whether another object record must exist for an associated object. An example of an association within SuccessFactors may be a Legal Entity, which can have many Business Units associated with it (One-to-Many association) but does not require a child Business Unit object to exist.

At present, Generic Objects can be associated to other Generic Objects and to Foundation Objects in the Metadata Framework. In order to create an association between a Foundation Object and a Generic Object, an implementation consultant needs to perform the configuration in the Corporate Data Model.

Here you are creating an Association between your Generic Object and another Generic object that you already created, Global Contract Data. To do this, go back to your object definition in Configure Object Definitions. Under the Associations heading there are seven attributes required to define the Association (Figure 18).

Figure 18

The details of an Association configuration

The following attributes exist for an Association:

• Name: An identifier for this specific association configuration
• Type: Defines whether the type of relationship is:
  • Composite: The instance of the associated object can only exist as a child of the current object (e.g., it cannot be an independent object in its own right).
  • Valid When: The object can exist with or without the existence of an instance of the associated object
• Multiplicity: Defines whether the relationship can have multiple records, such as:
  • One-to-One: Defines that the object can only be associated to one other object
  • One-to-Many: Defines that the object can be associated to multiple objects
• Destination Object: The object to be associated with
• Required: Determines if the association is required (Yes) or not (No) (from the August 2013 release (1308) on this can be determined using a Rule based on other values)
• Visibility: Defines whether the association can be modified (Editable), is hidden on the UI (Not Visible), or is visible but cannot be changed (Read Only)
• Label: The label visible on the UI for the association

For your Association, enter the following details:

• Name: cust_contractdata
• Type: Composite (because you need Contract data only if a user has a record of the Global Assgmt PreRequisite object)
• Multiplicity: One-to-Many (because you need to be able to enter more than one record for Global Contract data)
• Destination Object: Global Contract Data
• Required: Yes (if global assignment data is being maintained, then you need at least one global contract to be maintained)
• Visibility: Editable (you want the user to be able to add records)
• Label: Assignment Contract Data

Your configuration should now look like the screen in Figure 19.

Figure 19

The details of your Association with the Global Contract Data object

Now your Global Assgmt PreRequisite object has been associated with the Global Contract Data object. This allows you to create Assignment contract data every time a record of the Global Assgmt PreRequisite is created for a user. Figure 20 shows the association in a record, with two associated records.

Figure 20

The details of your Association with the Global Contract Data object

Now that you’ve created an association, let’s take a brief look at creating records for your Generic Object.

Creating Instances of a Generic Object

Instances of Generic Objects – also known as records – are created and viewed in OneAdmin in Manage Data, although, as previously stated, they also can be created in Employee Files if added to a Config UI and an Employee Files View. Similar to how Foundation Objects and Generic Object Definitions are created, the Generic Object is selected in the Create New drop-down. Select your Global Assgmt PreRequisite object. The Object Definition form is then presented for the object (Figure 21).

Figure 21

The Object Definition form for the Global Assgmt Prerequisite object

Here you can enter details for a record of the Global Assgmt Prerequisite object. When completing the form the various fields behave as per the configuration in your Object Definition. Your Rule takes effect when you save the record (Figure 22).

Figure 22

The new Workers Council Rule being triggered when saving the Global Assgmt PreRequisite object

Since your Rule was configured as a Warning, the system allows you to proceed and create the record when you click the Yes button. This results in the screen shown in Figure 23.

Figure 23

A record of the Global Assgmt PreRequisite object

Now you have completed the steps to create a record for your Global Assgmt PreRequisite object.

Tips and Tricks

Here are a few tips and tricks to keep in mind when working with Metadata Framework objects.

1. When creating a Metadata Framework object to be used in the Employee Files, the data type of the externalCode must always be User. If you fail to do this then the Configuration UI linked to your base object does not appear in the drop-down options when you go to Configure Employee Files > User Elements > Insert Portlet > Create and Add Live Profile MDF Information.
2. When a Metadata Framework object is created with Effective Dating, the system creates a number of auto-generated fields. If you need to change an Effective Dated object to a non-Effective Dated object, then we recommend that you create a new object instead of changing the existing Effective Dated object.
3. If you change any associations with your base object after the Configuration UI has been created, you need to re-create the Configuration UI for the system to function as expected. The best way to do this is to delete the existing Configuration UI and create a new Configuration UI with the same ID.
4. Rule Type is a standard picklist in the Metadata Framework. You can create custom values in this picklist by going to Configure Object Definitions > Search > Picklist > Rule Type. In the example in this article the Global Assignment Rule Type was created before assigning your Rule to it.
5. In a View, it is not possible to select different dates for Effective Dated records. The current active record always shows. If you select Edit and enter the date of a future or past-dated inactive record, then it is displayed on screen.

We’ve covered creating a Generic Object in the Metadata Framework, creating rules for validation of the object and its fields, and associating the Generic Object with another Generic Object. We’ve also shown how you can create these within your system step-by-step. You should now have an understanding of what the Metadata Framework can offer, how to create your own objects, how validations and associations can be leveraged to influence behavior of your objects, and how these can be assigned to objects within the SuccessFactors system.

Jyoti Sharma

Jyoti Sharma is an author, speaker and SAP/SuccessFactors solution architect. In her current role as Senior Solution Architect and Vice President, Consulting & Services Cloud HCM, at HRIZONS, she is responsible for the Cloud HCM LoB,  working with customers  on their cloud migration strategies, deployment strategies, and execution of SuccessFactors implementations. Her primary focus is on the implementation of SuccessFactors Employee Central as the core HRIS in the cloud, its integration with other products of the SuccessFactors HCM suite (such as Talent and Analytics products), external systems such as SAP on-premise, and other traditional on-premise applications. Jyoti is a co-author of the first edition of SuccessFactors with SAP ERP HCM, and is an active contributor to the SAP Community Network (SCN).  She is a frequent conference speaker, with over 11 years of Information technology and SAP experience. Jyoti earned her MBA at Symbiosis Institute of Management Studies, India, and has a Certificate in Business Analysis from Boston University.

You may contact the author at jyoti.sharma@hrizons.com.

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.

Luke Marson

Luke Marson is co-founder, CEO Americas, and Principal Architect for Employee Central at iXerv, a global SAP SuccessFactors consulting partner. In addition to his duties as CEO, he is an active architect and subject-matter expert on SAP SuccessFactors. Luke is a Certified Professional in SuccessFactors Employee Central who has worked with over 15 customers, and is the co-author of the following books: SuccessFactors with SAP ERP HCM and SAP SuccessFactors Employee Central. He is also an author, blogger, speaker, strategist, and widely recognized expert in SAP SuccessFactors and SAP ERP HCM. Luke can be found on Twitter at @lukemarson.

You may contact the author at .

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.