Employees

Employees datasource specification

This page describes the file-based datasource specification for syncing Employees into TechWolf when no standardized connector (such as Workday or SAP SuccessFactors) is available. It covers the Employee baseline, the organisational structure, and every skill-relevant signal attached to an Employee: learning, work history, certifications, education, feedback, projects, tickets, performance, Skill notes, resumes, and merge requests. It defines the files TechWolf expects, the fields within each file, and which fields are required. Use this specification when a customer exports Employee data from any source system to flat files. The Employee Baseline file is required and establishes each Employee; every other file on this page references it through employee_id. Two files link out to other entities: the Employee Baseline points to a Job through assigned_position, and Learning History points to a Course through course_id. The Jobs and Courses specifications must be synced as well for those links to resolve. For the broader picture of how file-based integrations work and how they compare to API-based connectors, see Key concepts.

Technical data flow

Files are delivered to TechWolf over SFTP and land in an AWS S3 bucket, from where the file-based integration ingests them.

The customer (or their source system) exports the Employee files described below to a customer-hosted SFTP server.
TechWolf connects to that SFTP server, pulls the files, and writes them to the customer’s S3 bucket under the file-based ingest prefix.
The file-based integration reads the files from S3 and syncs the data into the TechWolf SkillEngine API.

To configure the SFTP server and the folder mappings TechWolf pulls from, see Self-service SFTP setup. For the S3 layout and naming conventions, see File Organization. Each file has a fixed location and naming pattern on S3. The base path is:

s3://techwolf-<customer>/production/external/input/integrations/file_based/

During the testing phase, the staging environment path is used instead: s3://techwolf-<customer>/staging/external/input/integrations/file_based/.

Reading the field tables

Each field is annotated in the Key column to indicate its role:

Primary key — the external ID of the file; uniquely identifies the entity.
Foreign key — references the primary key of another entity, linking the two.

Fields without a Key annotation are TechWolf data fields used for skill inference or context, not identifiers. Most files on this page use an external_id as their primary key. Share the identifier from the source system where one exists. Where it does not, leave the field empty and TechWolf generates an identifier for the record.

Employee Baseline

The baseline Employee file. Required. Establishes the existence of each Employee; every other file on this page references it. File on S3: .../file_based/TechWolf_Employee_Information/TechWolf_Employee_Information_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
employee_id	Required	Primary key	External ID of the file. ID of the Employee.
assigned_position	Required	Foreign key	The Employee’s current Job. Points to job_id in Job Information.
organisational_unit_id	Required	Foreign key	Points to organisational_unit_id in Organisational Information.
active	Optional

Organisational Information

The supervisory organisation structure. Highly recommended. File on S3: .../file_based/TechWolf_Supervisory_Organization/TechWolf_Supervisory_Organization_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
organisational_unit_id	Required	Primary key	External ID of the file.
organisational_unit_name	Required
organisational_unit_active	Optional
parent_organisational_unit_id	Required	Foreign key	Points to the organisational_unit_id of the parent unit.
parent_organisational_unit_name	Required

Learning History

Courses an Employee has completed. Highly recommended. File on S3: .../file_based/TechWolf_Learning_History/TechWolf_Learning_History_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
course_id	Required	Foreign key	Points to course_id in Course Information.
timestamp	Optional		Defaults to the current date if empty.

Internal Work History

The Employee’s history of internal Jobs. Highly recommended. Should include the current assigned position and its start date. File on S3: .../file_based/TechWolf_Internal_Work_History/TechWolf_Internal_Work_History_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
job_id	Required	Foreign key	Points to job_id in Job Information.
start_date	Required		Also used as the timestamp.
end_date	Required

External Work History

The Employee’s work experience outside the organisation. Highly recommended. File on S3: .../file_based/TechWolf_External_Work_History/TechWolf_External_Work_History_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
job_title	Required		Title and description cannot both be empty.
job_description	Required
company	Optional
start_date	Required
end_date	Required

Certification History

Certifications held by the Employee. Recommended. File on S3: .../file_based/TechWolf_Certification/TechWolf_Certification_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
certification_name	Required		Name and description cannot both be empty.
certificate_description	Required
timestamp	Optional

Education History

The Employee’s formal education. Recommended. File on S3: .../file_based/TechWolf_Education/TechWolf_Education_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
degree_name	Required		Name and description cannot both be empty.
degree_description	Required
start_date	Optional
end_date	Optional		Also used as the timestamp.

Feedback

Feedback given to the Employee. Recommended. File on S3: .../file_based/TechWolf_Feedback/TechWolf_Feedback_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
timestamp	Optional
source	Optional
description	Optional

Project Data

Projects the Employee has worked on. Recommended. File on S3: .../file_based/TechWolf_Project/TechWolf_Project_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
project_description	Required
timestamp	Optional

Ticket Data

Tickets the Employee has handled. Highly recommended. File on S3: .../file_based/TechWolf_Ticket/TechWolf_Ticket_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
ticket_title	Required
ticket_description	Required
ticket_system	Optional
ticket_status	Optional
ticket_type	Optional
timestamp	Optional

Performance Data

Performance records for the Employee. Recommended. File on S3: .../file_based/TechWolf_Performance/TechWolf_Performance_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
title	Required
description	Required
status	Optional		Only send entries perceived as relevant (e.g. “Completed”, “On Track”).
type	Optional
timestamp	Optional

Skill Notes

Free-text notes about an Employee’s Skills. Highly recommended (if available). File on S3: .../file_based/TechWolf_Skill_Notes/TechWolf_Skill_Notes_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
description	Required

Resume

The Employee’s resume document. Recommended. File on S3: .../file_based/TechWolf_Resume_Attachment/TechWolf_Resume_Attachment_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Points to employee_id in Employee Baseline.
mimeType	Required		Only application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, and text/plain are supported; other types are ignored.
base64Content	Required		The document encoded as a base64 string.

Merge Requests (Commit Messages)

Commit messages authored by the Employee. Recommended. Only commit messages linked to a merged merge request should be included. File on S3: .../file_based/TechWolf_Merge_Request/TechWolf_Merge_Request_[yyyy][MM][dd]_[HH][mm][ss].csv

TechWolf field	Required	Key	Notes
external_id	Recommended	Primary key	Share the ID from the source system if you have one. If it is not provided, TechWolf generates one.
employee_id	Required	Foreign key	Mapped to the Employee based on the author of the commit message.
merge_request_title	Required
merge_request_description	Required
commit_message	Required		Each row contains a single commit message.
status	Optional
timestamp	Optional

Integrations

Datasource Integrations

Employee Skill Assistant

TechWolf Analyst Agent

Entity Sync

Reporting

Webhooks

References

Employees datasource specification

Technical data flow

Reading the field tables

Employee Baseline

Organisational Information

Learning History

Internal Work History

External Work History

Certification History

Education History

Feedback

Project Data

Ticket Data

Performance Data

Skill Notes

Resume

Merge Requests (Commit Messages)

​Employees datasource specification

​Technical data flow

​Reading the field tables

​Employee Baseline

​Organisational Information

​Learning History

​Internal Work History

​External Work History

​Certification History

​Education History

​Feedback

​Project Data

​Ticket Data

​Performance Data

​Skill Notes

​Resume

​Merge Requests (Commit Messages)

Employees datasource specification

Technical data flow

Reading the field tables

Employee Baseline

Organisational Information

Learning History

Internal Work History

External Work History

Certification History

Education History

Feedback

Project Data

Ticket Data

Performance Data

Skill Notes

Resume

Merge Requests (Commit Messages)