Create your (first) integration with SuccessFactors Integration Center: Full step-by-step guide
Hello SAP community,
It was quite a journey to get my first integration ready to hit the ground running, hence I will share a full step-by-step guide that goes through every step that you need to take to get your (first) integration up and running with Integration Center.
In this guide, I will be setting up an integration called Everbridge with Integration Center to go through all steps and considerations that are to be expected whilst setting an outbound integration from SuccessFactors to another system. This integration will leverage personal, phone and email related data and will show how to overcome the challenges when you are working with such data.
Objective: Setting up an outbound integration
Essentially how you set-up your integration depends on the business needs and what the target system requires. A Cloud Architect could help you a lot here, but with some guidelines and an example of an outbound integration I hope to make this more clear.
1. Go to Integration Center ==> My Integrations ==> Create ==> More Integration Types
2. Choose your type and integration format
Although the source is always SuccessFactors for an outbound integration, the system you wish to integrate with commonly dictates the allowed trigger, destination and format for your integration, hence it’s always important to check this upfront. If you have multiple options, the easiest approach would be picking CSV as option (although integration allows you to change the extension to .dat or .txt instead) that is sent to an SFTP server, but different options become available as visible below dependent on what you select. When you for instance wish to create an inbound integration, you choose Trigger Type Scheduled and Source Type SFTP and thereby the destination type is automatically set to SuccessFactors and this will cause all format options to be grayed out apart from None selected and CSV.
Options before selecting:
Options after selecting an inbound integration:
Options after selecting an outbound integration:
3. Pick the entity within Integration Center
You need the full picture of the required fields (so please make sure that this is provided up front, preferably with an example of the data). As the sample integration required personal, phone and email related data and one row per employee, including future employees, I chose the User entity and pressed Select.
My choice may not be so obvious if you have data that comes from multiple entities, hence you can use these guidelines based on the most relevant piece of data you need to deliver:
– Current/multiple lines of job related data + other data (i.e. first name, date of birth)?
==> Job Information (EmpJob)
– Current/multiple lines of compensation related + other data (i.e. name, date of birth)?
==> Compensation Information (EmpCompensation)
– Data from custom MDF object(s) and/or other data?
(Special note: especially useful if you need data for future hires, because a lot of data commonly won’t show for future hires when you don’t select date ranges, although it will show in this entity).
– Nothing specific?
==> Biographical Information (PerPerson).
(Special note, do not use this if you use global assignments/concurrent employment, because the system cannot easily differentiate between the different users that are on such assignments).
4. Create the integration content
After creating a name, description, having Output File Type: CSV, setting a simple header and pressing the Next button, the actual integration content can be created. The easiest (granted you have already gathered all matching fields) is uploading a CSV file with the field names that your target system (in this case Everbridge) requires. These fields were placed as headers in an Excel file, saved as an Excel file and have been uploaded as this file.
5. Set default values/associated fields/calculated fields and format.
As the uploaded file already ensured the right name was applied, the next actions ensure that each field gets the right values. You can do this by clicking the field name each time and taking actions.
– External ID
* Situation: You need to select the field that represents the External ID for users;
* Challenge: SuccessFactors has multiple fields that can be seen as the employee’s External ID;
identify the available ID’s (in this case user-id and person-id-external);
associate each field to gather the output and compare which output matches best for
the target system. Often these numbers are the same, hence the choice won’t matter
that much, but this does not always have to be the case.
* Result: As userid was the only direct option in the user entity, I have associated the field userid.
– Last name.
* Situation: You need to select the field that represents the first name at birth of users;
* Challenge: Dutch last names can be set-up in different ways with fields that are not per se part of the User Entity (i.e. last name: de Groot could also be preferred without using “de”);
* Solution: Either make a calculated column with an IF statement or ensure you associate a field that already contains the preferred last name. In this case there already was a field that contained the correct last name called: preferred name. This field could be leveraged by typing the name in the search bar and by selecting the match. You will notice that the screen has jumped to another entity by using so called “Nav”. These basically allow you to step to a related other table to get the right data. If you are not sure which one to take, you can of course search for a term and pick the most suitable entity (in this case PerPersonal) and this automatically guided me via the right Nav’s to the right field. Note! Make sure you never select the option with (External…) as those entities are rarely used and will give you a warning.
* Result: The last name is always filled with the correctly formatted last name.
– Record Type,
* Situation: You need to select the field that represents the type of user and by default this is: Employee;
* Challenge: There is no field available with this exact value for everyone.
* Solution: Set a default value: Employee
* Result: All fields in the column Record Type will display the value: Employee
* Situation: You need to select the field that contains the Dutch value of the employee’s department;
* Challenge: the common Department field reflects a combination of the employee’s English Department name and code and when searching for the department it initially only provides the technical code;
* Solution: Search for department and select the version that is in EmpJob and from there scroll down to the departmentNav to select this and hereafter select Department Name (name_nl_NL). Note, If you would have taken the option from the search you would in this case have been directed to the wrong department;
* Result: The Dutch names of the departments are visible in the Groups field.
– Phone 1, Phone 2, Phone 3, Phone 4, SMS 1, SMS 2
* Situation: You need to select the field that represents the country of the user’s phone and by default this is: NL;
* Challenge: There is no field available with this exact value for everyone.
* Solution: Set a default value: NL for all these fields
* Result: All Phone and SMS fields will display the value: NL
– Phone Country 1,Phone Country 2, Phone Country 3,Phone Country 4, SMS 1 Country, SMS 2 Country
* Situation: You need to select the correct phone number for each user dependent on the purpose (i.e. business, home etc.). You have a field that directly provides the business phone and for other phone types the system by default only picks the value that corresponds with the first applicable phone type;
* Challenge: You need a different phone number for different fields of an employee;
* Solution: Select the Business Phone for Phone Country 1 and SMS 1 Country, but for the other fields search for phone number and set a field filter for the phone types by filling out their technical value (i.e. O, H,P);
* Result: Each field will only reflect the applicable phone number of the employee that suits its purpose and will otherwise remain blank.
– Email Address 1, Email Address 2
* Situation: You need to select the correct email address for each user dependent on the purpose (i.e. business and personal). You have a field that directly provides the business email and for other email types the system by default only picks the value that corresponds with the first applicable email type;
* Challenge: You only need the a user’s personal email address for Email Address 2;
* Solution: Select Email for Email Address 1 and for Email Address 2 search for email and set a field filter for the personal phone type by filling out the technical value (i.e. H);
* Result: Email Address 1 will only reflect business emails and Email Address 2 will only reflect the personal phone number of the employee and will otherwise remain blank.
* Situation: You need to select the field that contains END for everyone;
* Challenge: There is no field available with this exact value for everyone.
* Solution: Set a default value: END
* Result: All Phone fields will display the value: END
6. Exclude employees based on criteria
After clicking Next, you can exclude employees with certain job codes for instance. I have set an advanced filter to ensure the users that did have a specific job code were excluded. Hereafter I would press next again.
7. Filling out the destination details
Fill out the SFTP details (note: if you don’t have an SFTP server you can request one via a ticket):
– the name of my file (in this case: everbridge);
– the extension (in this case: “csv”);
– no date suffix format (as it was not applicable);
– the file extension (even though you have indicated CSV before, you need to select “csv” here to make sure the file actually ends with .csv and will be seen by other systems as such );
– indicate in which folder the file will be placed (in this case /incoming). Maybe good to note is that in a standard SF SFTP the first folder looks like ‘My Folders’, but in fact this folder doesn’t count so you must take the next first folder instead with a / in front of it (/incoming).
9. Review and save.
After pressing next again I would see the summary of what I had created and I could set the schedule and save and schedule to ensure my integration would be up and running. You do however have to communicate this with the receiver before setting your schedule as it could always be that they are not ready yet.
After taking the steps above you will be able to run your new outbound integration and you can check the content by looking at the output by logging into the SFTP server and by downloading the file. Additionally, you can of course make changes to the integration to get more out of it.
I hope that the steps above help you set up your (first) integration and that you will make many more integrations after that. ?
Thank you for the great guide, Jasper! Will definitely try to create an integration on my own 🙂
No problem at all Valentina, hope you'll get the most out of it!
Thank you for your great job!
I created my last integration scenario with relationship one-to-many. And I had big problem with represent the information because I had a pop-up "You have used one to many field navigation while adding this field. You have used default field filter with value <first> or not used any field filter.” I did not use any filter as result I have just first values from my MDF form.
I read a lot of KBA, guides and I understand about this restriction but maybe you know some solution or advise how I can resolve this issue.
I will be appreciated for any help.
It's indeed a restriction that by default the 1st value is picked, but you may have some options dependent on the scenario.
1. Below in the screen where you pick your field (Entity View), there's another tab below it that you can open called "Field Filters". When you select the entity to filter (often it's just 1 where you can select the circle next to the "Target Entity", but sometimes you get more hence you would then have to select the one where you will likely have a useful field to apply the filter on) you will notice that you get a dropdown to select below it and by default that's always on <first> aka 1st value. You can then filter on a field (the downside is that you can only put text values in it if you want to use specific fields). If you for instance want integration center to only pick active records you could pick status with value A for example to ensure you only get active records. Again it really depends on your use case if this makes sense.
2. You could also consider taking a different starting entity. If you for instance do an integration with EC and you start with PerPerson and then pick PerPersonal then you will always have to choose with the method above, but if you swap it around then you can first select the correct records with PerPersonal and then via a Nav get correct data with it as Integration Center won't have to pick from many records anymore in this scenario,
If neither of these options work for you, you can only split up the integration to ensure you don't get this scenario or accept this limitation unfortunately.
On the same note how would you extract country specific personal information when your starting entity is Job info.
I am able to see the value extracted in preview when i navigate through Job info >> Employment Details NAV >> Biographical info Nav>>personal infor Nav>>Country specific personal info nav>> custom string 6
But when I save this I get the same message "You have used one to many field navigation while adding this field. You have used default field filter with value <first> or not used any field filter." after I save the output is blank.
I tried adding different field filters but not sure what it is expecting...is this even possible?
I personally haven't had a use case for it as stuff that is perceived as country specific for personal info usually has a normal field in personal info or job info too (i.e. challenged status vs. the local stuff around it). Hence that way I basically never need to navigate for such stuff.
The navigation seems understandable until personal info nav.
In my instances it would be more like localNavBEL (i.e. for Belgium) or something similar, but maybe that's just phrasing.
There are 3 things I could think of to check:
- It could be that another route works better. Aside from the current route you could also for instance navigate over usernav instead (usernav --> empinfo --> personnav). If you do so I would definitely recommend checking the next point as well.
- Sometimes the API in a way misses some data as it sees the users as inactive.
You could try to filter the status field via Usernav with the operation 'is contained in' and then use values r,t (this refers to active and inactive). You are basically instructing the API with this to also include anything it somehow sees as inactive.
- In the Entity Tree View you could (when selecting the localized field of your preference) open the field filters part for personal info. In the dropdown below it, select last. It then takes the most recent data and that can sometimes be an issue.
Thank you for writing this blog. Really helpful.
I have one question. Is there a way to encrypt/mask a file before sending it through SFTP?
Rather late than never, but yes there is. In the Destinations tab, there's a section called advanced settings. On the right bottom corner, there's a section called advanced settings and there you could apply a PGP key. The actions to get a PGP key in the first place are detailed out quite well over here:
Thank you very much. This blog is really helpful.