⚠️ Prerequisite: Accessing third-party integration reports requires the "View third-party integration reports" permission.
Good to know before continuing with this article:
- This documentation is intended only for accounts that have active integrations (flows).
- It covers only common/standard cases, covering the basics, and not specificities particular to your account.
- For any questions related to the Workelo API, please go here
📋 Table of contents
✨ Definition of a third-party tool integration
ℹ️ Understanding error messages
🙋 If you have questions: investigations to carry out
✨ Definition of a third-party tool integration (flow)
An integration is a technical interface that enables the exchange of data and information between Workelo and another application or external system.
- This can include APIs (application programming interfaces) or other communication protocols that allow Workelo to synchronize with other software to automate processes, share data in real time, and improve operational efficiency.
- It can also work via flat file exchanges over SFTP.
💡 An integration execution (called a "Run") corresponds to the automatic processing of data from your source system (HRIS, SFTP file, API…).
📑 Flow reports
If your permissions allow it, you will find the details of all flows from your "Analyses" tab > "Reports" page.
🆕 New: For compatible journey creation integrations, a new detailed tracking interface is available directly from the new "Integrations" tab (see next section).
🖥️ The different interfaces
Workelo offers two interfaces to monitor your integrations, depending on the flow type and your account configuration:
🔹 Classic interface: Integration reports ("Analyses" > "Reports")
- For all flow types: New hire journey creation, employee and/or organization directory updates, data sending and receiving, etc.
- For flows not yet covered by the new interface
- For a quick overview of historical flows
Features:
- View flow history
- Export data as a file
- Summary view of errors by flow
🔹 New interface: "Integrations" tab
- Only for journey creation integrations already migrated to this interface (the feature is being gradually rolled out)
- Accessible from: "Account" tab > "Integrations" > click on "Activity" in the relevant flow block
🙋 To find out whether one of your flows is covered by this new interface:
- A redirect banner is displayed from the old interface ("Analyses" > "Reports" > Open the corresponding report)
- The "Activity" button is present on the relevant flow block in the "Account" tab > "Integrations" (if the button is not present, the flow has not yet been migrated, and tracking will therefore be available on the old "Analyses" > "Reports" interface).
- If any doubt remains, contact support via the request form, or your account manager
Advanced features:
- Real-time tracking: view runs currently in progress
- Line-by-line detailed view: check the status of each processed employee
- Advanced filters: by period, status, last name/first name/email
-
5 possible line statuses:
- 🟢 Success: journey created successfully
- 🟡 Partial success: journey created but with warnings
- 🔴 Failure: journey not created due to a validation error
- ⚪ Filtered: line excluded according to the configured filtering rules (expected behavior)
- 🔵 Already created: journey already exists for this employee (no action taken)
ℹ️ Understanding error messages
Error messages can appear at two levels:
🏃 Run errors (global pipeline)
These errors stop the entire flow execution:
| Error type | Message | Cause | 🙋 Action |
|---|---|---|---|
| Configuration | Integration is not active |
The integration has been deactivated | Reactivate the integration in the settings |
| Configuration | Missing headers: {columns} |
Missing columns in the source file | Check that all required columns are present |
| Configuration | Error to define the extractor |
No API or SFTP configuration associated | Contact Workelo support via the request form |
| SFTP | Error during SFTP connection |
Unable to connect to the SFTP server | Check credentials and server availability |
| API | Error during {Source} extraction |
Failed to retrieve data from the third-party API | Check the availability of the source API |
🤸♀️ Line errors (individual level)
These errors affect only the processing of one employee:
Field errors
-
missing {field}— Required field empty or absent (e.g.:missing first_name,missing email,missing start_date) -
{stakeholder} not found— Stakeholder not found in Workelo (e.g.:hr not found,manager not found) -
value not found in the defined list— Value not allowed for this field -
email_does_not_contain_mapped_values— Email does not contain the allowed domains
Email errors
-
Invalid email— Incorrect email address format -
Domain name is not valid— The email domain does not exist or has no valid MX record
Date errors (journey creation)
-
Invalid date format— Unusable date format -
Start date is too old/Invalid date (too old)— Start date too old according to the configuration
Role errors (journey creation)
-
actor {stakeholder} is not yet arrived— An involved stakeholder (HR/Manager) is an employee whose start date has not yet passed
🙋 If you have questions: investigations to carry out before contacting support
👉 I cannot find an employee/new hire who should have appeared in the tool
Step 1: Check whether this person is present in the report associated with the flow
➡️ If yes:
- Check the error message associated with their line in the report
-
New interface: Check the line status (Failure / Partial success / Filtered / Already created)
- If Filtered (⚪): expected behavior, the person does not match the configured criteria
- If Already created (🔵): a journey already exists for this employee
- If Failure (🔴) or Partial success (🟡): read the error message in the "Message" column
➡️ If no:
- Exchange via API: Check that all upstream conditions are met (filters, selection rules)
- Exchange via SFTP: Check that the person is present in the sent file with all required information
👉 My report is empty
- Are there any expected entries today? If there is no data to process, the report is empty (expected behavior).
- Exchange via SFTP: Check that the file format matches what is expected. If the format is incorrect, the data cannot be imported.
- New interface: Check the Run status — a Run in "Failure" (🔴) with a comment will indicate the cause of the interruption.
👉 An existing employee has been created as a duplicate (or a new hire)
For Workelo, one email = one profile. If a person is pushed via a different email, they will appear as independent and will be created as a duplicate.
💡 Exception: In the case of certain employee directory update flow, matching can also be done via the technical ID. This type of specificity is indicated in the flow documentation provided by Workelo to the internal project manager.
👉 An employee's journey was created correctly, but something seems incorrect
(for example: wrong template applied, wrong HR stakeholder involved, wrong scope associated, etc.)
Contact your internal project manager so they can check directly via your integration documentation the criteria, codes and creation rules.
For example: if the employee's contract type is "permanent" and their nationality is French, then template "X" will be assigned.
If questions still remain, the project manager is the person in charge of contacting Workelo support, with as much information as possible: integration concerned, email of the new hire/employee, date (or date range) of the relevant flow, expected behavior, etc.