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:
An outbound integration based on the above settings will be taken as an example in
the next steps. There was a shortcut to this after you have pressed “Create”, but the
example below assists better in showing what options you are actually taking. This
integration will scheduling a CSV file from SuccessFactors to an SFTP server with a
CSV format (and after selecting this you need to press the Create button).
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?
==> User
(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;
* Solution:
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.
– First Name
* Situation: You need to select the field that represents an employee’s first name at
birth;
* Challenge: The first name at birth can be different from the preferred first name
and isn’t always filled;
* Solution: Make a calculated column that chooses the first name at birth if available,
else the first name;
Note, When selecting birth name you may get a pop-up like: “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.” In this situation it is however fine as is (as
it takes the birthname that is applicable as of now).
* Result: The first name is always filled with the first name at birth, if available, and
otherwise with the preferred first name.
– 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
– Groups,
* 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.
– END
* 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).
8. Scheduling
After pressing next again, I would only have to fill out scheduling details. I’ve
indicated a weekly occurrence on weekdays and a relevant date in the near future
for this sample situation. It’s important to always select a date in the near future and
to press set schedule afterwards. If you update your integration and you do not
follow these steps, your integration may keep running based on a different version,
which does not allow the changes you have made to apply to the file that is sent out.
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.
Conclusion:
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.
