SAP Knowledge Base Article - Public

3050437 - How associations between Foundation Objects (FOs) and migrated FOs (MDF FOs) in Employee Central are translated to properties in their OData API entities - SAP SuccessFactors HXM Suite

Symptom

You're using SF's OData API and you wish to understand how the associations between foundation objects reflect in the properties of their OData API entities.

NOTE: Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental.

Environment

  • SAP SuccessFactors HXM Suite
    • OData API


Resolution

Associations between objects are translated to API properties in different ways, depending on which type of objects are associated (FO or MDF FO) and the association type itself.

Here's a glossary of the terms we'll be using in this KBA and their synonyms:

  • FO = Foundation Object;
  • MDF = Metadata Framework;
  • MDF Object = Generic Object = GO;
  • MDF FO = Migrated FO = EC2MDF Object;

Foundation Objects (FOs) are defined in the Corporate Data Model, which is an XML file that can be downloaded and uploaded via Provisioning.

Generic objects (MDF Objects) are part of the MDF framework and are defined inside the SF instance, under Admin Center -> Configure Object Definitions

Migrated FOs (MDF FOs) are foundation objects which were previously defined in the Corporate Data Model, but later were moved to the MDF, and hence are also defined under Admin Center -> Configure Object Definitions. Since they are MDF objects, they are also classified as MDF Objects (GOs).

If you're not familiar with the terms above, I suggest reading the following sections of the EC guide:

Moving on to how these differences impact the OData API entities:

Associations defined between FOs will translate into a field and/or navigation field in the entity's metadata. Since we have two types of FOs (FOs and MDF FOs), the resulting fields and field properties may vary.

In short: the rules below apply to all scenarios except for MDF FO to MDF FO associations (for that, please refer to Section 2 - Scenarios 3 and 4):

If the multiplicity of the association is 'One To One':

  • The entity will contain a simple property that is visible and upsertable, and a navigation property that is only visible and not upsertable;

If the multiplicity of the association is 'One To Many'

  • The entity will contain a simple property that is only upsertable and not visible (will not appear in queries), and a navigation property that is only visible and not upsertable;

If you'd like to dive deeper, let's go through each possible scenario below.


Section 1 - When the root entity (where the association is defined) is a Foundation Object (FO)

Foundation objects and their properties are defined in the Corporate Data Model, which is an XML file that can be downloaded in Provisioning and modified if needed.

We'll be using some sample associations defined for the 'payRange' FO to describe the possible scenarios:

The Pay Range object's OData API entity is called 'FOPayRange'. Now let's head to some examples to illustrate how the associations are mapped to entity properties when Pay Range (FO) is associated to another FO or to an MDF object (also called Generic Object or GO):


Scenario 1: FO association to FO - Multiplicity: One To One

Taking the association of 'payRange' to 'geozone' (both FOs), for instance:


The following properties will appear in the FOPayRange API entity's metadata:

  • Simple property: geozoneFlx (associated object's name + Flx) -> Visible and upsertable;
  • Navigation property: geozoneFlxNav (associated object's name + FlxNav) -> Visible only


Scenario 2: FO association to FO - Multiplicity: One To Many

Taking the association of payComponentGroup to payComponent (both FOs), for instance:

The following properties will appear in the FOPayComponentGroup's API entity's metadata:

  • Simple property: payComponentFlx (associated object's name + Flx) -> Upsertable only (replaces the associated records by the ones provided in the upsert);
  • Navigation property: payComponentFlxNav (associated object's name + FlxNav) -> Visible only

Since this is a one to many association, there can be many pay components associated to a pay component group. Therefore, if you perform an upsert operation on an existing FOPayComponentGroup record with the 'payComponentFlx' field, whatever value(s) you provide will replace the previously associated pay components, if there were any. The values should be separated by "|". Example:

"__metadata": {
"uri": "FOPayComponentGroup"
},
"startDate": "/Date(-2208988800000)/",
"externalCode": "AnnualizedSalary",
"payComponentFlx": "BASESAL_US|BASE_CN|BASIC_AU"
}

This will associate the pay components "BASESAL_US", "BASE_CN" and "BASIC_AU"  to the pay component group. Now if we query this FOPayComponentGroup record and expand the payComponentFlxNav property, the 3 pay component records will be contained inside the nav property.

If we make another upsert passing only one pay component to the 'payComponentFlx' field, the 3 previous ones will be dissociated from the record and replaced by the new one passed.


Scenario 3: FO association to a migrated FO (MDF FO) - Multiplicity: One To One

Same behavior as scenario 1.


Scenario 4: FO association to a migrated FO (MDF FO) - Multiplicity: One To Many

Same behavior as scenario 2.


Section 2 - When the root entity (where the association is defined) is a migrated FO (MDF FO or GO)


Scenario 1: MDF FO association to FO - Multiplicity: One To One

A direct association from a GO to an FO is not possible. For that purpose, there are GOs called FO Wrappers, which you can think of as a link from GOs to FOs.

As an example, here's the wrapper of the Location FO:


Note that since effective dating attribute is 'From Parent', the association type should be composite (only objects whose Effective Dating is From Parent should choose association type as Composite).

Composite objects are not independent and only exist within their parent objects, therefore you cannot find records of these objects by themselves in Admin Center → Manage Data;

Let's look at an example of a custom association to Location Wrapper (FOWLocation), defined in the 'Division' FO:


If you add that association and check the FODivision entity's metadata (OData API Data Dictionary), you'll see that no fields or navigations appear. To fix that, we need to create an Element Type Mapping as explained in 2950496 - How to add a custom association from a generic object to a Wrapper object as a navigation property in the OData entity - SuccessFactors.

The following properties will appear in the FODivision entity:

  • Simple property: locationFlx (associated object's name + Flx) -> Upsertable and visible;
  • Navigation property: locationFlxNav (associated object's name + FlxNav) -> Visible only


Scenario 2: MDF FO association to FO - Multiplicity: One To Many

Using the same association from the scenario above, but changing the multiplicity from 'One To One' to 'One To Many' results in the following:

  • Simple property: locationFlx (associated object's name + Flx) -> Upsertable only (replaces the associated records by the ones provided in the upsert, refer to the example in Section 2: Scenario 2 for more details);
  • Navigation property: locationFlxNav (associated object's name + FlxNav) -> Visible only

The upsert behavior is the same as described in Section 1: Scenario 2.


Scenario 3: MDF FO association to MDF FO - Multiplicity: One To One

Using an association from 'Cost Center' to 'Department' as example:


If the association is defined in the 'Element Type Map for EC Migration' of the Cost Center FO:



  • Simple property: departmentlFlx (associated object's name + Flx) -> Upsertable and visible;
  • Navigation property: departmentFlxNav(associated object's name + FlxNav) -> Visible only;
  • Navigation property: cust_Department (name of the association) -> Visible and upsertable (merge behavior);


If the association is NOT defined in the 'Element Type Map for EC Migration' of the Cost Center FO:

  • Simple property: cust_DepartmentProp (name of the association + Prop) -> Upsertable and visible;
  • Navigation property: cust_Department (name of the association) -> Visible and upsertable (merge behavior);


Scenario 4: MDF FO association to MDF FO - Multiplicity: One To Many

Using an association from 'Cost Center' to  'Legal Entity' as example:


If the association is defined in the 'Element Type Map for EC Migration' of the Cost Center FO:


  • Simple property: companyFlx (associated object's name which is changed from LegalEntity to company in this case + Flx) -> Upsertable only (replaces the associated records by the ones provided in the upsert, refer to the example in Section 2: Scenario 2 for more details);
  • Navigation property: companyFlxNav(associated object's name which is changed from LegalEntity to company in this case + FlxNav) -> Visible only;
  • Navigation property: cust_LegalEntity (name of the association) -> Visible and upsertable (merge behavior);


If the association is NOT defined in the 'Element Type Map for EC Migration' of the Cost Center FO:

  • Simple property: cust_LegalEntityProp (name of the association + Prop) -> Upsertable only (replaces the associated records by the ones provided in the upsert);
  • Navigation property: cust_LegalEntity(name of the association) -> Visible and upsertable (merge behavior);


Scenario 5: MDF FO association to a regular or custom MDF object

As an example, let's assume an association from 'Division' (MDF FO) to a custom MDF object called 'cust_Example'. Regardless of multiplicity, this type of association will result in the following properties in the FODivision entity:

  • Simple property: cust_ExampleProp (name of the association + Prop) -> Upsertable only (replaces the associated records by the ones provided in the upsert);
  • Navigation property: cust_Example (name of the association) -> Visible and upsertable (merge behavior);

Keywords

upsert, visible, cannot, see, does, not, appear, dictionary, odata, api, field, association, foundation, object, objects, ec, employee central, navigation, nav, property, associated, generic, mdf, fo, ec2mdf, mfo, go , KBA , LOD-SF-INT-EC , Employee Central SFAPI & OData Entities , LOD-SF-INT-MDF , Metadata Framework API (MDF) , LOD-SF-INT , Integrations , LOD-SF-INT-ODATA , OData API Framework , How To

Product

SAP SuccessFactors HXM Suite all versions

Attachments

Pasted image.png
Pasted image.png
Pasted image.png