SAP SuccessFactors employee read and write scenarios

SAP SuccessFactors employee read scenarios

Each of the Read topic has its own prompts, configurations, and so on, but the actual execution of SAP SuccessFactors is encapsulated in the SuccessFactors System Get Common Execution topic expecting the following inputs:

• Filter parameters: Generally passing Employee ID and User ID for filtering query for Employee Read topics.
• ScenarioName: Config Name, which is used by Dataverse call to get scenario configuration.
• userIdentifier: User ID.

A common orchestrator then returns a ModelResponse and LabelResponse, which the Large Language Model (LLM) then parses using the following instructions to generate an answer for the user:

• Extract the input from the following response (map the Label response value as key in model response attribute then provide model value).
• Provide the response to the user in a human readable form.
• Format the response properly to make it clean and readable.
• Use only data values from the variable named successfactorsModelResponse and use the variable named successfactorsLabelResponse for labeling the data.
• Response example:
  • Label Response:key:company,value:company
  • Model Response: company:12345
  • Example Output: Your company is 12345 (Contoso Germany)

The "Get Employee ID" and "Get Service Anniversary" topics are exceptions to this common execution method, which is further explained in their respective sections.

Authorization for all the topics is as follows:

• Authorization is done using the permissionsMetadata part of the starter configuration. The permissionsMetadata and User ID are used to create the query string for OData connector in SuccessFactors Check User Permissions flow.
• You should include permissionMetadata or rolePermission in the starter config file, as there's no other authorization check if both of those fields are missing.

Get Base Compensation

Configuration:

{ 
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetBaseCompensationAndCompaRatio", 
    "rootEntity": "EmpEmployment", 
    "filter": "personIdExternal eq '{personIdExternalVal}' and userId eq 
'{userIdVal}'", 
    "requestEntities": [ 
        { 
            "key": "CompaRatio", 
            "valuePath": "compInfoNav/empCompensationCalculatedNav/compaRatio", 
            "labelPath": "EmpCompensationCalculated/compaRatio" 
        }, 
        { 
            "key": "Currency", 
            "valuePath": "compInfoNav/empCompensationCalculatedNav/currency", 
            "labelPath": "EmpCompensationCalculated/currency" 
        }, 
        { 
            "key": "AnnualBaseSalary", 
            "valuePath": 
"compInfoNav/empCompensationCalculatedNav/yearlyBaseSalary", 
            "labelPath": "EmpCompensationCalculated/yearlyBaseSalary" 
        } 
    ], 
    "permissionsMetadata": [ 
        { 
            "permType": "DATA_MODEL", 
            "permLongValue": -1, 
            "permStringValue": "$_payCompGroup_AnnualizedSalary_read" 
        } 
    ] 
} 

Get Company Code

Configuration:

{ 
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetCompanyCode", 
"rootEntity": "EmpEmployment", 
"filter": "personIdExternal eq '{personIdExternalVal}' and userId eq '{userIdVal}'", 
"requestEntities": [ 
{ 
"key": "CompanyCode", 
"valuePath": "jobInfoNav/company", 
"labelPath": "EmpJob/company" 
}, 
{ 
"key": "CompanyName", 
"valuePath": "jobInfoNav/companyNav/name", 
"labelPath": "" 
} 
], 
"permissionsMetadata": [ 
{ 
"permType": "DATA_MODEL", 
"permLongValue": -1, 
"permStringValue": "$_jobInfo_company_read" 
} 
] 
} 

Get Cost Center

Configuration:

{ 
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetCostCenter", 
"rootEntity": "EmpEmployment", 
"filter": "personIdExternal eq '{personIdExternalVal}' and userId eq '{userIdVal}'", 
"requestEntities": [ 
{ 
"key": "CostCenterCode", 
"valuePath": "jobInfoNav/costCenter", 
"labelPath": "EmpJob/costCenter" 
}, 
{ 
"key": "CostCenterName", 
"valuePath": "jobInfoNav/costCenterNav/name", 
"labelPath": "" 
} 
], 
"permissionsMetadata": [ 
{ 
"permType": "DATA_MODEL", 
"permLongValue": -1, 
"permStringValue": "$_jobInfo_cost-center_read" 
} 
] 
} 

Get Hire Date

Configuration:

{ 
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetHireDate", 
"rootEntity": "EmpEmployment", 
"filter": "personIdExternal eq '{personIdExternalVal}' and userId eq 
'{userIdVal}'", 
"requestEntities": [ 
{ 
"key": "HireDate", 
"valuePath": "originalStartDate", 
"labelPath": "EmpEmployment/originalStartDate" 
} 
], 
"permissionsMetadata": [ 
{ 
"permType": "DATA_MODEL", 
"permLongValue": -1, 
"permStringValue": "$_employmentInfo_seniorityDate_read" 
} 
] 
} 

Get Service Anniversary

Configuration:

{ 
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetHireDate", 
"rootEntity": "EmpEmployment", 
"filter": "personIdExternal eq '{personIdExternalVal}' and userId eq 
'{userIdVal}'", 
"requestEntities": [ 
{ 
"key": "HireDate", 
"valuePath": "originalStartDate", 
"labelPath": "EmpEmployment/originalStartDate" 
} 
], 
"permissionsMetadata": [ 
{ 
"permType": "DATA_MODEL", 
"permLongValue": -1, 
"permStringValue": "$_employmentInfo_seniorityDate_read" 
} 
] 
} 

Get Employee ID

Get Job Info

Configuration:

{ 
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetJobInfo", 
"rootEntity": "EmpEmployment", 
"filter": "personIdExternal eq '{personIdExternalVal}' and userId eq 
'{userIdVal}'", 
"requestEntities": [ 
        { 
            "key": "JobCode", 
            "valuePath": "jobInfoNav/jobCodeNav/name", 
            "labelPath": "EmpJob/jobCode" 
        }, 
        { 
            "key": "JobTitle", 
            "valuePath": "jobInfoNav/jobTitle", 
            "labelPath": "EmpJob/jobTitle" 
        }, 
        { 
            "key": "JobFunction", 
            "valuePath": "jobInfoNav/jobCodeNav/jobFunction", 
            "labelPath": "FOJobCode/jobFunction" 
        }, 
        { 
            "key": "JobFunctionType", 
            "valuePath": "jobInfoNav/jobCodeNav/jobFunctionNav/jobFunctionType", 
            "labelPath": "FOJobFunction/jobFunctionType" 
        } 
    ], 
    "permissionsMetadata": [ 
        { 
            "permType": "DATA_MODEL", 
            "permLongValue": -1, 
            "permStringValue": "$_jobInfo_job-code_read" 
        } 
    ] 
} 

Get Position Number

Configuration:

{ 
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetPositionNumber", 
"rootEntity": "EmpEmployment", 
"filter": "personIdExternal eq '{personIdExternalVal}' and userId eq '{userIdVal}' 
and tolower(jobInfoNav/positionNav/effectiveStatus) eq 'a'", 
"requestEntities": [ 
{ 
"key": "JobCode", 
"valuePath": "jobInfoNav/position", 
"labelPath": "EmpJob/position" 
} 
], 
"permissionsMetadata": [ 
{ 
"permType": "DATA_MODEL", 
"permLongValue": -1, 
"permStringValue": "$_jobInfo_position_read" 
} 
] 
} 

SAP SuccessFactors employee write scenarios

Employee write topics logic is as follows:

1. Get user data

Get user data and Picklist data (if necessary) by using SuccessFactors System Get Common Execution, which expects the following inputs:

FilterParams: The following example shows a user data request, but picklist data request follow the same rules for prepping the filterParams.

Example format used in Topic:

"{""personIdExternalVal"": """ & Global.ESS_UserContext_Employee_Id & """,""userIdVal"": """ & Global.ESS_UserContext_User_Id & """}" 

Snippet of Template configuration:

{ 
  ... 
  "filter": "personIdExternal eq '{personIdExternalVal}' and userId eq '{userIdVal}'", 
  ... 
} 

The keys present in the filterParam must match what is expected in the Template configuration. In the examples above personIdExternalVal would be used as a key to insert Global.ESS_UserContext_Employee_Id into the filter expression.

ScenarioName: Configuration name, which is used by the Dataverse call to get scenario configuration userIdentifier: User Id

SuccessFactors System Get Common Execution then returns a ModelResponse and LabelResponse, which are parsed for the user's data, and then stored in variables.

2. Confirm information

Present the user their current information asking for their confirmation to update or cancel to trigger the respective flow using either inline messaging or with an adaptive card.

3. Submit update

If the user submits their update, then data is collected and used to call the SuccessFactors System Update Common Execution. This flow will UPSERT user data in SuccessFactors using the OData connector. SuccessFactors System Update Common Execution requires the following inputs:

• TargetUserId: User ID
• var_requestParam: An array of objects

Example Format used in Topic:

"[{""key"":""personIdExternalVal"", ""value"":"""&Global.ESS_UserContext_Employee_Id&"""},         {""key"":""countryVal"", ""value"":"""&First(Topic.var_parsedModel).country&"""},{""key"":""startDateVal"", ""value"":"""&DateDiff(Date(1970, 1, 1), First(Topic.var_parsedModel).startDate, TimeUnit.Seconds) * 1000&"""},{""key"":""genericString1Val"", ""value"":"""&Topic.id_raceAndEthnicity&"""}]" 

Snippet from Template configuration

{ 
    "__metadata": { 
        "uri": "PerGlobalInfoUSA" 
    },   
    "personIdExternal": "personIdExternalVal", 
    "country": "countryVal", 
    "startDate": "/Date(startDateVal)/", 
    "genericString1": "genericString1Val", 
 } 

The keys present in the var_requestParam must match what is expected in the Template configuration. In the previous examples personIdExternalVal would be used as a key to insert Global.ESS_UserContext_Employee_Id into the request body.

• var_scenarioName: Configuration name, which is used by Dataverse call to get scenario configuration.

4. Success or fail notification to user

If SuccessFactors System Update Common Execution succeeds, then Copilot responds to a user that their update succeeded. If the operation fails, the user gets a failure message.

Multi-country/region configurations

To accommodate support for multiple country/regions and their respective entities, distinct configurations are established tailored to each scenario. These configurations adhere to the established naming convention, with the addition of _<CountryCode> appended at the end. This differentiation serves not only to distinguish between configurations but also to ensure retrieval of the appropriate configuration from the topics. Within the topic, the correct configuration is identified by appending UserContext_Country_Code to the standard configuration name.

For example: Concatenate("msdyn_HRSAPSuccessFactorsHCMEmployeeUpdateRaceAndEthnicity_", Global.ESS_UserContext_Country_Code)

For all Write configurations, ensure that requestBody is a string by including single quotes outside the brackets. This is the expected data type for query flow.

Customizations

Customizations to the Template configuration will generally require these changes:

1. Adding fields to Get Config:

2. Adding fields to Adaptive card:

After adding fields to get schema, they can be accessed in the adaptive card design formula:

The adaptive card label property is set by the value stored in the pared label variable and the value property is set using the var_veteranInfo variable, which stores the parsed user data.

If another input type needs to be added to the adaptive card to collect data for another field, then use the following input control code:

{
type: "Input.ChoiceSet",
placeholder: "No Selection",
id: "id_veteran",
label: Lookup(Topic.var_parsedLabel, key="genericNumber1").value,
value: First(Topic.var_veteranInfo).genericNumber1,
choices: Topic.var_veteranPicklist
}

After updating the code, you must update the output binding schema with the string given in id property. In the previous example, id = id_veteran. Therefore, the output binding schema must have a variable with the same name set with the correct data type. For example:

kind: Record
properties:
  actionSubmitId: String
  id_challenged_veteran: String
  id_special_disabled_veteran: String
  id_veteran: String

3. Adding fields to update

After adding the new field to update configuration, it must be updated with the var_requestParam to include added field and the values to send to update with.

Refer to the built-in "write" scenarios for further guidance to extend other scenarios.

Authorization

• Authorization is done using the permissionsMetadata/rolePermission that is part of the Template configuration. The permissionsMetadata and User ID are used to create the query string for OData Connector in SuccessFactors Check User Permissions flow. If SuccessFactors Check User Permissions flow doesn't find permissionsMetadata it runs roleBased Permissions flow using role permission and user roles variable

• It's important to include permissionMetadata or rolePermission in template configuration file as there's no other authorization check if both of those fields are missing.

Veteran Info

Veteran info	Description
Description	Retrieves the employee's current veteran information and presents it in an adaptive card, which the employee can edit and submit to update their veteran info
Validations & Errors	If employee's Country_Code does not exist in SuccessFactors_VeteranInfo_Countries environment variable then Topic won't run and instead return a "Sorry, this capability isn't available in <ESS_UserContext_Country_Code> at this moment." message
Prompts	Can I update my Veteran status? Is there a process to update my military/veteran status? Do I have to provide my military/veteran details?
Adaptive Card	There are two adaptive cards for each support country/region, which are picked using a switch statement based on the employees ESS_SuccessFactors_UserContext_Country_Code

Get configurations

There are differences between where the data is stored between country/region. You must have a two template configurations. These configurations differ in:

• RootEntity
• RequestEntities

Configuration

	{
  "scenario": "VeteranInformation",
  "rootEntity": "PerGlobalInfoUSA",
  "filter": "personIdExternal eq {personIdExternalVal} and personNav/employmentNav/userId eq '{userIdVal}'",
  "requestEntities": [
    {
      "key": "Country",
      "valuePath": "country",
      "labelPath": ""
    },    
    {
      "key": "StartDate",
      "valuePath": "startDate",
      "labelPath": ""
    },
    {
      "key": "Veteran",
      "valuePath": "genericNumber1",
      "labelPath": "PerGlobalInfoUSA/genericNumber1"
    },
    {
      "key": "ChallengedVeteran",
      "valuePath": "genericNumber2",
      "labelPath": "PerGlobalInfoUSA/genericNumber2"
    },
    {
      "key": "SpecialDisabledVeteran ",
      "valuePath": "genericNumber6",
      "labelPath": "PerGlobalInfoUSA/genericNumber6"
    }
  ], 
  "permissionsMetadata": [],
  "rolePermissions": []
}

Configuration:

	{
  "scenario": "VeteranInformation",
  "rootEntity": "PerGlobalInfoGBR",
  "filter": "personIdExternal eq {personIdExternalVal} and personNav/employmentNav/userId eq '{userIdVal}'",
  "requestEntities": [
{
      "key": "Country",
      "valuePath": "country",
      "labelPath": ""
    },    
{
      "key": "StartDate",
      "valuePath": "startDate",
      "labelPath": ""
    },
{
      "key": "Veteran",
      "valuePath": "genericNumber1",
      "labelPath": "PerGlobalInfoGBR/genericNumber1"
    }
  ], 
  "permissionsMetadata": [],
  "rolePermissions": []
}

Picklist Configuration

There are differences between where the data is stored between countries therefore it's required to have two template configurations. These configurations differ in:

• RootEntity
• RequestEntities

Configuration

{
    "scenario": "VeteranInfo_USA",
    "rootEntity": "PicklistLabel",
    "filter": "picklistOption/picklist/picklistId eq 'yesNo' and locale eq '{localeValue}'",
    "requestEntities": [
                {
            "key": "optionId",
            "valuePath": "optionId",
            "labelPath": ""
        },
        {
            "key": "label",
            "valuePath": "label",
            "labelPath": ""
        }
        ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

Configuration:

	{
    "scenario": "MilitaryStatus_GBR",
    "rootEntity": "PicklistLabel",
    "filter": "picklistOption/picklist/picklistId eq 'MILITARYSTATUS_GBR' and locale eq '{localeValue}'",
    "requestEntities": [
                {
            "key": "optionId",
            "valuePath": "optionId",
            "labelPath": ""
        },
        {
            "key": "label",
            "valuePath": "label",
            "labelPath": ""
        }
        ],
    "permissionsMetadata": [],
    "rolePermissions": []
}

Write Configuration

The difference between countries/regions in these write configurations are the uri/RootEntity and number of fields being different, such as GBR configuration doesn't have genericNumber2 & genericNumber6 as they are not used.

Configuration:

	{
    "scenario": "UpdateVeteranInformation",
    "requestBody": '{
        "__metadata": {
            "uri": "PerGlobalInfoUSA"
        },  
        "personIdExternal": "personIdExternalVal",
        "country": "countryVal",
        "startDate": "/Date(startDateVal)/",
        "genericNumber1": "genericNumber1Val",
        "genericNumber2": "genericNumber2Val",
        "genericNumber6": "genericNumber6Val",
    }',
    "permissionsMetadata": [],
    "rolePermissions": []
}

Configuration

{
    "scenario": "UpdateVeteranInformation",
    "requestBody": '{
        "__metadata": {
            "uri": "PerGlobalInfoGBR"
        },
        "personIdExternal": "personIdExternalVal",
        "country": "countryVal",
        "startDate": "/Date(startDateVal)/",
        "genericNumber1": "genericNumber1Val"
    }',
    "permissionsMetadata": [],
    "rolePermissions": []
}

Customizations Adding an additional country/region requires the following:

1. Add all the respective template configurations
2. If new country/region has different fields or collects a different data type, then input the text and add a new condition for the new country/region. Then, set up the adaptive card as required for country/region and any other requirements.

Race & Ethnicity

Get configurations

There are differences between where the data is stored between countries/regions. Therefore, two template configurations are required. These configurations differ in:

• RootEntity

Configuration

	{
  "scenario": "RaceAndEthnicity",
  "rootEntity": "PerGlobalInfoUSA",
  "filter": "personIdExternal eq {personIdExternalVal} and personNav/employmentNav/userId eq '{userIdVal}'",
  "requestEntities": [
    {
      "key": "EthnicGroup",
      "valuePath": "genericString1",
      "labelPath": "PerGlobalInfoUSA/genericString1"
    },
{
      "key": "Country",
      "valuePath": "country",
      "labelPath": ""
    },
{
      "key": "startDate",
      "valuePath": "startDate",
      "labelPath": ""
    }
  ], 
  "permissionsMetadata": [],
  "rolePermissions": []
}

Configuration

{
  "scenario": "RaceAndEthnicity",
  "rootEntity": "PerGlobalInfoGBR",
  "filter": "personIdExternal eq {personIdExternalVal} and personNav/employmentNav/userId eq '{userIdVal}'",
  "requestEntities": [
    {
      "key": "EthnicGroup",
      "valuePath": "genericString1",
      "labelPath": "PerGlobalInfoGBR/genericString1"
    },
{
      "key": "Country",
      "valuePath": "country",
      "labelPath": ""
    },
{
      "key": "startDate",
      "valuePath": "startDate",
      "labelPath": ""
    }
  ], 
  "permissionsMetadata": [],
  "rolePermissions": []
}

Picklist Configuration

The only difference between countries in picklist config is the picklistId each is pointing to.

Configuration

{
    "scenario": "RaceAndEthnicity_USA",
    "rootEntity": "PicklistLabel",
    "filter": "picklistOption/picklist/picklistId eq 'ETHNIC-GROUP_USA' and locale eq '{localeValue}'",
    "requestEntities": [
                {
            "key": "optionId",
            "valuePath": "optionId",
            "labelPath": ""
        },
        {
            "key": "label",
            "valuePath": "label",
            "labelPath": ""
        }
        ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

Picklist configuration in Race & Ethnicity | Configuration | Description | | --- | --- | |Template configuration | HRSAPSuccessFactorsHCMGetPicklistRaceAndEthnicity_GBR| |Scenario name| msdyn_HRSAPSuccessFactorsHCMGetPicklistRaceAndEthnicity_GBR| |Filter | Filters for picklistId 'ETHNICGROUP_GBR' and locale which is ESS_UserContext_Locale | |**Values queried**|<li>optionId: Value used for data corresponding to label name<li>Label`: Human readable name|

Configuration

	{
    "scenario": "RaceAndEthnicity_GBR",
    "rootEntity": "PicklistLabel",
    "filter": "picklistOption/picklist/picklistId eq 'ETHNICGROUP_GBR' and locale eq '{localeValue}'",
    "requestEntities": [
                {
            "key": "optionId",
            "valuePath": "optionId",
            "labelPath": ""
        },
        {
            "key": "label",
            "valuePath": "label",
            "labelPath": ""
        }
        ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

Write Configuration

The difference between countries in these write configurations is:

• RootEntity

Configuration:

	{
    "scenario": "UpdateRaceAndEthnicity",
    "requestBody": '{
        "__metadata": {
            "uri": "PerGlobalInfoUSA"
        },
        "personIdExternal": "personIdExternalVal",
        "country": "countryVal",
        "startDate": "/Date(startDateVal)/",
        "genericString1": "genericString1Val"
    }',
    "permissionsMetadata": [],
    "rolePermissions": []
}

Configuration

	{
    "scenario": "UpdateRaceAndEthnicity",
    "requestBody": '{
        "__metadata": {
            "uri": "PerGlobalInfoGBR"
        },
        "personIdExternal": "personIdExternalVal",
        "country": "countryVal",
        "startDate": "/Date(startDateVal)/",
        "genericString1": "genericString1Val"
    }',
    "permissionsMetadata": [],
    "rolePermissions": []
}

Customizations Adding an additional country/region requires the following:

1. Adding all the respective template configurations
2. If the new country/region has different fields or collects a different data type, then input the text and add a new condition for the new country/region. Then, set up the adaptive card as required for country and any other requirements

Emergency Contact

Race & Ethnicity	Description
Description	Retrieves the employee's current emergency contacts, presents them to employees, and asks if they would like to update or add an emergency contact. Depending on their answer they are presented with an adaptive card to either update a current contact or a blank card for them to add a contact
Prompts	Update my current/existing emergency contact My emergency contact has changed; can I update it in the system? How/where can I update my emergency contact? I want to add new emergency contact Add my emergency contact
Adaptive card	Two kinds of adaptive cards are used in the following examples: Update emergency contact Add emergency contact Initial message Update emergency contact Add emergency contact

Get configurations - emergency contact and pick list for relationship type

Retrieving the existing emergency contact information along with relationship type is the first step in the flow | Configuration | Description | | --- | --- | |Template configuration |HRSAPSuccessFactorsHCMEmployeeGetEmergencyContact| |Scenario name| msdyn_HRSAPSuccessFactorsHCMEmployeeGetEmergencyContact| |Filter|Filters on personIdExternal using ESS_UserContext_Employee_Id and if emergencyContactNav/primaryFlag is equal to 'Y'| |Values queried|

	{
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetEmergencyContact",
    "rootEntity": "PerPerson",
    "filter": "emergencyContactNav/primaryFlag eq 'Y' and personIdExternal eq '{personIdExternalVal}'",
    "requestEntities": [
        {
            "key": "name",
            "valuePath": "emergencyContactNav/name",
            "labelPath": ""
        },
        {
            "key": "phone",
            "valuePath": "emergencyContactNav/phone",
            "labelPath": ""
        },
        {
            "key": "relationship",
            "valuePath": "emergencyContactNav/relationship",
            "labelPath": ""
        }, 
        {
            "key": "primaryFlag",
            "valuePath": "emergencyContactNav/primaryFlag",
            "labelPath": ""
        }
    ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

	{
    "scenario": "HRSAPSuccessFactorsHCMGetPicklistRelationshipType",
    "rootEntity": "PicklistLabel",
    "filter": "picklistOption/picklist/picklistId eq 'relation' and locale eq '{localeValue}'",
    "requestEntities": [ 
                {
            "key": "optionId",
            "valuePath": "optionId",
            "labelPath": ""
        },
        {
            "key": "label",
            "valuePath": "label",
            "labelPath": ""
        }
        ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

phone: Emergency contact phone number collected from employee|

Configuration

	{
    "scenario": "HRSAPSuccessFactorsHCMEmployeeUpdateEmergencyContact",
    "requestBody": '{
        "__metadata": {
            "uri": "PerEmergencyContacts"
        },
        "personIdExternal": "personIdExternalVal",
        "relationship": "relationshipVal",
        "name":"nameVal",
        "primaryFlag":"primaryFlagVal",
        "phone":"phoneVal"
    }',
    "permissionsMetadata": [],
    "rolePermissions": []
}

Delete existing emergency contact

Update emergency contact flow has an extra configuration which deletes an existing emergency contact for the employee. This configuration is used exclusively when an employee updates name of one of their current emergency contacts which must delete the current entry and add a new one with the change.

Configuration	Description
Template configuration	HRSAPSuccessFactorsHCMEmployeeDeleteEmergencyContact
Scenario name	msdyn_HRSAPSuccessFactorsHCMEmployeeDeleteEmergencyContact
Request Body	personIdExternal: ESS_UserContext_Employee_Id relationship: relationship value of emergency contact name: Emergency contact name collected from employee primaryFlag:PrimaryFlag value from get call is automatically used here unless a new contact is added or else its false. If a first contact is being added, then it is automatically primary phone:Emergency contact phone number collected from employee

Configuration:

	{
    "scenario": "HRSAPSuccessFactorsHCMEmployeeUpdateEmergencyContact",
    "requestBody": '{
        "__metadata": {
            "uri": "PerEmergencyContacts"
        },
        "operation": "operationVal",
        "personIdExternal": "personIdExternalVal",
        "relationship": "relationshipVal",
        "name":"nameVal",
        "primaryFlag":"primaryFlagVal",
        "phone":"phoneVal"
    }',
    "permissionsMetadata": [],
    "rolePermissions": []
}

Phone

Phone	Description
Description	Retrieves the employee's phone data, presents them to the employee, and asks if they would like to update or add a phone number. Depending on their answer they are presented with an adaptive card to either update a current contact or a blank card for them to add a phone number
Prompts	Update my current/existing emergency contact My emergency contact has changed; can I update it in the system? How/where can I update my emergency contact? I want to add new emergency contact Add my emergency contact
Adaptive card	Two kinds of adaptive cards can be used to change an employee's phone information: Update phone Add phone The following screenshot shows an example of an adaptive card to add a phone number.

Get configurations - existing phone numbers and pick list for phone number type option

Retrieving the existing phone numbers along with phone number type is the first step in the flow.

Configuration	Description
Template configuration	HRSAPSuccessFactorsHCMEmployeeGetContactPhone
Scenario name	msdyn_HRSAPSuccessFactorsHCMEmployeeGetContactPhone
Filter	Filters on personIdExternal using ESS_UserContext_Employee_Id
Values queried	areaCode: Area code section of phone number phoneNumber: All numbers after the area code in a phone number. Also defined as Prefix + line number countryCode: Country code designation of phone.Example: 1 for US phoneType: Phone type values come from ecPhoneType picklist Id isPrimary: Boolean flag for whether the Phone is primary or not

Configuration

	{
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetContactPhone",
    "rootEntity": "PerPerson",
    "filter": "personIdExternal eq '{personIdExternalVal}'",
    "requestEntities": [
        {
            "key": "areaCode",
            "valuePath": "phoneNav/areaCode",
            "labelPath": "PerPhone/areaCode"
        },
        {
            "key": "phoneNumber",
            "valuePath": "phoneNav/phoneNumber",
            "labelPath": "PerPhone/phoneNumber"
        },
        {
            "key": "countryCode",
            "valuePath": "phoneNav/countryCode",
            "labelPath": "PerPhone/countryCode"
        },
        {
            "key": "phoneType",
            "valuePath": "phoneNav/phoneType",
            "labelPath": "PerPhone/phoneType"
        },
        {
            "key": "isPrimary",
            "valuePath": "phoneNav/isPrimary",
            "labelPath": "PerPhone/isPrimary"
        }
    ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

Get picklist for phone types

Getting the list of phone number type options like Cell, Work, etc.

Configuration	Description
Template configuration	HRSAPSuccessFactorsHCMGetPicklistPhoneType
Scenario name	msdyn_HRSAPSuccessFactorsHCMGetPicklistPhoneType
Filter	Filters on picklistId in ecPhoneType and locale which is ESS_UserContext_Locale
Values queried	optionId: Value used for data corresponding to label name Label: Human readable name

Configuration

	{
    "scenario": "HRSAPSuccessFactorsHCMGetPicklistPhoneType",
    "rootEntity": "PicklistLabel",
    "filter": "picklistOption/picklist/picklistId eq 'ecPhoneType' and locale eq '{localeValue}' ",
    "requestEntities": [
                {
            "key": "optionId",
            "valuePath": "optionId",
            "labelPath": ""
        },
        {
            "key": "label",
            "valuePath": "label",
            "labelPath": ""
        }
        ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

Update contact phone

Update the contact phone number.

Configuration	Description
Template configuration	HRSAPSuccessFactorsHCMEmployeeUpdateContactPhone
Scenario name	msdyn_HRSAPSuccessFactorsHCMEmployeeUpdateContactPhone
Request Body	personIdExternal: ESS_UserContext_Employee_Id CountryCode: Country code input from employee areaCode:Area code input from employee phoneNumber: Phone number input from employee isPrimary:isPrimary value from get call is automatically used here unless a new contact is added or else it is false. If a first contact is being added, then it is automatically primary. phoneType: Phone number type value input from employee

Configuration

	{
    "scenario": "HRSAPSuccessFactorsHCMEmployeeUpdateContactPhone",
    "requestBody": '{
      "__metadata": {
        "uri": "PerPhone"
        },
      "personIdExternal": "personIdExternalVal",
      "countryCode": "countryCodeVal",
      "areaCode": "areaCodeNav",
      "phoneNumber": "phoneNumberVal",
      "isPrimary": isPrimaryVal,
      "phoneType": "phoneTypeVal"
      }',
    "permissionsMetadata": [],
    "rolePermissions": []
}

Email

Email	Description
Description	Retrieves the employee's current email address, displays it, and then prompts employee to submit a new email address
Prompts	I want to update my personal email update my personal email to [email_addressTobeUpdated] Update my email I'd like to update my email

Get configurations - contact email

Retrieving the existing contact email is the first step in the flow

Configuration	Description
Template configuration	HRSAPSuccessFactorsHCMEmployeeGetContactEmail
Scenario name	msdyn_HRSAPSuccessFactorsHCMEmployeeGetContactEmail
Filter	Filters on personIdExternal using ESS_UserContext_Employee_Id and email type using picklist emailType value for Personal
Values queried	emailAddress: Employee's current email address emailType: Types of Email values from picklist id 'ecEmailType'. isPrimary: Boolean flag for if Email is primary

Configuration

{
    "scenario": "HRSAPSuccessFactorsHCMEmployeeGetContactEmail",
    "rootEntity": "PerEmail",
    "filter": "emailType eq '{emailTypeVal}' and personIdExternal eq '{personIdExternalVal}'",
    "requestEntities": [
        {
            "key": "emailAddress",
            "valuePath": "emailAddress",
            "labelPath": "PerEmail/emailAddress"
        },
        {
            "key": "isPrimary",
            "valuePath": "isPrimary",
            "labelPath": ""
        },
        {
            "key": "emailType",
            "valuePath": "emailType",
            "labelPath": ""
        }
    ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

Get picklist for email types

Getting the list of email type options

Configuration	Description
Template configuration	HRSAPSuccessFactorsHCMGetPicklistEmailType
Scenario name	msdyn_HRSAPSuccessFactorsHCMGetPicklistEmailType
Filter	Filters on picklistId in ecEmailType and locale which is ESS_UserContext_Locale and picklistOption/externalCode eq 'P'
Values queried	optionId: Value used for data corresponding to label name Label: Human readable name

Configuration

	{
    "scenario": "HRSAPSuccessFactorsHCMGetPicklistEmailType",
    "rootEntity": "PicklistLabel",
    "filter": "picklistOption/picklist/picklistId eq 'ecEmailType' and locale eq '{localeValue}' and picklistOption/externalCode eq 'P'",
    "requestEntities": [ 
                {
            "key": "optionId",
            "valuePath": "optionId",
            "labelPath": ""
        },
        {
            "key": "externalCode",
            "valuePath": "picklistOption/externalCode",
            "labelPath": ""
        }, 
        {
            "key": "label",
            "valuePath": "label",
            "labelPath": ""
        }
        ],
    "permissionsMetadata": [],
        "rolePermissions": []
}

Update contact email

Updating the contact email

Configuration	Description
Template configuration	HRSAPSuccessFactorsHCMEmployeeUpdateContactEmail
Scenario name	msdyn_HRSAPSuccessFactorsHCMEmployeeUpdateContactEmail
Request Body	personIdExternal:ESS_UserContext_Employee_Id emailAddress: New email address input from employee emailType: Always set to 'Personal' from emailType picklist isPrimary: Always set to true value. No support for updating emails that are not primary

Configuration

{
    "scenario": "HRSAPSuccessFactorsHCMEmployeeUpdateContactEmail",
    "requestBody": '{
        "__metadata": {
            "uri": "PerEmail"
        },
        "personIdExternal": "personIdExternalVal",
        "emailAddress": "emailAddressVal",
        "emailType":"emailTypeVal",
        "isPrimary": isPrimaryVal
    }',
    "validationRules": "",
    "permissionsMetadata": [],
    "rolePermissions": []
}

Preferred Name

Preferred Name	Description
Description	Retrieves the employees current preferred name, displays it, and then prompts employee to submit a new name. Employee can also include name in prompt.
Prompts	Update my preferred name Change my preferred name Change my preferred name to[new_preferred_name] I'd like to update my preferred name to [new_preferred_name]

Get configurations - preferred name

Retrieving the existing preferred name is the first step in the flow

Configuration	Description
Template configuration	HRSAPSuccessFactorsHCMEmployeeGetPreferredName
Scenario name	msdyn_HRSAPSuccessFactorsHCMEmployeeGetPreferredName
Filter	Filters on personIdExternal using ESS_UserContext_Employee_Id
Values queried	preferredName: Employee's current preferred name

Configuration

{
  "scenario": "HRSAPSuccessFactorsHCMEmployeeGetPreferredName",
  "rootEntity": "PerPerson",
  "filter": "personIdExternal eq '{personIdExternalVal}'",
  "requestEntities": [
    {
      "key": "preferredName",
      "valuePath": "personalInfoNav/preferredName",
      "labelPath": "PerPersonal/preferredName"
    }
  ],
  "permissionsMetadata": [],
  "rolePermissions": []
}

Update preferred name

Updating the preferred name | Configuration | Description | | --- | --- | |Template configuration|HRSAPSuccessFactorsHCMEmployeeUpdatePreferredName| |Scenario name|msdyn_HRSAPSuccessFactorsHCMEmployeeUpdatePreferredName| |Request Body|

	{
    "scenario": "HRSAPSuccessFactorsHCMEmployeeUpdatePreferredName",
    "requestBody": '{
        "__metadata": {
            "uri": "PerPersonal"
        },
        "personIdExternal": "personIdExternalVal",
                "startDate":"/Date(startDateVal)/",
        "preferredName": "preferredNameVal"
    }',
    "validationRules": "",
    "permissionsMetadata": [],
    "rolePermissions": []
}