The purpose of this document is to highlight a number of considerations that should be made when choosing the starting entity for an integration in Integration Center.
- You are creating a new integration in Integration Center
- You are unsure what entity you should choose as a starting entity
Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental.
- SAP SuccessFactors HXM Suite
- Integration Center
With simple / non-complex integrations, the choice of starting entity may not severely affect your integration but is still very important.
However, when creating complex integrations (i.e. multiple - entities, navigations, filters, sorting/ordering):
- The choice of starting entity is very important and should be selected in adherence with your current requirement
- Your choice of starting entity will form the basis / foundation of the Integration Center job
- If you do not plan and test in advance of implementing the integration, the job can encounter issues in future
- These issues can be a direct result of the starting entity which has been chosen
As mentioned in the Integration Center Guide:
When creating an integration, your first and most important task is to decide on the starting entity.
Your choice of starting entity depends on your use case.
If you choose the one side of a one to many relationship as your starting entity, unless you use a field filter, any navigation to the dependent/many record will not logically return the correct entity.
It will instead just return the first entity in the list.
There are a number of considerations that must be taken into account when choosing the starting entity.
These considerations will be primarily based upon your requirements but will also be dictated by the availability functionality and limitations of the system.
Please keep in mind, the below considerations, when creating your job:
- Data Reporting: Consider what kind of data will be the primary metric of the job? (e.g. are you reporting based up Persons, Employments, Compensation, etc.)
- PersonIdExternal for reporting on persons - e.g. data that is associated with the person and not tied to one employment
- UserId for reporting on individual employments (e.g. if a user has multiple employments, the multiple employments will be tied to the same personIdExternal)
- Historical / Future Records: Do you need to retrieve effective-dated data (historical / future dated data)?
- Current Records (currently effective): Do you need to retrieve current data? (effective today)?
- Status: Will you be reporting on both active and inactive users?
- Employments: Are any of these users on Global Assignment or have a concurrent employment?
- Filtering on Record Data: Will you be filtering based upon time?
- Filtering on Time: Or on data contained in the record?
- Filtering on Both: Or will you be filtering upon both?
- Filters: Are the fields upon which you need to filter set to 'filterable' in the OData API Data Dictionary?
- Navigations: Are the required navigations available from the chosen starting entity?
(Please Note: when using the "Find Field from Starting Entity", this functionality attempts to find the shortest navigation route to the defined field.
Keep in mind that this may not always be the most logically efficient route to retrieve the desired data)
- Relationships: What relationships exist between the entities from which you need to retrieve data?
- (e.g. one-to-many, many-to-one, one-to-one, many-to-many)
The example case shown in the guide is as follows:
You are creating an outbound integration for New Hires:
- Your best choice is to choose Job Information (EmpJob) as the starting entity.
- This is because an employee can have many EmpJob/Job History records, but you only want the one for EmpJob.Event=New Hire.
- By choosing EmpJob as the starting entity, you can navigate to other employee information via EmpJob/empEmploymentNav/perPersonNav.
- Although you could possibly choose Person Info (PerPerson) as the starting entity, it would not be your best choice.
Image taken from Data Model Navigator tool.
If the cause of the reported issue outlined by support / engineering / development, is deemed the choice of starting entity,
It is the responsibility of the partner / customer to reconfigure the job correctly to address the reported issue.
- If the change in starting entity recommended by support / engineering / development, cannot be performed, as it will pose further issues
- This is not something that support can address, you will have to re-review and re-consider your requirements accordingly.
- The functionality / limitations of the system cannot be changed to meet a customer requirement
- The requirement must be adjusted to adhere to the available functionality / current limitations of the system
Integration Center, Data Model Navigator, Starting Entity, EmpJob, one to many, 1:many, 1:n, one-to-many, filter, unpredictable, not predictable, , KBA , LOD-SF-INT-INC , Integration Center , LOD-SF-INT , Integrations , LOD-SF-INT-ODATA , OData API Framework , Problem