Objective
Create an automated process for keeping your employee data up to date based on your employee data. It will enable you to use all the data you have available in your HR or IT systems in Actimo as well as make sure your employees are created and deleted based on their journey within your company.
The integration will act as a data co-pilot that helps you focus on connecting with employees.
Requirements
You need to have the following requirements in place to be able to use the CSV integration.
Purchase integration options (if unsure reach out to our support)
Access to an sftp server or web server with Basic Authentication
Be able to dump a csv file with employee data in to the server
Admin Access in Actimo
We can have one CSV integration per client.
The file name must stay the same and not contain date or similar.
The file should contain all employees. Creates, deletes and updates are handled by us.
The first line should be a header line explaining the different columns.
There needs to be a Unique ID, that doesn’t change if the employee changes position, name, email or similar. Usually the primary id in the source system.
Names need to be separated in First Name and Last Name.
Country code can be part of the mobile number, or a separate column, but is needed to parse phone numbers correctly.
You can create employee relations using the Unique ID, typically a manager_id column with the Unique ID of the manager.
You can add validation to the different columns, based on type. If validation fails the employee is not transferred to Actimo and if previously transferred the employee will be deleted.
String: “Equal”, “Empty” and “Not Empty”
Number: “>”, “>=“, “<” and “<=”
Date: “Before Now or Empty” and “After Now or Empty”.
Case example
In this scenario we are gonna use a case to example how to setup the integration. Let's imagine that we are Retailer who wants to run an employee app for 500 employees in different regions, functions, departments. We also know that even though we will run a native app there is a wish for being able to send sms and emails. We are tasked to integrate and automatically handle employee data. We now have the following jobs:
Import relevant data, so our communications department can connect with the employees and use Smart groups and Feeds to differentiate employees from one another
Make sure people who stops working in the company are deleted
Make sure that new employees are automatically added
Addition: We have also been asked to try to see if we can connect direct manages to employees i Actimo via the integration
Steps to launch
Step 1: Which data is needed?
You need to talk to your teams and make sure you have the relevant data available for the goals you are trying to reach. In our case we will grab the following data:
first name
last name
employee id (or another unique identifier for an employee)
title
job function
store
region
country code
mobile phone number
email
manager employee id (columns that show the id of an employees manager)
Tip: Ask your HR / IT for an example of the CSV file that they is supposed to be inserted in to the sftp server, so you get an overview of which data you can choose from. You will need this file later on as well when you have to map the different columns to fields on contacts in Actimo.
You will also be able to see the column names when you test your integration first time with example data in Actimo.
Step 2: Lets setup Actimo to receive employee data
Once you have decided on which data you wish to shoot across you need to have the right fields ready to grab the data in Actimo. For this purpose we use Contact Fields.
Go to Admin top right corner --> Click Contacts
Actimo comes with default fields such as Country, Employee id, firs name etc. You need to identify if you have data that does not fit the the current setup. In our example we have created a new custom field for Store and Function. Once you click Save they will be ready to use.
Another important step to prepare your Actimo platform is to choose your Duplicate Key setup. This is the way you make sure you never get duplicated employees in your platform. It has to be 100% unique to the employee.
When using an integration you will need the dropdown to "Source Data".
Go to Admin top right corner --> Click Contacts --> scroll down to the bottom of the page
Tip: In some case you may not have an employee id, in this case you can use email. Please write support at [email protected] if you have any questions.
Step 3: Lets connect Actimo and your SFTP server
Before we can sync all the data we need to connect the two systems to each other.
Go to Admin top right corner --> Click Integration --> Click Add External CSV
You will need a bunch of information from your IT department or the person who set up the SFTP server on your side. The fields marked in red are required. See a fields explanation below.
Full URI Schema to CSV file: Either an sftp:// or https:// full path to the actual file. If the port is different than standard (sftp 22, https 443) then that need to be included.
Field separator: The type of delimiter used, typically either semi colon or comma , or ; - but can be another.
Encoding: typically either utf8 or latin1 - defaults to utf8
File is without a header row: In CSV you normally have a first line with column names defined. If there is no definition line in the file, then this checkbox must be ticked.
Credentials (username, password, passphrase, private key):
If protocol is https, then always username and password
If protocol is sftp, then it can be username and password, or username and private key, or username and private key and passphrase, or username and password and private key and passphrase.
Fill in the information for your setup --> Click Save at the bottom --> Click Test
You should now be able to see a green confirmation message telling you that you are connected and an example of your data from the CSV file.
Step 4: Map CSV data to contacts in Actimo
It is important that we make sure that the correct data is mapped to the correct fields on contacts in Actimo. This will enable you to group all employees in a specific store, region, function etc automatically using smart groups.
Go to Admin top right corner --> Click Integration --> Scroll down and click Ad Custom Field.
The goal here is to make sure that your employee data is inserted correctly in to contact fields in Actimo. This is done by creating a field for your column headers and then mapping it to the correct field in Actimo.
Click + Add Custom Field --> Write name same as header title in CSV --> Save --> Map to field in Actimo.
Then it is just a matter of making sure you map all the CSV columns in your CSV to a field in Actimo according to step 1 in this guide.
Finally you can select which workspace you wish your data to be inserted in to. We recommend importing in to your primary workspace and only running with one on your account unless you have a special need for more. Please reach out to our support if needed.
Click Save when finished mapping your data.
Step 5: Sync to Actimo
Once you are done with all the steps above it is only a matter of starting the integration.
Go to Admin top right corner --> Click Integration --> Click Sync Now
You should experience that all your employees will be inserted in to Contacts in Actimo. You will be able to see the data by clicking contacts. It should look something like this.
Supported ciphers sFTP can use are:
aes128-ctr,
aes192-ctr,
aes256-ctr,
aes128- [email protected],
Please write our support for IP whitelisting if necessary at [email protected] or have a talk with your integration specialist if one has been assigned your case.
Tags: custom, field, contacts, integration, SFTP, CSV, URI, Ciphers