Aggregation of Additional Schema Attributes Using SFAPI

The SuccessFactors source supports the aggregation of additional schema attributes.

In the SuccessFactors managed system, on the Additional Attribute Mapping panel, in the Schema Attribute field, enter the name of the additional attribute. In the Navigation Path (SFAPI Path) field, enter the navigation path of the attribute as defined in SFAPI (SuccessFactors Data API). For example:

/person/employment_information/job_information/pay

Note
The SFAPI is SuccessFactors Data API. It is a SOAP Web Service designed for importing and exporting data to and from your SuccessFactors instance.

To aggregate the value of the additional schema attributes for an account:

  1. Add the entry key of the schema attribute and its respective path. For the navigation path, perform the following steps:

    • On a SuccessFactors managed system, go to Admin Centre > SFAPI Data Dictionary.

    • Search for CompoundEmployee in the list.

    • Expand the CompoundEmployee entity that displays the attribute fields with their respective information.

    • Search for the attribute you want to add. Its path will be displayed in the Name field.

    For example:

    Label: Nationality

    Path: /person/personal_information/nationality

    This is the SFAPI path that must be copied and entered in the Navigation Path (SFAPI Path) field in the source UI.

  2. Add the same attribute name entry in SuccessFactors source account schema. For more information on adding account schema attribute, refer to Adding Attributes to a Source Schema.

    Note

  • Ensure that the names of additional attributes and details are added in both the source account schema and the source UI fields, respectively.

  • This would aggregate the attributes that are returned from the Compound Employee API from the following entities.

    • person

    • personal_information

    • address_information

    • email_information

    • phone_information

    • employment_information

    • job_information

Additional Information

To aggregate additional information types associated with supported entities such as personal_information, address_information, email_information, or phone_information, you can configure a path in the attribute mapping.

For example, there are two address information types in the following node. The first is type home and second is type Payroll.

Copy
<address_information>
    <address_type>home</address_type>
    <country>ARG</country>
</address_information>

<address_information>
      <address_type>Payroll</address_type>
      <country>AUS</country>
</address_information>

If you want to fetch the country for Payroll, then set the navigation path / SFAPI path as follows:

/person/address_information[address_type= "Payroll"]/country

The SuccessFactors source aggregates the PrimaryEmailAddress. To aggregate a different type of email address, set the navigation path as follows:

/person/email_information[email_type="O"]/email_address

where, O indicates the Office email address type.

Additional Attributes with XPath

The SuccessFactors source supports the SFAPI path value in XPath 2.0 format to aggregate additional attributes.

The supported additional attributes are part of following entities:

Entity

Employees

Users

User

No

Yes

Compound Employee API sub-structures

Yes

Yes

To aggregate the value of additional account schema attributes for Compound Employee API sub-structures, you must add the attribute name to the account schema and the corresponding navigational path. The following Compound Employee API substructures are standard:

  • person

  • personal_information

  • address_information

  • phone_information

  • email_information

  • person_relation

  • employment_information

  • job_information

  • compensation_information

  • paycompensation_recurring

  • paycompensation_non_recurring

  • payment_information

  • accompanying_dependent

  • alternative_cost_distribution

  • job_relation

  • direct_deposit

  • national_id_card

  • deduction_recurring

  • deduction_non_recurring

  • global_assignment_information

  • ItDeclaration

  • dependent_information

  • personal_documents_information

  • EmployeeDataReplicationElement

  • associated_employee_information

  • emergency_contact_primary

  • DRTMPurgeStatusOverview

You can include additional sub-structures by providing the sub-structure name in the Include Compound Employee API Entities field on the SuccessFactors managed system. To add multiple entities, separate the names with commas. For example: WorkOrder, SecondaryAssignments.

The SuccessFactors Connector can aggregate additional account schema attributes for user management. These attributes belong to the user entity whose Navigation Target property is blank.

User attributes must use the user prefix. For example, user.city.

To include additional attributes in aggregation processes using XPath:

  1. On the SuccessFactors managed system, go to Admin Center.

  2. Search for and select SFAPI Data Dictionary.

    The SFAPI Data Dictionary page displays.

  3. Search for and expand the CompoundEmployee entity to display the attribute fields.

  4. Find the required attribute and the path displayed under the Name field and copy the path. For example:

    Label: Nationality

    Name (Path): /person/personal_information/nationality

    The Name path is the required field value for Navigation Path (SFAPI Path).

  5. On the SuccessFactors managed system, in the Additional Attribute Mapping sub-panel, set the following:

    Attributes

    Description

    Include Compound Employee API Entities

    Enter the name of Compound Employee API extended sub-structures/Entities (separated by comma) to query for additional attributes.

    Attribute Mapping

    Define the schema attribute name along with navigation path that connector will aggregate from the SuccessFactors managed system.

Specifying Values from Multiple Sub-Structures

By default, the SuccessFactors source aggregates the values without applying logic. It fetches the value that matches the specified SFAPI path. If an attribute value includes multiple sub-structures and you want to aggregate the data from a specific entity, you can provide the XPath 2.0 value.

Use Case 1:

You want to aggregate the country value for address_type, but address_type has multiple values, such as home or payroll. To specify the payroll address, set the Navigation Path (SFAPI Path) as follows:

/person/address_information[address_type= "Payroll"]/country

Use Case 2:

By default, the SuccessFactors source aggregates the PrimaryEmailAddress. If you want to return specific email addresses, such as the Office type email address, set the Navigation Path (SFAPI Path) as follows:

/person/email_information[email_type="O"]/email_address

where O represents that the email address is an Office type.

Use Case 3:

An employee is being promoted and you want to aggregate information based on the future position to trigger approvals by the future manager. In this use case, the employee has two sets of job information - the current and future. To fetch the future manager information, set the Navigation Path (SFAPI Path) as follows:

/person/employment_information/job_information[xs:date(start_date) ge currentdate()]/ manager_person_id_external

Use Case 4:

A user has concurrent assignments and you want aggregate the primary position. To aggregate only the primary position, set the Navigation Path (SFAPI Path) as follows:

/person/employment_information[not(SecondaryAssignmentPeriod)]/job_information [xs:date(start_date) le current-date()and xs:date(end_date) ge current-date ()]/position

Future Actions

The Future Actions attribute stores information about Future Actions in the following JSON format:

{"Actions": [{"ActionType" : "<ActionCode>","ActionReason" : "<Action Reason value>","ActionStartDate" : "<Start date>","ActionEndDate" : "<End date>"}]}

For example, you can use the following:

{"Actions": [{"ActionType" : "SCWK","ActionReason" : "Start CWK","ActionStartDate" : "2018-08-26","ActionEndDate" : "2018-09-08"}]}

Note
The Future Actions attribute aggregates future employment actions only.