# AI Integration Source: https://developers.techwolf.ai/reference/ai-integration Connect AI agents/applications to the TechWolf Developer Portal using MCP, llms.txt, or llms-full.txt. AI applications can access the TechWolf Developer Portal documentation programmatically, enabling AI agents to answer questions about the Skill Engine API, generate integration code, and even execute API calls on behalf of users. There are three ways to connect AI applications to our documentation, each suited for different use cases. ## MCP Server The Model Context Protocol (MCP) server allows AI applications to search and query the TechWolf Developer Portal in real-time. This is the recommended approach for interactive AI workflows. **URL:** `https://developers.techwolf.ai/mcp` ### Setup Add the following to your MCP client configuration (Claude Code, Cursor, Windsurf, etc.): ```json theme={null} { "mcpServers": { "techwolf": { "type": "http", "url": "https://developers.techwolf.ai/mcp" } } } ``` ### Available tools | Tool | Description | | - | - | | `SearchTechWolfDeveloperPortal` | Search across the knowledge base for documentation, code examples, API references, and guides. | ### When to use * Building AI-powered integrations that need to look up API documentation on-the-fly. * AI coding assistants (Cursor, Windsurf, Claude Code) that need context about the Skill Engine API while writing integration code. ## llms-full.txt A single file containing the full content of the TechWolf Developer Portal. Load this into an AI application's context window for comprehensive, one-shot access to all documentation. **URL:** `https://developers.techwolf.ai/llms-full.txt` ### When to use * You need the AI to have complete knowledge of the documentation upfront. * Your AI tool does not support MCP. > [!NOTE] > > This file is very large. Ensure your AI application's context window can > accommodate it or use subagents. ## llms.txt An AI-friendly sitemap that lists all documentation pages with their URLs. This helps AI systems discover and index the TechWolf Developer Portal content. **URL:** `https://developers.techwolf.ai/llms.txt` ### When to use * AI crawlers or indexing systems that need to discover available documentation. * You want the AI to selectively fetch only the pages relevant to a specific question, rather than loading everything at once. * Lighter alternative when full context loading is not practical. # Authentication Source: https://developers.techwolf.ai/reference/latest/API Documentation/Authentication/Authentication The Skill Engine API uses OAuth 2.0 for authentication with support for two methods: **Client Credentials Flow** and **Private Key JWT Authentication**. ## Getting Started Contact your TechWolf representative to obtain your credentials: * `client_id` - Your unique client identifier * `audience` - The API audience * `tenant` - Your organization's tenant identifier * Method-specific credentials (client secret or private key) **Token Endpoints:** * **EU tenants**: `https://techwolf.eu.auth0.com/oauth/token` * **US tenants**: `https://techwolf-us.us.auth0.com/oauth/token` **Audience:** * **EU tenants**: `eu3.techwolf.ai` * **US tenants**: `us3.techwolf.ai` > [!WARNING] > > **Cache your tokens!** Tokens expire and requesting new ones adds latency. Always reuse tokens until they expire. ### Client Credentials Flow Simple server-to-server authentication using a shared secret. Contact your TechWolf representative to obtain your credentials. **What TechWolf provides to you:** * The `client_id` and `client_secret` #### Step 1: Request a token **Basic Request:** ```bash theme={null} curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "", "client_secret": "", "audience": "eu3.techwolf.ai", "grant_type": "client_credentials", "tenant": "" }' ``` **With Scopes:** ```bash theme={null} curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "", "client_secret": "", "audience": "eu3.techwolf.ai", "grant_type": "client_credentials", "tenant": "", "scopes": ["read", "write"] }' ``` ### Private Key JWT Authentication Enhanced security using asymmetric cryptography - no shared secrets to store. **What you need to provide to TechWolf:** * The public key associated with your private key **What TechWolf provides to you:** * The `client_id` #### Step 1: Create JWT Assertion Sign a JWT with your private key containing these claims: ```json theme={null} { "iss": "your_client_id", "sub": "your_client_id", "aud": "https://techwolf.eu.auth0.com/oauth/token", "exp": 1640995200, "iat": 1640994900, "jti": "unique-jwt-id-12345" } ``` **Requirements:** * Sign with RS256 algorithm * Set `exp` 5-10 minutes in the future * Use unique `jti` for each request * Include current timestamp in `iat` #### Step 2: Exchange JWT for Token **Basic Request:** ```bash theme={null} curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \ -H 'Content-Type: application/json' \ -d '{ "grant_type": "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" "client_assertion": "", "audience": "eu3.techwolf.ai", "tenant": "" }' ``` The `assertion` field is the JWT you just created and signed with your private key. **With Scopes:** ```bash theme={null} curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \ -H 'Content-Type: application/json' \ -d '{ "grant_type": "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" "client_assertion": "", "audience": "eu3.techwolf.ai", "tenant": "", "scopes": ["read", "write"] }' ``` ## Token Response Both methods return a JSON object with the following fields: ```json theme={null} { "access_token": "eyJhbGciOiJSUzI0I0seiEw...", "expires_in": 10800, "scope": "read write", "token_type": "Bearer" } ``` ## Scopes | Scope | Access | | - | - | | `read` | Read API resources | | `write` | Write API resources | | `read_reports` | Read access to reports (only aggregated info) | *Default: All available scopes for your credentials* ## Using Your Token Add to the `Authorization` header of all API calls: ```bash theme={null} curl -X GET '[server-url]/your-endpoint' \ -H 'Authorization: Bearer ' ``` **Test your token:** ```bash theme={null} curl -X GET '[server-url]/version' \ -H 'Authorization: Bearer ' ``` ## Additional Resources * [OAuth 2.0 Client Credentials](https://auth0.com/docs/api/authentication#client-credentials-flow) * [JWT Bearer Token Spec](https://tools.ietf.org/html/rfc7523) # Introduction Source: https://developers.techwolf.ai/reference/latest/API Documentation/Introduction/Introduction The TechWolf API is organized around REST. It accepts and returns JSON-encoded data, and uses HTTP response codes, authentication, and verbs. It provides access to entity and skill data, and utility endpoints to provide additional insights. To make use of the API, requests need to be authenticated; see the [Authentication](../Authentication/Authentication) section for more information. # Breaking Changes Source: https://developers.techwolf.ai/reference/latest/API Versioning/Breaking Changes/Breaking Changes The list below provides an overview of breaking changes to the SkillEngine API. Breaking changes are modifications that may cause your existing integrations to stop working. These changes are only applied to your tenant when you request a version update. ### October 2026 * Removed the `GET /employees/{employee_external_id}/task_profile` endpoint from the public API. * Removed the `PATCH /employees/{employee_external_id}/task_profile` endpoint. ### September 2026 * Removed the `POST /reports/skill_inventory` endpoint. * `ticket`, `merge_request` and business record Skill Events (`it_incident`, `support_ticket`, … — see `GET /skill_event_types`) are no longer accepted on the `POST /employees/{employee_external_id}/skill_events` endpoint on tenants with a model configuration older than `MC_2025_Q1_V1`. Such requests are rejected with a `422 Unprocessable Entity` response stating that the model configuration of the tenant is outdated. To keep using these Skill Event types, contact TechWolf to upgrade your tenant to the latest model configuration. ### August 2026 * Removed the `include=relevant_experience` query/body parameter and the `relevant_experience` response field from the `POST /employees/{external_id}/matching_vacancies`, `POST /vacancies/{external_id}/matching_employees`, and `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` endpoints. ### July 2026 * Removed the deprecated `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` endpoint; use the `POST` variant on the same path instead. * Removed the `POST /reports/job_architecture_benchmark` endpoint. ### March 2026 * The `proficiency_level`, `proficiency_float`, and `critical` response fields have been replaced with `governed_proficiency_level`, `inferred_proficiency_level`, `governed_proficiency_float`, `inferred_proficiency_float`, `governed_critical`, and `inferred_critical` on the following endpoints: * `GET /job_architecture/jobs/{job_external_id}/skill_profile` * `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` * `POST /job_architecture/export/jobs/skill_profiles` * `POST /job_architecture/export/job_families/skill_profiles` * The `validation_state` field is now always returned on each Skill in the Skill Profile response for the above endpoints. The `include=skill_validation_state` query/body parameter has been removed. * Suggested Skills (with `validation_state: "suggested"`) are now included alongside governed Skills in the Skill Profile response for the above endpoints. ### December 2025 * Changed the `GET /reports/data_maturity_scan/employee_quality_matrix` endpoint to `POST` and added optional `filters` request body to filter by Employee external IDs. * Changed the `GET /reports/data_maturity_scan/job_quality_matrix` endpoint to `POST` and added optional `filters` request body to filter by Job external IDs. ### September 2025 * Removed `translation_found` field from the `GET /employees/suggestions/skills` endpoint. * Removed skill names from unsupported languages from the output of the `GET /employees/suggestions/skills` endpoint. ### August 2025 * Deprecated the `domains` response format from the `GET /courses/{course_external_id}/skill_profile` and the `GET /vacancies/{vacancy_external_id}/skill_profile` endpoints. ### March 2025 * Removed the `skill_vocab` and `external_id` fields from the `GET /taxonomy/skills` endpoint * Removed the `skill_vocab` and `external_id` fields from the `GET /taxonomy/skills/{skill_id}` endpoint * Removed the `skill_vocab` and `external_id` fields from the `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills` endpoint * Removed the `skill_vocab` and `external_id` fields from the `GET /taxonomy/export` endpoint ### February 2025 * Removed the `POST /integrations/file_load_task` endpoint. * Removed the `GET /integrations/file_load_task/{task_id}` endpoint. * Removed the `/job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint. ### January 2025 * Removed the `response_format=trending` query paramter option for all `GET //skill_profile` endpoints. ### December 2024 * Removed the `GET /employees/{external_id}/metrics/position_alignment` endpoint. ### November 2024 * Removed the `POST /vacancies/{external_id}/metrics/fillability` endpoint. * Renamed the value of query parameter `include=description` to `include=skill_description` in the `GET /taxonomy/skills` endpoint. ### October 2024 * Changed the format for duplicate data examples from the `GET /reports/data_maturity_scan/data_improvement_actions` endpoint. * Removed the `POST /reports/skills_alignment` endpoint. * Removed the `POST /reports/workforce_alignment` endpoint. * Removed the `POST /reports/strategy_map` endpoint. * Removed the `POST /reports/skill_frequencies` endpoint. * Removed the `POST /reports/organization_names` endpoint. * Removed the `POST /reports/employee_skill_distribution` endpoint. * Removed the `POST /reports/vacancy_skill_distribution` endpoint. ### September 2024 * Renamed the field `name` to `skill_name` in the `GET /employees/{external_id}/skill_profile` endpoint when the `response_format` query parameter is set to `skill_clusters` or `domains`. ### August 2024 * Removed the `GET /reports/succession_risk` endpoint. * Removed the `GET /reports/employees/skills` endpoint. * Removed the `GET /reports/employees/position_alignment` endpoint. * Removed the `POST /reports/replacement_risk` endpoint. * Removed `count` response body field from the `POST /employees/search` endpoint. * Removed `count` response body field from the `POST /vacancies/search` endpoint. * Removed `count` response body field from the `POST /companies/search` endpoint. * Removed `count` response body field from the `POST /employees/{external_id}/recommended_courses` endpoint. * Removed `count` response body field from the `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` endpoint. * Removed `count` response body field from the `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses` endpoint. * Removed `count` response body field from the `POST /employees/{external_id}/matching_vacancies` endpoint. * Removed `count` response body field from the `POST /employees/{external_id}/matching_companies` endpoint. * Removed `count` response body field from the `POST /employees/{external_id}/matching_jobs` endpoint. * Removed `count` response body field from the `POST /employees/{external_id}/matching_job_families` endpoint. * Removed `count` response body field from the `POST /vacancies/{external_id}/matching_employees` endpoint. * Removed `count` response body field from the `POST /companies/{external_id}/matching_employees` endpoint. * Removed `count` response body field from the `POST /job_architecture/jobs/{external_id}/matching_employees` endpoint. * Removed `count` response body field from the `POST /job_architecture/job_families/{external_id}/matching_employees` endpoint. ### July 2024 * Removed the `GET /reports/employees/employability` endpoint. * Removed the `GET /employees/{external_id}/metrics/employability` endpoint. * Removed the `GET /vacancies/{external_id}/metrics/fillability` endpoint. ### June 2024 * Removed support for the `language` filter in the `POST /companies/{external_id}/matching_employees` endpoint. * Removed `feedback_format=skill_clusters` support for the `PATCH /vacancies/{external_id}/skill_profile` endpoint. * Removed `feedback_format=skill_clusters` support for the `PATCH /courses/{external_id}/skill_profile` endpoint. * Removed `response_format=skill_clusters` support for the `GET /vacancies/{external_id}/skill_profile` endpoint. * Removed `response_format=skill_clusters` support for the `GET /courses/{external_id}/skill_profile` endpoint. * Removed the `POST /reports/clustered_trending_skills` endpoint. * Removed the `POST /reports/emerging_skills` endpoint. * Removed the `POST /employees/{external_id}/similar` endpoint. * Removed the `POST /vacancies/{external_id}/similar` endpoint. * Removed the `POST /courses/{external_id}/similar` endpoint. * Removed Occupation entity and its functionalities, along with the Reskilling & Deployment report ### May 2024 * Removed the `include=skill_match_scores` query parameter of `POST /employees/{external_id}/matching_job_families` * Replaced the `skill_type` field with `skill_types` for the `skills` response body field of the `GET /job_architecture/job/{job_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_id}/skill_profile` endpoints. * Replaced the `skill_type` field with `skill_types` for the `skills` field of the `records` response body field of the `POST /job_architecture/export/jobs/skill_profiles`, and `POST /job_architecture/export/job_families/skill_profiles` endpoints. * Replaced the `skill_type` field with `skill_types` for the `skills` field of `skill_clusters` field of the `records` response body field of the `POST /job_architecture/export/jobs/skill_clusters`. ### February 2024 * Removed the `include=skill_clusters` query parameter of `POST /vacancies/{external_id}/matching_employees` and `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`. * Moved the `relevant_experience` response body field of the `response_format=explained` query parameter to the newly added `include=relevant_experience` query parameter of the `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` endpoint. * Renamed the `skill` response body field to `skill_name` of the `GET employees/{external_id}/vacancies/{external_id}/gap` endpoint. ### January 2024 * The `GET /job_architecture/job/{job_id}/skill_profile` endpoint has a new Skill type called `Family-Specific`. * The `GET /job_architecture/job_families/{job_family_id}/skill_profile` endpoint has a new Skill type called `Family-Specific`. ### December 2023 * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /employees/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /vacancies/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /courses/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /occupations/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /vacancies/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /courses/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. * The `skills` request body field of the `SkillProfileUpdateMessage` of the endpoint `PATCH /occupations/{external_id}/skill_profile` now requires either a `skill` or a `skill_id`, not both. ### November 2023 * Removed the deprecated `GET /employees/{external_id}/profile/related` endpoint. * Removed the deprecated `POST /employees/{external_id}/profile/related` endpoint. * Removed the deprecated `GET /vacancies/{external_id}/profile/related` endpoint. * Removed the deprecated `POST /vacancies/{external_id}/profile/related` endpoint. * Removed the deprecated `GET /courses/{external_id}/profile/related` endpoint. * Removed the deprecated `POST /courses/{external_id}/profile/related` endpoint. * Removed the deprecated `GET /occupations/{external_id}/profile/related` endpoint. * Removed the deprecated `POST /occupations/{external_id}/profile/related` endpoint. * Removed the deprecated `GET /skills/{skill_name}/related` endpoint. ### October 2023 * Remove `POST /skill_clusters` in favor of `POST /taxonomy/skill_clusters`. * Remove `DELETE /skill_clusters/{skill_cluster_id}` in favor of `DELETE /taxonomy/skill_clusters/{skill_cluster_id}`. * Remove `PATCH /skill_clusters/{skill_cluster_id}` in favor of `PATCH /taxonomy/skill_clusters/{skill_cluster_id}`. ### June 2023 * Removed the deprecated `PUT {entity}/{external_id}/skill_profile` endpoint. ### April 2023 * A `skill_event` with `project_content` now assumes a textual description of a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.). The previous functionality of general project descriptions is removed. ### February 2023 * The `desired_functions` and `non_desired_functions` fields of the Employee have been changed from lists of titles to list of Function objects. A Function object consists of a Function title and a relative importance. ### January 2023 * All instances of `competency`, `competencies` or capitalized alternatives have been renamed to `skill_cluster` and `skill_clusters`, and their capitalized versions. * All instances of `category`, `categories` or capitalized alternatives have been renamed to `domain` and `domains`, and their capitalized versions. ### October 2022 * The `competency` and `score` fields in `PUT, PATCH /{entity}/{external_id}/skill_profile` in `competencies` format are now renamed to `competency_name` and `proficiency_level` respectively. * The `score` fields in `PUT, PATCH /{entity}/{external_id}/skill_profile` in `skills` format is replaced by `has_skill` which is a boolean instead of number. * The `competency` and `score` fields in `GET /{entity}/{external_id}/skill_profile` in `competencies` format are now renamed to `competency_name` and `proficiency_level` respectively. ### July 2022 * The `score` field in `GET /{entity}/{external_id}/skill_profile` in `list` format is now optional. ### June 2022 * Deprecated `GET /employees/{external_id}/recommended_courses` and added POST instead. * Removed `POST /competencies/{external_id}/similar` and `POST /competencies/{external_id}/profile/related` endpoints. ### May 2022 * Removed `PUT /competencies/{external_id}/skill_profile` feedback endpoint. ### November 2021 * Removed Document Entity and all its functionalities. ### July 2021 * Similar Entity endpoints are now `POST` instead of `GET`. * The response format of Similar Entity endpoints has changed from a list to an object containing two fields: the list of results and the total number of results available. ### June 2021 * Search endpoints now require weights in the body, in the same manner as matching endpoints. * Search endpoints now support a `score_min_threshold` query parameter, and defaults to 0.5 for this value instead of the previously internal 0.0. ### April 2021 * The language query parameter has become required for the creation and update of an entity. ### March 2021 * The response format of matching results (`GET/POST /employees/{external_id}/matching_vacancies` , `GET/POST /vacancies/{external_id}/matching_employees` , `GET /employees/{external_id}/matching_companies` and `GET /companies/{external_id}/matching_employees`) has changed from a list to an object containing two fields: the list of results and the total number of results available. * The response format of search results (`POST /employees/search` , `POST /vacancies/search` and `POST /companies/search`) has changed from a list to an object containing two fields: the list of search results and the total number of results available from the free text search. * The response format of list results (`GET /employees/`, `GET /vacancies/` , `GET /companies/`, `GET /courses/`, `GET /competencies/`, `GET /documents/` and `GET /occupations/`) has changed from a list to an object containing two fields: the list of results and the total number of results available. ### February 2021 * Employee creation (`POST /employees`) and updates (`PATCH /employees/{external_id}`) no longer support uploading individual resumes (as `employee_resume`) in favour of accepting a list of multiple resumes (as `employee_documents`) with the same format. * The list entity endpoints (`GET /employees`, `GET /vacancies`, `GET /courses` , `GET /occupations`, `GET /competencies` and `GET /documents`) no longer support the `response_format` query parameter. The response now corresponds to the former `objects` response format for all endpoints. ### January 2021 * The version endpoint now returns a body with a single field `version`, indicating the current version of your tenant. The version is returned as a date (ISO-8601, ex. 2021-01-19) and no longer as a number. # Compatible Changes Source: https://developers.techwolf.ai/reference/latest/API Versioning/Compatible Changes/Compatible Changes The list below gives a sorted overview of non-breaking changes to the SkillEngine API. These changes are immediately available to you and will be supported by your API, regardless of your version. ### October 2026 * Added the `GET /skill_event_types` endpoint that lists the Skill Event types your tenant can send and the content fields each one takes. * Added 25 Skill Event types for business records (`it_incident`, `support_ticket`, `technical_spec`, …) to `POST /employees/{employee_external_id}/skill_events`, enabled per tenant on request. ### August 2026 * Added `custom_properties` as an `include` value on `POST /export/employees/skill_profiles` and `POST /export/skills` that returns, per Skill, the custom properties set on it as a mapping of property name to value. * Raised the maximum length of `ticket_description` on `ticket` Skill Events from 10 000 to 50 000 characters. * Raised the maximum length of `description` on `merge_request` Skill Events from 5 000 to 250 000 characters, and of `commits[].message` from 500 to 100 000 characters. * Added the `skill_description` field to the `vocab_update_add_skill` operation of `GET /taxonomy/changes` and `POST /taxonomy/changes`. * Added the `vocab_update_description` operation type to `GET /taxonomy/changes` and `POST /taxonomy/changes`, emitted when a Skill's description changes between vocabulary versions. ### July 2026 * Added `output_language` as an `include` value on `POST /export/skills` that returns, per Skill, the language its information was resolved from, so fallback resolutions can be told apart from genuine translations. * Added `linked_jobs` as an `include` value on `POST /export/tasks` that expands each Task with the Jobs it is assigned to. * Added the `external_vendor` query parameter to `POST /export/tasks` for the `linked_jobs` include. * Added the `canonical_task_id_is_in_list` filter to `POST /export/tasks`. ### June 2026 * Added a top-level `unrecognized_skill_ids` array field to the `400 Bad Request` response of `PATCH /employees/{external_id}/skill_profile` when `feedback_format` is `external_vendor_skills` and one or more submitted Skill IDs are not recognised. All unrecognized IDs are returned in a single response so they can be removed and the request retried in one round trip. The field is purely additive; the `skills` feedback format response is unchanged. * Added the `domain_id`, `subdomain_id`, `cluster_id`, and `canonical_task_id` fields to the task `hierarchy` block, giving each task-hierarchy level a stable id alongside its name. The ids are returned (nullable) wherever the hierarchy appears: `GET /tasks/{task_id}`, `GET /tasks/search`, the Employee and Job Task Profile endpoints (both `list` and `hierarchy` response formats), and the task exports (`POST /export/tasks`, `POST /export/employees/task_profiles`, and `POST /job_architecture/export/jobs/task_profiles`). * Added the `response_format` query parameter to the Job Family task-based matching endpoints (`POST /job_architecture/job_families/{job_family_external_id}/matching_job_families_by_tasks` and `GET /job_architecture/job_families/{job_family_external_id}/job_families/{other_job_family_external_id}/task_match`). * Added the `match_type` field to each entry in the `similar_tasks` array of the `POST /tasks/validate` response, indicating how the similar Task was found. * Added `skill_source` as an `include` value on `GET /job_architecture/jobs/{job_external_id}/skill_profile`, `GET /employees/{external_id}/skill_profile`, `POST /job_architecture/export/jobs/skill_profiles`, and `POST /export/employees/skill_profiles`. When requested, each Skill in the response gains a `skill_source` field indicating whether the Skill is a custom Skill or originates from the TechWolf vocabulary. * Added the `GET /tasks/{task_id}` endpoint that fetches a single Task by id. * Added the `DELETE /tasks/{task_id}` endpoint that deletes a custom Task. * Added the `POST /tasks` endpoint that creates a custom Task. * Added the optional `source` body parameter to `POST /tasks` that records free-text attribution for a custom Task. * Added the `POST /tasks/validate` endpoint that screens candidate Task names for quality and uniqueness. * Added `task_source` and `enrichment_status` as `include[]` values on `GET /tasks/search` and `POST /export/tasks`, plus `ai_impact` and `hierarchy` on `GET /tasks/search`. * Added the `response_format` query parameter to the task-based matching endpoints (`POST /job_architecture/jobs/{job_external_id}/matching_jobs_by_tasks`, `GET /job_architecture/jobs/{job_external_id}/jobs/{other_job_external_id}/task_match`, and `POST /tasks/matching`). ### May 2026 * Added a new `POST /tasks/matching` endpoint that returns the symmetric task-based match score between two caller-supplied task sets. * Added a new `POST /job_architecture/jobs/{job_external_id}/matching_jobs_by_tasks` endpoint that returns the Jobs whose task profiles best match the given Job, ranked by task-match score. * Added a new `GET /job_architecture/jobs/{job_external_id}/jobs/{other_job_external_id}/task_match` endpoint that returns the symmetric task-based match score between two Jobs. * Added a new `POST /job_architecture/job_families/{job_family_external_id}/matching_job_families_by_tasks` endpoint that returns the Job Families whose task profiles best match the given Job Family, ranked by task-match score. * Added a new `GET /job_architecture/job_families/{job_family_external_id}/job_families/{other_job_family_external_id}/task_match` endpoint that returns the symmetric task-based match score between two Job Families. * Added the `normalized` query parameter to `POST /skills/lookup`. When set to `true`, the endpoint matches Skill names case-insensitively and diacritic-insensitively (Latin diacritics only), so inputs like `Café`, `café`, and `cafe` all resolve to the same Skill. Defaults to `false` (exact match). * Added the `query` field to every entry in the response of `POST /skills/lookup`. It echoes the Skill name as provided in the request body. When `normalized=false`, `query` always equals `skill_name`. When `normalized=true` and the Skill is matched, `query` may differ from `skill_name` in casing or Latin diacritics. On a miss, `skill_name` falls back to the input value, so the field is always non-null. ### April 2026 * Added a new `GET /taxonomy/skills/languages` endpoint that returns the list of language codes available for Skills in the tenant's vocabulary. An optional `external_vendor` query parameter can be provided to retrieve languages for a specific vendor vocabulary. * Extended the `vocab_language` query parameter to support 12 additional language codes **when scoped to the `workday` vendor** (via `external_vendor=workday`): `es` (Spanish), `fr_ca` (French Canadian), `it` (Italian), `ja` (Japanese), `ko` (Korean), `pt_br` (Brazilian Portuguese), `zh_cn` (Simplified Chinese), `zh_tw` (Traditional Chinese), `sv` (Swedish), `fi` (Finnish), `da` (Danish), and `no` (Norwegian). The default TechWolf vocabulary continues to support only `en`, `en_uk`, `en_us`, `de`, `fr`, and `nl`. Use the new `GET /taxonomy/skills/languages` endpoint to discover the exact set of languages available for a given vendor in your tenant. Additionally, IETF BCP 47 language tags (e.g. `fr-FR`, `zh-CN`, `nb-NO`) are now accepted and mapped to their internal equivalents. This applies to all endpoints that accept the `vocab_language` parameter. ### March 2026 * Added the `low_data_availability` filter to matching endpoints. When `exclude_low_data_availability` is set to `true`, entities with insufficient data for qualitative Skill inference are excluded from matching results. This filter is available on the following endpoints: * `POST /employees/{external_id}/matching_vacancies` * `POST /employees/{external_id}/matching_jobs` * `POST /vacancies/{external_id}/matching_employees` * `POST /job_architecture/jobs/{job_external_id}/matching_employees` * `POST /job_architecture/jobs/{job_external_id}/matching_source_jobs` * `POST /job_architecture/jobs/{job_external_id}/matching_target_jobs` * `POST /job_architecture/job_families/{job_family_external_id}/matching_employees` * `POST /companies/{external_id}/matching_employees` * `POST /employees/{external_id}/metrics/employability` * `POST /export/employees/matching_vacancies` * `POST /export/employees/matching_jobs` * `POST /export/vacancies/matching_employees` * `POST /job_architecture/export/jobs/matching_employees` * Added the `active_only` query parameter to `GET /reports/data_maturity_scan/data_improvement_actions`. When set to `true`, only active Employees and Jobs are included in the Data Improvement Actions. * Added the `category` query parameter to `POST /job_architecture/export/suggestions` and `POST /job_architecture/suggestions/interactions`. Set `category=tasks` to export or interact with task suggestions instead of the default skill suggestions. * Added the `429 Too Many Requests` response to all API endpoints. The API now returns this status code when rate limits are exceeded. * Added a new **Working History Dates** action generator to the Data Improvement Actions report (`GET /reports/data_maturity_scan/data_improvement_actions`). It identifies Working History Skill Events where a duration cannot be calculated due to missing `start_date`, missing `end_date`, or identical start and end dates. Examples are grouped by Employee. * The `include=proficiency_level` parameter on Job and Job Family Skill Profile endpoints now returns `governed_proficiency_level` and `inferred_proficiency_level` fields (instead of `proficiency_level`). Similarly, `include=proficiency_float` returns `governed_proficiency_float` and `inferred_proficiency_float`, and `include=critical` returns `governed_critical` and `inferred_critical`. This applies to the following endpoints: * `GET /job_architecture/jobs/{job_external_id}/skill_profile` * `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` * `POST /job_architecture/export/jobs/skill_profiles` * `POST /job_architecture/export/job_families/skill_profiles` * The `validation_state` field is now always included on each Skill in the response of the above endpoints. The `include=skill_validation_state` parameter is no longer needed. * Suggested Skills (with `validation_state: "suggested"`) are now returned alongside governed Skills in the Skill Profile response for the above endpoints. * Added the `strict` query parameter to `POST /employees/{employee_external_id}/skill_events`. When `strict` is enabled, Skill Event creation will fail if the referenced Job has an empty Skill Profile. * Added the `end_active_jobs` query parameter to `POST /employees/{employee_external_id}/skill_events`. When enabled, any currently active working history Skill Event (without an `end_date`) for the Employee will be ended automatically when the new Skill Event is created. ### February 2026 * Added the `include=business_relevant` query parameter to the `POST /export/skills` endpoint to include whether a Skill is marked as business relevant. * Added the `output_skills_sorting` query parameter to `GET /employees/{external_id}/skill_profile` to sort Skills alphabetically or by decreasing confidence. * The `output_skills_sorting` body parameter on `POST /export/employees/skill_profiles` now also works when an external vendor is specified. * Added the `vocab_language` query parameter to the following matching endpoints to specify the display language for Skill names in the response: * `POST /employees/{external_id}/matching_vacancies` * `POST /employees/{external_id}/matching_jobs` * `POST /employees/{external_id}/matching_job_families` * `GET /employees/{employee_external_id}/match_assigned_position` * `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` * `GET /employees/{employee_external_id}/jobs/{job_external_id}/match` * `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match` * `POST /vacancies/{external_id}/matching_employees` * `POST /job_architecture/jobs/{job_external_id}/matching_employees` * `GET /job_architecture/jobs/{job_external_id}/market_alignment` * `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles` * `POST /job_architecture/jobs/{job_external_id}/matching_source_jobs` * `POST /job_architecture/jobs/{job_external_id}/matching_target_jobs` * `POST /job_architecture/job_families/{job_family_external_id}/matching_employees` * `POST /export/employees/match_assigned_position` * `POST /export/vacancies/matching_employees` * `POST /export/employees/matching_vacancies` * `POST /export/employees/matching_jobs` * `POST /job_architecture/export/jobs/matching_employees` * `POST /job_architecture/export/jobs/market_alignment` * `POST /job_architecture/export/job_families/suggested_skill_profiles` * `POST /job_architecture/export/suggestions` * `POST /employees/{employee_external_id}/recommended_courses` * `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` * `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` * `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses` * `POST /skills/lookup` * `POST /export/employees/skill_profiles` * `POST /job_architecture/export/jobs/suggested_skill_profiles` * `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/gap` * Added the **Work Intelligence Task Profile** endpoints (experimental): * `GET /tasks/search` - Search for Tasks using a fuzzy text query with AI impact information * `GET /employees/{employee_external_id}/task_profile` - Retrieve an Employee's Task Profile with optional AI impact and source event information * `GET /job_architecture/jobs/{job_external_id}/task_profile` - Retrieve a Job's Task Profile with optional AI impact and source data information * `POST /export/employees/task_profiles` - Export Task Profiles for all Employees with pagination and filters * `POST /job_architecture/export/jobs/task_profiles` - Export Task Profiles for all Jobs with pagination and filters * `PATCH /employees/{employee_external_id}/task_profile` - Provide feedback on tasks in an Employee's Task Profile, setting each task's `validation_state` to `validated` or `rejected` * `PATCH /job_architecture/jobs/{job_external_id}/task_profile` - Provide feedback on tasks in a Job's Task Profile, setting each task's `validation_state` to `validated` or `rejected` * `POST /export/tasks` - Bulk export of Tasks. * Added the `inferred_proficiency_level` field to the return of the `POST /employees/suggestions/skills` endpoint when `include=proficiency` is set as a query parameter * Added the `include=inference_enabled` query parameter to indicate whether the Skill can be inferred, applicable to the following endpoints: * `GET /taxonomy/skills` * `GET /taxonomy/skills/{skill_id}` * `GET /taxonomy/export` * `POST /export/skills` ### January 2026 * Added the `vocab_language` query parameter to the following endpoints to specify the display language for Skill names in the response: * `POST /job_architecture/jobs/metrics/adoption_metrics` * `POST /job_architecture/export/job_families/skill_profiles` * `POST /job_architecture/export/jobs/skill_profiles` * `POST /job_architecture/export/jobs/market_skill_profiles` * `POST /employees/metrics/adoption_metrics` * Added the `merge_request` Skill Event type for Employees. When creating or updating Skill Events via `POST /employees/{employee_external_id}/skill_events` or `PATCH /employees/{employee_external_id}/skill_events/{skill_event_external_id}`, the `event_type` can now be `merge_request` with content containing `title`, `description`, and `commits` (list of objects with `message`). Merge request events are processed asynchronously to infer skills from the title, description, and commit messages. * Changed the `POST /taxonomy/skills` endpoint to require write\_skills scope access. * Added the `DELETE /taxonomy/skills/{skill_id}` endpoint which allows for deleting custom Skills from the system. This endpoint requires write\_skills scope access. * Added the `vocab_language` query parameter to the `PATCH /taxonomy/skills/{skill_id}` endpoint to support updating descriptions and names of Skills in different languages. * Added the `skill_source` to the output of the following endpoints: * `GET /taxonomy/skills/{skill_id}` * `GET /taxonomy/skills` * `GET /taxonomy/export` * `POST /export/skills` * Added the `default_skill_name` and `default_skill_description` to the output of the following endpoints: * `GET /taxonomy/skills/{skill_id}` * `GET /taxonomy/skills` * `GET /taxonomy/export` * Added the `include=default_skill_name` and `include=default_skill_description` to the `POST /export/skills` endpoint to add the `default_skill_name` and `default_skill_description` to the output. * Added the `filters` body parameter with the `skill_id_is_in_list` and `skill_source` filters to the `POST /export/skills` endpoint. * Added pagination to the `POST /export/skills` endpoint using the `limit` and `starting_after` body parameters. * Added the `external_vendor` query parameter to the `GET /taxonomy/changes` endpoint to support retrieving Taxonomy Changes in an external vendor's Skill vocabulary. * Added the `create_skill` and `delete_skill` operation types to the `GET /taxonomy/changes` and `POST /taxonomy/apply` endpoints. * Added the `POST /taxonomy/changes` endpoint. * Added the `vocab_update_add_skill` operation type to the `GET /taxonomy/changes` and `POST /taxonomy/changes` endpoint. ### December 2025 * Added the `include_overqualified` and `min_critical_skills_match_ratio` parameters to the employee-job matching endpoints to filter matches based on their overqualification status and on the matching ratio of critical skills. * Enhanced the employee-job matching and match endpoints (`POST /employees/{external_id}/matching_jobs`, `POST /job_architecture/jobs/{job_external_id}/matching_employees`, `POST /matching/export/employees/matching_jobs`, `POST /job_architecture/export/jobs/matching_employees`, `GET /employees/{employee_external_id}/match_assigned_position`, `GET /employees/{employee_external_id}/jobs/{job_external_id}/match`, and `POST /export/employees/match_assigned_position`) to automatically include additional fields when proficiency matching or criticality matching is enabled on the tenant. When proficiency matching is enabled, responses include `overqualified` status (for matching endpoints only), `skill_proficiency`, and `adjacent_skill_proficiency` fields. When criticality matching is enabled, responses include `critical` and `gap_impact` fields. * Added the `include` query parameter to the `GET /reports/data_maturity_scan/job_maturity_overview` and `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints to include additional metrics in the response. * For Jobs: `job_data_count` and `data_distribution`. * For Employees: `valid_assigned_position`, `has_business_data`, and `sufficient_working_history`. * Removed `MIN_SOURCE_CONFIRMATION` from the list of possible reasons in the Data Maturity Scan maturity overview endpoints. * Added the `is_active` query parameter to the `GET /reports/data_maturity_scan/job_maturity_overview` and `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints to filter entities by their active status. * Removed the `force_recalculate` parameter from the `GET /reports/data_maturity_scan/job_maturity_overview` and `GET /reports/data_maturity_scan/employee_maturity_overview` endpoints as the underlying data is now updated continuously. ### November 2025 * Added the `low_data_availability` query paremeter to the `GET /employees` endpoint. * Added the `low_data_availability` and `job_family` query parameters to the `GET /job_architecture/jobs` endpoint. * Added the `job_count` to the output of the `GET /job_architecture/export` endpoint. ### October 2025 * Added the `external_vendor` query parameter to the `PUT /taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}` and `DELETE /taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id}` endpoints to support applying Taxonomy Changes in an external vendor's Skill vocabulary. * Added the `external_vendor` query parameter to the `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills`, `GET /taxonomy/export` and `GET /taxonomy/skills` endpoints to display Skills in an external vendor's Skill vocabulary. * Added the `include=properties` query parameter to the following endpoints to show properties of each Skill: * `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills` (List skills in a skill cluster) * `GET /taxonomy/skills` (List all skills) * `POST /export/skills` (Export all skills) * `GET /taxonomy/export` (Taxonomy export) * `GET /taxonomy/skills/{skill_id}` (Get Skill endpoint) * `GET /employees/{external_id}/skill_profile` (Get Employee Skill profile) * `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` (Get Skill Profile Job Family) * `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile` (Get suggested skill profile Job Family) * `GET /job_architecture/jobs/{job_external_id}/skill_profile` (Get Skill Profile Job) * `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` (Get suggested skill profile Job) * `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles` (Get external market profiles for Job) * `POST /export/employees/skill_profiles` (Export Employee Skill Profile) * `POST /job_architecture/export/jobs/skill_profiles` (Export Job Skill Profile) * `POST /job_architecture/export/jobs/suggested_skill_profiles` (Export Suggested Job Skill Profile) * `POST /job_architecture/export/jobs/market_skill_profiles` (Export Market Job Skill Profile) * `POST /job_architecture/export/job_families/skill_profiles` (Export Job Family Skill Profile) * `POST /job_architecture/export/job_families/suggested_skill_profiles` (Export Job Family Skill Suggested Profile) * Added the `properties` query parameter to the following endpoints to filter skills by their properties: * `POST /employees/suggestions/skills` (Get suggestions, validated and rejected Skills for selected Employees) * `GET /skills/search` (Search for Skills similar to the text provided) The parameter uses the format `properties[property_name]=value` to filter skills that have a specific property with a specific value. For example, `properties[sap_status]=active` will only return skills that have the `sap_status` property set to `active`. * Added the `external_vendor` query parameter to the `PATCH /taxonomy/skills/{skill_id}` endpoint to support updating descriptions and properties of Skills in an external vendor's Skill vocabulary. * Added the `POST /taxonomy/skills` endpoint which allows for creating new Skills in the system, either in TechWolf Skill vocabulary or an external vendor's Skill vocabulary. This endpoint requires admin scope access. * Added the `restore` query parameter to the `POST /employees` endpoint to enable support for restoration of soft deleted Employees during the grace period. * Added the `include=proficiency` and `include=job_critical` to the query parameters of the `GET /employees/{employee_external_id}/suggestions/skills` endpoint to allow the `self_rated_proficiency_level` and `is_job_critical_skill` attributes to be included in the response. * Added the `external_vendor` query parameter to all matching endpoints and some additional endpoints: * `POST /employees/{external_id}/matching_vacancies` * `POST /vacancies/{external_id}/matching_employees` * `POST /employees/{external_id}/matching_jobs` * `POST /job_architecture/jobs/{external_id}/matching_employees` * `POST /job_architecture/jobs/{external_id}/matching_source_jobs` * `POST /job_architecture/jobs/{external_id}/matching_target_jobs` * `POST /employees/{external_id}/matching_job_families` * `POST /job_architecture/job_families/{external_id}/matching_employees` * `POST /employees/{external_id}/matching_companies` * `POST /companies/{external_id}/matching_employees` * `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` * `GET /employees/{employee_external_id}/jobs/{job_external_id}/match` * `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match` * `GET /employees/{employee_external_id}/match_assigned_position` * `POST /employees/{employee_external_id}/recommended_courses` * `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses` * `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` * `POST /export/employees/match_assigned_position` * `POST /export/employees/matching_jobs` * `POST /export/employees/matching_vacancies` * `POST /export/vacancies/matching_employees` * `POST /job_architecture/export/jobs/matching_employees` * `POST /employees/search` * `POST /companies/search` * `POST /vacancies/search` * `POST /skills/lookup` ### September 2025 * Added the `GET /export/vacancies/skill_profiles` endpoint to paginate through all Skill Profiles of Vacancies in the API in bulk. * Added support to display Skill Profiles in external vendor Skills with the `response_format=list` response format in the `POST /export/courses/skill_profiles` and `POST /export/vacancies/skill_profiles` * Added support to display hierarchical Skill profiles with the `response_format=hierarchy` response format, for the `POST /export/courses/skill_profiles` and the `POST /export/vacancies/skill_profiles` endpoints, both for TechWolf Skills and external vendor Skills. * Added an experimental `POST /export/skills` endpoint that exports the information for all Skills in the system. * Added the `POST /export/employees/matching_jobs` endpoint to export the top matching Jobs for Employees. * Added the `POST /job_architecture/export/jobs/matching_employees` endpoint to export the top matching Employees for Jobs. * Added the `POST /export/employees/matching_vacancies` endpoint to export the top matching Vacancies for Employees. * Added the `POST /export/vacancies/matching_employees` endpoint to export the top matching Employees for Vacancies. * Added the `external_vendor` query parameter to the `POST /taxonomy/apply` endpoint to support applying Taxonomy Changes in an external vendor's Skill vocabulary. ### August 2025 * Added instructions on how to set up OAuth authentication to the Workday Skill Sync Integration documentation. * Added support to display descriptions and domains for external vendor Skills in the `GET /taxonomy/skills/{skill_id}` endpoint. * Added support to display Skill Profiles in external vendor Skills with the `response_format=hierarchy` response format in the `GET /employees/skill_profiles` and `POST /export/employees/skill_profiles` endpoints. * Added support to display hierarchical Skill profiles with the `response_format=hierarchy` response format, for the `GET /courses/{course_external_id}/skill_profile` and the `GET /vacancies/{vacancy_external_id}/skill_profile` endpoints, both for TechWolf Skills and external vendor Skills. ### July 2025 * Add support to display adoption metrics in external vendor Skills in the `POST /job_architecture/jobs/metrics/adoption_metrics` and `POST employees/metrics/adoption_metrics` endpoints. * Add support to display Skill Profiles in external vendor Skills with the `response_format=hierarchy` response format in the `GET /job_architecture/jobs/skill_profiles` and `GET /job_architecture/job_families/skill_profiles` endpoints. * Add support to display Skill Profiles in external vendor Skills in the `POST /job_architecture/export/jobs/skill_profiles` and `POST /job_architecture/export/job_families/skill_profiles` endpoints. * Add support to display the market Skill Profiles in external vendor Skills in the `GET /job_architecture/jobs/market_skill_profiles` and `POST /job_architecture/export/jobs/market_skill_profiles` endpoints. ### June 2025 * Update the `include` parameter in the\ `GET /employees/{employee_external_id}/skill_profile` endpoint to allow `inferred_proficiency_level` and `inferred_proficiency_float` to be included with `response_format=list`. * Update the `include` body parameter in the\ `POST export/employees/skill_profiles` endpoint to allow the `self_rated_proficiency_level`, `self_rated_proficiency_float` ,`inferred_proficiency_level` and `inferred_proficiency_float` fields to be included. * Add the `GET /job_architecture/issues` endpoint to fetch Job issues. * Add the `GET /job_architecture/issues/summary` endpoint to get a summary of the number of Job issues per type. * Add the `include=issues` parameter to the `GET /job_architecture/export` endpoint. * Add the `GET /job_architecture/changes` endpoint to fetch Job architecture changes. * Add the `POST /job_architecture/changes` endpoint to start the batch generation of Job changes. * Add the `PATCH /job_architecture/changes` endpoint to bulk update multiple job architecture changes at once. * Add the `GET /job_architecture/changes/summary` endpoint to get a summary of the number of Job changes per type. * Add the `POST /job_architecture/changes/preview` endpoint to generate a preview Job change. * Add the `GET /job_architecture/changes/{change_id}` endpoint to get detailed information about a specific Job architecture change. * Add the `PATCH /job_architecture/changes/{change_id}` endpoint to update a specific Job architecture change with new data. ### May 2025 * Add the `self_rated_proficiency_level` and `self_rated_proficiency_float` attributes to the request body of the `PATCH /employees/{employee_external_id}/skill_profile` endpoint for the `skills` and `external_vendor_skills` feedback formats. * Update the `include` parameter in the `GET /employees/{employee_external_id}/skill_profile` endpoint to allow `self_rated_proficiency_level` and `self_rated_proficiency_float` to be included with `response_format=list`. ### April 2025 * Add the `GET /job_architecture/jobs/market_alignment` and `POST job_architecture/export/jobs/market_alignment` endpoints. ### March 2025 * Add `ticket_system` field to the `ticket` event type to be able to specify the ticketing system where the ticket originated from. This field is important for skill inference as different models may be used for different ticketing systems. ### February 2025 * Allow patching of Organisational Units with `parent_id=null` to become a root Organisational Unit in the `PATCH /organisational_units/{external_id}` endpoint. * Add `GET /job_architecture/peer_groups` endpoint. ### January 2025 * Add the optional `proficiency_float` field to the request body of the `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` and `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints. * Add the `include=proficiency_float` option to the include query parameter of the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints. * Add the `include=proficiency_float` option to the include body parameter of the `POST /job_architecture/export/jobs/skill_profiles` and `POST /job_architecture/export/job_families/skill_profiles` endpoints. * Add the `external_vendor` query parameter to the `POST /employees/suggestions/skills` endpoint * Remove the `strict` query parameter from the `POST /employees/suggestions/skills` endpoint * Add the `include=critical` option to the include query parameters to the `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` endpoint. * Update the `include` parameter in the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints to allow `proficiency_level` and `critical` to be included with `response_format=hierarchy` * Make the `skill_cluster_description` optional and set it to an empty string by default. Additionally, save any placeholder value or a description that exactly matches the Skill Cluster name as an empty string. ### December 2024 * Add the `include=proficiency_level` and `include=critical` options to the include body parameter of the `POST /job_architecture/export/jobs/skill_profiles` endpoint. * Add the `include=proficiency_level` and `include=critical` options to the include body parameter of the `POST /job_architecture/export/job_families/skill_profiles` endpoint. * Add the `external_vendor` query parameter to the `GET /skills/search` endpoint. * Return the default proficiency level when no proficiency level is set in the `GET /job_architecture/jobs/{job_external_id}/skill_profile`, `POST /job_architecture/export/jobs/skill_profiles`, `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`, and `POST /job_architecture/export/job_families/skill_profiles` endpoints. * Add the `force_recalculate` query parameter to all report endpoints. ### November 2024 * Add `limit`, `offset`, and `update_low_data_availability` query parameters to the `GET /reports/data_maturity_scan/employee_maturity_overview` and `GET /reports/data_maturity_scan/job_maturity_overview` endpoints. * Add `include=skill_cluster_description` parameter to the `GET /taxonomy/skill_clusters` endpoint. * Add `skill_cluster_description` response body field and query parameter `include=skill_cluster_description` to the `GET taxonomy/export` endpoint. * Add the `PATCH /taxonomy/skills/{skill_id}` endpoint. * Return the custom Skill description in the `GET /taxonomy/skills`, `GET /taxonomy/skills/{skill_id}`, and `GET /taxonomy/export` endpoints if one is set. * Add the `update_skill` operation type to the `GET /taxonomy/changes` and `POST /taxonomy/apply` endpoints. * Add `include=skill_description` parameter to the `/taxonomy/skill_clusters/{skill_cluster_external_id}/skills` endpoint. * Add `GET /job_architecture/jobs/{job_external_id}/market_skill_profiles` and `POST /job_architecture/export/jobs/market_skill_profiles` endpoints. * Add the `proficiency_level` and `critical` attributes to the request body of the `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` endpoint. * Add the `proficiency_level` and `critical` attributes to the request body of the `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoint. * Add the `include=proficiency_level` and `include=critical` query parameters to the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints. ### October 2024 * Add `POST /job_architecture/jobs/metrics/adoption_metrics` endpoint. * Add `POST /employees/metrics/adoption_metrics` endpoint. * Add `source_data` to `skills` returned in `GET/job_architecture/jobs/{job_external_id}/skill_profile` and `GET/job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints. * Add CRUD operations for Custom Properties and Custom Property Definitions for Organisational Units. * Add `active` attribute to the Organisational Unit entity. * Add `hierarchy` as a possible response format for the `GET /employees/{employee_external_id}/skill_profile` endpoint. * Add `include=custom_properties` parameter to `GET/job_architecture/job_families`, `GET/job_architecture/jobs`, `GET/courses`, `GET/vacancies`, `GET/employees`, `GET/companies`, `GET/taxonomy/domains`, `GET/taxonomy/subdomains`, `GET/taxonomy/skill_clusters` and `GET/taxonomy/skills` endpoints. * Add `output_skills_sorting` parameter to `GET /job_architecture/export/job_families/suggested_skill_profiles`, `GET /job_architecture/export/job_families/skill_profiles`, `GET /job_architecture/export/jobs/suggested_skill_profiles` and `GET /job_architecture/export/jobs/skill_profiles` endpoints. * Deprecate the `GET /job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint. * Add the `vocab_update_rename_skill`, `vocab_update_merge_skill`, and `vocab_update_remove_skill` operation types to the `GET /taxonomy/changes` endpoint. ### September 2024 * Add `GET /job_architecture/jobs/{job_external_id}/matching_source_jobs` endpoint. * Add `GET /job_architecture/jobs/{job_external_id}/matching_target_jobs` endpoint. * Add error code 400 as possible response code for `DELETE /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}` for `DELETE /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}` when trying to delete Skill Profile Feedback instances and respective examples for this * Add `GET /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}` endpoint. * Add `skill_profile_feedback` as a `data_type` to the Job Family Profile Data of a Job Family. This new `data_type` may be included the responses of `GET /job_architecture/job_families/{job_family_external_id}/profile_data` and `GET /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id}`. * Add `GET /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}` endpoint. * Add `skill_profile_feedback` as a `data_type` to the Job Profile Data of a Job. This new `data_type` may be included the responses of `GET /job_architecture/jobs/{job_external_id}/profile_data` and `GET /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id}`. * Add `skill_id` query parameter to the `GET /employees` and `GET /organisational_units/export` endpoints that allows for filtering the returned entities on whether their Skill Profile contains a certain Skill. * Add an experimental `POST /employees/suggestions/skill` endpoint that allows to find suggested, validated, and rejected Skill suggestions for Employees. * Add `en_us`, `de`, and `fr` to the list of supported values for the `vocab_language` query parameters in the `GET /{entity}/{external_id}/skill_profile`, `GET /taxonomy/skill_clusters/{external_id}/skills`, `GET /taxonomy/skill/`, and `GET /taxonomy/export/` endpoints. * Add the `low_data_availability_flag` to the possible values of the `include` query parameter of the `GET /organisational_units/export` and `GET /job_architecture/export` endpoints. * Add `skill_id` query parameter to the `GET /job_architecture/export` endpoint that allows for filtering the entities on whether their Skill Profile contains a certain Skill. * Add `source_coverage` metric to the response of the `GET /reports/data_maturity_scan/job_quality_matrix` and `GET /reports/data_maturity_scan/employee_quality_matrix` endpoints. * Add `skill_name`, `skill_cluster_name`, `subdomain_name`, and `domain_name` to the output of `GET /taxonomy/changes`. * Add `subdomain_name` to output of the `POST /job_architecture/export/jobs/skill_clusters`, `POST /export/employees/skill_clusters` and `GET /employees//skill_profile?response_format=skill_clusters` endpoints for 4-level Taxonomies. * Add `source_data` to the output of `GET /jobs/{job_external_id}/suggested_skill_profile`, `GET /job_families/{job_family_external_id}/suggested_skill_profile`, `POST /job_architecture/export/jobs/suggested_skill_profiles`, and `POST /job_architecture/export/job_families/suggested_skill_profiles`. * Add endpoints `POST /integrations/file_load_task` to upload a CSV-file from S3 into the system and `GET /integrations/file_load_task/{task_id}` to get the status of the File Load Task. ### August 2024 * Add `skill_validation_state` to the possible values of the `include` query parameter of the `GET /job_architecture/export/jobs/skill_profiles`, `GET /job_architecture/export/jobs/suggested_skill_profiles`, `GET /job_architecture/export/job_families/skill_profiles`, and `GET /job_architecture/export/job_families/suggested_skill_profiles` endpoints. * Add `skill_validation_state` to the possible values of the `include` query parameter of the `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` and `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile` endpoints. * Add `skill_validation_state` to the possible values of the `include` query parameter of the `GET /job_architecture/jobs/{job_external_id}/skill_profile` and `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` endpoints. * Add Employee and Job key metric reports. `GET /reports/employees/key_metrics` `GET /reports/jobs/key_metrics` `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` ### July 2024 * Add CRUD operations for Organisational Units. * Add export endpoint `GET /organisational_units/export` to get the full hierarchy of the Organisational Units including the `total_nr_of_employees` field. * Added `organisational_unit` field to Employees that is returned in `GET /employees` and `GET /employees/{external_id}`. * Added query parameter `organisational_unit` to `GET /employees` to filter Employees on their linked Organisational Unit. * Added the `low_data_availability_flag` to the possible values of the `include` query parameter of the `GET /employees/{external_id}/skill_profile` and `GET /job_architecture/jobs/{job_external_id}/skill_profile` endpoints. * Added the `low_data_availability_flag` to the possible values of the `include` body parameter of the `POST /export/employees/skill_profiles` and `POST /job_architecture/export/jobs/skill_profiles` endpoints that allows including the low data availability flag in the output. * Added the option to upload files of data type `job_description` as Job Profile Data. Available in the `POST /job_architecture/jobs/{job_external_id}/profile_data` and `PATCH /job_architecture/jobs/{job_external_id}/profile_data` endpoint. * Added the option to upload files of data type `job_family_description` as Job Family Profile Data. Available in the `POST /job_architecture/job_families/{job_family_external_id}/profile_data` and `PATCH /job_architecture/job_families/{job_family_external_id}/profile_data` endpoint. ### June 2024 * Add `low_data_availability` attribute to the Employee entity. * Add `low_data_availability` attribute to the Job entity. * Added Data Maturity Scan reporting endpoints: * `GET /reports/data_maturity_scan/employee_quality_matrix` * `GET /reports/data_maturity_scan/job_quality_matrix` * `GET /reports/data_maturity_scan/employee_maturity_overview` * `GET /reports/data_maturity_scan/job_maturity_overview` * `GET /reports/data_maturity_scan/data_improvement_actions` * Added `rejected_skills` to the possible values of the `include` body parameter of the `POST /export/employees/skill_profiles` endpoint that allows including rejected Skills in the output. ### May 2024 * Add `GET /employees/{employee_external_id}/jobs/{job_external_id}/match` endpoint that allows to match an Employee with a Job. * Add `POST /employees/{employee_external_id}/matching_jobs` endpoint that allows to find the top matching Jobs for an Employee. * Add `POST /job_architecture/jobs/{external_id}/matching_employees` endpoint that allows to find the top matching Employees for a Job. * Add `POST /job_architecture/job_families/{external_id}/matching_employees` endpoint that allows to find the top matching Employees for a Job Family. * Add `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses` endpoint that recommends Courses to address the Skill Gap between the Employee and the Job. * Add `GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match` endpoint that allows to match an Employee with a Job Family. * Add `GET /employees/{employee_external_id}/match_assigned_position` endpoint that allows to match an Employee with their assigned position. * Add `POST /export/employees/match_assigned_position` endpoint that allows to match Employees with their assigned position in bulk. * Add `output_skills_sorting` body parameter to the `POST /export/employees/skill_profiles` endpoint, allowing `alphabetical` to sort the Skills in the resulting profiles alphabetically, or `confidence` to sort them by decreasing confidence. * Add `is_active` filter to the `POST /job_architecture/export/jobs/skill_profiles`, `POST /job_architecture/export/jobs/suggested_skill_profiles`, `POST /job_architecture/export/jobs/skill_clusters`, `POST /job_architecture/export/job_families/skill_profiles`, `POST /job_architecture/export/job_families/suggested_skill_profiles`, `POST /export/employees/skill_profiles`, `POST /export/employees/skill_clusters`, `POST /export/courses/skill_profiles` export endpoints to only include active or inactive entities in the result based on the filter value. * Add `is_active` query parameter to the `GET /job_architecture/export` export endpoint to only include active or inactive jobs and job families in the result. * Add `is_active` query parameter to the `GET /employees`, `GET /vacancies`, `GET /courses`, `GET /job_architecture/jobs`, `GET /job_architecture/job_families` list endpoints to only include active or inactive entities in the result. * Add `include=entity` and `include=custom_properties` query parameter to `POST /employees/{external_id}/matching_job_families`. * Removed `Core` as a possible value of the `skill_type` field of a Skill in the Job Family Skill Profile. * Add `response_format=explained` query parameter to `POST /employees/{external_id}/matching_vacancies`, `POST /vacancies/{external_id}/matching_employees` and `POST /employees/{external_id}/matching_job_families`, that includes `missing_skills` and `present_skills` response body fields as additional information about the matches. * Add `include=adoption` query parameter to the `taxonomy/skills/{skill_id}` endpoint to include the adoption of the Skill in Jobs and Employees in the response. * Add `assigned_position_id` attribute to the Employee entity. * Allow `PATCH /employees//skill_events/` on the `resume_document`, `feedback`, `goal`, `project`, `certificate`, `learning` and `ticket` event types. ### April 2024 * Add `active` attribute to Course, Employee, Job and Job Family entity. * Add support to display Skill Profiles in external vendor Skills on GET, using the query parameter `external_vendor`, for Course, Employee, Job and Job Family entities. Usage: * `GET /employee/{employee_id}/skill_profile?external_vendor={external_vendor}` * `GET /job_architecture/jobs/{job_external_id}/skill_profile?external_vendor={external_vendor}` * `GET /job_architecture/job_families/{job_family_external_id}/skill_profile?external_vendor={external_vendor}` * `GET /courses/{external_id}/skill_profile?external_vendor={external_vendor}` * Add support to provide feedback to Skill Profiles in external vendor Skills, using the query parameter `feedback_format=external_vendor_skills`, for Course, Employee, Job and Job Family entities. Usage: * `PATCH /employee/{employee_id}/feedback_format=external_vendor_skills` * `PATCH /job_architecture/jobs/{job_external_id}/skill_profile?feedback_format=external_vendor_skills` * `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile?feedback_format=external_vendor_skills` * `PATCH /courses/{external_id}/skill_profile?feedback_format=external_vendor_skills` * Deprecate `GET /employee{employee_external_id}/vacancy/{vacancy_external_id}/recommend_courses` * Add `POST /employee{employee_external_id}/vacancy/{vacancy_external_id}/recommend_courses` endpoint which makes use of an updated and improved methodology to recommend Courses. * Update `POST /employee{employee_external_id}/recommend_courses` endpoint in line with the updated and improved methodology to recommend Courses. ### March 2024 * Add `POST /job_architecture/export/jobs/suggested_skill_profiles` endpoint to paginate through all suggested Skill Profiles of Jobs in the API in bulk. * Add `POST /job_architecture/export/job_families/suggested_skill_profiles` endpoint to paginate through all suggested Skill Profiles of Job Families in the API in bulk. * The `domain_namespace` query parameter is available on the `job_architecture/export/jobs/skill_profiles` and `job_architecture/export/job_families/skill_profiles` endpoints. * When requesting an Employee Skill Profile through either `GET /employee/{employee_id}/skill_profile` or `POST /export/employees/skill_profiles`, the response will now include the `source_events` field on all Skills, when requesting sources. `source_events` provides more insights into which Skill Event contributes to which skill. ### February 2024 * Add `GET /employees/{employee_id}/skill_events/{skill_event_id}` endpoint to be able to get a single Skill Event of an Employee. * Add `POST /job_architecture/export/jobs/skill_profiles` endpoint to paginate through all Skill Profiles of Jobs in the API in bulk. * Add `POST /job_architecture/export/job_families/skill_profiles` endpoint to paginate through all Skill Profiles of Job Families in the API in bulk. * Add support for `ticket` Skill Events. * Add support for `skill_notes` Job Profile Data. * Deprecated the `POST /job_architecture/export/job/skill_clusters` endpoint and added the `POST /job_architecture/export/jobs/skill_clusters`. ### January 2024 * A `source` attribute can now be added to each Skill Profile feedback endpoint to indicate the source of the feedback. See all `PATCH /{entity}/{entity_id}/skill_profile` endpoints. * An `include` query parameter can now be added to the `GET /employees/{external_id}/skill_profile` endpoint to include the source Skill Events where the reported Skills are inferred from. * Add `POST /export/employees/skill_profiles` endpoint to get the Skill profiles of all Employees in the API through pagination. * Add the `POST /skills/lookup` endpoint to get corresponding UUIDs for a list of Skill names. * Add `GET /job_architecture/job/{job_id}/suggested_skill_profile` to get suggested skills for a Job. * Add `GET /job_architecture/job_families/{job_family_id}/suggested_skill_profile` to get suggested skills for a Job Family. ### December 2023 * Add the `include=custom_properties` query parameter to the `GET /taxonomy/skills/{skill_id}` endpoint to include the Custom Properties of a Skill in the response. * Add the `include=custom_properties` query parameter to the `GET /taxonomy/skill_clusters/{skill_cluster_id}` endpoint to include the Custom Properties of Skill Clusters in the response. * Add the `include=custom_properties` query parameter to the `GET /taxonomy/subdomains/{subdomain_id}` endpoint to include the Custom Properties of Subdomains in the response. * Add the `include=custom_properties` query parameter to the `GET /taxonomy/domains/{domain_id}` endpoint to include the Custom Properties of Domains in the response. * Introduced a `skill_id` field alongside Skill names in our API endpoints to avoid ambiguities and conflicts. All endpoints that return Skill names will now also return a `skill_id` field. Using Skill names in a request body to denote an update of a Skill is deprecated, please use `skill_id` instead. * Mark all `/occupations` endpoints as deprecated. * Add the `vocab_language` query parameter to the `GET /{entity}/{external_id}/skill_profile` endpoints to specify the language of the Skill names in the Skill Profile response. * Add the `vocab_language` query parameter to the `GET /taxonomy/skill_clusters/{external_id}/skills` endpoint to specify the language of the Skill names in the Skill Profile response. * Add the `vocab_language` query parameter to the `GET /taxonomy/skill/` endpoints to specify the language of the Skill names in the Skill Profile response. * Add the `vocab_language` query parameter to the `GET /taxonomy/export/` endpoints to specify the language of the Skill names in the Skill Profile response. ### November 2023 * Add the `domain_namespace` query parameter to `GET /job_architecture/jobs/{job_external_id}/skill_profile` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. * Add the `domain_namespace` query parameter to `GET /job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. * Add the `domain_namespace` query parameter to `GET /job_architecture/job_families/{job_family_external_id}/skill_profile` endpoint to express the Skill domains in either TechWolf or Taxonomy Domains. * Add `domain_name` response body field and `domain_namespace` query parameter to `GET /taxonomy/skills/{skill_id}` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. * Add `domain_name` response body field and `domain_namespace` query parameter to `GET /taxonomy/skills` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. * Add the `domain_namespace` query parameter to `GET /skills/search` endpoint to express the Skill Domains in either TechWolf or Taxonomy Domains. * Add `POST /export/courses/skill_profiles` endpoint to paginate through all Skill Profiles of Courses in the API in bulk. * Add `last_updated_with_taxonomy_changes` filter to the POST `/export/employees/skill_clusters` and POST `/job_architecture/export/job/skill_clusters` endpoints. * Add `next_starting_after` field to response of `POST /export/employees/skill_clusters` endpoint. ### October 2023 * Add `GET /job_architecture/jobs/{job_external_id}/market_skill_profile` endpoint to get the market Skill Profile of a Job. * Update request sample for `POST /reports/job_architecture_benchmark` endpoint. * Mark all `/skill_clusters` endpoints as deprecated. ### September 2023 * Add `skill_description` response body field and query parameter `include=skill_description` to `GET taxonomy/export`. * Add a `vacancy` data type for Job Profile Data. Available in the POST `/job_architecture/jobs/{job_external_id}/profile_data` endpoint. * Add the `taxonomy/changes` endpoint to view all changes to the Taxonomy within a certain timeframe. * Add `skill_id` and `skill_sources` to Skills of response body field in `GET export/employees/skill_clusters`. * Add a `POST /job_architecture/export/job/skill_clusters` endpoint to fetch Job Skill clusters and Skills in bulk. * Add the `Subdomain` entity to enable a 4-level Taxonomy hierarchy. * Add CRUD operations for Custom Properties and Custom Property Definitions for the following Taxonomy entities: `taxonomy/domains`, `taxonomy/subdomains`, `taxonomy/skill_clusters`, and `taxonomy/skills`. * Add `external_id` and `skill_vocab` fields to the `taxonomy/export` and `taxonomy/skill_cluster//skills` endpoints. ### August 2023 * Add `skill_id` response body field and query parameter `search_method` to `POST skills/search`. * Add `GET` and `POST /taxonomy/domains` to see all Domains and create a new Domain respectively. Add `GET`, `PATCH` and `DELETE /taxonomy/domains/{external_id}` to see a single Domain, update a Domain and delete a Domain respectively. * Add `GET` and `POST /taxonomy/skill_clusters` to see all Skill Clusters and create a new Skill Cluster respectively. Add `GET`, `PATCH` and `DELETE /taxonomy/skill_clusters/{external_id}` to see a single Skill Cluster, update a Skill Cluster and delete a Skill Cluster respectively. * Add `GET /taxonomy/skill_clusters/{external_id}/skills` to see all Skills in a Skill Cluster. Add `PUT` and `DELETE /taxonomy/skill_clusters/{external_id}/skills/{skill_external_id}` to add a Skill to a Skill Cluster and remove a Skill from a Skill Cluster respectively. * Add `GET /taxonomy/skills/{concept_uuid}` and `GET /taxonomy/skills` to get meta information of a single Skill or multiple Skills. * Add `GET /taxonomy/export` to export the full structure of the Taxonomy. * Add `POST /taxonomy/apply` to apply a set of changes to the Taxonomy. * Add `skill_id` to the response body of `GET job_architecture/jobs/{job_external_id}/skill_profile` and `GET job_architecture/job_families/{job_family_external_id}/skill_profile`. * Add functionality for Jobs to not be linked to a Job Family. * Skill Profile feedback in Skill Cluster format (`PATCH /employees/{external_id}/skill_profile?feedback_format=skill_clusters`) can now be given with a `skill_cluster_id`. * Add `GET /job_architecture/export`. ### July 2023 * Add `POST /reports/job_architecture_benchmark`. * Add the `include=skill_match_scores` query parameter to the `POST /employees/{external_id}/matching_job_families`, which includes match scores between the Employee and individual Skills in the response. ### June 2023 * Add `POST /reports/internal_talent_mobility`. * Update `POST /reports/skill_inventory`. * Add `GET /employees/{employee_external_id}/interactions` and `GET /employees/{employee_external_id}/interactions/{interaction_external_id}` endpoints, which allow for listing all interactions of an Employee and getting a single Interaction respectively. * Deprecated the `PUT /employees/{external_id}/skill_profile`, `PUT /vacancies/{external_id}/skill_profile`, `PUT /courses/{external_id}/skill_profile` and `PUT /occupations/{external_id}/skill_profile` endpoints. * Add `POST /employees/{employee_external_id}/matching_job_families` endpoint, which calculates and returns matching Job Families for an Employee. Weights are not customizable, but filtering on Custom Properties, external IDs and the `last_updated` field is allowed. * Add the `used_event_types` body parameter to the `POST /employees/{employee_id}/matching_vacancies` endpoint, allowing to use only events of certain types to be taken into account when calculating matching Vacancies for an Employee. ### May 2023 * Vacancy searching now works based on literal text matching by default. Skills based searching is still possible, as well as a combination of both. * Allow `PATCH` on SkillEvents with type `skill_notes`. * Add progress to the `POST /reports/skill_inventory` endpoint. * Add `skill_cluster_id` to the output of Employee, Vacancy, Course, Occupation `GET /{entity}/{external_id}/skill_profile?response_format=skill_clusters` endpoints, the `POST /export/employees/skill_clusters` endpoint, and the `POST /vacancies/{external_id}/matching_employees?include=skill_clusters` endpoint. * Add `POST /employees/{employee_external_id}/interactions` and `DELETE /employees/{employee_external_id}/interactions/{interaction_external_id}` endpoints, which allow the creation and deletion of Interactions between the Employee and a title or Vacancy. * Add `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` and `PATCH /job_architecture/job/{job_external_id}/skill_profile` which allow feedback on the Skill Profile of Job Families and Jobs respectively. * Add a breakdown of the matching Vacancies for a company in the results of the `/companies/search` endpoint. ### April 2023 * Courses can now have a `source` field. When creating Skill Events from a Course with a source, the source of the Course will be used if no source is provided in the Skill Event. * Add `POST /reports/skill_inventory` endpoint to get the Skill Inventory report. ### March 2023 * Add Update `/employees/{employee_external_id}/skill_events/{skill_event_external_id}` endpoint to support updating an Employee's Skill Event. * Add Job and Job Family entities to `job_architecture/jobs` and `job_architecture/job_families` endpoints respectively. * Add Job Profile Data and Job Family Profile Data to the `job_architecture/job_families/{job_family_external_id}/profile_data` and `job_architecture/jobs/{job_external_id}/profile_data` endpoints respectively. * Add `custom_property_is_in_list` filter to `POST employees/{employee_external_id}/recommended_courses`. * Add the `property_value` and `assigned_position` fields of an Employee to the Skill Cluster Adoption report (`reports/employees/skill_cluster_adoption`). * Add `GET job_architecture/jobs/{job_external_id}/skill_profile` and `GET job_architecture/job_families/{job_family_external_id}/skill_profile` endpoints * Add `match_feedback` option for the `include` parameter of the `/employees/{employee_external_id}/matching_vacancies` and `/vacancies/{vacancy_external_id}/matching_employees` endpoints, which includes feedback given to a match in the result if applicable. * Custom Properties have been added to the Job and Job Family entities. They can be requested by using the `custom_properties` include option when sending to the `GET job_architecture/jobs/{job_external_id}` and `GET job_architecture/job_families/{job_family_external_id}` endpoints. * Add Update `/job_architecture/jobs/{job_external_id}/profile_data/{profile_data_external_id}` and Update `/job_architecture/job_families/{job_family_external_id}/profile_data/{profile_data_external_id}` endpoints to support updating Job Profile Data and Job Family Profile Data. * Create or update working history Skill Events using a `job_id` at `POST /employees/{employee_external_id}/skill_events` and `PATCH /employees/{employee_external_id}/skill_events/{skill_event_external_id}` respectively ### February 2023 * Add the multi\_max\_geo\_distances filter in matching for endpoints `/employees/{external_id}/matching_vacancies` and `/vacancies/{external_id}/matching_employees`. * Add the Succession Risk Report available under the `/reports/succession_risk` endpoint. * Add the `rejected_skills` include option to the `POST /export/employees/skill_clusters` endpoint. * Add the option to create learning Skill Events from a `course_id` ### January 2023 * Add `competency_type` in `GET /competencies` and `GET /competencies/{external_id}`. * Add support for specifying the location in LocationAddress format in the MaxGeoDistanceFilter. * Add the Replacement Risk Report available under the `/reports/replacement_risk` endpoint. ### December 2022 * The Get Skill Profile endpoints `/entity_type/{external_id}/skill_profile` with `response_format=competencies` now return Skill information. * Add `custom_property_list_overlap` filter for Employee and Vacancy matching. * Add `GET vacancies/{vacancy_external_id}/metrics/fillability` endpoint, which calculates the fillability metric of a Vacancy. The fillability is influenced by the number of matching Employees and the number of Vacancies that can be filled by those Vacancies. More matching Employees will result in a higher fillability, and more matching Vacancies will result in a lower fillability. * Add `POST vacancies/{vacancy_external_id}/metrics/fillability` endpoint which allows for filtering the used entities on maximal allowed distance and Custom Properties, and assigning weights to the different factors used in the fillability calculation. * Add `exclude_match_feedback` filter to `POST employees/{employee_external_id}/recommended_courses` and `POST employees/{employee_external_id}/matching_vacancies` * Add `DELETE` endpoints to `employees/{employee_external_id}/vacancies/{vacancy_external_id}/match_feedback` and `employees/{employee_external_id}/courses/{course_external_id}/match_feedback` * Add `include=competencies` query parameter to `vacancies/{vacancy_external_id}/matching_employees`. * Add `include` query parameter for the `employees/{employee_external_id}/similar` endpoint. Possible values are: `entity`, `competencies` and `custom_properties`. * Add `validation_state` to Skills returned from `GET employees/{employee_external_id}/skill_profile` endpoint in `list` and `competency` format. * Add `validation_state` to Skills returned from `POST export/employees/competencies` endpoint. * Add `exclude_match_feedback` filter to the `employees/search` and `vacancies/search` endpoints. * Add `related_skills` to `include` in `POST export/employees/competencies` endpoint. * Adding a `proficiency_level` to a competency in the body is no longer required when sending feedback via `PUT` or `PATCH` to `/employees/{employee_external_id}/skill_profile?feedback_format=competencies` * Add `score_breakdown` option for the `include` parameter of the `/employees/{employee_external_id}/matching_vacancies` and `/vacancies/{vacancy_external_id}/matching_employees` endpoints, which includes a breakdown of the contribution of all input weights to the total match score in the response body. ### November 2022 * Add the `skill_notes` event type. * Add the Competency Adoption Report available under the `/reports/employees/competency_adoption` endpoint. * Add `POST employees/{employee_external_id}/metrics/employability` endpoint which allows for filtering the used entities on maximal allowed distance and Custom Properties, and assigning weights to the different factors used in the calculation. * Add `PATCH` endpoint to `vacancies/{external_id}/skill_profile`, `occupations/{external_id}/skill_profile` and `courses/{external_id}/skill_profile`. * Add `include=relevant_experience` query parameter to `employees/{employee_external_id}/matching_vacancies` and `vacancies/{vacancy_external_id}/matching_employees`. * For `LocationAddress` inputs, `city` can be used instead of `postal_code` now, making one of them required instead of having `postal_code` required. * The Get Skill Profile endpoints `/entity_type/{ID}/skill_profile` with `response_format=competencies` now return Skill category information. ### October 2022 * Add a not equals option (`neq`) to the `custom_property` filter. * Add `sources` in the `/export/employees/competencies` endpoint, to be able to track from which Skill Events the given competencies originate from. * Add support for addresses as an alternative for location coordinates. ### August 2022 * Add `include` query parameter to `vacancies/{vacancy_external_id}/matching_employees` to allow retrieving Employee information without extra calls. * Add `include=location` query parameter option to `employees/{employee_external_id}/matching_vacancies` * Add a `validation_state` field to the `/export/employees/competencies` response. Indicating whether the competencies linked to Employees are already validated by a manager or Employee or still suggested. ### July 2022 * Add a category field to the `POST /competencies` and `PATCH /competencies/{external_id}` endpoints to change the category of a competency. ### June 2022 * Add a PATCH endpoint for Skill Profile feedback on Employees such that Skill profiles can be partially updated. * Add `last_updated` filter for Employee and Vacancy matching. * Add an experimental `POST /export/employees/competencies` endpoint for extracting Employee competencies and Skills from the API. ### May 2022 * Change how the `GET /competencies/{external_id}/skill_profile` endpoint returns Skill Profiles for clients who use a Taxonomy managed by TechWolf. ### April 2022 * Add support for `project` and `certificate` Skill Events. * Add support for explicit `working_history`, `education_history`, and `resume_document` Skill Events. ### March 2022 * Add support for `feedback` and `goal` Skill Events. ### February 2022 * Add `include` query parameter to `employees/{employee_external_id}/recommended_courses` to allow retrieving Course information without extra calls. ### January 2022 * Add Delete `/employees/{employee_external_id}/skill_events/{skill_event_external_id}` endpoint to support removing an Employee's Skill Event from the API. * Add GET `/employees/{employee_external_id}/skill_events` endpoint to support fetching an Employee's Skill Events of a specified type in the API. The only allowed event type is a `learning_event`. * Add POST `/employees/{employee_external_id}/skill_events` endpoint to support the creation of Skill Events in the API. The only allowed event type is a `learning_event`. ### December 2021 * Add `/employees/{employee_external_id}/recommended_courses` endpoint, returning the recommended Courses to improve an Employee's Skill Profile. * Removed Certificates from Employees and all its functionalities. * The Custom Property weights for the matching endpoints now support the `custom_property_contains`, `custom_property_contains_element` , `custom_property_is_in` and `custom_property_is_in_list` configurations. Match scores are increased when the applied condition on the matching entities' specified Custom Property checks out. * The matching endpoints now support the `language` weight configurations. Match scores are increased when the matching entities' language levels fall between a range of the source entity language levels. ### October 2021 * All endpoints supporting the `explained` response format now return additional category information when the explained response format is requested. * The Get Skill Profile endpoints `/entity_type/{ID}/skill_profile` now support `response_format=categories` and thereby return Skill category information. * The Skill Search endpoint `/skills/search` now returns Skill category information. * The Search endpoints now support German (`de`) language. * You can now create and update entities in German with the `language=de` query parameter. * The Reskilling & Deployment report now provides information for key missing Skills on an Employee-level. ### September 2021 * The `/employees/{employee_external_id}/vacancies/{vacancy_external_id}/match` endpoint with `response_format=explained` query parameter now returns the body with missing Skills included under the `missing_skills` key. * Add external Company hiring activity profiling with NACE-codes under the `/companies/{external_id}/nace` endpoint. * Add the Reskilling & Deployment Report available under the `/reports/reskilling_and_deployment` endpoint. * Reskilling & Deployment report now supports a Qlik-friendly CSV output format. * Reskilling & Deployment report now supports `score_min_threshold`. * The `external_id_is_in_list` filter is now supported for the Job Matching and external Company Matching endpoints. Additionally, this filter is also supported for the Search and Similar endpoints of Employee, Vacancy, and external Company. ### August 2021 * The Employability metric now takes into account the supply of Employees that could fill in the demand as well. * The Search endpoints now support an optional `language` query parameter, to indicate the language of the input text. ### July 2021 * `companies/:external_id/desired_functions` now supports the `PUT` method. Calling this method replaces all existing desired function Vacancies with the new set. * Similar Entity endpoints now support `score_min_threshold`. * Similar Entity endpoints now support Custom Property filters. * Similar Entity endpoints for Employees and Vacancies now support location and language based filters. * Similar Entity endpoints now support Custom Property weights. * Similar Entity endpoints for Employees and Vacancies now support location weight. ### June 2021 * Add the option to override the location used for geo-distance calculation in matching request filters. * `max_geo_distance` field on Employee entities was deprecated. * remove `max_geo_distance` field on Employee entities. ### May 2021 * You can now use a Vacancy-prefix when looking for matching external Companies such that filtering and weighting is based on the Custom Properties of the Vacancies associated with the external company, rather than the external company itself. ### April 2021 * Add strict parameter to entity creation and update operations (Employees, Competencies, Courses, Documents, Occupations, Vacancies). * Change the outward facing side of (non-)desired functions during Employee creation. Output and input now better reflect internal results. * Add languages field to external Companies. * You can now add a geo distance weight to the matching endpoints. Match scores are increased when two entities are in proximity to each other. * You can now add Custom Property weights to the matching endpoints. Match scores are increased when the applied condition on the matching entities' specified Custom Property checks out. * Extraction language can now be specified for the POST `companies/{external_id}/desired_functions` endpoint. ### March 2021 * You can now specify the non-desired functions when creating or updating an Employee to take their negative preference into account when matching to new positions. * You can now modify the non-desired functions boost used during matching by setting the appropriate weight on the match endpoints `employees/{external_id}/matching_vacancies` and `vacancies/{external_id}/matching_employees`. * You can now submit multiple desired functions linked to a given External Company through a single multiline string using the new `request_format=free_text` query parameter on the `/companies/{external_id}/desired_functions` endpoint. * You can now submit free text, multiline strings desired functions & non-desired functions for an Employee through the `desired_functions` & `non_desired_functions` attributes. * You can now search for Vacancies and external Companies based on free text, through the endpoints `/vacancies/search` and `/companies/search`. * You can now add datetime-typed Custom Properties. * You can now provide a list of filters when searching for entities using free text through the endpoints `/employees/search`, `/vacancies/search` and `/companies/search`. * You can now provide multiple values (as a list) when using the `custom_property_contains_element` filter. Entities will not be filtered out if they contain at least one of the provided values in the list Custom Property. * You can now specify the comparison operator when using the `custom_property` filter. If no operator is specified, the filter defaults to the `equals` operator. * You can now specify an offset on matching endpoints for `employees` ,`vacancies` and `companies`. * You can now specify an offset on search endpoints for `employees`,`vacancies` and `companies`. * You can now pass the `null` value for optional fields during creation and updating of all entities. Passing the `null` value during an update will unset the entity's attribute. Objects will be unset as `null`, arrays as the empty array `[]` and strings as the empty string `''`. * External Companies now support Custom Properties. * (Non-)desired function score boosting is now calculated relative to the relevancy of the function title, instead of a binary boost on occurrence of a title. * You can now provide a list of filters at the match endpoints `employees/{external_id}/matching_companies` and `companies/{external_id}/matching_employees`. This will be used to filter out entities that do not need to be considered during matching. * You can now provide a list of weights at the match endpoints `employees/{external_id}/matching_companies` and `companies/{external_id}/matching_employees`. The weights can override some default weights during matching (e.g. desired functions boost). * Custom Property definitions are no longer allowed to contain double underscores in their name. * You can now set the weight of the skills-related match component contributing to the final match score (this was previously hard-coded to 1.0). * You can now filter on the Custom Properties of External Companies linked to a Vacancy, when matching Employees to Vacancies and vice versa. ### February 2021 * You can now search for Employees based on free text, through the endpoint `/employees/search`. * You can add an (optional) External Company link to a Vacancy, through the endpoint `/vacancies` and attribute `company`. * You can now list, create, retrieve, update and delete External Companies through the endpoints `/companies/*`. * You can now optionally mark Vacancies as inactive using the field `active`. When this is field has the value `false`, the Vacancy will not be used for matching. * Deleting External Companies now deletes all linked inactive Vacancies in cascade. * You can now find the best Employees for a given External Company with an overview of its matching Vacancies, through the endpoint `/companies/{external_id}/matching_employees`. * You can now find the best External Companies for a given Employee with an overview of the matching Vacancies per External Company, through the endpoint `/employees/{external_id}/matching_companies`. * You can now upload desired functions as inactive Vacancies linked to a given External Company, through the endpoint `/companies/{external_id}/desired_functions`. * You can now see when an entity was last updated by checking the attribute `last_updated` upon entity retrieval. * You can now provide a list of filters at the match endpoints `employees/{external_id}/matching_vacancies` and `vacancies/{external_id}/matching_employees`. This will be used to filter out entities that do not need to be considered during matching. * You can now provide a list of languages with proficiency levels during Vacancy creation. * You can now provide a list of weights at the match endpoints `employees/{external_id}/matching_vacancies` and `vacancies/{external_id}/matching_employees`. The weights can override some default weights during matching (e.g. desired functions boost). * The POST-type methods on `matching_vacancies` and `matching_employees` are now the preferred way to request the matches. * You can now add a list of strings as a Custom Property. * You can now explicitly provide the language used in Skill Profile extraction during entity creation/update using the `language` query parameter. Supported languages are `auto`, `nl`, `fr` and `en`. * You can now optionally add a Job description to the entries in the working\_history of an Employee. These descriptions will also be used for Skill extraction. ### January 2021 * You can add a (optional) `max_geo_distance` attribute when creating an Employee through the endpoint `/employees`. This is used for matching if there is no `max_geo_distance`. provided as query parameter. The default distance in our system when nothing is provided, is 50 km. # Deprecations Source: https://developers.techwolf.ai/reference/latest/API Versioning/Deprecations/Deprecations This section lists all currently deprecated features in the SkillEngine API. Deprecated features will be supported for a certain period of time before being removed. We recommend updating your integration to use the newer alternatives as soon as possible. ### March 2026 * Deprecated the Suggested Skill Profile endpoints. Use the corresponding Skill Profile endpoints instead. The following endpoints are affected: * `GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile` * `GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile` * `POST /job_architecture/export/jobs/suggested_skill_profiles` * `POST /job_architecture/export/job_families/suggested_skill_profiles` ### January 2026 * Deprecated the `GET /taxonomy/changes` endpoint. This endpoint will be replaced by the newly introduced `POST /taxonomy/changes` endpoint. ### December 2023 * Introduced a `skill_id` field alongside Skill names in our API endpoints to avoid ambiguities and conflicts. Using Skill names in a request body to denote or update a Skill is deprecated, please use `skill_id` instead. Existing functionality is backward-compatible. The following endpoints are affected: * `PATCH /employees/{external_id}/skill_profile` * `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile` * `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` * `PATCH /vacancies/{external_id}/skill_profile` * `PATCH /courses/{external_id}/skill_profile` * `PATCH /occupations/{external_id}/skill_profile` # Versioning Overview Source: https://developers.techwolf.ai/reference/latest/API Versioning/Versioning Overview/Versioning Overview The SkillEngine API is a date-based versioned API system, such that each integrator interacts with a certain version of our product. To know your own version, you can call the `/version` endpoint (description can be found [here](/reference/latest/Version/Version/get-version)). Your version is set by us at the time your tenant is created. This version controls how your API will behave (in terms of supported parameters, response formats, etc.). As it is possible that we introduce breaking changes in future updates that may break your code, we will not update your version **unless you specifically request this**. Breaking changes will always be released under a new date and can be tracked in the documentation [here](). Deprecations will be announced in the documentation and will be supported for a certain period of time. After this period, the deprecation will become a breaking change. Deprecations can be tracked in the documentation [here](). Non-breaking changes, on the other hand, will be supported by your API, **regardless of your version**. An overview can also be found [here](). In case you want to test a specific version of the API, e.g. when switching versions, you can add the header `X-API-Version` to your requests. The value of this header is the version of the API you want to use, for example `2021-03-19`. When you see an endpoint marked with Experimental it is considered experimental or in beta. These endpoints can undergo breaking changes without any notice or promises on backwards compatibility. You should not use them in production. # Delete Employee Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeCRUD/delete-employees-external-id DELETE /employees/{external_id} Remove an Employee from the system. This step deletes all information linked exclusively to this Employee. By deleting an Employee, you delete their Skill Profile history, which cannot be recreated or recovered afterwards. If grace periods are enabled, Employees are soft deleted and will only be permanently deleted after their grace period ends. During the grace period, soft deleted Employees can be restored by adding the `restore=true` parameter to the create endpoint. This restores the Employee to the state before deletion. # List Employees Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeCRUD/get-employees GET /employees Get a list of all Employees available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get Employee Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeCRUD/get-employees-external-id GET /employees/{external_id} Get the Employee information stored inside the system. As resumes are not stored inside our system, they are not returned in this call. # Overview Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeCRUD/overview Employees in the Skill Engine API represent either a person within your organisation or a candidate within the Job market. More info about entities can be found on the [How it Works page](/technology/entities/). [Custom Properties]() are supported for this entity. # Update Employee Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeCRUD/patch-employees-external-id PATCH /employees/{external_id} Submit the most up-to-date Employee information to update their profile inside the system. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is. Since the Employee resume is deleted after creating a Skill Profile, it is a required field for recalculating the Skill Profile based on the resume. If no resume is provided, the Skill Profile will be recalculated based on the other available properties. Passing the `null` value removes non-required attributes. Object attributes will be removed when passing `null`, arrays with `[]` and strings with the empty string `''`. # Create Employee Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeCRUD/post-employees POST /employees Submit new Employee information to initialise their Skill Profile inside the Skill Engine API. # Delete Employee Interaction Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeInteractions/delete-employees-employee-external-id-interactions-interaction-external-id DELETE /employees/{employee_external_id}/interactions/{interaction_external_id} Remove an Employee Interaction from an Employee. # List Interactions of an Employee Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeInteractions/get-employees-employee-external-id-interactions GET /employees/{employee_external_id}/interactions Get all Interactions linked to an Employee. # Get Employee Interaction Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeInteractions/get-employees-employee-external-id-interactions-interaction-external-id GET /employees/{employee_external_id}/interactions/{interaction_external_id} Get an Employee Interaction from an Employee. # Overview Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeInteractions/overview Interactions can be used to handle Employees interacting with Vacancies or titles in ways that express their desired functions. # Create a new Interaction for an Employee Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeInteractions/post-employees-employee-external-id-interactions POST /employees/{employee_external_id}/interactions Create a new Interaction for an Employee. # Get Employee count Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeMetrics/get-employees-metrics-count GET /employees/metrics/count Get the total number of Employee objects stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeMetrics/overview A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . # Get the employability metric using filters and weights Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeMetrics/post-employees-external-id-metrics-employability POST /employees/{external_id}/metrics/employability Retrieve the employability for this Employee. Employability is influenced by two factors: the number of matching Vacancies (demand) & the number of Employees that could fill those Vacancies (supply). It is reported as a number between 0 and 1, with the upper end indicating that an Employee has many matching opportunities (= high demand) for which there are not many matching Employees (= low supply). A lower score indicates fewer opportunities (= low demand), or that there is already a high supply of those profiles. Only active Vacancies and Employees are taken into account. # Get Employee adoption metrics Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeMetrics/post-employees-metrics-adoption-metrics POST /employees/metrics/adoption_metrics Get adoption metrics across a collection of Employee objects stored in the system, aggregated over their Skills and your Taxonomy. # Get the Skill Profile for an Employee Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeProfile/get-employees-external-id-skill-profile GET /employees/{external_id}/skill_profile Get an export of the Employee Skill Profile to leverage it for user interaction. Check our tutorials for a clear overview of how to get the most out of each format! # Partially update an Employee Skill Profile with feedback Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile PATCH /employees/{external_id}/skill_profile Provide feedback about an existing Employee Skill Profile to update it inside the system. When the `feedback_format` query parameter is `skills`, the body of the feedback message overwrites, adds or updates Skills in the original profile. When the `feedback_format` query parameter is `skill_clusters`, this endpoint will change the Skill Cluster Skills in the Skill Profile to fit the given Skill Cluster proficiency level. # Search for Employees based on free text Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeSearch/post-employees-search POST /employees/search Search for Employees # Get suggestions, validated and rejected Skills for selected Employees Source: https://developers.techwolf.ai/reference/latest/Employees/EmployeeSuggestions/post-employees-suggestions-skills POST /employees/suggestions/skills ![Beta](https://img.shields.io/badge/-Experimental-orange) This endpoint retrieves Skill suggestions and validated and rejected Skills for selected Employees. Users can customize the response with optional query parameters like language, the number of suggestions, and the format (Skill Profiles or Skill Clusters). It supports filtering by Skill types (suggested, validated, rejected). The response includes detailed Skill suggestions, with translated names and sources. # Delete Skill Event Source: https://developers.techwolf.ai/reference/latest/Employees/SkillEvents/delete-employees-employee-external-id-skill-events-skill-event-external-id DELETE /employees/{employee_external_id}/skill_events/{skill_event_external_id} Remove a Skill Event from an Employee. This step deletes all information linked exclusively to this Skill Event. If a Skill Event contained a non-empty Skill Profile, the Employee's Skill Profile is recalculated with the remaining Skill Events. **Note:** It may take some time for these changes to be reflected in the employee's final skill profile, since they are processed asynchronously. # List Skill Events of an Employee by event type Source: https://developers.techwolf.ai/reference/latest/Employees/SkillEvents/get-employees-employee-external-id-skill-events GET /employees/{employee_external_id}/skill_events Get all Skill Events of a specified event type linked to an Employee. # Get a Skill Event Source: https://developers.techwolf.ai/reference/latest/Employees/SkillEvents/get-employees-employee-external-id-skill-events-skill-event-external-id GET /employees/{employee_external_id}/skill_events/{skill_event_external_id} Get a single Skill Event for an Employee. # List the Skill Event types Source: https://developers.techwolf.ai/reference/latest/Employees/SkillEvents/get-skill-event-types GET /skill_event_types Returns every Skill Event type the tenant can send, with the content fields each one takes: `working_history`, `ticket`, … and, when they are enabled for the tenant, the business record types (`it_incident`, `support_ticket`, `technical_spec`, …). Contact TechWolf to enable the business record types. Use `data_type_id` as the `event_type` of a Skill Event and `record_schema` to build its `content`: every field marked `required` must be present, and no field outside `record_schema` is accepted. Every text field is used as context to infer the Employee's skills. # Overview Source: https://developers.techwolf.ai/reference/latest/Employees/SkillEvents/overview A Skill Event influences the Skillset of an Employee. When an Employee finishes a Course, receives feedback, starts a new function, or when another event occurs that gives additional info to an Employee's Skill Profile, a Skill Event can be generated. Skill Events allow you to monitor the evolution of an Employee's Skill Profile and allow you to pinpoint exactly what Skills your Employees had at a certain time. Skill Events also enable an easy method of adding new information to a profile. Check the how it works article to find out everything you need to know about Skill Events. [How it Works](/technology/skill_events/) # Update Skill Event Source: https://developers.techwolf.ai/reference/latest/Employees/SkillEvents/patch-employees-employee-external-id-skill-events-skill-event-external-id PATCH /employees/{employee_external_id}/skill_events/{skill_event_external_id} Update a Skill Event for an Employee. **Note:** It may take some time for these changes to be reflected in the employee's final skill profile, since they are processed asynchronously. # Create a new Skill Event for an Employee Source: https://developers.techwolf.ai/reference/latest/Employees/SkillEvents/post-employees-employee-external-id-skill-events POST /employees/{employee_external_id}/skill_events Create a new Skill Event for an Employee. This can be used to track the Skill Profile of an Employee over time. **Note:** It may take some time for these changes to be reflected in the employee's final skill profile, since they are processed asynchronously. `ticket`, `merge_request` and business record Skill Events (`it_incident`, `support_ticket`, … — see `GET /skill_event_types`) require model configuration `MC_2025_Q1_V1` or later. On tenants with an older model configuration the request is rejected with a 422 response stating that the model configuration is outdated and asking to upgrade to the latest model configuration. # Delete Job Family Profile Data for a Job Family Source: https://developers.techwolf.ai/reference/latest/Job Families/Job Family Profile Data/delete-job-architecture-job-families-job-family-external-id-profile-data-job-family-profile-data-external-id DELETE /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id} Remove Job Family Profile Data from the system. This step deletes all information linked exclusively to this Job Family Profile Data. It is not possible to delete Skill Profile Feedback via this endpoint, use the Job Family Profile Data Patch endpoint instead. **Note:** It may take some time for these changes to be reflected in the Job Family's final Skill Profile, since they are processed asynchronously. # List Job Family Profile Data Source: https://developers.techwolf.ai/reference/latest/Job Families/Job Family Profile Data/get-job-architecture-job-families-job-family-external-id-profile-data GET /job_architecture/job_families/{job_family_external_id}/profile_data Get a list of all Job Family Profile Data available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get Job Family Profile Data Source: https://developers.techwolf.ai/reference/latest/Job Families/Job Family Profile Data/get-job-architecture-job-families-job-family-external-id-profile-data-job-family-profile-data-external-id GET /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id} Get a single Job Family Profile Data item for a Job Family. # Overview Source: https://developers.techwolf.ai/reference/latest/Job Families/Job Family Profile Data/overview Job Family Profile Data influences the Skillset of a Job Family. Profile Data enables an easy method of adding new information to a Job Family. # Update Job Family Profile Data Source: https://developers.techwolf.ai/reference/latest/Job Families/Job Family Profile Data/patch-job-architecture-job-families-job-family-external-id-profile-data-job-family-profile-data-external-id PATCH /job_architecture/job_families/{job_family_external_id}/profile_data/{job_family_profile_data_external_id} Update Profile Data for a Job Family. # Create Job Family Profile Data for a Job Family Source: https://developers.techwolf.ai/reference/latest/Job Families/Job Family Profile Data/post-job-architecture-job-families-job-family-external-id-profile-data POST /job_architecture/job_families/{job_family_external_id}/profile_data Submit new Job Family Profile Data information to initialise the Job Family inside the Skill Engine API. **Note:** It may take some time for these changes to be reflected in the Job Family's final Skill Profile, since they are processed asynchronously. # Delete Job Family Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyCRUD/delete-job-architecture-job-families-job-family-external-id DELETE /job_architecture/job_families/{job_family_external_id} Delete the Job Family information stored inside the system. By deleting the Job Family, all Job Family Profile Data is also deleted, together with every Job which is linked to this Job Family. # List Job Families Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyCRUD/get-job-architecture-job-families GET /job_architecture/job_families Get a list of all Job Families available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get Job Family Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyCRUD/get-job-architecture-job-families-job-family-external-id GET /job_architecture/job_families/{job_family_external_id} Get the Job Family information stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyCRUD/overview Job Families in the Skill Engine API represent a group of Jobs that are related within your organisation. More info about Job Families can be found at the [Job Architecture Tutorial](/tutorials/job_architecture/overview/). [Custom Properties]() are supported for this entity. # Update Job Family Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyCRUD/patch-job-architecture-job-families-job-family-external-id PATCH /job_architecture/job_families/{job_family_external_id} Submit the most up-to-date Job Family information. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is. # Create Job Family Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyCRUD/post-job-architecture-job-families POST /job_architecture/job_families Submit new Job Family information to initialise their Job Family inside the Skill Engine API. # Get the Skill Profile for a Job Family Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyProfile/get-job-architecture-job-families-job-family-external-id-skill-profile GET /job_architecture/job_families/{job_family_external_id}/skill_profile Get an export of the Job Family Skill Profile to leverage it for user interaction. The response includes both governed and suggested Skills, distinguished by their `validation_state`. # Get the suggested Skill Profile for a Job Family Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyProfile/get-job-architecture-job-families-job-family-external-id-suggested-skill-profile GET /job_architecture/job_families/{job_family_external_id}/suggested_skill_profile **Deprecated:** Use [Get the Skill Profile for a Job Family]() instead. The Skill Profile endpoint returns both governed and suggested Skills, distinguished by their `validation_state`. Get an export of the Job Family Skill Profile to leverage it for user interaction. The suggested Job Family Skill Profile automatically updates with changes to the Job Family Profile Data or Job Profile Data for any of its underlying Jobs. # Partially update a Job Family Skill Profile with feedback Source: https://developers.techwolf.ai/reference/latest/Job Families/JobFamilyProfile/patch-job-architecture-job-families-job-family-external-id-skill-profile PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile Provide feedback about an existing Job Family Skill Profile to update it inside the system. When the `feedback_format` query parameter is `skills`, the body of the feedback message overwrites, adds or updates Skills in the original profile. # Delete Job Profile Data for a Job Source: https://developers.techwolf.ai/reference/latest/Jobs/Job Profile Data/delete-job-architecture-jobs-job-external-id-profile-data-job-profile-data-external-id DELETE /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id} Remove Job Profile Data from the system. This step deletes all information linked exclusively to this Job Profile Data. It is not possible to delete Skill Profile Feedback via this endpoint, use the Job Profile Data Patch endpoint instead. **Note:** It may take some time for these changes to be reflected in the Job's final Skill Profile, since they are processed asynchronously. # List Job Profile Data Source: https://developers.techwolf.ai/reference/latest/Jobs/Job Profile Data/get-job-architecture-jobs-job-external-id-profile-data GET /job_architecture/jobs/{job_external_id}/profile_data Get a list of all Job Profile Data available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get Job Profile Data Source: https://developers.techwolf.ai/reference/latest/Jobs/Job Profile Data/get-job-architecture-jobs-job-external-id-profile-data-job-profile-data-external-id GET /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id} Get a single Job Profile Data item for a Job. # Overview Source: https://developers.techwolf.ai/reference/latest/Jobs/Job Profile Data/overview Job Profile Data influences the skillset of a Job. Profile Data enables an easy method of adding new information to a Job. # Update Job Profile Data Source: https://developers.techwolf.ai/reference/latest/Jobs/Job Profile Data/patch-job-architecture-jobs-job-external-id-profile-data-job-profile-data-external-id PATCH /job_architecture/jobs/{job_external_id}/profile_data/{job_profile_data_external_id} Update Profile Data for a Job. **Note:** It may take some time for these changes to be reflected in the Job's final Skill Profile, since they are processed asynchronously. # Create Job Profile Data for a Job Source: https://developers.techwolf.ai/reference/latest/Jobs/Job Profile Data/post-job-architecture-jobs-job-external-id-profile-data POST /job_architecture/jobs/{job_external_id}/profile_data Submit new Job Profile Data information to initialise the Job inside the Skill Engine API. **Note:** It may take some time for these changes to be reflected in the Job's final Skill Profile, since they are processed asynchronously. # Delete Job Source: https://developers.techwolf.ai/reference/latest/Jobs/JobCRUD/delete-job-architecture-jobs-job-external-id DELETE /job_architecture/jobs/{job_external_id} Delete a Job by its external ID. Delete the Job information stored inside the system. By deleting the Job, all Job Profile Data is also deleted. Recalculates the Job Family Skill Profile if the Job Family is specified for the Job. # List Jobs Source: https://developers.techwolf.ai/reference/latest/Jobs/JobCRUD/get-job-architecture-jobs GET /job_architecture/jobs Get a list of all Jobs available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get Job Source: https://developers.techwolf.ai/reference/latest/Jobs/JobCRUD/get-job-architecture-jobs-job-external-id GET /job_architecture/jobs/{job_external_id} Get a Job by its external ID. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Overview Source: https://developers.techwolf.ai/reference/latest/Jobs/JobCRUD/overview Jobs in the Skill Engine API represent a specific role within your organisation. They are linked to Job Families. More info about Jobs can be found at the [Job Architecture Tutorial](/tutorials/job_architecture/overview/). [Custom Properties]() are supported for this entity. # Update Job Source: https://developers.techwolf.ai/reference/latest/Jobs/JobCRUD/patch-job-architecture-jobs-job-external-id PATCH /job_architecture/jobs/{job_external_id} Update a Job by its external ID. If you change the Job Family, it will result in the loss of all Skills validated for the previous Job Family and the addition of all Skills validated for the new Job Family. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Create Job Source: https://developers.techwolf.ai/reference/latest/Jobs/JobCRUD/post-job-architecture-jobs POST /job_architecture/jobs Submit new Job information to initialise this inside the Skill Engine API. If a Job has a Job Family, the Job Skill Profile will be generated automatically, incorporating all Skills validated for the specified Job Family. # List Job Issues Source: https://developers.techwolf.ai/reference/latest/Jobs/JobIssues/get-job-architecture-issues GET /job_architecture/issues Get a list of the data issues identified for each Job. # Job Issue Summary Source: https://developers.techwolf.ai/reference/latest/Jobs/JobIssues/get-job-architecture-issues-summary GET /job_architecture/issues/summary Get a list of Job issue types with the number of issues per type. # Overview Source: https://developers.techwolf.ai/reference/latest/Jobs/JobIssues/overview A Job Issue represents a data issue identified for a particular job, e.g. a missing or short Job description. # Get the external market Skill Profiles of a Job. Source: https://developers.techwolf.ai/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-market-skill-profiles GET /job_architecture/jobs/{job_external_id}/market_skill_profiles Get a list of external market Skill Profiles for a Job, based on the peer groups defined in the tenant. For every peer group, the Skill Profile is a combination of Profiles found in external market data from the companies in that peer group. # Get the Skill Profile for a Job Source: https://developers.techwolf.ai/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-skill-profile GET /job_architecture/jobs/{job_external_id}/skill_profile Get an export of the Job Skill Profile to leverage it for user interaction. The response includes both governed and suggested Skills, distinguished by their `validation_state`. # Get the suggested Skill Profile for a Job Source: https://developers.techwolf.ai/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-suggested-skill-profile GET /job_architecture/jobs/{job_external_id}/suggested_skill_profile **Deprecated:** Use [Get the Skill Profile for a Job](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-skill-profile) instead. The Skill Profile endpoint returns both governed and suggested Skills, distinguished by their `validation_state`. Get an export of the Job Skill Profile to leverage it for user interaction. The suggested Job Skill Profile automatically updates with changes to the Job Profile Data. # Partially update a Job Skill Profile with feedback Source: https://developers.techwolf.ai/reference/latest/Jobs/JobProfile/patch-job-architecture-jobs-job-external-id-skill-profile PATCH /job_architecture/jobs/{job_external_id}/skill_profile Provide feedback about an existing Job Skill Profile to update it inside the system. When the `feedback_format` query parameter is `skills`, the body of the feedback message will overwrite, add or update Skills in the original profile. This endpoint allows you to validate skills and add/remove properties such as proficiency levels and criticality. # Get the Task Profile for a Job Source: https://developers.techwolf.ai/reference/latest/Jobs/JobTaskProfile/get-job-architecture-jobs-job-external-id-task-profile GET /job_architecture/jobs/{job_external_id}/task_profile ![Experimental](https://img.shields.io/badge/-Experimental-orange) Retrieve the Task Profile associated with a Job. The response contains a list of tasks assigned to the Job. Use the `include` query parameter to optionally expand each task with AI impact information and/or the source data (job profile data entries) that contributed to the task being assigned. **Note:** This endpoint is experimental and may change in future versions. # Provide feedback on tasks in a Job's Task Profile Source: https://developers.techwolf.ai/reference/latest/Jobs/JobTaskProfile/patch-job-architecture-jobs-job-external-id-task-profile PATCH /job_architecture/jobs/{job_external_id}/task_profile ![Experimental](https://img.shields.io/badge/-Experimental-orange) Provide feedback on one or more tasks in a Job's Task Profile. **Note:** This endpoint is experimental and may change in future versions. # Get Taxonomy changes Source: https://developers.techwolf.ai/reference/latest/Taxonomy/Taxonomy/get-taxonomy-changes GET /taxonomy/changes Get a list of changes to the Taxonomy within a certain timeframe. # Overview Source: https://developers.techwolf.ai/reference/latest/Taxonomy/Taxonomy/overview Taxonomy operations can be used to view or edit large parts of the Taxonomy. # Apply Taxonomy changes Source: https://developers.techwolf.ai/reference/latest/Taxonomy/Taxonomy/post-taxonomy-apply POST /taxonomy/apply Apply a set of changes to the Taxonomy in the system. The changes are applied in the order they are given in the request body. # Delete Domain Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomyDomains/delete-taxonomy-domains-domain-external-id DELETE /taxonomy/domains/{domain_external_id} Delete Domain information stored inside the system. By deleting a Domain, all Skill Clusters linked to this Domain are also deleted. # List Domains Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomyDomains/get-taxonomy-domains GET /taxonomy/domains Get a list of all Domains available in the system. # Get Domain Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomyDomains/get-taxonomy-domains-domain-external-id GET /taxonomy/domains/{domain_external_id} Get Domain information stored in the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomyDomains/overview Domains in the Skill Engine API allow enterprise customers to adapt Domains in their Taxonomy. [Custom Properties]() are supported for this entity. # Update Domain Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomyDomains/patch-taxonomy-domains-domain-external-id PATCH /taxonomy/domains/{domain_external_id} Submit the most up-to-date Domain information. Any field that is present will overwrite existing values within the system, while absent fields will be left as is. # Create Domain Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomyDomains/post-taxonomy-domains POST /taxonomy/domains Create a new Domain in the system. # Delete Skill Cluster Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/delete-taxonomy-skill-clusters-skill-cluster-external-id DELETE /taxonomy/skill_clusters/{skill_cluster_external_id} Delete Skill Cluster information stored inside the system. # Remove Skill Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/delete-taxonomy-skill-clusters-skill-cluster-external-id-skills-skill-id DELETE /taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id} Remove a Skill from a Skill Cluster. # List Skill Clusters Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/get-taxonomy-skill-clusters GET /taxonomy/skill_clusters Get a list of all Skill Clusters available in the system. # Get Skill Cluster Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/get-taxonomy-skill-clusters-skill-cluster-external-id GET /taxonomy/skill_clusters/{skill_cluster_external_id} Get the Skill Cluster information stored in the system. # List Skills Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/get-taxonomy-skill-clusters-skill-cluster-external-id-skills GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills Get a list of all Skills linked to a Skill Cluster. # Overview Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/overview Skill Clusters in the Skill Engine API allow enterprise customers to adapt Skill Clusters in their Taxonomy. [Custom Properties]() are supported for this entity. # Update Skill Cluster Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/patch-taxonomy-skill-clusters-skill-cluster-external-id PATCH /taxonomy/skill_clusters/{skill_cluster_external_id} Submit the most up-to-date Skill Cluster information. Any field that is present will overwrite existing values within the system, while absent fields will be left as is. # Create Skill Cluster Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/post-taxonomy-skill-clusters POST /taxonomy/skill_clusters Create a new Skill Cluster in the system that is linked to a Domain or Subdomain. A Skill Cluster must be linked to a Domain in a 3-level Taxonomy, and it can only be linked to a Subdomain in a 4-level Taxonomy. # Add Skill Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkillClusters/put-taxonomy-skill-clusters-skill-cluster-external-id-skills-skill-id PUT /taxonomy/skill_clusters/{skill_cluster_external_id}/skills/{skill_id} Add a Skill to a Skill Cluster. # Delete Skill Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkills/delete-taxonomy-skills-skill-id DELETE /taxonomy/skills/{skill_id} Delete the Skill identified by the `skill_id` from the vocabulary. This operation cannot be undone. This step deletes all information linked exclusively to this Skill. By deleting a Skill, you delete it from all Skill Clusters and Skill Profiles containing it. This endpoint requires write_skills scope access. Please note that it is only possible to delete Skills flagged as `custom`. # List Skills Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills GET /taxonomy/skills Get the Skill information stored inside the system for multiple Skills. # List available Skill languages Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-languages GET /taxonomy/skills/languages Get the list of languages available for Skills in the tenant's vocabulary. The available languages depend on the vocabulary version associated with the specified external vendor. # Get Skill Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-skill-id GET /taxonomy/skills/{skill_id} Get the Skill information stored in the vocabulary. This can be for either a Skill in the TechWolf vocabulary or a Skill in an external vendor's vocabulary. For TechWolf Skills, meta information such as Skill adoption can also be requested. # Overview Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkills/overview Skills in the Skill Engine API allow enterprise customers to get Skills in their Taxonomy. [Custom Properties]() are supported for this entity. # Update Skill Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkills/patch-taxonomy-skills-skill-id PATCH /taxonomy/skills/{skill_id} Update the Skill information stored in the vocabulary. To add or update translations, set the `vocab_language` query parameter to the desired language. This can be for either a TechWolf Skill, a Skill in an external vendor's vocabulary, or a custom Skill. To revert to the default name or description provided by TechWolf, set the `skill_name` or `skill_description` field to null. It is not possible to revert the name or description of a custom Skill in the default (en_uk) language. # Create Skill Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySkills/post-taxonomy-skills POST /taxonomy/skills Create a new Skill in the system. This endpoint requires write_skills scope access. The new Skill will be flagged as `custom`. # Delete Subdomain Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySubdomains/delete-taxonomy-subdomains-subdomain-external-id DELETE /taxonomy/subdomains/{subdomain_external_id} Delete Subdomain information stored inside the system. # List Subdomains Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySubdomains/get-taxonomy-subdomains GET /taxonomy/subdomains Get a list of all Subdomains available in the system. # Get Subdomain Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySubdomains/get-taxonomy-subdomains-subdomain-external-id GET /taxonomy/subdomains/{subdomain_external_id} Get the Subdomain information stored in the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySubdomains/overview Subdomains in the Skill Engine API allow enterprise customers to adapt Subdomains in their Taxonomy. > [!WARNING] > > By default, **Subdomains are disabled**. The 3-level Taxonomy only consists of > Domains, Skill Clusters and Skills. Enabling Subdomains allows a 4-level > Taxonomy consisting of Domains, Subdomains, Skill Clusters and Skills. To enable > Subdomains on your tenants, contact [support@techwolf.ai](mailto:support@techwolf.ai)! [Custom Properties]() are supported for this entity. # Update Subdomain Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySubdomains/patch-taxonomy-subdomains-subdomain-external-id PATCH /taxonomy/subdomains/{subdomain_external_id} Submit the most up-to-date Subdomain information. Any field that is present will overwrite existing values within the system, while absent fields will be left as is. # Create Subdomain Source: https://developers.techwolf.ai/reference/latest/Taxonomy/TaxonomySubdomains/post-taxonomy-subdomains POST /taxonomy/subdomains Create a new Subdomain in the system that is linked to a Domain. # Delete Course Source: https://developers.techwolf.ai/reference/latest/Courses/CourseCRUD/delete-courses-external-id DELETE /courses/{external_id} Remove a Course from the system. This step deletes all information linked exclusively to this Course and cannot be undone. # List Courses Source: https://developers.techwolf.ai/reference/latest/Courses/CourseCRUD/get-courses GET /courses Get a list of all Courses available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get Course Source: https://developers.techwolf.ai/reference/latest/Courses/CourseCRUD/get-courses-external-id GET /courses/{external_id} Get the Course information stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Courses/CourseCRUD/overview Courses in the Skill Engine API correspond to internal/external training or education. More info about entities can be found on the [How it Works page](/technology/entities/). [Custom Properties]() are supported for this entity. # Update Course Source: https://developers.techwolf.ai/reference/latest/Courses/CourseCRUD/patch-courses-external-id PATCH /courses/{external_id} Submit the most up-to-date Course information to update their profile inside the system. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is. # Create Course Source: https://developers.techwolf.ai/reference/latest/Courses/CourseCRUD/post-courses POST /courses Submit new Course information to initialise its Skill Profile inside the Skill Engine API. # Get Course count Source: https://developers.techwolf.ai/reference/latest/Courses/CourseMetrics/get-courses-metrics-count GET /courses/metrics/count Get the total number of Course objects stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Courses/CourseMetrics/overview A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . # Get the Skill Profile for a Course Source: https://developers.techwolf.ai/reference/latest/Courses/CourseProfile/get-courses-external-id-skill-profile GET /courses/{external_id}/skill_profile Get an export of the Course Skill Profile to leverage it for user interaction. Check our tutorials for a clear overview of how to get the most out of each format! # Update a Course Skill Profile with feedback Source: https://developers.techwolf.ai/reference/latest/Courses/CourseProfile/patch-courses-external-id-skill-profile PATCH /courses/{external_id}/skill_profile Provide feedback about an existing Course Skill Profile to update it inside the system. When the `feedback_format` query parameter is `skills`, the body of the feedback message updates the existing Skill Profile, so if a Skill is not present in the body, it will not be affected. The feedback can contain updates that either validate or remove the Skill. # Remove a Custom Property Definition from the system Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesDefinitions/delete-entity-type-custom-properties-property-name DELETE /{entity_type}/custom_properties/{property_name} Remove a Custom Property Definition from the system. # Get all Custom Property Definitions Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesDefinitions/get-entity-type-custom-properties GET /{entity_type}/custom_properties Get a list of all the Custom Property Definitions stored inside the system. # Get Custom Property Definition Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesDefinitions/get-entity-type-custom-properties-property-name GET /{entity_type}/custom_properties/{property_name} Get the Custom Property Definition information stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesDefinitions/overview Custom Properties within the Skill Engine API offer users the capability to finely customize attributes for a wide array of entities, including: * [taxonomy/domains](/reference/latest/Taxonomy/TaxonomyDomains) * [taxonomy/subdomains](/reference/latest/Taxonomy/TaxonomySubdomains) * [taxonomy/skill\_clusters](/reference/latest/Taxonomy/TaxonomySkillClusters) * [taxonomy/skills](/reference/latest/Taxonomy/TaxonomySkills) * [employees](/reference/latest/Employees) * [organisational\_units]() * [job\_architecture/job\_families]() * [job\_architecture/jobs](/reference/latest/Jobs) * [vacancies](/reference/latest/Vacancies) * [courses](/reference/latest/Courses) * [skill\_clusters]() * [companies]() More info about entities can be found on the [How it Works page](/technology/entities/). # Rename a Custom Property Definition Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesDefinitions/patch-entity-type-custom-properties-property-name PATCH /{entity_type}/custom_properties/{property_name} Rename a Custom Property Definition. # Create a Custom Property Definition Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesDefinitions/post-entity-type-custom-properties POST /{entity_type}/custom_properties Create a new Custom Property Definition in the system. # Delete all Custom Properties of an entity Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesProperties/delete-entity-type-entity-type-external-id-custom-properties DELETE /{entity_type}/{entity_type_external_id}/custom_properties Drop all entity's Custom Properties from the system (if any exists). # Retrieve all Custom Properties of an entity Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesProperties/get-entity-type-entity-type-external-id-custom-properties GET /{entity_type}/{entity_type_external_id}/custom_properties Fetch all entity's Custom Properties from the system (if any exists, otherwise an empty list is returned). # Update Custom Properties of an entity Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesProperties/patch-entity-type-entity-type-external-id-custom-properties PATCH /{entity_type}/{entity_type_external_id}/custom_properties In addition to the default fields available for each entity, a set of Custom Properties can be added. Each entity is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters). # Replace Custom Properties of an entity Source: https://developers.techwolf.ai/reference/latest/Custom Properties/CustomPropertiesProperties/put-entity-type-entity-type-external-id-custom-properties PUT /{entity_type}/{entity_type_external_id}/custom_properties In addition to the default fields available for each entity, a set of Custom Properties can be added. Each entity is allowed to have a maximum of 100 properties, with properties being numbers or strings (maximum length 1000 characters). # Delete External Company Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/delete-companies-external-id DELETE /companies/{external_id} Remove an External Company from the system. The External Company's linked Vacancies will be processed in cascade based on: * linked __active__ Vacancy: the reference to the External Company is removed, but the Vacancy itself is not removed from the system. * linked __inactive__ Vacancy: the reference to the External Company as well as the Vacancy itself is removed from the system. # List External Companies Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/get-companies GET /companies Get a list of all External Companies available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get External Company Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/get-companies-external-id GET /companies/{external_id} Get the External Company information stored inside the system. # List External Company's Vacancies Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/get-companies-external-id-vacancies GET /companies/{external_id}/vacancies Get an overview of all the Vacancies stored inside the system that are linked to the specified External Company. # Overview Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/overview An External Company in the Skill Engine API represents **any external company**. They can be used to match against, using the Vacancies that are linked to them. Employment and staffing customers can match candidates with external companies, even when they do not have an explicitly advertised position. Enterprise customers can use External Companies too to profile and compare themselves to other External Companies. More info about External Companies can be found on the [How it Works page](/technology/companies/) and the [External Company tutorial](/tutorials/companies/overview/). [Custom Properties]() are supported for this entity. # Update External Company Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/patch-companies-external-id PATCH /companies/{external_id} Submit the most up-to-date External Company information to update the information stored inside the system. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is. # Create External Company Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/post-companies POST /companies Submit new External Company information to store inside the Skill Engine API. # Upload and add desired functions Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/post-companies-external-id-desired-functions POST /companies/{external_id}/desired_functions Upload a list of desired functions that will be created as inactive pseudo Vacancies linked to the External Company. If no Skill Profile can be created from the Job title alone, the desired function will not be stored. The desired function Vacancies will be added to the already existing desired function Vacancies of the External Company. # Profile External Company's hiring activity with NACE-codes Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/post-companies-external-id-nace POST /companies/{external_id}/nace Profiles the market-average hiring activity of an External Company based on their linked NACE-codes by creating corresponding pseudo-Vacancies in the system. This operation is **additive** and remembers previously profiled pseudo-Vacancies. # Replace existing desired functions Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/put-companies-external-id-desired-functions PUT /companies/{external_id}/desired_functions Replace the list of desired functions that are used as inactive pseudo Vacancies linked to the External Company. If no Skill Profile can be created from the Job title alone, the desired function will not be stored. Previously existing desired function Vacancies will be removed when using this endpoint. # Reprofile External Company's hiring activity with NACE-codes Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanyCRUD/put-companies-external-id-nace PUT /companies/{external_id}/nace Profiles the market-average hiring activity of an External Company based on their linked NACE-codes by creating corresponding pseudo-Vacancies in the system. This operation is **substituting** and replaces previously profiled pseudo-Vacancies. # Search for External Companies based on free text Source: https://developers.techwolf.ai/reference/latest/External Companies/CompanySearch/post-companies-search POST /companies/search Search for External Companies # List Job Architecture Changes Source: https://developers.techwolf.ai/reference/latest/Jobs/JobChanges/get-job-architecture-changes GET /job_architecture/changes Get a list of Job architecture changes with optional filtering by Job IDs. # Get Job Architecture Change Details Source: https://developers.techwolf.ai/reference/latest/Jobs/JobChanges/get-job-architecture-changes-change-id GET /job_architecture/changes/{change_id} Get detailed information about a specific Job architecture change. # Get Job Architecture Changes Summary Source: https://developers.techwolf.ai/reference/latest/Jobs/JobChanges/get-job-architecture-changes-summary GET /job_architecture/changes/summary Get a summary overview of Job architecture changes, including counts and statistics. # Overview Source: https://developers.techwolf.ai/reference/latest/Jobs/JobChanges/overview Job changes represent data changes that were suggested and/or applied to Jobs in the Job Architecture. # Bulk Update Job Architecture Changes Source: https://developers.techwolf.ai/reference/latest/Jobs/JobChanges/patch-job-architecture-changes PATCH /job_architecture/changes Update multiple Job architecture changes at once by providing a list of change IDs and the new status. # Update Job Architecture Change Source: https://developers.techwolf.ai/reference/latest/Jobs/JobChanges/patch-job-architecture-changes-change-id PATCH /job_architecture/changes/{change_id} Update a specific Job architecture change with new data. # Bulk generate Job changes Source: https://developers.techwolf.ai/reference/latest/Jobs/JobChanges/post-job-architecture-changes POST /job_architecture/changes Start a batch generation of Job changes for specified Jobs. # Generate preview Job change Source: https://developers.techwolf.ai/reference/latest/Jobs/JobChanges/post-job-architecture-changes-preview POST /job_architecture/changes/preview Generate a preview Job change for a specific Job. # Overview Source: https://developers.techwolf.ai/reference/latest/Jobs/JobMetrics/overview A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . # Get Job adoption metrics Source: https://developers.techwolf.ai/reference/latest/Jobs/JobMetrics/post-job-architecture-jobs-metrics-adoption-metrics POST /job_architecture/jobs/metrics/adoption_metrics Get adoption metrics across a collection of Job objects stored in the system, aggregated over their Skills and your Taxonomy. # Overview Source: https://developers.techwolf.ai/reference/latest/Jobs/JobSuggestions/overview Job architecture suggestions represent AI-generated recommendations for changes to job skill profiles, such as adding or removing skills, or updating proficiency levels and criticality flags. # Bulk Accept or Reject Job Architecture Suggestions Source: https://developers.techwolf.ai/reference/latest/Jobs/JobSuggestions/post-job-architecture-suggestions-interactions POST /job_architecture/suggestions/interactions Accept or reject multiple suggestions in a single request. Use the `category` query parameter to choose between skill suggestions (default) and task suggestions. **Skill suggestions** (`category=skills`): When a skill suggestion is accepted, the corresponding change is applied to the job's governed skill profile: - `add_job_skill`: Adds the skill to the job's skill profile with `validation_state: validated` - `remove_job_skill`: Marks the skill as rejected on the job's skill profile - `set_job_skill_proficiency`: Updates the skill's proficiency level - `set_job_skill_criticality`: Updates the skill's critical flag **Task suggestions** (`category=tasks`): When a task suggestion is accepted, the task is added to the job's task profile: - `add_job_task`: Adds the task to the job's task profile The `data.weekly_hours` field is required for all task suggestion interactions. **Side Effects (skill suggestions only):** - Accepting a `set_job_skill_proficiency` or `set_job_skill_criticality` suggestion will automatically accept the corresponding `add_job_skill` suggestion for the same skill if it exists. **Overriding Values (skill suggestions only):** - When accepting a `set_job_skill_proficiency` suggestion, you can optionally provide a different `proficiency_level` in the `data` field to override the suggested value. - When accepting a `set_job_skill_criticality` suggestion, you can optionally provide a different `critical` value in the `data` field to override the suggested value. # Get Course recommendations to improve the Skill Profile of an Employee Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Course Recommendations/get-employees-employee-external-id-recommended-courses GET /employees/{employee_external_id}/recommended_courses # Get Course recommendations to bridge the Skill gap between an Employee and a Job Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Course Recommendations/post-employees-employee-external-id-jobs-job-external-id-recommended-courses POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses Courses that are connected through a SkillEvent with the Employee, indicating that the Employee has already taken the Course, are excluded from the recommendations. Additionally, Courses of which the `active` attribute is set to `false` are filtered out as well. # Get Course recommendations to improve the Skill Profile of an Employee Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Course Recommendations/post-employees-employee-external-id-recommended-courses POST /employees/{employee_external_id}/recommended_courses Courses that are connected through a SkillEvent with the Employee, indicating that the Employee has already taken the Course, are excluded from the recommendations. Additionally, Courses of which the `active` attribute is set to `false` are filtered out as well. # Get Course recommendations to bridge the Skill gap between an Employee and a Vacancy Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Course Recommendations/post-employees-employee-external-id-vacancies-vacancy-external-id-recommended-courses POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses Courses that are connected through a SkillEvent with the Employee, indicating that the Employee has already taken the Course, are excluded from the recommendations. Additionally, Courses of which the `active` attribute is set to `false` are filtered out as well. # Find the best Employees for a given External Company Source: https://developers.techwolf.ai/reference/latest/Matchmaking/External Company Matching/post-companies-external-id-matching-employees POST /companies/{external_id}/matching_employees You can use filters in the request body to restrict the match results based on distance, language & Custom Properties. If the `max_geo_distance` filter is not provided, a default value of 50km is used. # Find the best External Companies for a given Employee Source: https://developers.techwolf.ai/reference/latest/Matchmaking/External Company Matching/post-employees-external-id-matching-companies POST /employees/{external_id}/matching_companies You can use filters in the request body to restrict the match results based on distance, language & Custom Properties. If the `max_geo_distance` filter is not provided, a default value of 50km is used. # Get the match score between an Employee and a Job Family Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Family Matching/get-employees-employee-external-id-job-families-job-family-external-id-match GET /employees/{employee_external_id}/job_families/{job_family_external_id}/match # Get the task-based match score between two Job Families Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Family Matching/get-job-architecture-job-families-job-family-external-id-job-families-other-job-family-external-id-task-match GET /job_architecture/job_families/{job_family_external_id}/job_families/{other_job_family_external_id}/task_match Get the symmetric task-based match score between two Job Families, computed from their merged member-Job task profiles. The score is an hours-weighted, continuous task similarity, harmonic-meaned across both directions, and is symmetric: swapping the two Job Families yields the same score. # Get the top matching Job Families for an Employee Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Family Matching/post-employees-external-id-matching-job-families POST /employees/{external_id}/matching_job_families Get an export of the best matching Job Families for an Employee. Only active Job Families are included in the results. # Get the top matching Employees for a Job Family Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Family Matching/post-job-architecture-job-families-external-id-matching-employees POST /job_architecture/job_families/{external_id}/matching_employees # Get the match score between an Employee and a Job Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/get-employees-employee-external-id-jobs-job-external-id-match GET /employees/{employee_external_id}/jobs/{job_external_id}/match # Get the match score between an Employee and their assigned position Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/get-employees-employee-external-id-match-assigned-position GET /employees/{employee_external_id}/match_assigned_position # Get the match scores between a Job and its market Skill Profiles Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/get-job-architecture-jobs-external-id-market-alignment GET /job_architecture/jobs/{external_id}/market_alignment We calculate two types of match scores for every Skill Profile in the market, linked to a peer group. More information about external market Skill Profiles can be found in the documentation of the relevant [endpoint](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-market-skill-profiles). The Job to peer score indicates how well the Job Skill Profile covers the Skill requirement of the external market Skill Profile of a certain peer group. The second score is the peer to Job score, which indicates how well the market Skill Profile of a peer group covers the Skill requirements of the Job Skill Profile. The higher the score, the better the match. # Get the task-based match score between two Jobs Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/get-job-architecture-jobs-job-external-id-jobs-other-job-external-id-task-match GET /job_architecture/jobs/{job_external_id}/jobs/{other_job_external_id}/task_match Get the symmetric task-based match score between two Jobs, computed from their task profiles. The score is an hours-weighted, continuous task similarity, harmonic-meaned across both directions, and is symmetric: swapping the two Jobs yields the same score. # Get the top matching Jobs for an Employee Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/post-employees-external-id-matching-jobs POST /employees/{external_id}/matching_jobs Get an export of the best matching Jobs for an Employee. Only active Jobs are included in the export. The Employee's current Job is excluded from the results. # Get the top matching Employees for a Job Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/post-job-architecture-jobs-external-id-matching-employees POST /job_architecture/jobs/{external_id}/matching_employees Get an export of the best matching Employees for a Job. Only active Employees are included in the export. The Employees that have the Job assigned are excluded from the results. # Get the most relevant jobs from which can be hired for the given job. Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/post-job-architecture-jobs-external-id-matching-source-jobs POST /job_architecture/jobs/{external_id}/matching_source_jobs Identify the most relevant jobs from which potential candidates can be hired to fill the given job's skill requirements. Relevant for succession planning. Only active Jobs are included in the results. # Get the most relevant jobs to which can be moved from the given job. Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/post-job-architecture-jobs-external-id-matching-target-jobs POST /job_architecture/jobs/{external_id}/matching_target_jobs Identify the most relevant jobs to which employees in the given job can be moved based on job skill requirements. Relevant for career development and internal mobility opportunities. Only active Jobs are included in the results. # Get the most task-relevant Jobs to the given Job Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks POST /job_architecture/jobs/{job_external_id}/matching_jobs_by_tasks Identify the Jobs whose task profiles best match the given Job's task profile, ranked by symmetric task-match score (descending). The score is an hours-weighted, continuous task similarity, harmonic-meaned across both directions. Whether suggested tasks contribute alongside validated tasks is governed by the tenant's `tasks_on_jobs` setting. Results are subject to a result-level minimum score: matches scoring below 0.30 are not returned. A Job whose best match falls below this floor returns an empty result list rather than a weak, potentially misleading ranking. # Get the match score between an Employee and a Vacancy Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy Matching/get-employees-employee-external-id-vacancies-vacancy-external-id-match GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match # Overview Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy Matching/overview The Skill Engine API allows you to fetch matching entities and External Companies with a wide range of different configurations. The system leverages a set of *filters* (constraints that are applied before matching, making a binary decision for each entity whether they should be considered) and *weights* (reweighting of the match scores) to let you tailor results to your wishes. You can find more information about how filters work [here](). Match results can be queried in a paginated manner, allowing you to iteratively fetch all relevant results for a match query using the common `limit` and `offset` setup. Under the hood, the Skill Engine API uses a two-step process to enable paginated results: first, *approximate matching* is applied to create an initial ordering of results, followed by *refinement* of these results into the final scores. The ordering of the results, and therefore also the contents of any given page, are determined entirely by the approximate matching. This allows us to provide high volumes of matches without the delay caused by refining all possible matches for every single query. As approximate and refined scores can in some cases deviate from each other slightly, it is expected that in some cases the last result of a given page can have a lower score than the first result of the next -- if this is problematic for your use case (i.e. you want the exact top 10), then we recommend using a higher limit and trimming down results, as this suffices to capture any reordering caused by refinement. By default, a geographic distance filter is applied by default such that only entities within a 50 km range are considered. This range can be adapted by configuring the `max_geo_distance` filter. To retain fast response times, any matching request that has more than 10.000 entities fulfilling all filter criteria will be cut off at the 10.000 entities that are geographically closest to the search point. # Get the top matching Vacancies for an Employee Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy Matching/post-employees-external-id-matching-vacancies POST /employees/{external_id}/matching_vacancies You can use filters in the request body to restrict the match results based on distance, language & Custom Properties. If the `max_geo_distance` filter is not provided, a default value of 50km is used. Only active Vacancies are included in the results. # Get the top matching Employees for a Vacancy. Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy Matching/post-vacancies-external-id-matching-employees POST /vacancies/{external_id}/matching_employees You can use filters in the request body to restrict the match results based on distance, language & Custom Properties. If the `max_geo_distance` filter is not provided, a default value of 50km is used. # Delete Organisational Unit Source: https://developers.techwolf.ai/reference/latest/Organisational Structure/OrganisationalUnits/delete-organisational-units-external-id DELETE /organisational_units/{external_id} Remove an Organisational Unit and all its subordinate units from the system. This action will remove all information associated exclusively with these units and cannot be undone. # List Organisational Units Source: https://developers.techwolf.ai/reference/latest/Organisational Structure/OrganisationalUnits/get-organisational-units GET /organisational_units Get a list of all Organisational Units available in the system. # Get Organisational Unit Source: https://developers.techwolf.ai/reference/latest/Organisational Structure/OrganisationalUnits/get-organisational-units-external-id GET /organisational_units/{external_id} Get the Organisational Unit information stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Organisational Structure/OrganisationalUnits/overview Organisational Units in the Skill Engine API represent groupings of Employees arranged in a hierarchical structure. [Custom Properties]() are supported for this entity. # Update Organisational Unit Source: https://developers.techwolf.ai/reference/latest/Organisational Structure/OrganisationalUnits/patch-organisational-units-external-id PATCH /organisational_units/{external_id} Submit the most up-to-date Organisational Unit information. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is. # Create Organisational Unit Source: https://developers.techwolf.ai/reference/latest/Organisational Structure/OrganisationalUnits/post-organisational-units POST /organisational_units Create a new Organisational Unit in the Skill Engine API. # List Peer Groups Source: https://developers.techwolf.ai/reference/latest/Peer Groups/PeerGroups/get-job-architecture-peer-groups GET /job_architecture/peer_groups Get a list of all the actived peer groups and the companies within them. # Overview Source: https://developers.techwolf.ai/reference/latest/Peer Groups/PeerGroups/overview A peer group consists of a list of companies used to create external market Skill Profiles for Jobs. More information about external market Skill Profiles can be found in the documentation of the relevant [endpoint](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-market-skill-profiles). # List Skill Clusters Source: https://developers.techwolf.ai/reference/latest/Skill Clusters/SkillClusterCRUD/get-skill-clusters GET /skill_clusters Get a list of all Skill Clusters available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get Skill Cluster Source: https://developers.techwolf.ai/reference/latest/Skill Clusters/SkillClusterCRUD/get-skill-clusters-external-id GET /skill_clusters/{external_id} Get the Skill Cluster information stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Skill Clusters/SkillClusterCRUD/overview Skill Clusters in the Skill Engine API allow enterprise customers to use their own Skill Cluster framework. More info about Skill Clusters can be found at the [How it Works page](/technology/skill-clusters/) and the [Skill Cluster Tutorial](/tutorials/skill-clusters/overview/). [Custom Properties]() are supported for this entity. # Get Skill Cluster count Source: https://developers.techwolf.ai/reference/latest/Skill Clusters/SkillClusterMetrics/get-skill-clusters-metrics-count GET /skill_clusters/metrics/count Get the total number of Skill Cluster objects stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Skill Clusters/SkillClusterMetrics/overview A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . # Get the Skill Profile for a Skill Cluster Source: https://developers.techwolf.ai/reference/latest/Skill Clusters/SkillClusterProfile/get-skill-clusters-external-id-skill-profile GET /skill_clusters/{external_id}/skill_profile Get an export of the Skill Cluster Skill Profile to leverage it for user interaction. # Get the Skillgap between an Employee and a Vacancy Source: https://developers.techwolf.ai/reference/latest/Skills/Skill Gaps/get-employees-employee-external-id-vacancies-vacancy-external-id-gap GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/gap # Look up the Skill IDs of a list of Skill names Source: https://developers.techwolf.ai/reference/latest/Skills/Skill Lookup/post-skills-lookup POST /skills/lookup # Search for Skills similar to the text provided Source: https://developers.techwolf.ai/reference/latest/Skills/Skill Search/get-skills-search GET /skills/search # Search Tasks Source: https://developers.techwolf.ai/reference/latest/Tasks/TaskSearch/get-tasks-search GET /tasks/search ![Experimental](https://img.shields.io/badge/-Experimental-orange) Search for Tasks using a fuzzy text query. Results are ordered by similarity to the query string (highest first). Low-confidence matches are excluded. Useful for looking up tasks by name when building or updating task profiles. **Note:** This endpoint is experimental and may change in future versions. # Validate Tasks Source: https://developers.techwolf.ai/reference/latest/Tasks/TaskValidation/post-tasks-validate POST /tasks/validate Validate a batch of 1-15 candidate Task names before persisting them, without creating anything. Each candidate is screened with fast whole-string quality heuristics and a near-duplicate lookup against your existing Tasks. - **Quality heuristics** are hard rejections. A candidate that trips one or more heuristics gets `status: "rejected:formatting"` and a `rejection_reasons` list naming the failing codes (`too_short`, `too_long`, `too_few_words`, `low_letter_ratio`). - **Near-duplicate detection** is advisory only. `similar_tasks` lists existing Tasks similar to the candidate (highest similarity first), populated only for candidates that pass the quality heuristics and empty otherwise. It never rejects on its own, so the caller decides whether a match is a true duplicate. A candidate that passes the heuristics has `status: "valid"` and an empty `rejection_reasons`, even when `similar_tasks` is non-empty. # Delete a custom Task Source: https://developers.techwolf.ai/reference/latest/Tasks/TasksCRUD/delete-tasks-task-id DELETE /tasks/{task_id} Delete a custom Task from the catalogue. Only Tasks with `task_source: "custom"` can be deleted. Standard Tasks (`task_source: "vocabulary"`) return `403`. After deletion, the Task no longer appears in any Job or Employee task profile. # Get a Task Source: https://developers.techwolf.ai/reference/latest/Tasks/TasksCRUD/get-tasks-task-id GET /tasks/{task_id} Fetch a single Task by its `task_id`. The `task_id` of Tasks can be found via the task search or task export endpoints. For custom Tasks, the `POST /tasks` endpoint also returns the associated `task_id`. By default the response contains only `task_id` and `task_name`; request additional attributes via `include`. # Create a custom task Source: https://developers.techwolf.ai/reference/latest/Tasks/TasksCRUD/post-tasks POST /tasks Create a new custom Task in the catalogue. The `task_id` is derived deterministically from `task_name`, so re-submitting the same name returns `409`. Custom Tasks are immediately matchable. # Delete Vacancy Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyCRUD/delete-vacancies-external-id DELETE /vacancies/{external_id} Remove a Vacancy from the system. This step deletes all information linked exclusively to this Vacancy. If these need to be removed as well, make sure to do this separately. By deleting a Vacancy, you delete their Skill Profile history, which cannot be recreated or recovered afterwards. # List Vacancies Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyCRUD/get-vacancies GET /vacancies Get a list of all Vacancies available in the system. This can for example be used to keep track of proper synchronisation between your system and the Skill Engine API. # Get Vacancy Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyCRUD/get-vacancies-external-id GET /vacancies/{external_id} Get the Vacancy information stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyCRUD/overview Vacancies in the Skill Engine API correspond to Job postings or open positions. More info about entities can be found on the [How it Works page](/technology/entities/). [Custom Properties]() are supported for this entity. # Update Vacancy Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyCRUD/patch-vacancies-external-id PATCH /vacancies/{external_id} Submit the most up-to-date Vacancy information to update their profile inside the system. Any field that is present will overwrite existing values within the system, while absent fields will be left as-is. Passing the `null` value removes non-required attributes. Object attributes will be removed when passing `null`, arrays with `[]` and strings with the empty string `''`. # Create Vacancy Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyCRUD/post-vacancies POST /vacancies Submit new Vacancy information to initialise their Skill Profile inside the Skill Engine API. # Get Vacancy count Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyMetrics/get-vacancies-metrics-count GET /vacancies/metrics/count Get the total number of Vacancy objects stored inside the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyMetrics/overview A metric is a single number representing some amount of information about an entity or a collection of entities of the same type. More info about Metrics can be found on the [How it Works page](/technology/metrics-reports/) . # Get the Skill Profile for a Vacancy Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyProfile/get-vacancies-external-id-skill-profile GET /vacancies/{external_id}/skill_profile Get an export of the Vacancy Skill Profile to leverage it for user interaction. Check our tutorials for a clear overview of how to get the most out of each format! # Update a Vacancy Skill Profile with feedback Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancyProfile/patch-vacancies-external-id-skill-profile PATCH /vacancies/{external_id}/skill_profile Provide feedback about an existing Vacancy Skill Profile to update it inside the system. When the `feedback_format` query parameter is `skills`, the body of the feedback message updates the existing Skill Profile, so if a Skill is not present in the body, it will not be affected. The feedback can contain updates that either validate or remove the Skill. # Search for Vacancies based on free text Source: https://developers.techwolf.ai/reference/latest/Vacancies/VacancySearch/post-vacanies-search POST /vacanies/search Search for Vacancies. Unlike other entities, searching happens based on the `job_title` text match by default, not based on Skills match. Literal string matching is fuzzy, meaning that typo's and misspellings should still turn up desired results. For example, searching for `deceptionist` could still show `receptionist` Vacancy results. Literal search will always result in a score of `1.0`. A combination of both types is possible. # Key concepts Source: https://developers.techwolf.ai/integrations/datasource-integrations/datasources-key-concepts Datasource integrations play a crucial role in populating the TechWolf SkillEngine API with data from different systems. This document outlines our **vision** for datasource integrations, explains the differences between file‑based and API‑based integrations, and clarifies what is **possible** with our current datasource integration offering. To build your own datasource integration, see the [Datasource Integration Guide](/integrations/datasource-integrations/how-to-datasource-integration). It provides an overview of how TechWolf integrates datasources and explains the challenges involved. ## Vision At TechWolf, our vision for datasource integrations is to make unstructured and semi-structured data usable for skill inference, optimizing for **time-to-value**, and **minimal back-and-forth communication**, both on TechWolf's side and the customer's. We aim to: * Accept the variability of real-world enterprise data. * Enable low-friction, high-trust integrations, especially for customers without resources to build their own integrations. * Build highly specialized connectors for common use cases, and standardize platforms through file‑based integrations to increase coverage. * Make it easy to onboard, maintain, and evolve integrations across different data types. * Ensure integrations can also be built by customers; we use our own API to ingest data. ## File-based vs API-based integrations File‑based integrations ingest data from files exported by the source system, either directly or via other export methods (e.g., API exports). Examples of file-based integrations: * Workday EIB exports * SAP Integration Center or Report Center export integrations * Jira ticket exports to CSV API‑based integrations pull data from a source API or react to webhooks, and submit that data to a destination API. Examples of API‑based integrations: * Workday SOAP API syncs * Consuming Jira webhooks * Consuming GitHub webhooks A comparative table: | | File-based | API-based | | - | - | - | | Destination | TechWolf API | TechWolf API | | Format | CSV, Parquet, etc. | JSON, XML, etc. | | Ingestion strategy | Work with files | Consume API or webhooks | | Frequency | Daily, weekly, etc. | Real-time, or also daily, weekly, etc. | | Volume | Limits apply to destination API | Both source and destination API limits apply | | Eventual consistency | Easier: you can combine files to produce complete datasets | Harder: you must track failures somewhere (in files or other storage) | | Maintenance | Keep file formats consistent | Keep up with development of the source API | | Observability | Files clearly indicate the data to be synced | API logs and monitoring track what data leaves the source system | | Reusability | Files are always required, but loading functionality is reusable across sources | Easy to build a common foundation, but each source must be re‑implemented | ## What is possible today? ### Standardized Integrations See our [Integrations Overview](/integrations/overview) of the standardized integrations we offer, such as Workday or SAP. We will continue building these standardized integrations, to provide the best onboarding and integration experience for our customers. ### Other platforms While we have standardized integrations for specific platforms that provide optimized data processing and seamless connectivity, TechWolf's flexible file-based integration approach allows us to ingest data from virtually any business system, for example: * Your company's custom learning platform * Salesforce data * ServiceNow * ... If there is a file for it, we can ingest it into the TechWolf API. ### Supported Data Types To see which types of data we currently support, we refer to the [API Documentation](/reference). If your data can map to the API, we can ingest it through file-based integrations. For example, to see which fields of courses can be ingested, see the [Courses API](/reference/latest/Courses/CourseCRUD/overview). ### Supported File Types We currently only support `.csv` files for standard integrations. If you need to ingest other file types, please reach out to us. # How To: Load Export Integration Definitions Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions **1. Go to the Integration Center** To go to the Integration Center, enter `Integration Center` in the search bar at the top of the screen. **2. Import the integration definition** In the Integration Center, click `My Integrations`. In the resulting page, click the `Create` button at the top of the screen and select `Import an Integration Definition`. **3. Upload the desired integration definition** In the popup that opens, upload the correct `.icd` file containing the integration definition and click `upload`. If a warning pops up, click `OK`. **4. Leave the Options page, Configure Fields page and Filter and Sort pages as is** The Options page, Configure Fields page, and the Filter and Sort page should not be modified. **5. Fill in the destination settings** On the destination settings page, fill in the following: * Server details (Host and Port) can be found at [SFTP server ](/integrations/reference/sftp/sftp#server-details) * Authentication Type: `Basic Authentication` * SFTP User Name: SFTP User Name shared by TechWolf * SFTP Password: SFTP Password shared by TechWolf If TechWolf provided you with SFTP access by SSH key instead of a password, follow [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center) and fill in the authentication fields as described there. **6. Set schedule** Under Scheduling, select `Daily` in the dropdown menu. Then choose the appropriate time (e.g. 12:00 AM tomorrow) under `Start Time`. Note that the time of day of the start time will be the time of day for all future automatic integration runs. It is not required to set the `Ending On` field. If desired, set `Ending On` to a date far enough in the future and set up a reminder for yourself to extend the schedule when the expiry date is approaching. # How To: Set Up a Report Schedule Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/how-to-set-up-report-schedule **1. Navigate to report center** Search for `Go to Reports Center`, and navigate to the Reports Center. ![Reports Center main page](https://mintcdn.com/techwolf/l5Opy3H2R3whFQiJ/integrations/datasource-integrations/sap-standard-input-integration/step_by_step_images/1_reports_center_main_page.png?fit=max\&auto=format\&n=l5Opy3H2R3whFQiJ\&q=85\&s=4fcef98954020ecfe1661bda2786464f) **2. Create new import** In the Report Center, click `Import`. Enter the name and description for the report. **3. Upload report definition (.sfr)** Then, click `Browse` and upload the report `.sfr` for the integration. Continue by confirming the import and click on `Import`. ![Import pop-up window](https://mintcdn.com/techwolf/l5Opy3H2R3whFQiJ/integrations/datasource-integrations/sap-standard-input-integration/step_by_step_images/2_import_report_definition.png?fit=max\&auto=format\&n=l5Opy3H2R3whFQiJ\&q=85\&s=e1803dc5772d06277490ca0cc7b5ec1f) **4. Open the report scheduler** Close the import window, and find the report you just uploaded in the report center. Click the 3 dots on the right and select `New Schedule` to create a new schedule. ![Create a new schedule](https://mintcdn.com/techwolf/l5Opy3H2R3whFQiJ/integrations/datasource-integrations/sap-standard-input-integration/step_by_step_images/3_create_new_schedule.png?fit=max\&auto=format\&n=l5Opy3H2R3whFQiJ\&q=85\&s=63a27108ca71a36c23a043ab1b8e0dcf) **5. Set name and format** Set the schedule name and report format. ![Step 1](https://mintcdn.com/techwolf/l5Opy3H2R3whFQiJ/integrations/datasource-integrations/sap-standard-input-integration/step_by_step_images/4_first_step_create_schedule.png?fit=max\&auto=format\&n=l5Opy3H2R3whFQiJ\&q=85\&s=1bbd5a6caf9a55fe2e33a18099df8378) **6. Setup SFTP** `Step 2`, filtering can be skipped. Continue to `Step 3`. In the Destination section choose `File Transfer Protocol (FTP)` as method. Fill in `Host Address`, `FTP Login` and `FTP Password` with the values received from TechWolf. Click `Test Connection` and `Test File Put Permission` to ensure that the connection is working. ![Step 3](https://mintcdn.com/techwolf/l5Opy3H2R3whFQiJ/integrations/datasource-integrations/sap-standard-input-integration/step_by_step_images/5_destination_settings_schedule.png?fit=max\&auto=format\&n=l5Opy3H2R3whFQiJ\&q=85\&s=59aa53d7234ed0e87e226006c132b454) **7. Set file details** In the same section, fill in the file path and file name for the integration. Select `yyyyMMdd` as the date format. Click `Step 4`. **8. Set schedule** Under Schedule Occurrence, select `Recurring` in the dropdown menu. Then choose `Daily` under Recurring Pattern, and choose 12:00 AM tomorrow under `First Occurrence`. Set `Ending On` to a date far enough in the future and set up a reminder for yourself to extend the schedule when the expiry date is approaching. ![Step 4: Schedule timing](https://mintcdn.com/techwolf/l5Opy3H2R3whFQiJ/integrations/datasource-integrations/sap-standard-input-integration/step_by_step_images/6_schedule_occurrence_settings.png?fit=max\&auto=format\&n=l5Opy3H2R3whFQiJ\&q=85\&s=0aee3462e7858705317ada6ba9afbbda) Finally, click `Submit`. The schedule is now live. # Installation - Employees Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/installation-employees ## Employees datasource specification This page describes the SAP SuccessFactors exports for syncing **Employees** into TechWolf: the Employee baseline, internal and external working history, education, certificates, Courses and resumes. TechWolf provides a templated definition for each export. You import them into the Integration Center (or the Report Center) and point them at the TechWolf SFTP server. The Employee to Job export, which links each Employee to their Job, is part of the [Jobs](/integrations/datasource-integrations/sap-standard-input-integration/installation-jobs) exports. For the broader picture of how file-based integrations work and how they compare to API-based connectors, see [Key concepts](/integrations/datasource-integrations/datasources-key-concepts). ### Prerequisites Before starting, ensure you have the following: * A valid TechWolf contract and access to a **live TechWolf tenant**. * Credentials to the TechWolf [SFTP server ](/integrations/reference/sftp/sftp) to host the integration files, with a password or an SSH key. See [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center). * An SAP support case to [whitelist the TechWolf SFTP server ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-whitelist-sap-sftp-server). * Access to either the **Integration Center** or the **Report Center** in your SAP SuccessFactors tenant, depending on the integration. > [!NOTE] > > Integration Center and Report Center schedules run under the account of the > user that creates them. We recommend setting up the schedules with a > dedicated technical user rather than a named administrator account. > Schedules created by a named account break when that account is deactivated. > An administrator creates the technical user, grants it the permissions > needed for the schedules, and proxies as it while creating them. ## Configuration To allow data to flow from SAP to TechWolf, all report schedules or integration definitions must be configured in the SAP SuccessFactors tenant. All definitions have already been templated by TechWolf, and can be imported into the SAP SuccessFactors environment by uploading those files. > [!TIP] > > We recommend using the Integration Center if available in your SAP > environment. Not all integrations support report-based data extraction. ### Integration Center Follow the steps in [How To: Load Export Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions) to create a new integration definition with the correct values for each export. The integration definition files to start from are contained in the zip archive below. SFTP credentials will be provided by TechWolf. SFTP details can be found at [SFTP details ](/integrations/reference/sftp/sftp#server-details). > **Employee Baseline Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_employee_baseline_export_definition.icd` | > | **File Name Prefix** | `TechWolfEmployeeBaselineExport` | > | **File Folder** | `/datasource/employee_baseline` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Employee Internal Working History Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_employee_internal_working_history_export_definition.icd` | > | **File Name Prefix** | `TechWolfEmployeeInternalWorkingHistoryExport` | > | **File Folder** | `/datasource/employee_internal_working_history` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Employee External Working History Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_employee_external_working_history_export_definition.icd` | > | **File Name Prefix** | `TechWolfEmployeeExternalWorkingHistoryExport` | > | **File Folder** | `/datasource/employee_external_working_history` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Employee Education History Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_employee_education_history_export_definition.icd` | > | **File Name Prefix** | `TechWolfEmployeeEducationHistoryExport` | > | **File Folder** | `/datasource/employee_education_history` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Employee Certificates Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_employee_certificates_export_definition.icd` | > | **File Name Prefix** | `TechWolfEmployeeCertificatesExport` | > | **File Folder** | `/datasource/employee_certificates` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Employee Courses Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_employee_courses_export_definition.icd` | > | **File Name Prefix** | `TechWolfEmployeeCoursesExport` | > | **File Folder** | `/datasource/employee_courses` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Employee Resume Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_resume_export_definition.icd` | > | **File Folder** | `/datasource/resumes` | > **Employee To Resume Link Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_employee_to_resume_link_export_definition.icd` | > | **File Name Prefix** | `TechWolfEmployeeResumeLinkExport` | > | **File Folder** | `/datasource/employee_resume_link` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **[Integration definitions](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/datasource-integrations/sap-employee-datasource-integration-definitions.zip)** > > Required integration definitions for the SAP Employee Data Input Integration. ### Report Center Follow the steps in [How To: Set Up a Report Schedule ](./how-to-set-up-report-schedule) to create a new report schedule with the values for each report. Files for these reports are contained in the zip archive below. SFTP credentials will be provided by TechWolf, SFTP details can be found at [SFTP details ](/integrations/reference/sftp/sftp#server-details). Use the following values when setting up the report schedules: > **Employee Information Report** > > | **Configuration Item** | **Value** | > | - | - | > | **Report Name** | `TechWolf Employee Information Report` | > | **Report Definition** | `techwolf_employee_information_report.sfr` | > | **Schedule Name** | `TechWolf Employee Information Report Schedule` | > | **File Name** | `EmployeeInformationExport.csv` | > | **File Path** | `/datasource/employee_information` | > | **Date Format** | `yyyyMMdd` | > **Job History** > > | **Configuration Item** | **Value** | > | - | - | > | **Report Name** | `TechWolf Employee Job History Report` | > | **Report Definition** | `techwolf_employee_job_history_report.sfr` | > | **Schedule Name** | `TechWolf Employee Job History Report Schedule` | > | **File Name** | `EmployeeJobHistoryExport.csv` | > | **File Path** | `/datasource/job_history` | > | **Date Format** | `yyyyMMdd` | > **Learning History** > > | **Configuration Item** | **Value** | > | - | - | > | **Report Name** | `TechWolf Employee Learning History Report` | > | **Report Definition** | `techwolf_employee_learning_history_report.sfr` | > | **Schedule Name** | `TechWolf Employee Learning History Report Schedule` | > | **File Name** | `EmployeeLearningHistoryExport.csv` | > | **File Path** | `/datasource/learning_history` | > | **Date Format** | `yyyyMMdd` | > **Education History** > > This information is already included in the Employee Information Report. > **[Report definitions](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/datasource-integrations/sap-employee-datasource-report-definitions.zip)** > > Required report definitions for the SAP Employee Data Input Integration. # Installation - Jobs Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/installation-jobs ## Jobs datasource specification This page describes the SAP SuccessFactors exports for syncing **Jobs** and their **Job Families** into TechWolf, together with the export that links Employees to their Job. TechWolf provides a templated integration definition for each export. You import them into the Integration Center and point them at the TechWolf SFTP server. The Employee data itself is exported as described on the [Employees](/integrations/datasource-integrations/sap-standard-input-integration/installation-employees) page. For the broader picture of how file-based integrations work and how they compare to API-based connectors, see [Key concepts](/integrations/datasource-integrations/datasources-key-concepts). ### Prerequisites Before starting, ensure you have the following: * A valid TechWolf contract and access to a **live TechWolf tenant**. * Credentials to the TechWolf [SFTP server ](/integrations/reference/sftp/sftp) to host the integration files, with a password or an SSH key. See [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center). * An SAP support case to [whitelist the TechWolf SFTP server ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-whitelist-sap-sftp-server). * Access to either the **Integration Center** or the **Report Center** in your SAP SuccessFactors tenant, depending on the integration. > [!NOTE] > > Integration Center and Report Center schedules run under the account of the > user that creates them. We recommend setting up the schedules with a > dedicated technical user rather than a named administrator account. > Schedules created by a named account break when that account is deactivated. > An administrator creates the technical user, grants it the permissions > needed for the schedules, and proxies as it while creating them. * Job Profile Builder is implemented in your SAP SuccessFactors environment. > [!NOTE] > > [Job Profile Builder > ](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/70097a1a469d47a0ae08809e4a240f98/172d1e58be474b8ab4c268c918b9d56c.html) > allows managing Job Roles and Job Families in SAP SuccessFactors. These > entities are synced to the TechWolf SkillEngine API as Jobs and Job > Families. ## Configuration To allow data to flow from SAP to TechWolf, all report schedules or integration definitions must be configured in the SAP SuccessFactors tenant. All definitions have already been templated by TechWolf, and can be imported into the SAP SuccessFactors environment by uploading those files. > [!TIP] > > We recommend using the Integration Center if available in your SAP > environment. Not all integrations support report-based data extraction. ### Integration Center Follow the steps in [How To: Load Export Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions) to create a new integration definition with the correct values for each export. The integration definition files to start from are contained in the zip archive below. SFTP credentials will be provided by TechWolf. SFTP details can be found at [SFTP details ](/integrations/reference/sftp/sftp#server-details). > **Job Family Information** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_job_family_export_definition.icd` | > | **File Name Prefix** | `TechWolfJobFamilyExport` | > | **File Folder** | `/datasource/job_family` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Job Role Information** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_job_role_export_definition.icd` | > | **File Name Prefix** | `TechWolfJobRoleExport` | > | **File Folder** | `/datasource/job_role` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Job Profile Information** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_job_profile_export_definition.icd` | > | **File Name Prefix** | `TechWolfJobProfileExport` | > | **File Folder** | `/datasource/job_profile` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Job Role To Job Code linking** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_job_role_to_code_export_definition.icd` | > | **File Name Prefix** | `TechwolfJobRoleToCodeExport` | > | **File Folder** | `/datasource/job_role_to_job_code` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **Employee to Job Export** > > | **Configuration Item** | **Value** | > | - | - | > | **Integration Definition** | `techwolf_employee_job_export_definition.icd` | > | **File Name Prefix** | `TechWolfEmpJobExport` | > | **File Folder** | `/datasource/emp_job` | > | **Date Suffix Format** | `yyMMddHHmmssZ` | > **[Integration definitions](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/datasource-integrations/sap-job-datasource-integration-definitions.zip)** > > Required files for the SAP Job Data Input Integration ### Report Center Due to the nature of the integration, the data that is needed for this integration cannot be exported through the Report Center. # Overview Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/overview This document describes the standard datasource integrations with SAP SuccessFactors, in which SAP serves as a source of data for TechWolf to infer skills from. This guide will walk you through deploying the SAP SuccessFactors integrations, configuring the required settings, and ensuring smooth data transfer for skill inference. > **[Employees](./installation-employees)** > > Load in Employee data from SAP SuccessFactors to TechWolf. > **[Jobs](./installation-jobs)** > > Load in Job data from SAP SuccessFactors to TechWolf. ## Integration Overview SAP SuccessFactors is a cloud-based human capital management (HCM) suite to address all your HR needs – core HR and payroll, talent management, HR analytics, workforce planning, and more. An enterprise's SAP SuccessFactors environment typically contains all HR-related data, including employee information, job roles, learning history, and more. Given the relevance of employee and job data for skill inference, we have developed integration solutions that connects SAP SuccessFactors to the TechWolf SkillEngine. These integrations extract the required employee data and job data from SAP SuccessFactors via the report center and/or integration center and feeds it into the SkillEngine for skill inference. The inferred skills can be used within the TechWolf SkillEngine API or synced back into SAP SuccessFactors to enrich employee and job profiles with inferred skill data. ### Functional Objective The datasource integration between SAP SuccessFactors and TechWolf is designed to extract employee data and job data from SAP SuccessFactors to provide TechWolf with valuable and relevant data to infer qualitative skill profiles for employees and jobs. **Key benefits:** * Seamless integration of SAP SuccessFactors data into TechWolf with minimal configuration, enabling effortless data transfer. ### Data Flow All integrations are one-way data flows from SAP SuccessFactors to TechWolf. # Integrations Overview Source: https://developers.techwolf.ai/integrations/overview Our API is built on open standards: we use a RESTful API design, described with detail through an [OpenAPI specification](/reference/). Each of these aspects enables you to build a connector between your system and the Skill Engine with ease. On top of this well-documented interface, we assist our customers in building connectors that bridge the gap between the Skill Engine and any popular HR, knowledge sharing, and communication systems. We are actively expanding our suite of standard integrations for both syncing skill profiles between systems as well as datasource integrations to infer skill data from. By standardising these integrations, we are elevating our offering by providing fully designed, vendor-certified integrations wherever possible, ensuring they require minimal effort from our customers to implement. These integrations are supported by comprehensive deployment guides, designed to streamline the setup process and provide clear instructions for optimal performance. Should you need an integration that is not listed below, please don't hesitate to contact us. We have a broad range of experience with various systems, some of which may not yet be standardised. TechWolf can synchronise data to any system (unless that system has functional limitations with skills) if we have the following: * Access to a test tenant * A technical point of contact who understands the system * Technical integration documentation if it is not publicly available ## Skill Assistant The [TechWolf Skill Assistant](/integrations/skill-assistant) brings skills closer to employees, allowing them to efficiently review and validate the skills recommended by TechWolf in a way that seamlessly integrates into their workflow. ## Skill sync integrations Skill sync integrations are designed to **synchronise skill profiles** for Employees, Jobs, Courses, candidates and Vacancies between TechWolf and a third party system. These integrations ensure a consistent and up-to-date view of skill profiles across platforms. ### Standard integrations | System | Integration description | | - | - | | [Workday - Employee Skill Sync](/integrations/workday-skill-sync-integration/overview-employees) | A Workday Certified standard skill sync integration where we supply and sync skill profiles for **Employees**. | | [Workday - Job Skill Sync](/integrations/workday-skill-sync-integration/overview-jobs) | A standard skill sync integration where we supply and sync skill profiles for **Jobs**. | | [SAP - Skills Taxonomy Sync](/integrations/sap-skill-sync-integration/overview-skills-taxonomy) | A standard integration where we supply and sync a **Skills Taxonomy**. | | [SAP - Employee Skill Sync](/integrations/sap-skill-sync-integration/overview-employees) | A standard skill sync integration where we supply and sync skill profiles for **Employees**. | | [SAP - Job Skill Sync](/integrations/sap-skill-sync-integration/overview-jobs) | A standard skill sync integration where we supply and sync skill profiles for **Jobs**. | | [Degreed - Employee Skill Sync](/integrations/degreed-skill-sync-integration/overview-employees) | A standard skill sync integration where we supply and sync skill profiles for **Employees**. | ## Datasource integrations Data source integrations involve establishing connections with HR and business data sources to gather and extract information about Employees, Jobs, Courses, Vacancies, and candidates. This enables our AI to **infer and structure skill data**. | System | Integration description | | - | - | | [Workday](/integrations/datasource-integrations/workday-datasource) | A standard datasource integration where we take in [Workday EIB](https://www.workday.com/content/dam/web/en-us/documents/datasheets/datasheet-workday-cloud-connect-platform.pdf) output files to **infer skills from employees, jobs and vacancies**. | | [SAP SuccessFactors](/integrations/datasource-integrations/sap-standard-input-integration/) | A standard datasource integration from SAP to TechWolf, enabling TechWolf to **infer skills from employees and jobs**. | | [Other systems (file-based)](/integrations/datasource-integrations/non-standard-datasource-integrations/technical-data-flow) | A file-based datasource specification for any system without a standard connector: the customer exports [Jobs](/integrations/datasource-integrations/non-standard-datasource-integrations/jobs), [Employees](/integrations/datasource-integrations/non-standard-datasource-integrations/employees) and [Courses](/integrations/datasource-integrations/non-standard-datasource-integrations/courses) to CSV files in the documented format, and TechWolf **infers skills from employees, jobs, vacancies and courses**. | ## Webhooks [Webhooks](/integrations/webhooks/overview) let you receive real-time change notifications when supported Entities or Skill Profiles undergo changes in the SkillEngine API. TechWolf sends HTTPS POST requests to your endpoint detailing the changed entities (by ID), after which you can fetch the authoritative state from the SkillEngine API. All supported events conform to the [CloudEvents 1.0 specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md). TechWolf events are versioned (e.g. `v1`); for every breaking change, a new version will be introduced. Signature verification (Ed25519) and optional OAuth2 endpoint authentication are available. # Overview Source: https://developers.techwolf.ai/reference/latest/Export/CoursesExportSkillProfiles/overview # Export Course Skill Profiles. Source: https://developers.techwolf.ai/reference/latest/Export/CoursesExportSkillProfiles/post-export-courses-skill-profiles POST /export/courses/skill_profiles Export all Skill Profiles of all Courses by paginating through the data. The Courses are returned based on their creation time, with those created first being returned first. # Get the match scores between Employees and their assigned position in bulk. Source: https://developers.techwolf.ai/reference/latest/Export/ExportEmployeeAssignedPosition/post-export-employees-match-assigned-position POST /export/employees/match_assigned_position Employees without an assigned position will be included in the result, with `job_id=null` and `score=0.0`. # Overview Source: https://developers.techwolf.ai/reference/latest/Export/ExportEmployeesSkillClusters/overview Export data from the API through pagination. Request the first page of an export by not specifying the `starting_after` field. Next pages can be requested by setting the `starting_after` field to the last `external_id` from the previous page. When there is no more data after the requested page, `has_next` will be `false`. # Export Employee AI Goals Source: https://developers.techwolf.ai/reference/latest/Export/ExportEmployeesSkillClusters/post-export-employees-ai-goals POST /export/employees/ai_goals ![Experimental](https://img.shields.io/badge/-Experimental-orange) Export AI Goals for Employees by paginating through the data. By default the latest AI Goal per Employee is returned; set the `versions` query parameter to `all` to return every version per Employee instead. Use `filters` to narrow the set of Employees returned. Pagination is always at Employee granularity: `limit` bounds the number of Employees scanned per page, and `starting_after` is the `external_id` of the last Employee from the previous page. Employees without an AI Goal are silently skipped, so the returned `records` array can be shorter than `limit`. With `versions=all`, every version for each Employee in the page is returned — the same `external_id` can appear multiple times and `records` can be longer than `limit`. Records are ordered by `external_id` ascending and then `version` descending, so the latest version for each Employee appears first. **Note:** This endpoint is experimental and may change in future versions. # Export Employee Skill Clusters data. Source: https://developers.techwolf.ai/reference/latest/Export/ExportEmployeesSkillClusters/post-export-employees-skill-clusters POST /export/employees/skill_clusters Export all Skill Clusters of all Employees by paginating through the data. The Employees are returned based on their creation time, with those created first being returned first. # Export Employee Skill Profile data Source: https://developers.techwolf.ai/reference/latest/Export/ExportEmployeesSkillClusters/post-export-employees-skill-profiles POST /export/employees/skill_profiles Export all Skill Profiles of all Employees by paginating through the data. The Employees are returned based on their creation time, with those created first being returned first. # Export Employee Task Profile data Source: https://developers.techwolf.ai/reference/latest/Export/ExportEmployeesSkillClusters/post-export-employees-task-profiles POST /export/employees/task_profiles ![Experimental](https://img.shields.io/badge/-Experimental-orange) Export Task Profiles for all Employees by paginating through the data. Employees are returned in the order they were created (oldest first). Employees without a task profile will be included with an empty `tasks` array. Use the `include` parameter to optionally expand tasks with AI impact information and/or their source events. Use `filters` to narrow the set of Employees returned. **Note:** This endpoint is experimental and may change in future versions. # Export Tasks Source: https://developers.techwolf.ai/reference/latest/Export/ExportTasks/post-export-tasks POST /export/tasks ![Experimental](https://img.shields.io/badge/-Experimental-orange) Export the information for all Tasks in the system. Results are paginated with a default limit of 50,000. This limit is required due to the large dataset size. Setting a lower limit would not improve performance and is therefore not supported. Use the `include` query parameter to expand each Task with AI impact information, its position in the work taxonomy, and/or the Jobs it is assigned to. Use `filters` to narrow the set of Tasks returned. **Note:** This endpoint is experimental and may change in future versions. # Export Job Architecture hierarchy Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/get-job-architecture-export GET /job_architecture/export Export the Job Architecture as a hierarchical structure. Job Families are grouped by their `job_family_group_name` and consist of multiple Jobs. Jobs that are not part of a Job Family, appear in a nameless Job Family entity. # Overview Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/overview # Export Job Family Skill Profiles. Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-job-families-skill-profiles POST /job_architecture/export/job_families/skill_profiles Export all Skill Profiles of all Job Families by paginating through the data. The Job Families are returned based on their creation time, with those created first being returned first. The response includes both governed and suggested Skills, distinguished by their `validation_state`. # Export Job Family Suggested Skill Profiles. Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-job-families-suggested-skill-profiles POST /job_architecture/export/job_families/suggested_skill_profiles **Deprecated:** Use [Export Job Family Skill Profiles](/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-job-families-skill-profiles) instead. The Skill Profile export endpoint returns both governed and suggested Skills, distinguished by their `validation_state`. Export all Suggested Skill Profiles of all Job Families by paginating through the data. The Job Families are returned based on their creation time, with those created first being returned first. # Export Job Skill market alignment. Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-jobs-market-alignment POST /job_architecture/export/jobs/market_alignment Export the match scores between a Job and its market Skill Profiles in bulk. More information about the match scores and peer groups can be found in the documentation of the relevant [endpoint](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-market-alignment). # Export Job external market Skill Profiles. Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-jobs-market-skill-profiles POST /job_architecture/export/jobs/market_skill_profiles Export all external market Skill Profiles of all Jobs by paginating through the data. The Jobs are returned based on their creation time, with those created first being returned first. # Export Job Skill Clusters data. Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-jobs-skill-clusters POST /job_architecture/export/jobs/skill_clusters Export all Skill Clusters for all Jobs by paginating through the data. The Jobs are returned based on their creation time, with those created first being returned first. # Export Job Skill Profiles. Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-jobs-skill-profiles POST /job_architecture/export/jobs/skill_profiles Export all Skill Profiles of all Jobs by paginating through the data. The Jobs are returned based on their creation time, with those created first being returned first. The response includes both governed and suggested Skills, distinguished by their `validation_state`. # Export Job Suggested Skill Profiles. Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-jobs-suggested-skill-profiles POST /job_architecture/export/jobs/suggested_skill_profiles **Deprecated:** Use [Export Job Skill Profiles](/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-jobs-skill-profiles) instead. The Skill Profile export endpoint returns both governed and suggested Skills, distinguished by their `validation_state`. Export all suggested Skill Profiles of all Jobs by paginating through the data. The Jobs are returned based on their creation time, with those created first being returned first. # Export Job Task Profile data Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-jobs-task-profiles POST /job_architecture/export/jobs/task_profiles ![Experimental](https://img.shields.io/badge/-Experimental-orange) Export Task Profiles for all Jobs by paginating through the data. Jobs are returned in the order they were created (oldest first). Jobs without a task profile will be included with an empty `tasks` array. Use the `include` parameter to optionally expand tasks with AI impact information and/or their source data. Use `filters` to narrow the set of Jobs returned, including filtering by job family. **Note:** This endpoint is experimental and may change in future versions. # Export Job Architecture Suggestions Source: https://developers.techwolf.ai/reference/latest/Export/JobArchitectureExport/post-job-architecture-export-suggestions POST /job_architecture/export/suggestions Export suggestions by paginating through the data. Use the `category` query parameter to choose between skill suggestions (default) and task suggestions. **Skill suggestions** (`category=skills`) represent AI-generated recommendations for changes to job skill profiles, such as: - Adding a new skill to a job (`add_job_skill`) - Removing an existing skill from a job (`remove_job_skill`) - Setting a proficiency level for a skill (`set_job_skill_proficiency`) - Setting the criticality flag for a skill (`set_job_skill_criticality`) **Task suggestions** (`category=tasks`) represent AI-generated recommendations for adding tasks to jobs: - Adding a new task to a job (`add_job_task`) Each suggestion can be in one of three states: - `suggested`: The suggestion has not been reviewed yet - `accepted`: The suggestion has been accepted and applied - `rejected`: The suggestion has been rejected Use the `response_format` parameter to choose between: - `list`: Returns a flat list of suggestions (paginated by suggestion) - `grouped`: Returns suggestions grouped by job (paginated by job) # Export Organisational Structure hierarchy Source: https://developers.techwolf.ai/reference/latest/Export/OrganisationalStructureExport/get-organisational-units-export GET /organisational_units/export Export the Organisational Structure as a hierarchy. Each Organisational Unit can have at most one parent unit, with no limit on the number of levels. # Get Taxonomy export Source: https://developers.techwolf.ai/reference/latest/Export/TaxonomyExport/get-taxonomy-export GET /taxonomy/export Get an export of the entire Taxonomy. # Overview Source: https://developers.techwolf.ai/reference/latest/Export/TaxonomyExport/overview # Export Skill info Source: https://developers.techwolf.ai/reference/latest/Export/TaxonomyExport/post-export-skills POST /export/skills ![Beta](https://img.shields.io/badge/-Experimental-orange) Export the information for all Skills in the system. Results are paginated by default with a fixed limit of 50,000. This limit is required due to the large dataset size. Setting a lower limit would not improve performance and is therefore not supported. # Export Taxonomy changes Source: https://developers.techwolf.ai/reference/latest/Export/TaxonomyExport/post-taxonomy-changes POST /taxonomy/changes Export Taxonomy changes with filtering and keyset pagination. This endpoint supports filtering by operation type, external ID, and timestamp, and uses keyset pagination for efficient retrieval of large datasets. This endpoint returns changes for all skills, including those outside the current Taxonomy, and includes the `external_id` field in the response. # Overview Source: https://developers.techwolf.ai/reference/latest/Export/VacanciesExportSkillProfiles/overview # Export Vacancy Skill Profiles. Source: https://developers.techwolf.ai/reference/latest/Export/VacanciesExportSkillProfiles/post-export-vacancies-skill-profiles POST /export/vacancies/skill_profiles Export all Skill Profiles of all Vacancies by paginating through the data. The Vacancies are returned based on their creation time, with those created first being returned first. # Filters Source: https://developers.techwolf.ai/reference/latest/Matching Configuration/Filters/Filters A crucial aspect of the configurability of matchmaking inside Skill Engine API is the use of *filters*. You can see filters as hard constraints that are applied prior to the calculation of any Skills based match. The filters available for a matching endpoint are described in the specification of this endpoint, but for further clarification, this section provides a more complete overview. Filters can apply to one side of the matching equation, or can use both. In the latter case, we distinguish between the **source entity** (the one you are searching matches for) and the **target entities** (the ones you are searching for matches within). For example, if you request matches on `/vacancies/{vid}/matching_employees`, then the source entity is the Vacancy with external\_id `vid`, while the target entities consist of all Employees together. ## Single Entity Filters Single entity filters are always applied to the target entities, irrespective of the properties of the source entity. ### Custom Property Comparison The `custom_property` filter is one of the base building blocks for filtering in Skill Engine API. It filters the target entities using a value you provide inside the filter itself, and supports equality as well as a range of greater than / less than varieties. To know if you've applied the filter in the right direction, it's good to phrase it as: "I want to receive all entities that have a `property_name` that is `operator` to/than `property_value`". For example, the filter below results in all entities that have a `wage` Custom Property above `3000`. ```json theme={null} { "filter": "custom_property", "property_name": "wage", "property_value": "3000", "operator": "gt" } ``` When looking for matching vacancies, you can use the prefix `company__` before the actual property name to apply the filter on the Custom Properties of the external company linked to the Vacancy, rather than on the Custom Properties of the Vacancies itself. For example if you only want the Vacancies linked to external Companies that allow telework, the filter would like this: ```json theme={null} { "filter": "custom_property", "property_name": "company__telework_policy", "property_value": "allowed" } ``` When looking for matching external companies, the prefix `vacancy__` can be used before the actual value of `property_name` to apply the filtering to the Custom Properties associated to the Vacancies linked to the external Companies instead the external Companies itself. ### Custom Property Contains Element The `custom_property_contains_element` can be applied to `list[text]` type Custom Properties, and selects those entities for which the Custom Property value contains the supplied `property_value`. For example, the filter below could be used in a situation where Employees indicate the industries they want to work in -- in that case, the filter selects only the Employees that want to work in `electronics`. ```json theme={null} { "filter": "custom_property_contains_element", "property_name": "industries", "property_value": "electronics" } ``` If you want to require the Custom Property value to contain multiple different elements, you can simply append more filters, which will create the desired effect. If you want to filter for entities containing one or more of multiple elements, you can supply a list of options instead of just one value. To update our example from above, the filter below selects Employees that want to work in `electronics`, `chemicals` or both. ```json theme={null} { "filter": "custom_property_contains_element", "property_name": "industries", "property_value": ["electronics", "chemicals"] } ``` When looking for matching vacancies, you can use the prefix `company__` before the actual property name to apply the filter on the Custom Properties of the external company linked to the Vacancy, rather than on the Custom Properties of the Vacancies itself. For the example above this would become `company__industries` . When looking for matching external companies, the prefix `vacancy__` can be used before the actual value of `property_name` to apply the filtering to the Custom Properties associated to the Vacancies linked to the external Companies instead the external Companies itself. ### Custom Property Is In List In similar fashion to the contains element filter, the `custom_property_is_in_list` filter selects entities for which (non-list) Custom Property `property_name` is contained in the passed list of `possible_values`. For example, if you're looking for an Employee that wants to work either full time or part time, you might submit a filter similar to the one below: ```json theme={null} { "filter": "custom_property_is_in_list", "property_name": "possible_work_regimes", "possible_values": ["fulltime", "parttime"] } ``` When looking for matching vacancies, you can use the prefix `company__` before the actual property name to apply the filter on the Custom Properties of the external company linked to the Vacancy, rather than on the Custom Properties of the Vacancies itself. For the example above this would become `company__possible_work_regimes`. When looking for matching external companies, the prefix `vacancy__` can be used before the actual value of `property_name` to apply the filtering to the Custom Properties associated to the Vacancies linked to the external Companies instead the external Companies itself. ### External ID is in List This filter allows explicit filtering on external IDs of the target entities. Any entity not mentioned in the list is excluded. ```json theme={null} { "filter": "external_id_is_in_list", "external_ids": ["external_id_1", "external_id_2", "external_id_3"] } ``` ## Entity Relation Filters Entity relation filters filter the target entities using some relation they may or may not have with the source entity. ### Geo Distance This rather simple filter allows you to filter the target entities based on their distance from the source entity. The distance is expressed in kilometers, and calculated in a straight line between the two points. If the source entity has no `location` set, this filter will not have any effect. If the source entity does have a location, then target entities without a location will not be considered. If no geo distance filter is provided, Employee/Vacancy matching defaults to a range of 50km. ```json theme={null} { "filter": "max_geo_distance", "max_geo_distance": 50 } ``` ### Language The `language` filter allows you to determine how language requirements are handled when matching between Employees and Vacancies. As each language indicated on either of these entity types also has a level, you can tune the strictness of this filter by modifying `max_underqualification` and `max_overqualification`. These respective values indicate how many levels below or above the languages in the source entity those in the target entities are allowed to be. Checking is only done for languages present in the source entity, so in case of an empty `languages` attribute on the source side, this filter will not have any effect. If `max_underqualification` is equal or greater than the level of one or more languages for the source entity, target entities that do not mention this language will also be considered valid combinations with it. ```json theme={null} { "filter": "language", "max_overqualification": 2, "max_underqualification": 1 } ``` ### Custom Property Equal The `custom_property_equal` filter simply checks for equality between properties on the source and target entities. By providing the name of the property to be used on the source side as `from_entity_property` and the one on the target side as `to_entity_property`, you can flexibly choose which Custom Properties to use. ```json theme={null} { "filter": "custom_property_equal", "from_entity_property": "employment_type", "to_entity_property": "employment_type" } ``` When the filtering is applied to vacancies, either as `from_entity` or as `to_entity`, you can use the prefix `company__` before the actual value of `from_entity_property` or `to_entity_property` to apply the filtering on the Custom Properties of the external company linked to the Vacancy rather than the Vacancy itself. When the filtering is applied to external Companies as `to_entity`, the prefix `vacancy__` can be used before the actual value of `to_entity_property` to apply the filtering to the Custom Properties associated to the Vacancies linked to the external Companies instead the external Companies itself. ### Custom Property Contains The `custom_property_contains` filter is very similar to the `custom_property_equal` filter, but instead works with a `list[text]` and `text` property, checking whether one contains the other. Specifically, this filter selects the target entities for which the value of `to_entity_property` is a part of the `from_entity_property` (which must be a list type) of the source entity. The example below reflects the scenario where an Employee might indicate in which countries they want to work, so that only Vacancies in one of these countries can be returned. If the Custom Property is not set for the source entity, the filter has no effect. If the target entities lack the `to_entity_property`, they are ignored. ```json theme={null} { "filter": "custom_property_contains", "from_entity_property": "allowed_countries", "to_entity_property": "country" } ``` When the filtering is applied to vacancies, either as `from_entity` or as `to_entity`, you can use the prefix `company__` before the actual value of `from_entity_property` or `to_entity_property` to apply the filtering on the Custom Properties of the external company linked to the Vacancy rather than the Vacancy itself. When the filtering is applied to external Companies as `to_entity`, the prefix `vacancy__` can be used before the actual value of `to_entity_property` to apply the filtering to the Custom Properties associated to the Vacancies linked to the external Companies instead the external Companies itself. ### Custom Property Is In The `custom_property_is_in` filter is the mirror image of the `custom_property_contains` filter. If you apply one type in fetching Vacancies for a given Employee, then you can transform it into the other to have the equivalent constraint while fetching Employees for a given Vacancy. The example below reflects the transformed version of the example given for the contains filter above. ```json theme={null} { "filter": "custom_property_is_in", "from_entity_property": "country", "to_entity_property": "allowed_countries" } ``` When the filtering is applied to vacancies, either as `from_entity` or as `to_entity`, you can use the prefix `company__` before the actual value of `from_entity_property` or `to_entity_property` to apply the filtering on the Custom Properties of the external company linked to the Vacancy rather than the Vacancy itself. When the filtering is applied to external Companies as `to_entity`, the prefix `vacancy__` can be used before the actual value of `to_entity_property` to apply the filtering to the Custom Properties associated to the Vacancies linked to the external Companies instead of the external Companies themselves. ### Custom Property List Overlap The `custom_property_list_overlap` filter checks for overlap between two `list[text]` Custom Properties. Specifically, this filter selects the target entities for which at least one of the values in `to_entity_property` (which must be a list type) is contained in `from_entity_property` of the source entity. The example below shows a scenario in which an Employee might indicate in which industries they want to be involved, such that only Vacancies that are linked to one of these industries will be returned. If the Custom Property is not set for the source entity, the filter has no effect. Target entities that lack the `to_entity_property` property are excluded. ```json theme={null} { "filter": "custom_property_list_overlap", "from_entity_property": "desired_industries", "to_entity_property": "industries" } ``` When the filtering is applied to Vacancies, either as `from_entity` or as `to_entity`, you can use the prefix `company__` before the actual value of `from_entity_property` or `to_entity_property` to apply the filtering on the Custom Properties of the External Company linked to the Vacancy rather than the Vacancy itself. When the filtering is applied to External Companies as `to_entity`, the prefix `vacancy__` can be used before the actual value of `to_entity_property` to apply the filtering to the Custom Properties associated to the Vacancies linked to the External Companies instead the External Companies themselves. ### Last Updated The `last_updated` filter allows you to filter the target entities based on `last_updated` property. The filter supports a range of greater than / less than varieties. ```json theme={null} { "filter": "last_updated", "operator": "gt, gte, lt, lte", "value": "datetime" } ``` ### Last Updated With Taxonomy Change The `last_updated_with_taxonomy_change` filter checks if a Taxonomy change took place within the constraints of the filter. If that it the case, all target entities are returned, as all can be affected by a Taxonomy change. If no Taxonomy change took place, the filter operates like a `last_updated` filter. ```json theme={null} { "filter": "last_updated_with_taxonomy_change", "operator": "gt, gte, lt, lte", "value": "datetime" } ``` # Export top matching Jobs for Employees. Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Export Matching/post-export-employees-matching-jobs POST /export/employees/matching_jobs # Export top matching Vacancies for Employees. Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Export Matching/post-export-employees-matching-vacancies POST /export/employees/matching_vacancies # Export top matching Employees for Vacancies. Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Export Matching/post-export-vacancies-matching-employees POST /export/vacancies/matching_employees # Export top matching Employees for Jobs. Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Export Matching/post-job-architecture-export-jobs-matching-employees POST /job_architecture/export/jobs/matching_employees # Get the most task-relevant Job Families to the given Job Family Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Job Family Matching/post-job-architecture-job-families-job-family-external-id-matching-job-families-by-tasks POST /job_architecture/job_families/{job_family_external_id}/matching_job_families_by_tasks Identify the Job Families whose merged member-Job task profiles best match the given Job Family's task profile, ranked by symmetric task-match score (descending). The score is an hours-weighted, continuous task similarity, harmonic-meaned across both directions. Whether suggested tasks contribute alongside validated tasks is governed by the tenant's `tasks_on_jobs` setting. Results are subject to a result-level minimum score: matches scoring below 0.30 are not returned. A Job Family whose best match falls below this floor returns an empty result list rather than a weak, potentially misleading ranking. # Delete feedback on the match between an Employee and a Course Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Match Feedback/delete-employees-employee-external-id-courses-course-external-id-match-feedback DELETE /employees/{employee_external_id}/courses/{course_external_id}/match_feedback # Delete feedback on the match between an Employee and a Vacancy Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Match Feedback/delete-employees-employee-external-id-vacancies-vacancy-external-id-match-feedback DELETE /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match_feedback # Give feedback on the recommendation of a Course for an Employee. Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Match Feedback/post-employees-employee-external-id-courses-course-external-id-match-feedback POST /employees/{employee_external_id}/courses/{course_external_id}/match_feedback # Give feedback on the match between an Employee and a Vacancy Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Match Feedback/post-employees-employee-external-id-vacancies-vacancy-external-id-match-feedback POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match_feedback # Get the task-based match score between two task sets Source: https://developers.techwolf.ai/reference/latest/Matchmaking/Task Matching/post-tasks-matching POST /tasks/matching Get the symmetric task-based match score between two explicit sets of tasks, computed directly from their task embeddings. Unlike the job task-match endpoints, the two sides are caller-supplied task lists rather than job profiles. Each task may carry an optional weekly_hours weight, so tasks with more weekly hours contribute proportionally more to the score; when weekly_hours is omitted the tasks are weighted equally, reducing to an unweighted mean. The score is a continuous task similarity, harmonic-meaned across both directions, and is symmetric. Swapping the two sets yields the same score. # Get Data Improvement Actions Source: https://developers.techwolf.ai/reference/latest/Reports/Data Maturity Scan/get-reports-data-maturity-scan-data-improvement-actions GET /reports/data_maturity_scan/data_improvement_actions ![Beta](https://img.shields.io/badge/-Experimental-orange) Generate Data Improvement Actions for all Entities, Skill Events and Job Profile Data in the system. # Get Employee Maturity Overview Source: https://developers.techwolf.ai/reference/latest/Reports/Data Maturity Scan/get-reports-data-maturity-scan-employee-maturity-overview GET /reports/data_maturity_scan/employee_maturity_overview ![Beta](https://img.shields.io/badge/-Experimental-orange) Generate the Employee Maturity Overview for all Employees in the system. # Get Job Maturity Overview Source: https://developers.techwolf.ai/reference/latest/Reports/Data Maturity Scan/get-reports-data-maturity-scan-job-maturity-overview GET /reports/data_maturity_scan/job_maturity_overview ![Beta](https://img.shields.io/badge/-Experimental-orange) Generate the Job Maturity Overview for all Jobs in the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Reports/Data Maturity Scan/overview Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . # Get Employee Quality Matrix Source: https://developers.techwolf.ai/reference/latest/Reports/Data Maturity Scan/post-reports-data-maturity-scan-employee-quality-matrix POST /reports/data_maturity_scan/employee_quality_matrix ![Beta](https://img.shields.io/badge/-Experimental-orange) Generate the Employee Quality Matrix for all Employees in the system. # Get Job Quality Matrix Source: https://developers.techwolf.ai/reference/latest/Reports/Data Maturity Scan/post-reports-data-maturity-scan-job-quality-matrix POST /reports/data_maturity_scan/job_quality_matrix ![Beta](https://img.shields.io/badge/-Experimental-orange) Generate the Job Quality Matrix for all Jobs in the system. # Get Employees key metrics Source: https://developers.techwolf.ai/reference/latest/Reports/Employee Reports/get-reports-employees-key-metrics GET /reports/employees/key_metrics ![Beta](https://img.shields.io/badge/-Experimental-orange) Retrieve all key metrics of all Employees # Overview Source: https://developers.techwolf.ai/reference/latest/Reports/Employee Reports/overview Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . # Get the Skill Cluster adoption report Source: https://developers.techwolf.ai/reference/latest/Reports/Employee Reports/post-reports-employees-skill-cluster-adoption POST /reports/employees/skill_cluster_adoption ![Beta](https://img.shields.io/badge/-Experimental-orange) Retrieve the Skill Cluster adoption report for all Employees with respect to the value of a Custom Property and one or more Skill Clusters. The report consists of three smaller reports. A heatmap, a Skill Cluster adoption report, and a Skill breakdown. - The heatmap returns the adoption of each requested Skill Cluster for all Employees which have the same Custom Property. - The Skill Cluster adoption gives the proficiency level per requested Skill Cluster for each Employee. - The Skill breakdown returns an overview of the Skills of the requested Skill Cluster for each Employee. # Get entity counts Source: https://developers.techwolf.ai/reference/latest/Reports/General Reports/get-reports-counts GET /reports/counts ![Beta](https://img.shields.io/badge/-Experimental-orange) Retrieve the total number of all entities in the system. # Overview Source: https://developers.techwolf.ai/reference/latest/Reports/General Reports/overview Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . # Get Jobs key metrics Source: https://developers.techwolf.ai/reference/latest/Reports/Job Reports/get-reports-jobs-key-metrics GET /reports/jobs/key_metrics ![Beta](https://img.shields.io/badge/-Experimental-orange) Retrieve all key metrics of all Jobs # Overview Source: https://developers.techwolf.ai/reference/latest/Reports/Job Reports/overview Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . # Vacancy Reports Source: https://developers.techwolf.ai/reference/latest/Reports/Vacancy Reports/Vacancy Reports Reports aggregate and group Metrics into a broader overview. More info about Reports can be found on the [How it Works page](/technology/metrics-reports/) . # Get API Version Source: https://developers.techwolf.ai/reference/latest/Version/Version/get-version GET /version Get the current version of the API for your tenant. # AI Lifecycle Source: https://developers.techwolf.ai/technology/ai-lifecycle We take a holistic approach to AI development, ensuring a lifecycle that helps us align each process and outcome with our [AI principles](./responsible-ai-principles). We govern our AI lifecycle explicitly through all its stages: inception, development, verification and deployment. New AI models go through this process, and improvements to existing features get scoped and prioritised based on their performance measured during deployment. TechWolf does not apply continuous online learning, which means that any change to the AI models runs through the process as pictured below. ![AI Lifecycle](https://mintcdn.com/techwolf/7TXsvK-gPA_qHtHt/images/ai-lifecycle.png?fit=max\&auto=format\&n=7TXsvK-gPA_qHtHt\&q=85\&s=c37f6a17e15b5f1ac219dba6791d256d) ## Inception TechWolf defines the scope and intended use of an AI model during the inception and design phase. This process ensures that both internal and external requirements are explicitly listed, and that all possible risks are identified. TechWolf specifies the requirements for the system design at inception to ensure the right level of transparency. The success criteria and testing requirements are listed during this process. ## Development We put high emphasis on data quality, representativeness and validity in the development of AI models. We adhere to standard practices of data cleaning and logging all data artefacts for each model version. Data annotation is performed in-house, using carefully designed tooling and guidelines to ensure high quality. ## Verification Before models are released, they are tested in several ways during the verification phrase. This step includes technical testing (unit, integration and end-to-end tests) as well as evaluation against different datasets. This way, we can measure the overall accuracy (precision, recall and level of detail) of the model, probe for [harmful bias](./ai-risk-regulation), and assess the performance of the model in specific test cases. TechWolf considers two types of updates: 1. **Minor updates** - these are small changes, such as adding a small number of skills to the model or tweaking local properties, which keep the rest of the model stable. As the difference between versions is only noticeable in the targeted areas of improvement, these models are verified by the TechWolf team using automated tests, evaluation datasets and manual verification. 2. **Major updates** - these are big upgrades, that can cause substantial shifts in outputs and results. For example, this could be an entirely new model architecture or algorithm. These bigger updates are grouped into milestone releases, which are communicated to the customer in advance. The customer gets the chance to test changes in development and acceptance environments, before being guided to the actual deployment. By distinguishing between these two, we make sure that we can innovate continuously while keeping disruptive changes to a controlled minimum. ## Deployment The skill timeline allows customers to configure the weight of each data type in their deployment, to maximise the accuracy of skill inference. Additionally, the accuracy of the full system is being monitored continuously. Human feedback automatically informs our KPIs on skill profile completeness and accuracy. Negative feedback on skills is traced back to the types of data on which they were identified. This is aggregated into an overview of live model performance, and signals risk of model drift. The fairness of the system can be monitored live using our [bias testing toolbox](./ai-risk-regulation). ## Evaluation TechWolf’s AI team internally keeps track of an overarching AI health map, which provides a detailed view of key aspects including the quality, fairness, explainability and maintainability of more than 30 AI components in the product. This framework is informed by the measures taken in the verification step, and the continuous monitoring in deployment. Our infrastructure gives us insight into the accuracy of outputs, as well as reflecting sudden or gradual changes in AI behaviour, making sure actions can be taken when needed. The AI health map is used to identify risks and opportunities, which drive the priorities for investment of our AI resources. ## Customer data TechWolf never trains on customer data without explicit permission. Customers can contribute data to improve and deepen the model’s understanding of their business area. Each customer environment is monitored for anomalies and performance gaps, which when detected can trigger a deeper investigation into improving aspects of our product. In this scenario, customers can be requested to voluntarily provide data to help drive improvements. # AI Research Source: https://developers.techwolf.ai/technology/ai-research On top of adopting the latest advancements in AI, TechWolf actively drives innovation through focused research efforts. Our research pushes the state-of-the-art in skills technology in collaboration with respected institutions like the University of Cambridge and Ghent University. In line with our transparency principle, we are actively engaged in the academic community. We do this by publishing a selection of our research, making this work accessible to others and showing that it meets the standards set by international, peer-reviewed venues. Below, we provide an overview of recent publications. *** Luis Gasco, Hermenegildo Fabregat, Laura García-Sardiña, Paula Estrella, Warre Veys, Casimiro Pío Carrino, Matthias De Lange, Daniel Deniz Cerpa, Álvaro Rodrigo, Jens-Joris Decorte and Rabih Zbib. **"Overview of the TalentCLEF 2026: Skill and Job Title Intelligence for Human Capital Management"** *Conference and Labs of the Evaluation Forum (CLEF) 2026.* *** Matthias De Lange, Warre Veys, Federico Retyk et al., including Jens-Joris Decorte and Jeroen Van Hautte. **"WorkRB: A Community-Driven Evaluation Framework for AI in the Work Domain"** *Preprint, arXiv:2604.13055 (2026).* *** Matthias De Lange, Jens-Joris Decorte and Jeroen Van Hautte. **"Unified Work Embeddings: Contrastive Learning of a Bidirectional Multi-task Ranker"** *Preprint, arXiv:2511.07969 (2025).* *** Jens-Joris Decorte, Matthias De Lange and Jeroen Van Hautte. **"Multilingual JobBERT for Cross-Lingual Job Title Matching"** *CLEF 2025 Working Notes, CEUR Workshop Proceedings Vol. 4038, pages 4428–4437.* *** Jens-Joris Decorte, Jeroen Van Hautte, Chris Develder and Thomas Demeester. **"Efficient Text Encoders for Labor Market Analysis"** *IEEE Access, vol. 13, pages 133596–133608 (2025).* *** Jens-Joris Decorte, Jeroen Van Hautte, Chris Develder and Thomas Demeester. **"On the Biased Assessment of Expert Finding Systems"** *International workshop on Recommender Systems for Human Resources (RecSys in HR) as part of RecSys 2024.* *** Jens-Joris Decorte, Jeroen Van Hautte, Thomas Demeester and Chris Develder. **"SkillMatch: Evaluating Self-supervised Learning of Skill Relatedness"** *International workshop on AI for Human Resources and Public Employment Services (AI4HR\&PES) as part of ECML-PKDD 2024.* *** Jens-Joris Decorte, Jeroen Van Hautte, Johannes Deleu, Chris Develder and Thomas Demeester. **"Career Path Prediction using Resume Representation Learning and Skill-based Matching"** *International workshop on Recommender Systems for Human Resources (RecSys in HR) as part of RecSys 2023. * *** Jens-Joris Decorte, Severine Verlinden, Jeroen Van Hautte, Johannes Deleu, Chris Develder and Thomas Demeester. **"Extreme Multi-Label Skill Extraction Training using Large Language Models"** *International workshop on AI for Human Resources and Public Employment Services (AI4HR\&PES) as part of ECML-PKDD 2023.* *** Jens-Joris Decorte, Jeroen Van Hautte, Johannes Deleu, Chris Develder and Thomas Demeester. **"Design of Negative Sampling Strategies for Distantly Supervised Skill Extraction"** *International workshop on Recommender Systems for Human Resources (RecSys in HR) as part of RecSys 2022. * *** Jens-Joris Decorte, Jeroen Van Hautte, Thomas Demeester, and Chris Develder. **"JobBERT: Understanding Job Titles through Skills."** *International workshop on Fair, Effective And Sustainable Talent management using data science (FEAST) as part of ECML-PKDD 2021.* *** Van Hautte, Jeroen, Vincent Schelstraete, and Mikaël Wornoo. **"Leveraging the Inherent Hierarchy of Vacancy Titles for Automated Job Ontology Expansion."** *Proceedings of the 6th International Workshop on Computational Terminology (2020).* *** Van Hautte, Jeroen, Guy Emerson, and Marek Rei. **"Bad Form: Comparing Context-Based and Form-Based Few-Shot Learning in Distributional Semantic Models.** *Proceedings of the 2nd Workshop on Deep Learning Approaches for Low-Resource NLP (DeepLo 2019).* ## # AI Risk & Regulation Source: https://developers.techwolf.ai/technology/ai-risk-regulation TechWolf's system infers skills and provides insights, both for individuals and other entities like jobs and courses. The main focus of our efforts around fairness, risk, and regulation is the application of our technology to employees, as our data and insights can be used to inform people-impacting decisions. We proactively assess and mitigate the risks tied to the use of AI with people data. ## Bias Audits TechWolf performs internal bias audits for all major model updates and makes the audit reports available to customers. Within these audits, we use a real-world dataset to detect harmful bias against several protected attributes. We use disparate impact analysis, a technique for which 80% is widely considered the minimum score at which a system is safe and unbiased enough for use. In all tests, TechWolf’s AI achieves scores over 90%, greatly outperforming this baseline. In addition to our own testing, we also provide customers with a bias testing toolbox, which enables them to perform the same evaluation on their own data. ## Risk Framework Our development process is covered by [our ISO27001 certification](https://techwolf.ai/iso-certificate), which includes explicit management of risks. In addition to this, we leverage an internal AI risk framework, which is aligned with the ISO/IEC TR 24027:2021 bias standard. AI risk is evaluated on a quarterly basis as well as before and after significant product or engineering initiatives. ## Privacy & Security Our broad approach to privacy and security is described in the [security section](./security). In addition to the general measures we take for the development and deployment of our product, we also take action specifically for our AI models. This includes adversarial testing of our models, as well as anomaly detection on the performance and outputs of each AI model. In specific instances, we conduct red teaming or an external penetration test for more sensitive models. ## Regulation We track active and upcoming AI regulations, including the New York AI law and EU AI Act, and proactively ensure our technology is compliant. Customers and prospects receive access to detailed documentation around legal requirements and compliance, as well as being supported by our AI & compliance teams where needed. We maximally align our approach with leading standards such as ISO/IEC TR 24027:2021, and plan to pursue certification when sufficiently mature options become available. # System Design Source: https://developers.techwolf.ai/technology/ai-system-design ## Decoupled Design TechWolf implements a decoupled design, which enables end-to-end explainability, strong control over bias in training, and more efficient development cycles. Inferring skills from documents, aggregating documents for an employee, and creating recommendations are trained and evaluated separately. ![Decoupled AI](https://mintcdn.com/techwolf/7TXsvK-gPA_qHtHt/images/decoupled-ai-figure.png?fit=max\&auto=format\&n=7TXsvK-gPA_qHtHt\&q=85\&s=57f23f13fe6953bbec3db8248940887a) For each data type supported by our product, we train individual NLP models. Our skill timeline mechanism aggregates the identified skills across all data of an employee into a complete and up-to-date skill profile. Skill-based recommendations operate on the anonymous skill profile level and take into account adjacencies between skills in TechWolf’s ontology. Isolating the different parts in this system allows us to clearly define the scope of each component, and validate or improve their correct functioning efficiently. ## Explainability TechWolf is end-to-end explainable, both for skills and recommendations. For skills inferred for an employee, we mainly provide explanations on which documents or events impacted the inference, but more detailed explanations that show the impact of sections of each document can be provided too. For recommendations, a skill-level breakdown of contributing factors is provided as an explanation. Thanks to our decoupled architecture and transparent models, explanations from our product reflect what’s actually happening, rather than being created after the fact. ## Configurability Data landscapes can be vastly different between organisations or departments, with differences in data availability, volume, and quality. The separation between inference on a document level, and the combination of those data points into an employee skill profile, allows us to configure and optimise the setup of our product for maximum accuracy in each scenario. TechWolf can control for noise in the data and ensure balanced skill profiles even if input data is skewed or inconsistent. As a part of our core product functionality, customers can import and govern their taxonomy and job framework inside the system, ensuring the AI works in line with existing structures in their ecosystem. # External Companies Source: https://developers.techwolf.ai/technology/companies External Companies form a special category of entities in the Skill Engine. They allow our employment and staffing customers to additionally perform matching with external companies that have not explicitly advertised a market position. This way, we open up new business opportunities by flagging highly relevant companies for candidates that may not have a suitable advertised vacancy nearby. The External Company entity also allow our enterprise customers to profile and compare their own company to other companies that they have added to the API. The External Company interface allows you to link historical and active vacancies to their respective organization. This functionality is compatible with the **TechWolf Data Lake**, providing historical hiring information for thousands of organizations across Europe, North America, and the rest of the world. You can match External Companies bidirectionally with Employees based on the Vacancies of that External Company. There are three ways to add Vacancies to an External Company: 1. Explicitly, by setting the `company` field for a Vacancy. If the Vacancy has been closed, you can retain it for External Company matching purposes by setting its `active` attribute to `false`. 2. Implicitly, by adding desired functions to the external company. These handle the creation of *inactive* Vacancies for you. 3. Passively, by fetching historical vacancies from the TechWolf Data Lake and assigning *inactive* Vacancies for you. You can request the Vacancies linked to an External Company to allow easy management through the Skill Engine API. External Company entities that use the TechWolf Data Lake are continuously updated, reflecting their changes in the market. ## # Data Handling Source: https://developers.techwolf.ai/technology/data-handling Key to any data-driven approach is to have clarity around the data and how it is handled. This page gives an answer to several data related questions. ## Supported Data Types and Sources The Skill Engine has the ability to process both structured and unstructured data - that means that it is compatible with a wide range of data sources. Below, you can find a table with possible data source types (and some examples of these), as well as the data that can typically be used from them. The list is non-exhaustive, so get in touch if you have questions about other options! | **Source** | **Example Data Types** | | - | - | | HR Information System (e.g. SAP SuccessFactors, Oracle HCM Cloud, Workday…) | Employee resume, Employee working history, Employee education, Employee location, Team & division information | | Learning Management System or Learing Experience Platform (e.g. Degreed, Docebo, Cornerstone…) | Available courses, Employee course history, Employee learning goals | | Knowledge Base or Project Management Tool (e.g. Microsoft Teams…) | Issue descriptions, Articles written by employees | | Communication Tool (e.g. Yammer, email…) | Messages exchanged | The accepted format is detailed in the [API Specification](/reference/) - typically, a minimal connector layer is used to bridge the gap between your systems and the Skill Engine API. In addition to this fixed format, the Skill Engine API also allows you to leverage your **metadata** through the custom properties system - this way, you can filter and analyze Employees, Vacancies, and Courses based on any variable you want. For example, you can use this system to compare the skills of entire teams, see the distribution of a specific Skill Cluster over years of service or age... Metadata is allowed as a string (for categorical types) or as a number (for continuous types and quantities). ## Data Processing The Skill Engine processes documents through a process called **skill extraction** (visualized below). In this process, the Skill Engine reads through both structured and unstructured data, interpreting the skills connected to it and aggregating them into structured skill profiles. If skills are the atoms, you could see skill profiles as the molecules, with the bonds between the atoms representing the interaction between skills. Skill extraction is carried out through artificial intelligence, depending on state-of-the-art language models. While accurately representing the skillset of people, jobs, and courses, skill profiles are anonymous. ![schematic representation of skill extraction](https://mintcdn.com/techwolf/O6Ad9BPC00x-v0KV/images/se-processing.svg?fit=max\&auto=format\&n=O6Ad9BPC00x-v0KV\&q=85\&s=5687cc6f9286f9f1c92dd4fd31ae6c4e) ## Stored Data The Skill Engine stores your data in a logically separated data store. Data stored is defined by a crucial principle: **only the information that is needed to provide results downstream is retained**. For example, resume files, which typically contain a wide range of sensitive personal information, are dropped immediately after their skill profile has been extracted, leaving only a pseudonymized profile. The same holds for any other unstructured data ( e.g. documents), which are never stored inside the Skill Engine. The metadata of an entity is retained until either the entity or the custom property containing the metadata is removed, since the metadata must be available for flexible queries. # Entities Source: https://developers.techwolf.ai/technology/entities We built the Skill Engine API around a domain-driven philosophy: our goal is to express functionality in the same language that our customers and end-users speak. That way, the Skill Engine API maps onto your use case with the least amount of friction. This page describes the available entity types and their meaning and functionality. Throughout this developer portal, entity names are capitalized. For example, 'Employee' indicates an Employee entity. The Skill Engine API supports four entity types: * **Employee**: represents either a person within your organization or a candidate within the job market. * **Vacancy**: corresponds to job postings or open positions. * **Course**: any internal or external training or education. * **Occupation**: a generic role or function defined by your organization. ```mermaid theme={null} classDiagram Entity <|-- Employee Entity <|-- Vacancy Entity <|-- Course Entity <|-- Occupation Entity : external_id Entity : custom_properties Entity : skill_profile class Employee{ location languages desired_functions skill_events ... } class Vacancy{ location job_title job_description ... } class Course{ course_title course_description ... } class Occupation{ occupation_name occupation_description occupation_titles ... } ``` All of these entities share the following properties: 1. An entity in the Skill Engine API corresponds to the same one in your organization and is mapped one-on-one with them. For example, each Employee entity links to one (and only one) employee in your core systems. 2. An entity has a single and *meaningful* skill profile. 3. An entity's lifecycle is explicitly managed: you are in control of its continued existence. 4. An entity can have **custom properties** that are used for filtering, enhanced matching, and advanced querying. ## Flexible Data Models We know that your use case may require unique business logic. We accommodated the Skill Engine to integrate your logic on demand. It has customization built-in, rather than worrying about it after the fact. Do you want to use properties like work regimes, country preferences, or ratings? Custom properties will be your go-to tool. Head over to the [custom properties tutorial](/tutorials/custom-properties/overview) to get started with your desired custom properties. We also provide our customers with integration support, so if you want to learn even more about mapping your use case, don't hesitate to get in touch! # Getting Started Source: https://developers.techwolf.ai/technology/index This section of the developer portal provides you with additional background information on the research, technology, and principles behind the Skill Engine. While primarily aimed at developers, this documentation can be insightful for anyone wishing to gain a deeper understanding of the technology powering the Skill Engine. The following categories are present, each answering a set of questions: * **Integrations**: How can I connect the Skill Engine API to my system? What happens to my data? How secure is the system? * **Artificial Intelligence**: What happens inside the Skill Engine? Can I understand how results came to be? What does TechWolf do against bias? * **Data Models**: What are the underlying entities and models in the Skill Engine API? If you would like a more exact overview of different functionalities, including exact requests and responses, please head over to the [API Reference](/reference/). For a more tailored overview of how our functionality comes together in various use cases, you may find our [Tutorials](/tutorials/) to be of use. ## # Metrics & Reports Source: https://developers.techwolf.ai/technology/metrics-reports The Skill Engine leverages a system of metrics and reports to provide individual and aggregated insights about its entities. In essence, you can see a **metric** as a single number representing some amount of information about an entity or a collection of entities of the same type. Below, you can see a handful of examples of metrics available through the Skill Engine API: * Employability of an Employee * Average employability of all Employees * Count for a given Skill in a set of entities * Skill level for a given Skill and Employee A **report** aggregates those metrics into a clear overview. * Employability for all Employees * High-level skill distribution of the company * Current position alignment for all Employees Reports are structured to enable you to combine them with different data sources inside your own BI tooling. For this reason, metrics tend to provide insights (e.g. an overall indication of your skills health), whereas the focus of reports is generally to aggregate these across a population. ## # Responsible AI Principles Source: https://developers.techwolf.ai/technology/responsible-ai-principles ![Responsible AI Principles](https://mintcdn.com/techwolf/7TXsvK-gPA_qHtHt/images/ai-principles-icons.png?fit=max\&auto=format\&n=7TXsvK-gPA_qHtHt\&q=85\&s=ab61f18569e5dd4042754c3686b22eb1) TechWolf's purpose is to make people flourish at work. Our AI approach reflects this purpose, as well as our values, through three guiding principles. These principles are reflected in our methods, architecture and overall AI lifecycle. ## 🙌 **We empower people** Our technology is built to make a positive impact on individuals and organisations. We aim to solve problems and create opportunities with AI while letting employees keep their skills and careers in their own hands. We support decision-making rather than taking it away from people. ## 🔍 **We create transparency** Our AI models are explainable, and help people understand results as much as possible. We focus on practical explanations that drive insight rather than overwhelm people with too much data. Our technical approach is open and well-documented, ensuring customers can understand and trust our product. ## ⚖️ **We innovate responsibly** We conduct our own technology research and don’t cut corners. Our AI life cycle is focused on allowing maximal innovation while ensuring positive impact and minimising risk. We measure and quantify the performance and fairness of our system continuously. # Information Security Source: https://developers.techwolf.ai/technology/security TechWolf takes information security seriously. Our up-to-date certifications, policies, infrastructure details, and security documentation live on the [**TechWolf Trust Center**](https://trust.techwolf.ai). For security questions, reach us at [security@techwolf.ai](mailto:security@techwolf.ai). For data protection and privacy inquiries, contact our DPO Office at [privacy@techwolf.ai](mailto:privacy@techwolf.ai). ## Skill Engine API A few specifics that are useful when integrating with the Skill Engine API: * The API is available over HTTPS only. * Authentication and authorization use the OAuth 2.0 protocol, allowing for secure and scoped access to the product's functionality. * Each customer runs in a strictly isolated environment. Data is never combined across customers, and any models trained or optimized on your internal data are never applied outside your environment. * You retain full control over the contents of your environment: the lifecycle of every [Entity](./entities) is managed explicitly by your company. See [Data handling](./data-handling) for how the Skill Engine treats the data you send it. # Skill Clusters Source: https://developers.techwolf.ai/technology/skill-clusters While the Skill Engine API works out of the box with the skills vocabulary provided by TechWolf, some organisations have a language of their own to express capabilities: a Skill Cluster framework. As we want our system to integrate with your company seamlessly, we allow you to import this Skill Cluster language into the Skill Engine API, **making our system speak your language**. The structure of a Skill Cluster in our system is relatively simple: all that's required as input is a **name** and a **description**. In essence, each Skill Cluster is mapped with one or more underlying skills -- this is done in a fully automated manner, based on the name and description provided for each Skill Cluster. Afterwards, you can use the feedback functionality to adapt the interpretation of each Skill Cluster to match your vision exactly. Skill Clusters in the Skill Engine API are modeled in a very similar way to [entities](/technology/entities/). As such, you can use the same functionality to create, read, update and delete them as you might do with an Employee or Vacancy entity. As managing an always up-to-date Skill Cluster framework can be quite a burden without intelligent tooling and insights, we assist our customers in optimising their frameworks. For example, this includes detection of potential duplicates or errors, analysing how well your framework covers your workforce and suggesting upcoming skills to be added in the form of a new Skill Cluster. This way, we assist you in keeping your framework accurate, active and relevant. # Skill Events Source: https://developers.techwolf.ai/technology/skill_events ## Introducing Time The skillset of an employee is not static. Over time, a person will work on many projects and topics, follow courses, and change positions. Past experiences become irrelevant compared to newer ones. That is why we made time an indispensable part of the Skill Engine through the concept of **Skill Events**. Skill Events encapsulate a single skill source and pin it down on the timeline. The timeline allows **point-in-time recovery**. You can compare how your workforce grew since last year, evaluate a single employee, or learn how fast your company can progress in its respective field. ### Increase quality Skill Events increase the quality of the skill profiles. Aside from resumes and working- and education histories, any information you can procure where an employee shows skills can serve as a source. Whenever a person's skillset grows, the Skill Engine can link a new Skill Event and update their profile. ### Skill Event Types We currently support multiple types of Skill Events: * **Working History Event**: Whenever an employee changes position or job, they acquire new skills in that domain. The Employee is assumed to have obtained the skills at the start date of the function unless stated otherwise. * **Education History Event**: Employees acquire a minimal skillset during their education. The Employee is assumed to have obtained the skills at the start date of the education unless stated otherwise. * **Resume Document Event**: Every once in a while, an employee's resume is updated. With this new resume come new skills. The Employee is assumed to have obtained the skills when the new resume enters the Skill Engine. * **Learning Event**: This event encapsulates any learning the Employee has achieved, such as courses and projects. The Skill Engine assumes the Employee acquired the skills at the timestamp assigned to the event. * **Feedback Event**: Feedback and performance assessments can be a great source of skills. Setting the feedback text in the description field of the content assures that skills mentioned in a positive context are extracted. * **Goal Event**: Employees can set personal development goals, performance goals, or other goals. Every completed goal can add skills to an employee's skillset. * **Project Event**: Working on a project requires skills and knowledge. These skills can be added to the employee's skill profile upon completing the project. * **Ticket Event**: Tickets from systems such as Jira or Salesforce Service Cloud (e.g. bugs, tasks, stories) can be sent as Skill Events. The title, type, and description are used to infer skills. * **Merge Request Event**: Merge requests (e.g. from GitLab, GitHub, Bitbucket) can be sent as Skill Events. The title, description, and commit messages are used to infer skills. Merge request events are processed asynchronously; the Employee's Skill Profile is updated after inference. * **Certificate Event**: Certificates can be a clear indicator that an employee is a skilled practitioner of a tool or technology. * **Skill notes Event**: This event allows free text input of one or multiple skills. The skills will be mapped to the TechWolf vocabulary automatically. It can be used to add skill badges, software knowledge, tools,... The Skill Engine assumes the Employee acquired the skills at the timestamp assigned to the event. The Skill Engine also reads the business records below. Send each one with its type as the `event_type` and its fields as the `content`; every text field is used as context to infer skills. `GET /skill_event_types` lists the types available to your tenant and the fields each one takes. These types are enabled per tenant; contact TechWolf to enable them. They are processed asynchronously, like merge requests: the Employee's Skill Profile is updated after inference. | Type | What to send | Required fields | Optional fields | | - | - | - | - | | `it_incident` | An unplanned IT disruption reported for resolution | `summary`, `body` | `category`, `subcategory`, `resolution_notes`, `activity_notes` | | `change_request` | A planned change to infrastructure or applications | `summary`, `body` | `category`, `subcategory`, `change_plan`, `backout_plan`, `test_plan`, `activity_notes` | | `problem_record` | A root-cause investigation across recurring incidents | `body` | `category`, `subcategory`, `activity_notes` | | `service_request` | A request for a catalogued service, such as access or provisioning | `summary`, `body` | `service_offering`, `activity_notes` | | `hr_case` | An employee query handled by HR on policy, procedure or benefits | `summary`, `body` | `service_offering`, `category`, `subcategory`, `activity_notes` | | `support_ticket` | A request routed to an internal support team | `summary`, `body` | `category`, `subcategory`, `resolution_notes`, `support_team` | | `work_task` | A work item under a parent incident, change or request | `summary`, `body` | `resolution_notes` | | `employee_recognition` | Praise from a peer or manager for a specific contribution | `body` | | | `customer_case` | A customer support case with the agent's comments | `summary`, `body` | `case_comments` | | `task` | A single to-do inside a project | `summary`, `body` | `project_name` | | `postmortem` | A post-incident review: root cause, impact and lessons | `summary`, `body` | `root_cause`, `impact`, `lessons` | | `deal_note` | A sales deal's strategy and next steps | `summary`, `body` | `next_step` | | `success_plan` | A customer-success account plan and its objectives | `summary`, `body` | `objectives` | | `audit_finding` | An internal-audit finding and its recommendation | `summary`, `body` | `recommendation` | | `work_order` | A field or maintenance job and its work notes | `summary`, `body` | `work_notes`, `close_notes` | | `technical_spec` | A technical specification: engineering design and implementation decisions | `title`, `body` | | | `technical_documentation` | Reference material on how systems work | `title`, `body` | | | `product_documentation` | Reference material on product features and usage | `title`, `body` | | | `knowledge_article` | A support or IT knowledge-base article | `title`, `body` | `category` | | `planning_document` | A roadmap, project plan or schedule | `title`, `body` | | | `process_document` | An internal procedure or workflow | `title`, `body` | | | `meeting_notes` | Meeting minutes: decisions and action items | `title`, `body` | | | `performance_review` | A manager's review or check-in about the Employee | `body` | | | `publication` | An academic paper the Employee authored | `title`, `abstract` | `keywords` | | `patent` | A patent naming the Employee as inventor | `title`, `abstract` | `keywords` | Every field value is text of at most 10,000 characters, and a Skill Event carries at most 50,000 characters in total. A field not listed for the type is rejected. ```mermaid theme={null} classDiagram SkillEvent <|-- WorkingHistoryEvent SkillEvent <|-- EducationHistoryEvent SkillEvent <|-- ResumeDocumentEvent SkillEvent <|-- LearningEvent SkillEvent <|-- FeedbackEvent SkillEvent <|-- GoalEvent SkillEvent <|-- ProjectEvent SkillEvent <|-- TicketEvent SkillEvent <|-- MergeRequestEvent SkillEvent <|-- CertificateEvent SkillEvent <|-- SkillNotesEvent SkillEvent : external_id SkillEvent : event_type SkillEvent : timestamp SkillEvent : content class WorkingHistoryEvent{ job_title job_description start_date end_date company } class EducationHistoryEvent{ school degree_name start_date end_date } class LearningEvent{ learning_title learning_description } class ResumeDocumentEvent{ mimeType base64Content } class FeedbackEvent{ description } class GoalEvent{ description } class ProjectEvent{ description } class TicketEvent{ ticket_title ticket_type ticket_description ticket_system } class MergeRequestEvent{ title description commits } class CertificateEvent{ certificate_title certificate_description } class SkillNotesEvent{ description } ``` # External Company Creation Source: https://developers.techwolf.ai/tutorials/companies/company-creation To get started, first you need to create one or more external companies within the Skill Engine API. This process is very similar to the [entity creation](/tutorials/vacancy-matching/entity-creation/) step from the Vacancy matching tutorial, with one key difference: as External Companies inside the Skill Engine API are not standard entities, they do not have a skill profile (and cannot result in a 422 error). For each External Company, a minimal set of details is required: * The company name * The VAT number * The location of the company, expressed as latitude and longitude As with entities, the `external_id` of each External Company is also controlled by you. To create one, simply submit a `POST` request to the `companies` endpoint: ```JSON theme={null} { "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7", "name": "TechWolf", "vat": "BE0702852201", "location": { "lat": 51.0216707, "lng": 3.6887328 } } ``` For more details on how to update or delete External Companies, please head over to the [API Reference](/reference/). ## # Fetching Matches Source: https://developers.techwolf.ai/tutorials/companies/fetching-matches Once you have created one or more External Companies and [linked Vacancies or desired functions](/tutorials/companies/linking-vacancies/) to it, you can start generating Company/Employee matches! The matching score between a given External Company and Employee is defined as the highest match score this Employee has with one of the Vacancies linked to the External Company. ## Finding External Companies for an Employee To find the most suitable External Companies for a given Employee, you can request the best matches through a `GET` request to `employees//matching_companies/`. As is the case in [matching between Employees and Vacancies](/tutorials/vacancy-matching/fetching-matches/) , you can use the `limit`, `max_geo_distance` and `score_min_threshold` query parameters to further filter results. ## Finding Employees for an External Company Finding the most suitable Employees for a given External Company is similar to the approach described above, with the only difference being the endpoint: `companies//matching_employees/`. You can use the same query parameters for filtering. ## Explainability The score calculation between an External Company and Employee is reflected transparently through the API response, which returns the Vacancy `external_id` and `job_title` for each Vacancy that contributed to the match result. This explanation is found in the `matching_vacancies` field in each item in the response. To dive a bit deeper into the match still, you can use the explained Employee/Vacancy matching. # Linking Vacancies Source: https://developers.techwolf.ai/tutorials/companies/linking-vacancies External Companies in the Skill Engine API are modeled by linking previous and current hiring behaviour, as well as desired functions to them. This is implemented through Vacancy entities, leveraging the `company` and `active` fields available for this entity type. ## Hiring History A first option is to link real Vacancies to an External Company. These Vacancies can include both positions that are currently open and historical Vacancy advertisements. It's possible to link a Vacancy while [creating or updating](/tutorials/vacancy-matching/entity-creation/) it, by specifying the `external_id` of the External Company via the `company` attribute in the request body of the Vacancy. If a position is currently open, and you want it to be taken into account in the overall [vacancy matching](/tutorials/vacancy-matching/overview/), the `active` attribute of the Vacancy needs to be set to `true`. If a position is no longer open, you can create or update the entity to set the same field to `false`, excluding it from the same process. Inactive vacancies in the Skill Engine API are currently only used in the context of matching with External Companies. ## Desired Functions If you don't have Vacancies on file for an External Company, but you do have information about their typical hiring needs through a different way, you can integrate this information into the Skill Engine API through the use of *desired functions*. You can add these functions by submitting their title to the `companies//desired_functions` endpoint. This endpoint will create a new Vacancy entity for every submitted title, linking each to the External Company and setting the Vacancy location to the same values as for the External Company. As these entities do not represent currently open Vacancies, their `active` field is set to `false` by default, making sure that they do are not involved in the traditional vacancy matching. # Overview Source: https://developers.techwolf.ai/tutorials/companies/overview ## Scenario This tutorial describes how you can use External Companies within the Skill Engine API, including: * Managing External Companies inside the system. * Linking Vacancies and desired functions to an External Company. * Matching between Employees and External Companies This functionality is primarily aimed at our staffing & employment agency customers. ## Preparation For this tutorial, we assume that you have a set of Employees created within the system already. This step is described in the [vacancy matching tutorial](/tutorials/vacancy-matching/entity-creation/). # Custom Properties Source: https://developers.techwolf.ai/tutorials/custom-properties/custom-properties After you've created the set of Employees & added the corresponding Custom Property Definitions, you can start adding the values for the specific custom properties. You can choose between replacing all the custom properties of an Employee ( via `PUT`), or only a subset of them (via `PATCH`). ## Example For example, to indicate that a specific Employee is a freelancer, you can submit a `PATCH` request to the `employees//custom_properties/` endpoint: ```json theme={null} [ { "property_name": "freelancer", "property_value": true } ] ``` If you had used `PUT` for this request, all the attributes that are not in the request body are automatically deleted. All custom properties of an Employee can be retrieved via submitting a `GET` request the `employees//custom_properties/` endpoint. # Custom Property Definitions Source: https://developers.techwolf.ai/tutorials/custom-properties/custom-property-definitions To be able to add custom properties to an Entity, you first need to create a custom property definition for the specific Entity type. This tutorial will walk you through the flow for an Employee, but the process is **similar for other Entity types**. ## Allowed Types Custom property definitions ensure that a custom property is consistent over all entities of that type. Using an inconsistent data type will result in a `HTTP 400: Bad Request`. An Employee can have custom properties of the following types: * `number`: Must be an integer or float (without double quotes) * `text`: Must be an empty or non-empty string * `boolean`: Must be a Boolean value true or false (without double quotes) * `datetime`: Must be an ISO8601-formatted datetime string (supported formats: `["%Y-%m-%dT%H:%M:%S.%f", "%Y-%m-%d"]`). * `list[text]`: Must be a list of strings ## Example If you want for example to indicate that an Employee is a freelancer, you can create a Boolean custom property definition `freelancer`. ```json theme={null} { "property_name": "freelancer", "property_type": "boolean" } ``` In order to create the definition use the following flow: ```mermaid Creation theme={null} sequenceDiagram participant Your System participant Skill Engine API Your System->>Skill Engine API: POST /employees/custom_properties activate Your System alt Creation Successful rect rgba(0, 255, 0, .15) Skill Engine API-->>Your System: ✅ HTTP 204 No Content end else Custom Property Definition Already Exists rect rgba(255, 0, 0, .15) Skill Engine API-->>Your System: ❌ HTTP 409 Conflict end end ``` You can retrieve, update, and delete all the custom property definitions for an Employee using the endpoint `/employees/custom_properties`. For more details on how to do this, please head over to the [API Reference](/reference/). # Overview Source: https://developers.techwolf.ai/tutorials/custom-properties/overview ## Scenario This tutorial describes how you can use custom properties within the Skill Engine API, including: * Creating a custom property definition for an Entity type. * Adding custom properties for Entity objects. This functionality is aimed at both enterprises (recruitment, outplacement, internal mobility) and staffing & employment agency customers. ## Preparation In this tutorial, we'll add custom properties to an Employee. We assume that you have a set of Employees created within the system already. This step is described in the [vacancy matching tutorial](/tutorials/vacancy-matching/entity-creation/). # Creating new Employees Source: https://developers.techwolf.ai/tutorials/employee-timeline/creating-new-employees You can create new Employees by sending a `POST` request with the corresponding request body to the `/employees` [endpoint](/reference/latest/Employees/EmployeeCRUD/post-employees). The only required fields are as follows: * `External_id` in the request body: corresponds with the unique ID in your system * Language query parameter: language of the input data, which has an impact on the Skill extraction * Strict query parameter: by setting this to false, you can add Employees without Skill information. This is necessary for this tutorial since the Skill information will only follow in the subsequent steps. ## Restoring Soft-Deleted Employees If grace periods are enabled for your tenant, Employees are soft-deleted rather than permanently removed for the specified period. They are permanently deleted once the grace period expires. To restore a soft-deleted Employee, include the `restore=true` query parameter along with the Employee's `external_id` in the request body. You can also update the Employee's data during restoration by including additional fields in the request body. ## Example Submit a `POST` call to `/employees?strict=false&language=auto` with the following body: ```JSON theme={null} { "external_id": "101" } ``` # Overview Source: https://developers.techwolf.ai/tutorials/employee-timeline/overview ## Scenario This tutorial describes how you can build the Skills Timeline for the Employees, including * Creating new Employees * Adding new Skill Events linked to these Employees, which will contribute to the Skill & Skill Cluster profile of the Employee * Adding, updating or removing those Skill Clusters by giving feedback * Exporting the Skill Clusters for (part of) the Employees ## Preparation In this tutorial, we assume that the Skill Cluster framework is already added to the API. (either by TechWolf or a framework uploaded by the customer) ## Postman collection It is possible to follow this tutorial hands-on by using the following postman collection. Download both the collection and the environment template and import them into postman. Set the given environment as active and fill in the credentials received by TechWolf. Once the environment is correctly set, the collection can be used to send requests to the API. Make sure to start with the Login request which will automatically set the session token in the following calls. [Download Postman collection](https://26502993.fs1.hubspotusercontent-eu1.net/hubfs/26502993/Developer%20portal/Employee-Timeline-Tutorial.postman_collection.json) [Download Postman environment](https://26502993.fs1.hubspotusercontent-eu1.net/hubfs/26502993/Developer%20portal/skillengine-api-template-environment.postman_environment.json) # Skill Cluster Export Source: https://developers.techwolf.ai/tutorials/employee-timeline/skill-cluster-export Exporting Skill Clusters profiles, e.g. on a daily basis, is possible via a `POST` call to the `/export/employees/skill_clusters` [endpoint](/reference/latest/Export/ExportEmployeesSkillClusters/post-export-employees-skill-clusters). This is implemented with keyset pagination: employees are returned in order of when they were created (old to new). The first page of the export (containing `limit` employees) is retrieved by not specifying the `starting_after` field. Next pages can be requested by setting the `starting_after` field to the last `external_id` from the previous page. When there is no more data after the requested page, `has_next` will be `False`. Via setting a filter on the `last_updated` attribute, you can export the employees who are updated since a specific timestamp. For example, if you want to get the Skill Cluster profiles of the employees changed since 2022/03/25, you can use the following body: ```JSON theme={null} { "limit": 10, "filters": [ { "filter": "last_updated", "value": "2022-03-25", "operator": "gt" } ], "include": [ "current_skills" ] } ``` Response: ```JSON theme={null} { "has_next": true, "records": [..., { "external_id": "5cbdbdbe-5f44-4423-8157-520f8a2f429a", "skill_clusters": [{ "skill_cluster_name": "Programming Languages", "domain_name": "Computer Science", "proficiency_level": 2, "current_skills": [{ "name": "Python" }, { "name": "Java" }] }] }, ...] } ``` Consecutive requests are similar, with `starting_after` set to the last `external_id` - until `has_next` in the response is `False`. ```JSON theme={null} { "starting_after": "5cbdbdbe-5f44-4423-8157-520f8a2f429a", "limit": 10, "filters": [ { "filter": "last_updated", "value": "2022-03-25", "operator": "gt" } ], "include": [ "current_skills" ] } ``` # Skill Cluster Feedback Source: https://developers.techwolf.ai/tutorials/employee-timeline/skill-cluster-feedback TechWolf infers skills based on evidence of data - which means that if there’s no evidence in the data, the skill isn’t inferred. There can be use cases for which the Employee wants to add these Skill Clusters anyway. For example, if Employee 101 wants to add the Skill Cluster “Programming Languages” to his Skill Profile & remove the Skill Cluster “Leadership Skills”, this can via the following `PATCH` call to the `employees/101/skill_profile?feedback_format=skill_clusters` [endpoint](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile): ```JSON theme={null} { "skill_clusters": [ { "skill_cluster_name": "Programming Languages", "proficiency_level": 2 }, { "skill_cluster_name": "Leadership Skills", "proficiency_level": 0 } ] } ``` Feedback on a skill level is also possible via passing the query parameter `feedback_format=skills`. For example if you want to delete the skill “Python”, you can send the following `PATCH` call to `employees/101/skill_profile?feedback_format=skills`: ```JSON theme={null} { "skills": [ { "skill": "Python", "score": 0 } ] } ``` # Skill Events Source: https://developers.techwolf.ai/tutorials/employee-timeline/skill-events The skill set of an employee is not static. Over time, a person will work on many projects and topics, follow courses, and change positions. Past experiences become irrelevant compared to newer ones. The concept of Skill Events allows adding those. ![Skills Timeline](https://mintcdn.com/techwolf/7TXsvK-gPA_qHtHt/images/skills_timeline.png?fit=max\&auto=format\&n=7TXsvK-gPA_qHtHt\&q=85\&s=ab6bddd67efdde88fdfb279cd9e8be81) Skill Events can be added via a `POST` call to the `/employees/{employee_external_id}/skill_events` [endpoint](/reference/latest/Employees/SkillEvents/post-employees-employee-external-id-skill-events). There are currently 11 event types supported, which all have different `content` in the request body. For example, take Employee 101 with the following history: * Graduated “Computer Science” in 2018 * Worked as a “Software Developer” from 2018-2020 & afterwards started a job as “Product Owner” * Took a course on “Agile & Scrum” in 2021 Adding these events to the Employee can by calling `/employees/101/skill_events?language=auto` with the following bodies: ```JSON theme={null} { "external_id": "degree-101-1", "event_type": "education_history", "timestamp": "2018-07-01", "source": "oracle", "content": { "degree_name": "Computer Science" } } ``` ```JSON theme={null} { "external_id": "working-history-101-1", "event_type": "working_history", "timestamp": "2020-05-02", "source": "oracle", "content": { "start_date": "2018-09-01", "end_date": "2020-05-02", "job_title": "Software Developer", "job_description": "Tools: Scala, Git, Docker" } } ``` ```JSON theme={null} { "external_id": "working-history-101-2", "event_type": "working_history", "timestamp": "2020-05-02", "source": "oracle", "content": { "start_date": "2020-05-02", "job_title": "Product Owner", "job_description": "-" } } ``` ```JSON theme={null} { "external_id":"learning-101-1", "event_type": "learning", "timestamp": "2021-05-01", "source": "coursera", "content": { "learning_title": "Agile & Scrum", "learning_description": "In this course you learn the fundamentals of Agile:stand-ups, retrospectives, sprints, …" } } ``` When adding a Skill Event, it automatically contributes to the Skill Profile - which is why you should only send completed events. (i.e. when a certificate is obtained or a goal is accomplished). Requesting the Skill Cluster profile of this Employee can via a `GET` call to the `/employees/101/skill_profile?response_format=skill_clusters` [endpoint](/reference/latest/Employees/EmployeeProfile/get-employees-external-id-skill-profile). The response body will be as follows: ```JSON theme={null} { "external_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7", "num_skill_events": 5, "skill_clusters": [{ "skill_cluster_name": "Programming", "proficiency_level": 2 }, { "skill_cluster_name": "Business Intelligence", "proficiency_level": 3 }] } ``` # Overview Source: https://developers.techwolf.ai/tutorials/filtering/overview ![Beta](https://img.shields.io/badge/Status-Experimental-yellow) > Filtering is in an experimental phase and breaking changes are possible > without announcements. Errors occurring when using filters will not be handled > with the highest priority. The SkillEngine API provides a syntax to filter the entities returned and used for a response. It allows you to find entities with specific properties easily. Because the SkillEngine API is developed in Django the syntax is fairly similar to the one used by Django. ```php theme={null} GET /employees?$employees=external_id='1' # Will only display the employee with external id equal to `1` # in the response ``` [separator]: # ```php theme={null} GET /reports/count?$employees=external_id='1'&$jobs=external_id='2' # Will only use the employee with external id equal to `1` and # the job with external id equal to `2` when calculating its response ``` Current filterable entities are * `employees` * `jobs` * `job_families` * `vacancies` * `courses` ## Operators The following operators are supported. * `exact` (default) * `iexact` * `contains` * `icontains` * `startswith` * `istartswith` * `endswith` * `iendswith` * `gt` * `gte` * `lt` * `lte` * `is_null` The operators can be used by separating the field and operators with `__` like this ```php theme={null} GET /employees?$employees=external_id__contains='1' # Will only display employees of which the external id contains '1' ``` More information on the workings of these operators can be found at [Django filter reference](https://docs.djangoproject.com/en/5.1/ref/models/querysets/#field-lookups). For some entities additional operators may be available; in those cases the behavior of the additional property will be explained in the API reference of that entity. ## Logical operators (AND, OR, NOT) Multiple filters can be combined using `and` and `or`; filters can also be negated by using `not`. ```php theme={null} GET /employees?$employees=(external_id__startswith='1' or external_id__startswith='2') # Will only display employees of which the external id either starts with '1' or with '2' ``` [separator]: # ```php theme={null} GET /employees?$employees=(external_id__contains='1' and external_id__contains='2') # Will only display employees of which the external id both contains '1' and '2' ``` > The precedence of the operators is `not`, `and`, `or` equal to the operator > precedence of Python and most other programming languages. ## Related fields Related fields can also be filtered, meaning you can limit the jobs returned by filtering on a property of the related job family as follow. ```php theme={null} GET /jobs?$jobs=job_family__external_id='1' # Will only display jobs which have the job family with external id equal to '1' ``` ## Custom properties Custom properties can also be used for filtering entities by using the `cp_` prefix. ```php theme={null} GET /employees?$employees=cp_language='de' # Will only display employees that have value 'de' for the customer property # with property name 'language' ``` ## Nuances When requesting an entity that is filtered out, you will get a 404 Not Found response, while trying to create this entity will result in a 409 Already Exists response. ## Addition to other filters If you have a credential that already has certain filters bound to it, all these filters will be added on top. ## Limitations Complex filters might significantly increase response times and database load, for that reason, the following limitations are in place. * The number of logical operators can not exceed 5 * Fields allowed for filtering are specified per entity # Authentication Source: https://developers.techwolf.ai/tutorials/getting-started/authentication The `SEAPIClient` class provides easy authentication and access to the SkillEngine API. The requirements of this class can be installed as follows after which the class can be copy pasted into your code. ```bash theme={null} pip install PyJWT requests ``` ```python theme={null} import time from urllib.parse import urljoin import requests from requests import Session import jwt import uuid from datetime import datetime, timedelta, timezone class SEAPIClient: def __init__( self, tenant: str, auth_url: str, api_identifier: str, facade_url: str, client_id: str, client_secret: str = None, private_key: str = None, timeout: int = 30, ): self._tenant = tenant self._client_id = client_id self._client_secret = client_secret self._private_key = private_key self._auth_url = auth_url self._api_identifier = api_identifier self._facade_url = facade_url self._session = Session() self._auth_token = None self._token_expiry = None self._timeout = timeout # Validate that we have either client_secret or private_key if not client_secret and not private_key: raise ValueError("Either client_secret or private_key must be provided") if client_secret and private_key: raise ValueError( "Only one of client_secret or private_key should be provided" ) def _get_auth_token(self): # 5 min expiration buffer if not self._auth_token or ( self._token_expiry and time.time() > self._token_expiry - 300 ): self._auth_token = self._fetch_new_auth_token() return self._auth_token def _create_jwt_assertion(self): """Create a JWT assertion for the private key flow""" if not self._private_key: raise ValueError("Private key is required for JWT assertion flow") now = datetime.now(timezone.utc) expiration = now + timedelta(minutes=5) audience = f"{self._auth_url}/" payload = { "iss": self._client_id, "sub": self._client_id, "aud": audience, "jti": str(uuid.uuid4()), "exp": int(expiration.timestamp()), "iat": int(now.timestamp()), } return jwt.encode(payload, self._private_key, algorithm="RS256") def _fetch_new_auth_token(self): url = urljoin(self._auth_url, "/oauth/token") headers = {"Content-Type": "application/x-www-form-urlencoded"} if self._private_key: # Private key flow - use JWT Bearer assertion client_assertion = self._create_jwt_assertion() data = { "grant_type": "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": client_assertion, "tenant": self._tenant, "audience": self._api_identifier, } else: # Client credentials flow data = { "client_id": self._client_id, "client_secret": self._client_secret, "audience": self._api_identifier, "grant_type": "client_credentials", "tenant": self._tenant, } response = requests.post(headers=headers, url=url, data=data, timeout=60) if response.status_code != 200: raise Exception( f"Failed to get auth token: {response.status_code} - {response.text}" ) token = response.json()["access_token"] decoded_token = jwt.decode(token, options={"verify_signature": False}) self._token_expiry = decoded_token["exp"] return f"Bearer {token}" def _get_url(self): protocol, base_url = self._facade_url.split("://") return f"{protocol}://{self._tenant}.{base_url}" def _create_headers( self, content_type: str = "application/json", version: str = None, ): headers = {"Content-Type": content_type} if version: headers["X-API-Version"] = version headers["Authorization"] = self._get_auth_token() return headers def get(self, endpoint: str, version: str = None): url = urljoin(self._get_url(), endpoint) headers = self._create_headers(version=version) response = self._session.get(headers=headers, url=url, timeout=self._timeout) return response def post(self, endpoint: str, data: dict, version: str = None): url = urljoin(self._get_url(), endpoint) headers = self._create_headers(version=version) response = self._session.post( headers=headers, url=url, json=data, timeout=self._timeout ) return response def patch(self, endpoint: str, data: dict, version: str = None): url = urljoin(self._get_url(), endpoint) headers = self._create_headers(version=version) response = self._session.patch( headers=headers, url=url, json=data, timeout=self._timeout ) return response def put(self, endpoint: str, data: dict, version: str = None): url = urljoin(self._get_url(), endpoint) headers = self._create_headers(version=version) response = self._session.put( headers=headers, url=url, json=data, timeout=self._timeout ) return response def delete(self, endpoint: str, version: str = None): url = urljoin(self._get_url(), endpoint) headers = self._create_headers(version=version) response = self._session.delete(headers=headers, url=url, timeout=self._timeout) return response ``` ```python EU customer (client_secret) theme={null} client = SEAPIClient( tenant="", client_id="", client_secret="", api_identifier="eu3.techwolf.ai", facade_url="https://eu3.techwolf.ai", auth_url="https://techwolf.eu.auth0.com", ) ``` ```python US customer (client_secret) theme={null} client = SEAPIClient( tenant="", client_id="", client_secret="", api_identifier="us3.techwolf.ai", facade_url="https://us3.techwolf.ai", auth_url="https://techwolf-us.us.auth0.com", ) ``` For private key authentication pass `private_key` instead of `client_secret`. Once the client has been initialized you can start making requests as follows ```python theme={null} response = client.get("/employees") print(response.status_code) print(response.json()) ``` # Overview Source: https://developers.techwolf.ai/tutorials/getting-started/overview This tutorial describes how one can easily start using our API within a Python environment. It provides code that handles the authentication to get you up and running within minutes. ## Preparation Before getting started we expect you to have a working Python environment. # Welcome Source: https://developers.techwolf.ai/tutorials/index The Skill Engine API is an AI toolkit to solve your skill-related challenges. Our aim is twofold. Firstly, we want to explain how individual components work. Secondly, we want to demonstrate how to assemble these components into a complete use case. This section of the developer portal provides a range of tutorials, showcasing the information flow and API calls needed to bring these scenarios to life. In each tutorial, the two communicating parties are **your system** and the **Skill Engine API**. A diagram shows the flow of the requests. For all requests, the message arrow indicates the corresponding method and endpoint. Responses are shown as a dotted line, indicating the HTTP response code. The following image shows an example of a request flow diagram: ```mermaid theme={null} sequenceDiagram participant Your System participant Skill Engine API Your System->>Skill Engine API: POST /employees activate Your System alt Creation Successful rect rgba(0, 255, 0, .15) Skill Engine API->>Skill Engine API: Skill Extraction Skill Engine API-->>Your System: ✅ HTTP 204 No Content end else Entity Already Exists rect rgba(255, 0, 0, .15) Skill Engine API-->>Your System: ❌ HTTP 409 Conflict end end ``` Keep the following rules in mind when reading sequence diagrams: * `opt` indicates optional operations (e.g. a feedback step). * `alt` indicates scenarios that are alternatives to each other ( e.g. a success and failure scenario). * Colours are meaningful: **green** indicates a success scenario, **red** indicates a critical failure (which ends the flow immediately), **orange** indicates a non-critical failure (which means an operation has no effect, but the flow can continue). * In more complex setups, only success paths are visible. For a complete overview of the scenarios in those cases, please consult the API spec. ## # Job and Job Family Creation Source: https://developers.techwolf.ai/tutorials/job_architecture/job_and_job_family_creation The essential first step of any flow with the Skill Engine API is creating the Entities within the system. First, a Job Family needs to be created. In order to create a Job Family, send over the Job Family information to the `/job_architecture/job_families` endpoint. Job Family information can contain a non-required `job_family_group` field. This field can be used if your organization has a hierarchical structure with Job Families grouped into higher level groups. After this creation, you can add Jobs to this Job Family by sending over the Job Information to the `/job_architecture/jobs` endpoint. The Job is added to the Job Family by providing the Job Family ID in the body of the request. If a Job would not fit any Job Family, it can be created without a Job Family ID. # Example If the Job Family with ID 101 is created, the Job with ID 1 can be added to this Job Family by sending the following request: ```json theme={null} { "external_id": 1, "job_name": "Frontend Developer", "job_family_id": "101" } ``` # Overview Source: https://developers.techwolf.ai/tutorials/job_architecture/overview ## Scenario This tutorial describes how you can implement a Job Architecture in the Skill Engine API. A Job Architecture consists of multiple Job Family Groups. One Job Family Group has one or more Job Families linked to it. Likewise, a Job Family has one or more Jobs linked to it. ![Job Architecture](https://mintcdn.com/techwolf/7TXsvK-gPA_qHtHt/images/job_architecture_schema.png?fit=max\&auto=format\&n=7TXsvK-gPA_qHtHt\&q=85\&s=9943242ebd7f7c8689e60e9f03a10c5a) Information about these Job and Job Families, used for skill extraction, can be added through the concept of Profile Data. This tutorial includes the following steps: * Managing Job Families and Jobs inside the system. * Enriching Jobs and Job Families with additional Profile Data. ## Preparation For this tutorial, knowledge of entity creation is required. This step is described in the [vacancy matching tutorial](/tutorials/vacancy-matching/entity-creation/). # Providing Profile Data Source: https://developers.techwolf.ai/tutorials/job_architecture/provide_profile_data After the creation of Job Families and Jobs, you can enrich them with additional Profile Data. This data will be used for calculating the suggested skill profiles of Jobs and Job Families. Profile Data information includes the following: * a `source` which indicates the source of the information * a `data_type` which indicates the type of the information, currently a Job Family supports the `job_family_description` type and a Job supports the `job_description`, `job_title`, `vacancy` and `skill_notes` types * a `data` field which contains the actual information Profile Data can be added to Jobs and Job Families by sending over the Profile Data to the `/job_architecture/jobs/{job_external_id}/profile_data` and `/job_architecture/job_families/{job_family_external_id}/profile_data` endpoints respectively. In this way, a suggested skill profile can be created where a clear distinction can be made between the skills coming from the Job and the skills coming from the Job Family. ## Example Assume that a Job Family with ID 101 is created, which represents a Software Developer. Additionally, a Job with ID 1 is created, which represents a Junior Software Developer. The following Profile Data can be added to the Job Family by calling `/job_architecture/job_families/101/profile_data` with the following body: ```json theme={null} { "external_id": "job-family-101-desc-1", "source": "Archives", "data_type": "job_family_description", "data": { "job_family_description": "A software developer is a person who creates computer software. This is achieved by writing code using programming languages. They build software components and test them." } } ``` The following Profile Data can be added to the Job by calling `/job_architecture/jobs/1/profile_data` with the following body: ```json theme={null} { "external_id": "job-1-desc-1", "source": "Archives", "data_type": "job_description", "data": { "job_description": "Frontend developers are responsible for implementing visual elements that users see and interact with in a web application." } } ``` # Governed Skill Profiles Source: https://developers.techwolf.ai/tutorials/job_architecture/skill_profile The goal of this tutorial is to explain how you can govern Job skill profiles using the Skill Engine API. Overview 1. Uploading Data: first, you upload Job Profile Data or Job Family Profile Data to the Skill Engine API. 2. Suggested skill profiles: the system generates suggested skill profiles based on this data. 3. Validating skills: skills can be validated by giving profile feedback. 4. Governed skill profiles: the governed skill profile of a Job or Job Family consists only of validated skills. You can provide feedback on both: * Job Profiles (affecting individual jobs) * Job Family Profiles (affecting all Jobs in that family) ## Skill Types A skill profile can contain two types of skills: * **Family-Specific (FS) skills**: skills related to a Job Family, validated through Job Family profile feedback. * **Job-Specific (JS) skills**: skills unique to a specific Job, validated through Job profile feedback. A skill profile of a Job can contain Family-Specific and Job-Specific skills. A skill profile of a Job Family can only contain Family-Specific skills. ## Governed Skill Profile Calculation **Job Family skill profile**: the system aggregates the latest Job Family feedback for each skill, keeping only validated skills. **Job Governed skill profile**: the system merges both Job Family feedback and Job-Specific feedback, using the latest feedback per skill, keeping only validated skills. **Key insights**: * The latest feedback counts * Providing feedback at the Job Family level is a bulk operation, it applies to all Jobs within that Job Family at that moment in time. Although this feedback is applied in bulk to all underlying Jobs at the time of applying it, it is still tied to the Job Family itself. This means that if you move the Job to a new Job Family, the old Job Family feedback will no longer be present on the Job and the new Job Family feedback will be applied. ## Example walkthrough ### Suggested skill profile calculation Consider a Job Family (ID: 101) representing "Software Developer" with two jobs: * Job 1 (Junior Software Developer) * Job 2 (Senior Software Developer) These Jobs belong to Job Family 101. After uploading the Job and Job Family data, the suggested skill profiles are: | Skill | Skill Type | Job Family | Job 1 | Job 2 | | - | - | - | - | - | | Machine Learning | Family-Specific | suggested | suggested | suggested | | Python | Job-Specific | - | suggested | - | ### Providing feedback At this point, no skills are validated yet. Let's validate some skills. ✅ Validating "Machine Learning" for all Jobs (via Job Family feedback). We want to: * Validate Machine Learning for all jobs. * Mark it as critical on each Job. Job Family Feedback (API Call): ```json theme={null} { "source": "TechWolf", "skills": [ { "skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11",, "has_skill": true, "critical": true, } ] } ``` ✅ Validating "Python" for Job 1 (via Job feedback) Job Feedback (API Call): ```json theme={null} { "source": "TechWolf", "skills": [ { "skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e12", "has_skill": true } ] } ``` Now, the skill profiles look like this: | Skill | Skill Type | Job Family | Job 1 | Job 2 | | - | - | - | - | - | | Machine Learning | Family-Specific | ✅ validated & critical | ✅ validated & critical | ✅ validated & critical | | Python | Job-Specific | - | ✅ validated | - | ### Conflicting feedback Now, let's assume we reject "Machine Learning" for Job 1. Job Feedback (API Call): ```json theme={null} { "source": "TechWolf", "skills": [ { "skill_id": "ac3a733e-b258-438d-8d39-9a2837a10e11", "has_skill": false } ] } ``` Now, Job 1 no longer contains "Machine Learning", since the latest feedback counts. The skill profiles of the Job Family and Job 2 remain unchanged: | Skill | Skill Type | Job Family | Job 1 | Job 2 | | - | - | - | - | - | | Machine Learning | Family-Specific | ✅ validated & critical | ❌ removed | ✅ validated & critical | | Python | Job-Specific | - | ✅ validated | - | ### Adding a Job to the Job Family Let's now add Job 3 (Software Developer) to Job Family 101. Job Creation (API Call): ```json theme={null} { "external_id": "3", "job_name": "Software Developer", "job_family_id": "101" } ``` **Automatic inheritance**: * Job 3 automatically inherits all Family-Specific skills with their skill properties (e.g. critical). * Job 3 does not inherit Job-Specific skills (e.g., Python). Updated skill profiles: | Skill | Skill Type | Job Family | Job 1 | Job 2 | Job 3 | | - | - | - | - | - | - | | Machine Learning | Family-Specific | ✅ validated & critical | - | ✅ validated & critical | ✅ validated & critical | | Python | Job-Specific | - | ✅ validated | - | - | # Overview Source: https://developers.techwolf.ai/tutorials/skill-clusters/overview ## Scenario Many companies (API users) have their own language to describe skills and traits of employees: **Skill Cluster frameworks**. These consist of a collection of Skill Clusters (i.e. combination of skills, knowledge, attributes and behaviours) and are essential in terms of defining job requirements and recruiting, retaining and developing staff. The Skill Engine API is made to fit your workflow and **speak your language**, so you're able to add the Skill Clusters of your framework. This allows the Skill Engine API to express insights in your Skill Cluster language. This tutorial describes how you can use Skill Clusters within the Skill Engine API, including: * **Adding the Skill Clusters** of a Skill Clusters framework * Providing **feedback** with those Skill Clusters to a skill profile ## Preparation In this tutorial, we assume that you have a Skill Clusters framework and that all Skill Clusters have a name and a description. # Profile Feedback Source: https://developers.techwolf.ai/tutorials/skill-clusters/profile-feedback Once you have added your Skill Cluster framework, you can provide skill profile feedback using those Skill Clusters as well! ## Feedback with Skill Clusters For example, if you want to add the Skill Cluster `Data Science Modelling` to a given Employees skill profile, you can send the following `PUT` to `employees//skill_profile` with query parameter `feedback_format=skill_clusters`. ```JSON theme={null} { "skill_clusters": [ { "skill_clusters_name": "Data Science Modelling", "proficiency_level": 2 } ] } ``` Note that for the Skill Cluster feedback, you only have to send the `Data Science Modelling` Skill Cluster (& not the existing Skill Clusters in the skill profile). # Skill Cluster Framework Source: https://developers.techwolf.ai/tutorials/skill-clusters/skill-cluster-framework ### Adding Skill Clusters The essential first step of any flow with the Skill Engine API is creating the Entities within the system. For example, to create a Skill Cluster you can simply submit a `POST` request to `/taxonomy/skill_clusters`: ```JSON theme={null} { "external_id": "CP-001", "skill_cluster_name": "Data Science Modelling", "skill_cluster_description": "The ability to use machine learning algorithms to extract value from data" } ``` The sequence diagram below shows the communication steps: ```mermaid theme={null} sequenceDiagram participant Your System participant Skill Engine API Your System->>Skill Engine API: POST /taxonomy/skill_cluster activate Your System alt Creation Successful rect rgba(0, 255, 0, .15) Skill Engine API->>Skill Engine API: Skill Extraction Skill Engine API-->>Your System: ✅ HTTP 204 No Content end else Creation Failed rect rgba(255, 0, 0, .15) Skill Engine API->>Skill Engine API: Skill Extraction Failed Skill Engine API-->>Your System: ❌ HTTP 422 Unprocessable Entity end else Entity Already Exists rect rgba(255, 0, 0, .15) Skill Engine API-->>Your System: ❌ HTTP 409 Conflict end end ``` After the initial creation, the Skill Clusters can be updated by sending a `PATCH` request to `/taxonomy/skill_clusters/CP-001`. More information can be found at the [endpoint specification](/reference/latest/Taxonomy/TaxonomySkillClusters/patch-taxonomy-skill-clusters-skill-cluster-external-id) . The lifecycle of each Entity is managed explicitly, meaning that you cannot overwrite an existing Entity with a POST message. To update an Entity, you can execute a PATCH call at its specific endpoint. # Configuring Matches Source: https://developers.techwolf.ai/tutorials/vacancy-matching/configuring-matches Two different types of matching configuration are supported: **filters** and **weights**. Filters oppose a hard constraint on the match results, while weights are a soft constraint. ## Filtering Matches You can **restrict the suitable matches** by using filters in the request body. Below you'll find a concrete example of using filters - if you want to have the exhaustive list of filters, you can check the Filters section at the [API reference](). For example, if you want to restrict matching to all the Employees that * live within 50 km of a Vacancy * speak the required language level of the Vacancy (or are 2 levels overqualified) * desire a yearly salary less than or equal (`lte`) to €45000 * have the required driving license you need to submit the following `POST` request to `vacancies//matching_employees`: ```json theme={null} { "filters": [ { "filter": "max_geo_distance", "max_geo_distance": 50 }, { "filter": "language", "max_overqualification": 2, "max_underqualification": 0 }, { "filter": "custom_property", "property_name": "desired_salary", "operator": "lte", "property_value": 45000 }, { "filter": "custom_property_equal", "from_entity_property": "required_driver_license", "to_entity_property": "driver_license" } ], "weights": [] } ``` This assumes that you have added the custom properties `required_driver_license` and `driver_license` upfront (to respectively Vacancy & Employee) as well as the custom property `desired_salary` to Employees - more info on this can be found at [the Custom Properties Tutorial](/tutorials/custom-properties/overview/). If the Employee does not have the custom property `desired_salary` or `driver_license`, the Employee is not included for matching. If other or more strict comparisons are needed for the `custom_property` filter on `desired_salary`, any of the `lt`, `lte`, `eq`, `gte`, `gt` or `neq` operators are also supported. In case you want to compare custom properties that are `list[text]` and `text`, you can also use the `custom_property_is_in` and `custom_property_contains` filters. ## Match weights Via the `weights` attribute in the `POST` request body, you can **tune the matching score calculation**. You can configure both the contribution of the skills-match as the (non-)desired functions for Employees. You can also increase the match score of an entity based on the location or on a custom property. ### The skills-match The skills-match will provide a score contribution of up to the passed weight, scaling linearly with the skills-match score ### (Non-)Desired functions A (non-)desired function will provide a score contribution of up to the passed weight, with the contribution scaling linearly with the relevancy of the function title to the matching vacancy. In case of multiple relevant functions, the most relevant one is used. In the example below, matching scores will be increased by up to `0.1` when a Vacancy title resembles a desired function of an Employee. ```json theme={null} { "filters": [], "weights": [ { "weight": "skills_match", "value": 1.0 }, { "weight": "desired_functions", "value": 0.1 } ] } ``` ### Geo distance The geo-distance will provide a score contribution when two entities (e.g. Vacancies and Employees) are in close proximity of each other. A full boost is applied when the entities are within `full_score_distance` of each other. No boost is applied when the entities are further away than `zero_score_distance`. Between the `full_score_distance` and `zero_score_distance`, the boost value decreases linearly. In the example below, matching scores will be increased by: * `0.1` when a Vacancy is within 10km of an Employee. * `0.05` when a Vacancy is within 30km of an Employee. * `0.0` when a Vacancy is farther away than 50km of an Employee. ```json theme={null} { "filters": [], "weights": [ { "weight": "geo_distance", "value": 0.1, "full_score_distance": 10, "zero_score_distance": 50 } ] } ``` ### Custom properties The custom property weight will provide a score contribution when the target entities meet the custom property criteria specified by you. For example, when submitting a `POST` request to `vacancies//matching_employees` with the following content, the Skill Engine API will: * Increase the match score by `0.05` for the employees that have a desired salary less than €45000. * Increase the match score by `0.1` for the employees that are immediately available (assuming the current date is 2021-04-13). * Increase the match score by `0.05` for the employees that are not a freelancer. ```json theme={null} { "filters": [], "weights": [ { "weight": "custom_property", "property_name": "desired_salary", "operator": "lt", "property_value": 45000, "value": 0.05 }, { "weight": "custom_property", "property_name": "available_from", "operator": "lte", "property_value": "2021-04-13", "value": 0.1 }, { "weight": "custom_property", "property_name": "freelancer", "operator": "eq", "property_value": false, "value": 0.05 } ] } ``` Note that employees that do not have the custom properties `desired_salary` , `available_from` and `freelancer` set, will still be included in the final match results, but without a boost to their match score. # Entity Creation Source: https://developers.techwolf.ai/tutorials/vacancy-matching/entity-creation The essential first step of any flow with the Skill Engine API is creating the Entities within the system. This is done by sending over the entity information to the respective endpoint (`POST` to `/employees` to create an Employee, to `/vacancies` to create a Vacancy). The sequence diagram below shows the flow for a single Employee. Its structure would be identical for other Entity types, and adding multiple Employees is just a matter of repeating the flow. ```mermaid theme={null} sequenceDiagram participant Your System participant Skill Engine API Your System->>Skill Engine API: POST /employees activate Your System alt Creation Successful rect rgba(0, 255, 0, .15) Skill Engine API->>Skill Engine API: Skill Extraction Skill Engine API-->>Your System: ✅ HTTP 204 No Content end else Creation Failed rect rgba(255, 0, 0, .15) Skill Engine API->>Skill Engine API: Skill Extraction Failed Skill Engine API-->>Your System: ❌ HTTP 422 Unprocessable end else Entity Already Exists rect rgba(255, 0, 0, .15) Skill Engine API-->>Your System: ❌ HTTP 409 Conflict end end ``` After the initial creation, the Entity can be updated through its Entity-specific endpoint, e.g. `/employees/101` for an Employee with ID 101. ```mermaid theme={null} sequenceDiagram participant Your System participant Skill Engine API opt Updating an existing Employee Your System->>Skill Engine API: PATCH /employees/ID alt Update Successful rect rgba(0, 255, 0, .15) Skill Engine API->>Skill Engine API: Skill Extraction Skill Engine API-->>Your System: ✅ HTTP 204 No Content end else Update Rejected rect rgba(255, 0, 0, .15) Skill Engine API->>Skill Engine API: Skill Extraction Failed Skill Engine API-->>Your System: ❌ HTTP 422 Unprocessable end else Employee Doesn't Exist rect rgba(255, 0, 0, .15) Skill Engine API-->>Your System: ❌ HTTP 404 Not Found end end end ``` The lifecycle of each Entity is managed explicitly, meaning that you cannot overwrite an existing Entity with a POST message. To update an Entity, you can execute a PATCH call at its specific endpoint. ## Providing Profile Feedback After the creation of a skill profile for an Employee or Vacancy, you or your user might still have something to add (or remove). Taking this feedback into account makes for a win-win situation; improving the user experience, the quality of your data and the accuracy of any matches generated. This can be done by sending a `PUT` request to respectively the `/employees/{external_id}/skill_profile` and `/vacancies/{external_id}/skill_profile` endpoint. # Fetching Matches Source: https://developers.techwolf.ai/tutorials/vacancy-matching/fetching-matches Once your Employees and Vacancies have been created inside the Skill Engine API, you can start generating Vacancy/Employee matches. ## Finding Vacancies for an Employee To find the most suitable Vacancies for a given Employee, submit a `POST` request to `/employees//matching_vacancies`. When you want to use the default matching configuration, the request body below is sufficient. In case you want to add filters & configure the matching score calculation, head over to [the next page](/tutorials/vacancy-matching/configuring-matches/)! ```json theme={null} { "filters": [], "weights": [] } ``` The matches in the response object are sorted by decreasing match score. They are returned with the following structure: ```json theme={null} [ { "employee_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7", "vacancy_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7", "score": 0.87657 }, { "employee_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7", "vacancy_id": "ae4fcdf2-cda5-11ea-87d0-0242ac130003", "score": 0.6544 } ] ``` You can tune the matching results to your preference via the query parameters `score_min_threshold` and `limit`. ## Finding Employees for a Vacancy Finding the most suitable Employees for a given Vacancy is similar to the approach described above, with the only difference being the endpoint: `/vacancies//matching_employees`. ## Getting Explanations With the `matching_employees` and `matching_vacancies` presenting the best matches for a given entity, we can also zoom in on an individual match, fetching not just the match score itself, but also the explanations behind it. By sending a `GET` request to `/employees//vacancies//match`, with query parameter `response_format=explained`, you can retrieve the relevant skills & relevant experience, which explain the matching score. You can then use these explanations to enrich your user experience, as well as to assist users in providing feedback about the match. # Overview Source: https://developers.techwolf.ai/tutorials/vacancy-matching/overview ## Scenario This tutorial describes the fundamentals for a vacancy matching system, with three distinct components: * Creating the Employees/Vacancies * Fetching the Employee/Vacancy matches * Filtering & configuring the matches Both enterprise customers and employment and staffing agencies typically use these three components. Because External Companies are considered separate entities, External Company matching is not included in this tutorial. Head over to the [External Company Tutorial](/tutorials/companies/fetching-matches/) for more information on matching with External Companies. ## Before you start In this tutorial, we assume: 1. All input data is available and grouped per entity (Employee or Vacancy). 2. There is no duplicate data. Our privacy-first policy prevents us from tracing back an employee's identity and merging duplicates. # How It Looks Source: https://developers.techwolf.ai/integrations/analyst-agent/copilot/how-it-looks # The end-user experience Once an administrator has [installed the agent](./installation) for a user, the TechWolf Analyst Agent appears inside Microsoft 365 Copilot as one of the user's agents. From there, using it is the same as any other Copilot agent: the user opens it and asks a question in natural language. This page walks through what an end user sees. # Finding the agent In Microsoft 365 Copilot, the user selects **More agents** in the sidebar to open the Agent Store. The TechWolf Analyst Agent is listed under **Built by your org**, because it was added to the tenant by an administrator rather than installed from the public marketplace. ![The Agent Store with the agent under Built by your org](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/agent-store.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=961e314c70354470cb0a93d5a86ee75a) The Analyst Agent is listed under Built by your org. Selecting the agent shows what it does and the permissions it uses. Adding it is the only step, and the agent is then pinned under **Agents** for next time. ![The agent details panel](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/agent-details.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=8068ce46184ea9c758f2f66674fd5319) The agent's details show what it does and the permissions it uses. # Asking a question The user opens the agent and sends a message to get started, the same as any other chat in Copilot. The first reply can take a moment while the agent gets to work. During that time the user may briefly see the agent's working notes before the answer replaces them. ![The agent working before the answer appears](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/agent-working-notes.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=418d0fa3435204db3ecc208b64920dcb) You may briefly see the agent's working notes before the answer replaces them. On first contact the agent introduces itself and lists what it can help with, such as job architecture, employee skills, AI impact, market intelligence, and workforce planning. From there the conversation continues naturally. ![The agent's introductory message](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/agent-greeting.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=80757f5bf7dc1461af90419bdafae2d0) The agent introduces itself and lists what it can help with. > [!NOTE] > > The answers, the data the agent reasons over, and the user's access scope > are unchanged by using Copilot; it grants no additional access. See > [How It Works](./how-it-works) for the identity and access model. # How It Works Source: https://developers.techwolf.ai/integrations/analyst-agent/copilot/how-it-works # Overview The TechWolf Analyst Agent is reached through **Microsoft 365 Copilot**. This page explains how that integration connects a user in Copilot to the agent. For what the agent itself does, see [What is the TechWolf Analyst Agent?](../overview). Copilot is a **delivery surface**: it changes where a user reaches the agent, not what the agent is, what data it reasons over, or where that data is processed. The integration has three parts: * A **delivery surface**, Microsoft 365 Copilot, through which the user reaches the agent. * A thin **integration layer** at TechWolf that authenticates the user, routes them to their region, and relays the conversation. It holds no business logic and does not interpret or store agent content. * The **Microsoft transport** that carries Copilot messages to TechWolf (Microsoft Azure Bot Service), operating over TLS 1.2+ in both directions. # Architecture A Copilot turn travels through the following path: ```mermaid theme={null} %%{init: {'flowchart': {'subGraphTitleMargin': {'top': 8, 'bottom': 18}}}%% flowchart LR subgraph CUST["Customer Microsoft 365 tenant"] Copilot["M365 Copilot
where the user works"] end subgraph TWAZ["TechWolf Azure tenant"] Entra["Microsoft Entra ID
SSO app, identity only"] Bot["Azure Bot Service
transport"] FD["Azure Front Door
region routing"] Entra --> Bot --> FD end subgraph TWAWS["TechWolf AWS, EU or US region"] GW["TechWolf integration layer
thin relay"] Agent["TechWolf Analyst Agent
tools + Amazon Bedrock, in-region"] GW --> Agent end Copilot --> Entra FD -->|"TLS 1.2+"| GW ``` The only component in your Microsoft 365 tenant is **Copilot itself**, where the user works. The Microsoft transport that carries the turn (the Entra SSO app, Azure Bot Service, and Azure Front Door) runs in **TechWolf's own Azure tenant**, not yours. TechWolf operates backends in **two regions, EU and US**. Azure Front Door is the only cross-cloud hop: keyed on the tenant identifier, it routes each turn to the correct regional backend. Everything from the integration layer onward is TechWolf on AWS, in the single region your tenant is bound to. ## What each hop does, and what it holds | Hop | Function | What it holds | | - | - | - | | **Microsoft 365 Copilot** | The surface the user works in, in **your Microsoft 365 tenant**. Enters as an admin-approved application package; no per-user setup. | Copilot chat history, in your tenant under your Microsoft agreement. | | **Microsoft Entra ID** | Single sign-on, through TechWolf's multi-tenant app in **TechWolf's Azure tenant**. Verifies the user against their own Microsoft directory and establishes the identity carried on every turn. | Nothing new. Identity is verified against your existing directory. | | **Azure Bot Service** | Microsoft's managed transport, operated in **TechWolf's Azure tenant**. Delivers Copilot messages to TechWolf and streams the response back, TLS 1.2+ in both directions. | Bot configuration and routing metadata, plus transient message caching under 24 hours. Transcript logging and conversation-state persistence are optional features TechWolf does not enable. | | **Azure Front Door** | TechWolf-operated Azure edge in **TechWolf's Azure tenant**. Inspects the Entra tenant identifier on each inbound message and routes it to the correct regional TechWolf backend (EU or US). | Nothing. Routing only. | | **TechWolf integration layer** (AWS) | Authenticates the user, resolves TechWolf identity and access scopes, selects the regional runtime, and relays the turn. | The user's email address, used to resolve their TechWolf identity. No business logic and no agent content; logs only. | | **TechWolf Analyst Agent** | The agent itself. Reasons over the organization's TechWolf data within its hard-coded tool whitelist, pinned to the tenant's region, and generates the answer. | Conversation history, in-region. | No agent content or business logic is stored outside the region your tenant is bound to. # Identity and access **Two independent checks gate every turn.** The integration does not broaden what any user can see. * **Microsoft authentication.** Every turn carries a verified Entra identity. The inbound message is cryptographically validated before any processing; no anonymous or unauthenticated request reaches the agent. * **TechWolf authorization.** The verified user is resolved through TechWolf's central identity and access service to a canonical TechWolf user and their access scopes, the same roles and entity-level grants that already govern that user's TechWolf access today. The customer tenant is resolved from the Entra tenant identifier. * **The existing data filter still applies.** The agent's per-user, entity-scope data filtering runs downstream on every turn, regardless of how the user reaches the agent. Reaching the agent through Copilot grants no additional access. ## Restricting access to data sources Dataset entitlements are enforced per tenant, default-deny, on every request, regardless of the surface the user comes from; the Copilot integration changes nothing about them. See [Which data the agent can draw on](../user-management#which-data-the-agent-can-draw-on). # Data residency and data flow TechWolf operates regional backends in the **EU** and the **US**. Each tenant is bound to a single region, keyed on its verified Entra tenant identifier, and every turn from that tenant is served there, with model inference served by the in-region Amazon Bedrock inference profile. **What crosses the Microsoft boundary:** * **Inbound:** the user's message text and their verified identity (email address and Entra tenant identifier). * **Outbound:** the agent's response, as the user reads it in Copilot. That is only the message the user types and the answer they read back. No raw customer documents and no personal data beyond a user identifier traverse this path. The integration adds no tool or data source. Under the Microsoft Data Processing Agreement, Microsoft may process this data only to provide the service, and not for profiling, advertising, or model training. The Microsoft transport carries the conversation in transit and is not a new system of record. # Security and data-isolation controls The integration's controls **fail closed**. When a precondition cannot be safely met, the turn is blocked rather than allowed to proceed in a degraded state. Each control is enforced on every turn. * **Tenant isolation.** Every turn carries the verified per-user identity, and the entity-scope data filter applies downstream. Cross-tenant data retrieval is architecturally prevented. * **Regional data residency.** Routing is keyed on the verified Entra tenant identifier. A request that cannot be mapped to a configured region is rejected, never defaulted. * **Verified identity on every turn.** No request is processed with an unresolved or elevated identity. * **Scoped access.** Bounded by Microsoft SSO combined with TechWolf's tenant and entity-level scoping, the access model that already governs the user's TechWolf access. * **Availability and continuity.** Connectivity is per-turn and stateless, and conversation continuity is preserved via a stable conversation identifier. The runtime runs across multiple availability zones and restarts automatically. ## What the user sees when a control cannot be satisfied | Condition | Behaviour | What the user sees | | - | - | - | | Entra identity cannot be resolved | Turn not processed | A sign-in card: "Sign in to use the TechWolf agent". On a transient fault: "The TechWolf agent could not verify your identity right now. Please try again." | | Tenant not onboarded, or cannot be mapped to a region | Turn not processed; never falls back to a default tenant | "You don't have access to the TechWolf agent. Please contact your administrator." | | Authorization check fails | Turn not processed | The same no-access message. | | Authorization service unreachable | Turn blocked; an outage never grants access | "We couldn't verify your access right now. Please try again in a moment." | | Dataset not covered by the subscription | Server-side, default-deny on every endpoint | An explanation of what the subscription does not cover, rather than a partial answer. | # Installation Source: https://developers.techwolf.ai/integrations/analyst-agent/copilot/installation # Installing the TechWolf Analyst Agent in Microsoft 365 Copilot Installing the Analyst Agent is a **one-time, administrator-gated** action. Nothing is enabled until an administrator acts: there is no per-user installation and no end-user self-service. TechWolf provides the agent as an admin-approved application package; it is not published to the Microsoft commercial marketplace for individual users to install. This guide is written for the Microsoft 365 / Teams administrator who performs the install. It corresponds to the recorded administrator walkthrough below. > [!NOTE] > > A recorded walkthrough of the full installation is available from your > TechWolf contact. # Required roles The installation needs two distinct administrator permissions. They are often, but not always, held by the same person: * **Teams Administrator** (or an equivalent role with **Manage apps** permission): uploads the app package and controls which users or groups the agent is available to. * **Global Administrator**: grants tenant-wide admin consent from the Teams admin center. Only this role can; a Teams Administrator sees the required permissions there but gets *"Contact a Global Administrator to request consent"* instead of a way to grant them. A **Privileged Role Administrator** or **Cloud Application Administrator** can grant the same consent, but has to do it from Microsoft Entra rather than the Teams admin center (see the **Grant admin consent** step). ![The Permissions tab showing 'Contact a Global Administrator to request consent' and no grant control](https://mintcdn.com/techwolf/NMn6OtzVhaa3G6Nl/integrations/analyst-agent/copilot/images/install-consent-required.png?fit=max\&auto=format\&n=NMn6OtzVhaa3G6Nl\&q=85\&s=b943d18ee05610894be64517f7d4d62f) The Permissions tab for an administrator who cannot grant consent. * **Customer contact with TechWolf**: a designated representative who shares the tenant identifier with TechWolf and coordinates the onboarding. No service principal, standing credential, or per-user secret is provisioned for this integration. # What the administrator consents to The integration requests consent for a **single capability**: verifying the signed-in user's Microsoft Entra identity, so each message can be tied to a known user. It needs no access to Microsoft Graph user data, and reads no directory, mailbox, or file content. The only identity data that crosses the boundary to TechWolf is the user's **email address** and **Entra tenant identifier**. > [!NOTE] > > The install grants a **delivery surface, not new data access**. A user who > reaches the agent through Copilot still sees only the data their existing > TechWolf scope permits. See [How It Works](./how-it-works) for the identity > and access model. # Installation steps The installation consists of the following steps. TechWolf first binds your tenant to the correct region, you grant your users access to the agent in the TechWolf Console, your administrator uploads the app package in the Teams admin center, an administrator grants consent once for the whole tenant, and only then do you decide who gets the agent. **1. Share your Entra tenant ID with TechWolf** Provide your **Microsoft Entra tenant identifier** to TechWolf. TechWolf registers it against the correct regional backend, which pins every Copilot turn from your tenant to that region. This is configured once, at onboarding. Follow [Find your Microsoft Entra tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant) if you need to locate it. > [!WARNING] > > A tenant that has not been onboarded is rejected, never defaulted to > another tenant. Until this step is complete, users in your tenant > cannot reach the agent. **2. Give users access to the agent in the TechWolf Console** A user can only reach the agent if they have been granted access to it in the TechWolf Console. Do this for every intended user before they use the agent from Copilot; a user without the agent role sees a no-access message. In the TechWolf Console, go to **User Management**. Use **Add users** to add a new user, or **Edit users** to update an existing one. ![Adding a user in the TechWolf Console](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/console-add-user.png?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=f14ea3af1562a76b11f7a2dc043bf953) Add a user in User Management. Assign the user their roles. The **Data Foundation** roles determine which data the user, and so the agent on their behalf, is allowed to see. ![Data Foundation roles](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/console-roles-data-foundation.png?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=c9a9bb9c65b23f25e11d225e0f4033c6) Assign the user's data roles. Under **TechWolf Agent**, set **Roles** to **Viewer** to grant access to the agent, then select **Add**. ![TechWolf Agent role set to Viewer](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/console-agent-role.png?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=b832bfa650b637990f4efdc8a8937b5a) Grant the TechWolf Agent role, then add the user. **3. Upload the app package** In the [Teams admin center](https://admin.teams.microsoft.com/), go to **Teams apps** -> **Manage apps**. Open the **Actions** menu in the top right and choose **Upload new app**, then **Upload a custom app**. Select the app package (`.zip`) you received from TechWolf. ![Selecting the app package](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/install-select-package.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=e85064a75fde6c96a984031fc1bbe5a8) Select the app package you received from TechWolf. The upload takes a moment and shows no progress indicator; give it ten seconds or so. ![Uploading the custom app](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/install-upload-custom-app.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=0a92915a9deeefd705a445a6a56e1fec) Uploading the custom app package. > [!NOTE] > > You may see an error even though the upload succeeded. Refresh the > page to check before retrying: the app usually appears in the list > after a refresh. **4. Confirm the upload** After refreshing, search for **TechWolf Analyst Agent** by name in **Manage apps** to confirm the upload went through. ![Confirming the app is in the list](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/install-confirm-in-list.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=b0d2b06d1f5bcb7999010ed9053294fb) Search for the app by name to confirm the upload. Open the app and check the **About** tab. It shows the publisher (TechWolf) and the uploaded version, so you can confirm you have the package TechWolf provided. ![The app's About tab](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/install-about-tab.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=5fa87410260a193a022125b2ff8052a8) The About tab shows the publisher and the uploaded version. **5. Grant admin consent** The agent verifies each user's Entra identity, and that verification needs tenant-wide admin consent. It is a separate action from the upload above and needs one of the Entra roles listed at the top of this page, so it may well be a different person. A **Global Administrator** does this on the app you just uploaded, in the same Teams admin center. Open **Teams apps** → **Manage apps**, search for the agent by name, open it, and go to its **Permissions** tab. Review the permissions in the dialog that opens, then select **Accept**. The tab lists exactly what is being granted: three delegated Entra ID permissions, `openid` (sign users in), `email` (view users' email address) and `profile` (view users' basic profile). That is enough to confirm who the signed-in user is, and nothing more. See [What the administrator consents to](#what-the-administrator-consents-to) above. ![The app's Permissions tab showing admin consent granted for openid, email and profile](https://mintcdn.com/techwolf/NMn6OtzVhaa3G6Nl/integrations/analyst-agent/copilot/images/install-grant-consent.png?fit=max\&auto=format\&n=NMn6OtzVhaa3G6Nl\&q=85\&s=0df1eec3f56c78a887e91a7246114bab) The Permissions tab once consent has been granted. When it is done, the tab shows **Admin consent granted for all required permissions**, which is also how you check it later. Consent covers the whole tenant, so it is granted once and applies to every user, never per person, and revoking it stops the agent for everyone. > [!NOTE] > > **If the person granting consent is not a Global Administrator**, a > Privileged Role Administrator or Cloud Application Administrator can > grant the same consent from Microsoft Entra instead. Open the > consent URL below, signed in as that administrator, and accept: > > ``` > https://login.microsoftonline.com//adminconsent?client_id=67e0fd02-01f0-4752-8776-7a3feb0428ec > ``` > > Substitute the tenant ID you shared in step 1. Putting it in the URL > rather than using `organizations` is deliberate: it pins the grant to > the tenant you are setting up, instead of whichever tenant the > signed-in account happens to belong to. > > Two things to expect. The browser lands on a > `token.botframework.com` page reporting a missing `code` parameter; > that is the redirect target being an API rather than a web page, and > the grant has already been recorded by then. Check for > `admin_consent=True` and your own tenant ID in the address bar to > confirm. Afterwards the application appears under **Enterprise > applications**, where the grant can be reviewed or revoked. > > The **Enterprise applications** pane cannot be used to grant it the > first time: an application only appears there once it is provisioned > in your tenant, which this consent is what does. > [!WARNING] > > Grant this **before** assigning users in the next step. Your users > cannot grant it themselves, so anyone who reaches the agent first > gets *"you need to agree to additional permissions"* followed by > *"Something went wrong. Please try again."*, and that prompt never > completes no matter how often it is retried. **6. Choose who gets access** Decide which users or groups get the agent, using the tenant's standard app-assignment controls, the same mechanism as any other Teams application. The integration grants no access on its own. The same **Users and groups** controls govern two things: the agent's **availability** (which users or groups can find and add it themselves) and its **installation** (installing it for them directly). You can make the agent available for users to add on their own, install it for specific users or groups, or both. The steps below install it directly. On the app page, open **Users and groups** and choose **Install app**. ![Choosing who gets access](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/install-choose-access.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=f9ab62dc13195c0c8fab3d4d592d5a73) Open Install app to choose who gets access. Set **Install** to **Specific users or groups**, then add the people or groups that should have the agent by name. ![Adding users and groups](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/install-add-users-groups.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=104847bf3be6822272301a7dd55bf0f6) Add the specific users or groups that should have the agent. Apply the change. The agent is now installed for the selected users, and only the users you add here get it: access stays under your control. ![Installation confirmed](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/install-confirmation.jpg?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=658be6b5c56d30fd47a70d456ac3965b) The agent is now installed for the selected users. > [!NOTE] > > Once assigned, users find the agent in Microsoft 365 Copilot under > **Agents**. See [How It Looks](./how-it-looks) for the end-user > experience. If anything in this documentation does not match your experience or needs clarification, contact us at [support@techwolf.ai](mailto:support@techwolf.ai). # Credits Source: https://developers.techwolf.ai/integrations/analyst-agent/credits # Credits The Analyst Agent comes with a weekly **credit allowance** for your whole organization, sized to comfortably cover regular use. The current balance is always visible in the product. # How the allowance works * **One shared pool per organization.** The allowance is held at the organization level, not per person. There is no per-user cap, so you do not need to divide it between your team in advance. * **It refreshes weekly.** The allowance resets at the start of each week. Unused credits do not carry forward. * **Cost scales with the work.** A simple lookup costs a small number of credits; a deep, multi-step analysis costs more. Clarifying questions the agent asks before starting work are free. * **Purchased credits are separate.** If your organization buys additional credits, they sit in their own pool, never expire, and are only drawn once the weekly allowance is used up. > [!NOTE] > > Using the agent through Microsoft 365 Copilot draws on the same shared > pool. There is no separate allowance or additional cost for that surface. > [!WARNING] > > The weekly allowance and its refresh apply to **production tenants only**. > Non-production tenants, such as staging and testing environments, receive a > fixed one-off grant instead. When it is used up, the agent stops responding > in that tenant until TechWolf grants more, so plan evaluation work > accordingly and contact your TechWolf representative when you need a > top-up there. # Checking your balance The credit badge in the top right of the agent shows the current balance and links to the credits page, which shows your weekly allowance, how much of it has been used this week, the cost of each type of request, and any purchased credits remaining. Administrators and end users see the same page. ![The Agent credits page](https://mintcdn.com/techwolf/GjFT9_YJionkLLPN/integrations/analyst-agent/images/agent-credits.jpg?fit=max\&auto=format\&n=GjFT9_YJionkLLPN\&q=85\&s=07488e938fbce09ec116774c8f7913d7) The credits page shows your allowance, usage and refresh date. > [!NOTE] > > There is no credit view inside the Microsoft 365 Copilot experience. Check > your balance in the TechWolf Console. # FAQ Source: https://developers.techwolf.ai/integrations/analyst-agent/faq # Frequently asked questions Access questions are covered in [User Management](./user-management), the allowance in [Credits](./credits). This page covers using the agent day to day. # Getting good answers ## Why did the same question give me a different answer the second time? It depends on the kind of question. **Recall questions are stable.** "How many employees have this skill" or "what percentage of time for this job is automatable" are calculations over your data: ask twice, get the same answer. If a recall answer did change, the most likely cause is that **your data changed** in between. The agent reads live data, so validated profiles, edited jobs or a completed integration run move the numbers with them. **Generative questions will vary.** "What are the role redesign opportunities for this job" asks the agent to reason and propose. Two runs produce two well-founded but differently worded answers, the same way two analysts would. This is intended behaviour. ## How do I get more consistent results? * **Be specific about scope.** Name the job family, organizational unit, peer group or time period rather than leaving it open. * **Say which data to use**, for example only validated skills, or only a named set of jobs. * **Start a new conversation for each new analysis.** Earlier context helps within one piece of work and confuses across two. * **Attach the exact list.** If you want a specific set of jobs or employees, upload it rather than describing it. ## The agent says it cannot answer my question. Should I rephrase it? Once, yes. Repeatedly, no. When the agent says it cannot do something, that is usually accurate: the question needs an analysis the underlying data products do not support, and pressing it into attempting one produces a long wait or an unreliable result. If you believe the question should be answerable, raise it with your TechWolf representative; knowing which analyses people want shapes what we build. # Data and conversations ## Why can a colleague see something I cannot? The agent shows you exactly what your Console access allows. See [What determines what a user sees](./user-management#what-determines-what-a-user-sees). ## What languages can I use? You can hold the conversation in any language the agent's multi-lingual models support: prompting in French returns an answer in French. The surrounding interface is English only. ## How is my data handled? The agent reads only from your organization's TechWolf data, within your deployment region. See [Responsible AI Principles](/technology/responsible-ai-principles) and [Security](/technology/security). For the Copilot surface specifically, see [How It Works](./copilot/how-it-works). # What is the TechWolf Analyst Agent? Source: https://developers.techwolf.ai/integrations/analyst-agent/overview # TechWolf Analyst Agent The TechWolf Analyst Agent is a workforce intelligence agent. A user asks it questions in natural language, and it answers from the organization's TechWolf data combined with external labour-market data. It can help with: * **Job architecture:** what skills roles require, how jobs are structured, and where the gaps are. * **Employee skills:** who has which skills, and where the gaps are. * **AI impact:** which tasks and roles are most affected by automation. * **Market intelligence:** what the external market is hiring for, and how the organization's roles compare. * **Workforce planning:** internal mobility, role redesign, and strategic planning. The agent is advisory and read-only: it explains and analyses, and it cannot take actions in any HR system. It runs on TechWolf's infrastructure, with model inference served by Amazon Bedrock in the organization's region. # Where users reach it The agent is available in two places: * **The TechWolf Console.** Users with agent access open it directly from the Console. Access is granted per user by your own administrators; see [User Management](./user-management). * **Microsoft 365 Copilot.** The same agent, inside the tools your teams already work in. Your Microsoft 365 administrator sets it up once for the whole organization; see [Installation](./copilot/installation). Both surfaces answer from the same data with the same per-user access rules, and draw on the same credit allowance. # In this section * [User Management](./user-management): granting and removing access, and what determines the data each user sees. * [Credits](./credits): how your organization's weekly credit allowance works. * [M365 Copilot](./copilot/installation): installing the agent in Copilot, how the integration works, and what it looks like. * [FAQ](./faq): day-to-day usage questions. If you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please reach out to us at [support@techwolf.ai](mailto:support@techwolf.ai). # Usage Reports Source: https://developers.techwolf.ai/integrations/analyst-agent/reports # Usage Reports The Analyst Agent keeps a query-level record of how your organization uses it, and lets your administrators download that record as CSV for any period. Use it to monitor adoption, review what the agent is being asked, and account for credit consumption. Reports cover **every surface**: questions asked in the TechWolf Console and questions asked through Microsoft 365 Copilot appear in the same files. # Who can see reports Reports are available to users with the **Reports Viewer** role under **Analyst Agent**, assigned per user in the Console's User Management exactly like agent access itself. Any user who can manage users in your Console can assign it; see [User Management](./user-management). > [!NOTE] > > **Reports Viewer** includes everything **Viewer** gives, plus the reports, > so it replaces **Viewer** rather than sitting next to it. Users with plain > **Viewer** keep using the agent but do not see the reports. Users with **Reports Viewer** open the menu in the top right of the agent and select **Usage Reports**. > [!NOTE] > > There is no reports view inside the Microsoft 365 Copilot experience. > Copilot usage is included in the reports, but the reports themselves are > downloaded from the TechWolf Console. # The reports page ![The Analyst Agent usage reports page](https://mintcdn.com/techwolf/ntVGLhMANT-yHKMd/integrations/analyst-agent/images/agent-reports-page.png?fit=max\&auto=format\&n=ntVGLhMANT-yHKMd\&q=85\&s=8cefd70af6c2849cd0d20d6029272e7f) Pick a period, then download either report as CSV. Pick a **From** and **To** date. The summary line gives the number of queries and the number of distinct people in that period, and the graph breaks both down by week (Monday to Sunday, UTC) so you can see the trend before downloading anything. The page offers two reports over the chosen period. ## Usage report One row per query: who asked, when, from which surface, and the credits it drew. Queries that drew no credits are included as zero-credit rows, so this is the complete record of activity rather than only the chargeable part. | Column | What it holds | | - | - | | `timestamp` | When the answer was returned, in UTC | | `user_id` | The person who asked. Stable and consistent across surfaces, so one person is one id | | `conversation_id` | The chat the query belongs to, so related queries can be grouped | | `query_id` | The query itself, and the join key to the question-answer report | | `source` | Where it was asked: `console` or `copilot` | | `size` | How much work the query took: `none`, `small`, `medium` or `large` | | `credits` | Credits the query drew, `0` in the `none` band. See [Credits](./credits) | ## Question-answer report Each question with the final answer it received. Nothing else: no reasoning steps, no tool activity, no intermediate output. It carries the same first five columns as the usage report, so the two files join on `query_id`. | Column | What it holds | | - | - | | `timestamp` | When the answer was returned, in UTC | | `user_id` | The person who asked | | `conversation_id` | The chat the query belongs to | | `query_id` | The join key to the usage report | | `source` | `console` or `copilot` | | `question` | The question as the user asked it | | `answer` | The final answer the user received | # What the reports contain * **People are identified by a stable id, not by name or email address.** The same person carries the same `user_id` in both reports and on every surface, so you can count distinct users and follow one user's activity without the files carrying anyone's identity. * **TechWolf accounts are excluded.** Sessions run by TechWolf staff assisting your team do not appear, and never draw on your credits. * **Answered queries only.** A question the agent asked you back, before it started any work, is not a query. If you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please reach out to us at [support@techwolf.ai](mailto:support@techwolf.ai). # User Management Source: https://developers.techwolf.ai/integrations/analyst-agent/user-management # Managing access to the TechWolf Analyst Agent Your own administrators manage agent access, per user, in the TechWolf Console's **User Management**. It is the same user management you already use for Console access; there is no separate admin surface. Two independent things determine what a user can do: * **Whether they can reach the agent:** the **Viewer** role under **TechWolf Agent**, assigned per user. * **What they see once inside:** their **Data Foundation** roles and entity access. The agent never widens access. > [!NOTE] > > Signing in through single sign-on is not by itself enough to reach the > agent. Nobody has the agent role until an administrator assigns it; a user > without it sees a no-access message. # Granting access Any user who can manage users in your Console can grant agent access. **1. Open the user in User Management** In the TechWolf Console, go to **User Management**. Use **Add users** to add a new user, or **Edit users** to update an existing one. ![Adding a user in the TechWolf Console](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/console-add-user.png?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=f14ea3af1562a76b11f7a2dc043bf953) Add a user in User Management. **2. Check the user's Data Foundation roles** The **Data Foundation** roles determine which data the user, and so the agent on their behalf, is allowed to see. Confirm they match what you expect the user to be able to analyse; see [What determines what a user sees](#what-determines-what-a-user-sees). ![Data Foundation roles](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/console-roles-data-foundation.png?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=c9a9bb9c65b23f25e11d225e0f4033c6) Assign the user's data roles. **3. Grant the agent role** Under **TechWolf Agent**, set **Roles** to **Viewer**, then select **Add** (or save your changes for an existing user). ![TechWolf Agent role set to Viewer](https://mintcdn.com/techwolf/tsN6h2ZCZ5XiSEJ7/integrations/analyst-agent/copilot/images/console-agent-role.png?fit=max\&auto=format\&n=tsN6h2ZCZ5XiSEJ7\&q=85\&s=b832bfa650b637990f4efdc8a8937b5a) Grant the TechWolf Agent role, then add the user. > [!NOTE] > > Access changes apply immediately. Users do not need to sign out and > back in. To see who has access today, review the **Analyst Agent** column in **User Management**. To remove access, clear the user's **Viewer** role there; this also takes effect immediately. # What determines what a user sees The agent inherits each user's Console access exactly. If a user cannot see something in the Console, the agent will not show it or reason over it on their behalf. These are the settings that shape the answers a user gets: | Console access | Effect in the agent | | - | - | | **Skill Supply Roles** | Whether the user sees employee skills at all | | **Employee Org Units** | Which employees are in scope | | **Skill Demand Roles** | Whether the user sees job skills at all | | **Tasks on Jobs Roles** | Whether the user sees job tasks | | **Jobs** | Which jobs are in scope, all or a named subset | > [!NOTE] > > A user whose access is narrowed gets a correspondingly narrower answer, not > an error. If an answer looks incomplete, check the user's data access > first. > [!WARNING] > > A user cannot be given view access to all jobs while owning only some of > them. If a user owns a subset of jobs, they see only that subset, and the > agent answers accordingly. Differing view permissions per job are not > supported today. # Which data the agent can draw on Separately from per-user access, the agent only uses the TechWolf data products your organization subscribes to. These dataset entitlements are enforced server-side on every request, **default-deny** and applied **per tenant**, not per user. A tenant scoped to Market Intelligence receives only Market Intelligence; when a question needs data outside your subscription, the agent explains what is not covered rather than returning a partial answer. Access is **read-only by construction**: the agent cannot execute actions in any HR system. > [!NOTE] > > Restricting specific user groups *within* a tenant to a subset of data > sources is a roadmap item rather than a capability available today. > Entitlements are applied at the tenant level. # Access through Microsoft 365 Copilot Reaching the agent through Copilot changes nothing about who can see what. Every message carries a verified Microsoft Entra identity, resolved to that user's existing TechWolf role and data scope before any data is read. Users still need the **Viewer** role, assigned exactly as above. See [How It Works](./copilot/how-it-works) for the full identity and access model. # Troubleshooting * **A user cannot open the agent.** Confirm the **Viewer** role is assigned under **TechWolf Agent**. This is the most common cause. * **A user sees fewer employees or jobs than expected.** This is data access working as intended. Review their organizational unit and job access. * **Nobody in the organization can open the agent.** Contact [support@techwolf.ai](mailto:support@techwolf.ai). Access checks fail closed, so a temporary service issue results in access being denied, never granted. # Installation Source: https://developers.techwolf.ai/integrations/datasource-integrations/connectors/cornerstone/installation Step-by-step guide to configure Cornerstone OnDemand for the TechWolf Data Source Connector. This page walks through the Cornerstone OnDemand setup required for the TechWolf Data Source Connector. ## Prerequisites * An active TechWolf contract. * A Cornerstone OnDemand tenant with the Reporting API enabled in Edge Marketplace and API Management. Production tenants may require Reporting API purchase and enablement first. * Access to Cornerstone Edge and API Management. * The `Edge APIs - Manage` security permission. * A service-account user that has, or can be granted, the `Reporting API - Read Only` security permission. * Employees already synchronized into TechWolf through an HRIS connector. **Important:** Cornerstone completed learning events are linked to TechWolf Employees by an Employee identifier. By default, TechWolf assumes `users_core.user_ref` in Cornerstone is the same value as the Employee `external_id` in the SkillEngine API. Confirm this alignment with TechWolf before enabling the connector. ## Cornerstone configuration ### 1. Confirm the Cornerstone portal Find the Cornerstone portal value for your tenant. This is the exact host prefix before `.csod.com`. If your Cornerstone URL is: ```text theme={null} https://acme.csod.com ``` the portal value to share with TechWolf is: ```text theme={null} acme ``` For a pilot or staging tenant, use that environment's host prefix, for example `acme-pilot` from `https://acme-pilot.csod.com`. ### 2. Enable Reporting API access In Cornerstone, go to **Admin > Tools > Edge > Marketplace** and enable the **Reporting API** for the tenant. Then go to **Admin > Tools > Edge > API Management** and make sure the Reporting API toggle is enabled. ### 3. Register an OAuth 2.0 application In Cornerstone, go to **Admin > Tools > Edge > API Management > Manage OAuth 2.0 Applications** and register a new application for the TechWolf connector. Configure the application with: * A descriptive application name, for example `TechWolf Connector`. * The **User ID** of the service-account user that has `Reporting API - Read Only`. * An access token validity period that matches your security policy. After registering the application, securely store the generated **Client ID** and **Client Secret**. You will share them with TechWolf at the end of this guide. ### 4. Add the required Data Exporter API scopes In the application **Endpoint scopes/permissions**, select **Reporting API**, filter for Data Exporter API endpoints by typing `obj`, and add the following read scopes: | Scope | Used for | | - | - | | `obj_training_local_core:read` | Course titles, descriptions, and language-specific catalog data | | `obj_training_core:read` | Course active status and learning object metadata | | `obj_culture_core:read` | Language lookup for catalog entries | | `obj_transcript_core:read` | Completed learning transcripts | | `obj_users_core:read` | Mapping Cornerstone transcript users to Employee identifiers | ### 5. Grant Reporting API read access Grant the service-account user linked to the OAuth app the following Cornerstone permission: ```text theme={null} Reporting API - Read Only ``` This permission is required in addition to the OAuth scopes. The scopes allow the token to request the objects; the service-account permission allows Cornerstone to return the Data Exporter API rows. ### 6. Confirm Employee identifier alignment Confirm that Cornerstone `users_core.user_ref` contains the same identifier as the Employee `external_id` loaded into the SkillEngine API by the customer's HRIS connector. If Cornerstone uses a different Employee key, align with TechWolf before continuing. Without this mapping, completed learning events cannot be attached to the right Employees. ## Share credentials with TechWolf Once the Cornerstone configuration is complete, securely share the following values with TechWolf: | Credential | Description | | - | - | | Portal | The Cornerstone portal subdomain, for example `acme` from `https://acme.csod.com` | | Client ID | The OAuth app client ID | | Client secret | The OAuth app client secret | **Important:** The client secret grants access to your Cornerstone Data Exporter API objects. Share it only through the secure channel agreed with your TechWolf representative. Never share it over plain email or chat. # Overview Source: https://developers.techwolf.ai/integrations/datasource-integrations/connectors/cornerstone/overview API-based connector that extracts learning data directly from Cornerstone OnDemand using the Data Exporter API. # Cornerstone OnDemand Data Source Connector The Cornerstone OnDemand Data Source Connector is an API-based integration that extracts learning data directly from Cornerstone OnDemand (CSOD) using the Cornerstone Data Exporter API. It synchronizes the course catalog and completed learning history into TechWolf on a scheduled basis. The connector is intended for customers who use Cornerstone as their learning management system. Employees, organisational units, and jobs are normally synchronized through an HRIS connector such as Workday or SAP SuccessFactors. Cornerstone learning events then attach to those Employees using the default assumption that Cornerstone `users_core.user_ref` matches the Employee `external_id` in the SkillEngine API. ## Key benefits * **No file infrastructure**: no SFTP server, export schedule, or manual file transfer is required. * **Learning-focused setup**: the connector syncs the course catalog and completed learning events from Cornerstone. * **Customer-controlled access**: the customer creates the OAuth app in Cornerstone Edge and controls exactly which Data Exporter objects TechWolf can read. * **Setup validation**: TechWolf validates the OAuth scopes and Reporting API access before enabling the scheduled connector. ## How it works 1. You enable Reporting API access in Cornerstone Edge. 2. You register an OAuth 2.0 application in Cornerstone API Management. 3. You grant the app read access to the required Data Exporter API objects. 4. You securely share the Cornerstone portal and OAuth credentials with TechWolf. 5. TechWolf validates the credentials and configures the connector. 6. The connector reads the course catalog and completed transcripts from Cornerstone and loads them into SkillEngine. The connector reads Cornerstone through the Data Exporter API. It does not receive raw export files and does not require access to a customer-hosted file server. ## Available data types ### Courses The course catalog in Cornerstone. | Output field | Description | | - | - | | `external_id` | Cornerstone learning object ID | | `course_title` | Course title | | `course_description` | Course description. If Cornerstone has no description, the connector uses the title. | | `active` | Whether the learning object is active in Cornerstone | | `language` | Language of the catalog entry | ### Learnings Completed learning events for Employees. | Output field | Description | | - | - | | `employee_external_id` | Employee identifier used to attach the learning to the TechWolf Employee | | `course_id` | Cornerstone learning object ID of the completed course | | `completion_date` | Completion date from the Employee transcript | **Important:** Cornerstone learning events can only attach to Employees that already exist in TechWolf. By default, TechWolf assumes Cornerstone `users_core.user_ref` is the same value as the Employee `external_id` in the SkillEngine API. Confirm this with TechWolf before enabling the connector. ## Next steps Continue with the [Installation](/integrations/datasource-integrations/connectors/cornerstone/installation) guide to configure the Cornerstone OAuth app and share the required credentials with TechWolf. # How It Works Source: https://developers.techwolf.ai/integrations/datasource-integrations/connectors/sap-btp/how-it-works This page describes how the SAP SuccessFactors via BTP Data Source Connector moves data from SuccessFactors to TechWolf, what is configured per install, and how the components authenticate to each other. ## Shape The connector consists of two Integration Flows deployed in the customer's SAP Integration Suite: a **Frontend**, a **Worker**, and one Value Mapping artifact that holds per-tenant configuration. TechWolf calls the Frontend over HTTPS. The Frontend hands work to the Worker through an internal queue. The Worker calls SuccessFactors and writes the results to TechWolf-managed storage. TechWolf reads from that storage to ingest data into the SkillEngine API. ``` TechWolf ──HTTPS──▶ Frontend iFlow ──queue──▶ Worker iFlow ──OData V2──▶ SuccessFactors │ └──▶ TechWolf-managed storage ──▶ TechWolf ``` ## Per-run lifecycle 1. **TechWolf requests a run**: TechWolf POSTs a run request to the Frontend for a specific data type. The Frontend validates the data type against an allowlist baked into the package and rejects unknown names. 2. **Frontend acknowledges and queues**: The Frontend writes an initial run state to TechWolf-managed storage, kicking off the integration. It hands off the processing to the Worker through an internal queue, and returns a run identifier to TechWolf. 3. **Worker calls SuccessFactors**: The Worker looks up the OData V2 EntitySet and query for the requested data type, calls the SuccessFactors OData V2 API with paging, and writes each page of results to TechWolf-managed storage as it arrives. 4. **Worker maintains run state**: Throughout the run, the Worker updates a run state record in TechWolf-managed storage so TechWolf can track progress, liveliness, and completion. The final state records whether the run completed successfully or failed. 5. **TechWolf ingests**: TechWolf reads the staged data from storage and ingests it into the SkillEngine API. ## Per-install configuration The connector exposes one tenant-specific Value Mapping artifact called `TenantConfig`. It holds the values that differ between installations. Everything else (the list of data types, the SuccessFactors EntitySet and query for each data type, the page size, and the output mapping) is baked into the Content Package. Adjusting the query for a data type is currently a package update from TechWolf, not a customer reconfiguration. The `TenantConfig` artifact holds the following values: | Field | Description | TechWolf Provided | | - | - | :-: | | `SF_address` | Base URL of your SuccessFactors data center (e.g. `https://api.successfactors.eu`). | | | `SF_credential_name` | Name of the OAuth 2 SAML Bearer Assertion credential created in BTP Security Material, used by the Worker to authenticate to SuccessFactors. | | | `S3_bucket` | TechWolf-managed S3 bucket the Worker writes to. Provided by TechWolf. | | | `S3_region` | AWS region of the TechWolf-managed S3 bucket. Provided by TechWolf | | | `S3_base_path` | Base path inside the bucket under which run artifacts are written. | | | `S3_access_key_alias` | Alias of the BTP Keystore entry holding the access key for the TechWolf-managed S3 bucket. | | | `S3_secret_key_alias` | Alias of the BTP Keystore entry holding the secret key for the TechWolf-managed S3 bucket. | | The values for these fields are provided by your TechWolf representative during installation. ## Authentication The connector uses two distinct authentication flows. ### TechWolf → Frontend TechWolf authenticates to the Frontend iFlow using **OAuth 2 Client Credentials**. The credentials are backed by a Process Integration Runtime service key created during installation and shared with TechWolf. Every call carries the standard OAuth 2 client-credentials bearer token; the iFlow validates it through the BTP-managed authorization server. ### Worker → SuccessFactors The Worker authenticates to SuccessFactors using an **OAuth 2 SAML Bearer Assertion** flow, backed by a customer-managed X.509 certificate stored in the BTP Keystore. The flow ties together a key pair in the BTP Keystore, a SuccessFactors technical user, and a SuccessFactors OAuth 2 Client Application. All three are identified by the same Common Name. The detailed setup is described in the [Set up BTP ↔ SuccessFactors authentication](/integrations/datasource-integrations/connectors/sap-btp/installation#set-up-btp--successfactors-authentication) section of the installation guide. ## Observability * **Customer side**: Every Frontend and Worker invocation appears in SAP BTP's **Monitor Message Processing** view, including the data type, the run identifier, and per-step logs. This is the customer's view of every call the connector makes to SuccessFactors. * **TechWolf side**: Run state in TechWolf-managed storage reflects the lifecycle of every run (`queued`, `running`, `done`, `failed`). TechWolf uses this to drive ingestion and to surface failures. ## Reference material * [SAP Integration Suite documentation ](https://help.sap.com/docs/integration-suite) * [SAP SuccessFactors OData V2 API ](https://help.sap.com/docs/successfactors-platform/sap-successfactors-api-reference-guide-odata-v2/sap-successfactors-api-reference-guide-odata-v2) * [Installation](/integrations/datasource-integrations/connectors/sap-btp/installation) — the full BTP package install and SuccessFactors auth procedure for this connector. # Installation Source: https://developers.techwolf.ai/integrations/datasource-integrations/connectors/sap-btp/installation This page walks through installing the SAP SuccessFactors via BTP Data Source Connector in your SAP BTP tenant, from importing the BTP package and setting up SuccessFactors authentication through to deploying the iFlows. ## Prerequisites * An active **TechWolf contract** with SkillEngine API credentials. * A working **SAP SuccessFactors** tenant. * An SAP SuccessFactors administrator user with permissions: * **Manage Permission Roles** * **Manage Permission Groups** * **Manage OAuth 2 Client Applications**. * A working **SAP BTP** tenant with: * **SAP Integration Suite** provisioned including the *Build Integration Scenarios* capability. * Your user must have the following roles: * `PI_Administrator` * `PI_Integration_Developer` * The **Content Package** for this connector, which can be found below. * The **Integration User Definition** file for setting up an API user in SAP SF. For more information on setting up Integration Suite, refer to [the SAP community guide ](https://community.sap.com/t5/technology-blog-posts-by-members/step-by-step-guide-create-trial-account-for-sap-integration-suite-2025-amp/ba-p/14002055). > **[Content Package](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/datasource-integrations/techwolf-sap-successfactors-input-integrations.zip)** > > Content Package for the SAP BTP Datasource Integration > **[Integration User Definition](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/datasource-integrations/techwolf_sap_btp_datasource_api_user_definition.csv)** > > Integration user definition for import ## Install the BTP package These steps import the connector's Content Package into your BTP tenant and create the inbound authentication TechWolf uses to call the iFlow. **1. Create a User Role for the integration** In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > User Roles**, then click **Add**. Enter a **Name** that you will remember in the next step and when configuring the iFlows later (e.g. `TechWolfBTPIntegration.send`) and click **Add**. **2. Create a Process Integration Runtime instance** In SAP BTP Cockpit, create a new instance of the **Process Integration Runtime** service with the `integration-flow` plan. ![Create a new Process Integration Runtime instance](https://mintcdn.com/techwolf/lBwiSzmFbw0l1PI9/integrations/datasource-integrations/connectors/sap-btp/images/new-instance.png?fit=max\&auto=format\&n=lBwiSzmFbw0l1PI9\&q=85\&s=bee86d893dd11ebe98ea98568e93cc0d) * Check *"I understand that enabling a service might result in costs, depending on the plan selected."* * **Runtime Environment**: Cloud Foundry. * **Space**: the Cloud Foundry space you're deploying in. * **Instance Name**: a CLI-friendly name (e.g. `tw-it-rt-iflow`). * Click **Next** to continue to the Parameters step. * In **Parameters**, set the role to the one created in the previous step (e.g. `TechWolfBTPIntegration.send`). * **Grant-types**: `Client Credentials`. * Leave all other fields on their default values. Click **Create**. For SAP's reference on creating the service instance and service key, see [Creating Service Instance and Service Key for Inbound Authentication ](https://help.sap.com/docs/integration-suite/sap-integration-suite/creating-service-instance-and-service-key-for-inbound-authentication). **3. Create a Service Key on the instance** Find the newly created Process Integration Runtime instance. Click the three dots on the right, then click **Create Service Key**. * **Service Key Name**: any value (e.g. `TechWolfBTPDatasourceIntegration`). * **Key Type**: `ClientId/Secret`. * Leave all other fields on their default values. Click **Create**. On the instance, go to **Service Keys** and wait for the key to be created, then click the service key and click **Download**. Keep the **service key file** available, as you will share it with your TechWolf representative at the end of this guide. > [!WARNING] > > The service key file contains credentials that grant access to invoke your > iFlows. Store it securely. Share it with your TechWolf representative > through a secure channel agreed with them. **Never share it over plain email > or chat.** For SAP's reference on creating the service instance and service key, see [Creating Service Instance and Service Key for Inbound Authentication ](https://help.sap.com/docs/integration-suite/sap-integration-suite/creating-service-instance-and-service-key-for-inbound-authentication). **4. Import the Content Package** In SAP Integration Suite, go to **Design > Integrations and APIs** and click **Import**. In the file picker, select the Content Package zip file provided by your TechWolf representative. Additionally, Under **Discover > Integrations**, search for `Amazon Web Services Adapter for SAP Integration Suite`. Press **Copy** to add the adapter to your Integration Suite integrations. After import, the package and its iFlows are available under **Design > Integrations and APIs**, but are not yet deployed. The iFlows are configured and deployed later in this guide. ## Set up BTP ↔ SuccessFactors authentication These steps let the Worker iFlow call SuccessFactors on TechWolf's behalf. The authentication uses an **OAuth 2 SAML Bearer Assertion** flow, backed by a customer-managed X.509 certificate in the BTP Keystore. The same certificate's Common Name is used in three places: the certificate itself, the SuccessFactors technical user, and the SuccessFactors OAuth 2 Client Application. The flow only succeeds if all three values match exactly. If you choose a different name than `TechWolf_BTP_Datasource`, be sure to update it in all the locations it is used, especially the user import definition. **1. Create a key pair in the BTP Keystore** * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > Keystore**, then click **Create > Key Pair**. * Set **Alias** to a value you will remember when configuring the SAML Bearer credential later (e.g. `techwolf_btp_datasource_successfactors`). * Set **Common Name** to `TechWolf_BTP_Datasource` (or a different choice). * Set **Country** to the two-letter ISO 3166-1 alpha-2 code for your country (e.g. `BE` for Belgium, `US` for the United States). [List of ISO 3166-1 alpha-2 codes ](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). * (Optional) Change **Valid Until** to a date of your choice. * Leave all other fields on their default values. * Click **Create**. The new key pair appears in the Keystore overview. * Click the new key pair, then click **Download > Certificate**. Keep the downloaded certificate file available; you will paste its contents into SuccessFactors when registering the OAuth 2 Client Application below. For SAP's reference on creating the key pair, see [Creating a Key Pair/SSH Key Pair ](https://help.sap.com/docs/integration-suite/sap-integration-suite/creating-key-pair-ssh-key-pair). **2. Create the TechWolf technical user in SuccessFactors** In SuccessFactors, create a technical user with **User ID** `TechWolf_BTP_Datasource` (matching the Common Name set in the key pair step) by importing the provided Integration user definition CSV via **Admin Center > Import Employee Data**. Use **Basic Import** under `Select an entity`. Assign the user to a Permission Group that holds the permissions listed in [Grant SuccessFactors permissions](#grant-successfactors-permissions) below. For SAP's reference on importing a user definition, see [Managing Basic User Data by Using a Data File ](https://help.sap.com/docs/successfactors-platform/managing-user-information/managing-basic-user-data-by-using-data-file). **3. Register the SuccessFactors OAuth 2 Client Application** * In SuccessFactors, in the search bar at the top right, enter `Manage OAuth 2 Client Applications` and press enter. * Click **Register Client Application**. * Fill in the following fields: * **Application Name**: any value (e.g. `techwolf_btp_datasource`). * **Application URL**: any valid URL (e.g. `https://www.techwolf.ai`). * **Bind to Users**: check the checkbox. * **User IDs**: `TechWolf_BTP_Datasource` (matching the Common Name and technical user ID from the previous steps). * **X.509 Certificate**: paste the contents of the certificate downloaded in the key pair step. Remove the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` guards if present, and strip any line breaks so the value is a single continuous string. * Click **Register**. The Client Application appears in the overview. * Click **View** on the new Client Application and copy the **API Key**. You will need it in the next step. **4. Configure the SAML Bearer credential in BTP Security Material** * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > Security Material** and click **Create > OAuth 2 SAML Bearer Assertion**. * Set **Name** to a value you will remember when configuring the Worker iFlow's `SF_credential_name` later (e.g. `techwolf_btp_datasource_assertion`). * Set **Audience** to `www.successfactors.com`. * Set **Client Key** to the API Key copied in the previous step. * Set **Token Service URL** to your SuccessFactors **API URL** with `/oauth/token` appended. See [How to find the SAP SuccessFactors Company ID and API URL](/integrations/sap-btp-skill-sync/how-to-find-company-id-and-api-url) to locate both values. * Set **User ID** to **Key pair Common Name (CN)**. * Set **Key Pair Alias** to the alias of the key pair created earlier (see **Create a key pair in the BTP Keystore**). * Click **Deploy**. ## Grant SuccessFactors permissions The SuccessFactors technical user created during authentication setup needs permission to read the OData V2 EntitySets used by this connector. Grant a Permission Role to the technical user through a Permission Group that includes the View permissions below. Every **employee** data type also needs **Manage User > Employee Export**; only enable the data types you plan to use. The **job-architecture** data types (Job Families, Job Roles, Job Profiles) are organization-wide Job Profile Builder objects — they need only the grants shown below, with no **Employee Export** and no **Target Population**. Expand a data type to see the exact permission path to grant in **Manage Permission Roles**. > **Employee Basic Info** > > OData V2 EntitySet: `UserAccount` > > **Manage User** > > **Employee Export** > > **User Account OData entity** > > **Employee Data** > > **Employee Profile** > > **Department: View** > **Employee Certificates** > > OData V2 EntitySet: `Background_Certificates` > > **Manage User** > > **Employee Export** > > **Employee Data** > > **Background** > > **Certifications/Licenses: View** > **Employee Courses** > > OData V2 EntitySet: `Background_Courses` > > **Manage User** > > **Employee Export** > > **Employee Data** > > **Background** > > **Courses/Workshops/Seminars: View** > **Employee Education** > > OData V2 EntitySet: `Background_Education` > > **Manage User** > > **Employee Export** > > **Employee Data** > > **Background** > > **Formal Education: View** > **External Work Experience** > > OData V2 EntitySet: `Background_OutsideWorkExperience` > > **Manage User** > > **Employee Export** > > **Employee Data** > > **Background** > > **Previous Employment: View** > **Internal Work Experience** > > OData V2 EntitySet: `EmpJob` > > **Manage User** > > **Employee Export** > > **Employee Central Effective Dated Entities** > > **Job Information** > > **Job Information Actions: View Current | View History** > > **Job Classification: View Current | View History** > > **Job Title: View Current | View History** > **Job Families** > > OData V2 EntitySet: `FamilyEntity` > > **Manage Job & Skill Profile Visibility** > > **Family: View** > > If `Family` is not visible under **Manage Job & Skill Profile > Visibility**, enable separate security permissions for the `FamilyEntity` > object definition: > > * In the search bar at the top, enter `Configure Object Definitions` and > open it. > * Search for `Object Definition` → `Family`. > * Use `Take Action` → `Make Correction`. > * In the `Security` section, click the `+` button if the fields are > missing, then set: > * `Secured`: `Yes` > * `Permission Category`: `Manage Job & Skill Profile Visibility` > * `RBP Subject User Field`: leave blank > * `CREATE Respects Target Criteria`: `No` > * `Base Date Field For Blocking`: leave blank > * Scroll to the bottom of the page and click `Save`. > * Return to **Manage Permission Roles** and grant `Family: View`. > **Job Roles** > > OData V2 EntitySet: `RoleEntity` > > **Manage Job & Skill Profile Visibility** > > **Role: View** > > This single grant also covers the role's job-code mappings, from which > the canonical `job_code` is resolved. > **Job Profiles** > > OData V2 EntitySet: `JobProfile` > > **Manage Job Profile Builder** > > **Manage Job Profiles** > > This grant covers the profile and its section content (header, footer, > long and short description) reached via the profile's localized data. For employee data types, set the Permission Role's **Target Population** to the population of Employees you want the connector to read. This is typically *All* for a full deployment, or a constrained group during a pilot. > [!NOTE] > > Exact label paths can vary slightly between SuccessFactors releases. If a > permission is not found at the path above, search for the permission name > itself in **Manage Permission Roles**. For SAP's reference on how role-based permissions work and how to set up permission groups and roles, see [SAP - Implementing Role-Based Permissions ](https://help.sap.com/docs/successfactors-platform/implementing-role-based-permissions/introduction-to-implementing-rbp) for an overview. To create Permission Groups, see [SAP - Creating Dynamic Permission Groups ](https://help.sap.com/docs/successfactors-platform/implementing-role-based-permissions/creating-dynamic-permission-groups). To create Permission Roles, see [SAP -Creating a Permission Role ](https://help.sap.com/docs/successfactors-platform/implementing-role-based-permissions/creating-permission-role). To assign Permission Roles to permission groups, see [SAP - Assigning a Permission Role ](https://help.sap.com/docs/successfactors-platform/implementing-role-based-permissions/assigning-permission-role). ## Configure and deploy the iFlows Each iFlow is configured through its own **Configure** dialog. The SuccessFactors connection, the S3 destination, and the inbound settings are set as externalized parameters on the `SF_Worker` and `SF_Frontend` iFlows. **1. Add the S3 access key and secret to Security Material** Both iFlows reach the TechWolf-managed S3 bucket with an access key and secret key **provided by TechWolf**. Store each as a secure parameter first, then reference their names when configuring the iFlows. * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > Security Material**, then click **Create > Secure Parameter**. * Create the **access key** parameter: * **Name**: a value you will remember (e.g. `techwolf_s3_access_key`). This is the `S3_access_key_alias` you enter when configuring the iFlows. * **Secure Parameter**: the S3 **access key** provided by TechWolf. * Click **Deploy**. * Click **Create > Secure Parameter** again for the **secret key**: * **Name**: a value you will remember (e.g. `techwolf_s3_secret_key`). This is the `S3_secret_key_alias` you enter when configuring the iFlows. * **Secure Parameter**: the S3 **secret key** provided by TechWolf. * Click **Deploy**. Both now appear under **Security Material** with type **Secure Parameter**. Use the same two names on both the Worker and Frontend iFlows. **2. Configure and deploy the Worker iFlow** Open the imported package in **Design > Integrations and APIs** and go to **Artifacts**. Locate the **SF\_Worker** iFlow, click the three dots, and select **Configure**. Set the values provided by TechWolf and the SAML Bearer credential name created during the BTP ↔ SuccessFactors authentication setup. On the **`SuccessFactors`** receiver, set: | Field | Value | | - | - | | `Address` | Base URL of your SuccessFactors data center (e.g. `https://api.successfactors.eu`). | | `Credential Name` | The SAML Bearer credential name from the authentication setup (e.g. `techwolf_btp_datasource_assertion`). | The **Receiver** dropdown defaults to `SuccessFactors`; switch it to **`AWS_S3`** to reach the S3 fields, then set: | Field | Value | | - | - | | `Region Name` | AWS region of the TechWolf-managed S3 bucket (provided by TechWolf). Common values: `eu-west-3`, `us-east-1`, `ca-central-1` | | `Bucket Name` | TechWolf-managed S3 bucket name (provided by TechWolf). `data-integrator-production-`, where region code is eu, us, or ca. | | `Access Key Alias` | The name of the S3 access-key secure parameter you created in the first step (e.g. `techwolf_s3_access_key`). | | `Secret Key Alias` | The name of the S3 secret-key secure parameter you created in the first step (e.g. `techwolf_s3_secret_key`). | | `S3_base_path` | Base path inside the bucket. Set to: `/tenants/-/connector_temp/sap_btp`; provided by TechWolf | The TechWolf-managed S3 bucket is provisioned and owned by TechWolf; the access key and secret key are provided by TechWolf and stored in your BTP Security Material as secure parameters under the aliases above. Click **Save**, then **Deploy**. **3. Configure and deploy the Frontend iFlow** In the package's **Artifacts** tab, locate the **SF\_Frontend** iFlow. Click the three dots and select **Configure**. On the S3 receiver, set the **same** S3 variable values you used on the Worker (they must be identical to the Worker's), then set: | Field | Value | | - | - | | `User Role` | The User Role created during the BTP package install (e.g. `TechWolfBTPIntegration.send`). | Leave `Address` and `Body Size (in MB)` at their defaults (`/techwolf/v3/sf/*` and `40`). Click **Save**, then **Deploy**. ## Share with TechWolf Once the configuration is complete, share the following with your TechWolf representative through a secure channel agreed with them: | Value | Source | | - | - | | Service key file | The service key downloaded during the BTP package install. | | SuccessFactors base URL | The `Address` value used when configuring the Worker iFlow. | | Enabled data types | The list of data types you granted permissions for. | TechWolf will validate the end-to-end connection and configure the ingestion side. No further action is required from your side unless permission or connectivity issues are reported. # SAP BTP Connector Source: https://developers.techwolf.ai/integrations/datasource-integrations/connectors/sap-btp/overview The SAP SuccessFactors via BTP Data Source Connector is an API-based integration that extracts HR data from SAP SuccessFactors through the SAP Integration Suite. TechWolf calls the iFlow over HTTPS; the iFlow calls SuccessFactors on the customer's behalf and stages the results in TechWolf-managed storage for ingestion into the SkillEngine API. ## Prerequisites * An active TechWolf contract. * A working **SAP SuccessFactors** tenant. * A working **SAP BTP** tenant with **SAP Integration Suite** provisioned, including the *Build Integration Scenarios* capability. The full prerequisites and the BTP-side roles required are listed on the [Installation](/integrations/datasource-integrations/connectors/sap-btp/installation) page. ## Key benefits * **Customer-owned infrastructure**: every call to SuccessFactors is performed in the customer's BTP tenant, giving the customer full visibility via BTP's Monitor Message Processing view and keeping SuccessFactors credentials inside the customer's BTP Keystore. * **Single package, multiple data types**: one BTP package serves all enabled data types. Enabling or disabling a data type does not require a new install. * **No file infrastructure**: no SFTP, no report schedules, no export files (integration center definitions). Data flows from SuccessFactors through the iFlow to TechWolf storage. Note that this is a valid but equivalent alternative to the Integration Center definition-based method of extracting data. The most notable difference is that data moves through the BTP platform. ## How it works 1. TechWolf calls the integration over HTTPS to request a run for a given data type. 2. The integration acknowledges the request and processes the work asynchronously. 3. The process calls SuccessFactors with the entity set and query for the requested data type, paginates through the results, and writes them to TechWolf-managed storage. 4. TechWolf ingests the staged data into the SkillEngine API using connectors. See the [How It Works](/integrations/datasource-integrations/connectors/sap-btp/how-it-works) page for the full flow. ## Available data types The connector supports the following data types. Each data type corresponds to a SuccessFactors OData V2 EntitySet and requires the corresponding SuccessFactors permissions to be granted to the technical user used by the iFlow. These permissions are detailed on the [Installation](/integrations/datasource-integrations/connectors/sap-btp/installation) page. > **Employee Basic Info** > > Basic Employee identity and account status, sourced from the `UserAccount` > EntitySet. > > | Output field | Description | > | - | - | > | `accountId` | The SuccessFactors account ID | > | `accountUuid` | The SuccessFactors account UUID | > | `accountStatus` | Whether the account is active | > | `userType` | The user type | > | `perPersonUuid` | The Per Person UUID linking the account to the underlying person | > | `personIdExternal` | The external Person ID | > | `userId` | The User ID | > | `department` | The user's department | > | `managerUserId` | The User ID of the user's manager | > | `lastModifiedDateTime` | Timestamp of the last modification | > **Employee Certificates** > > Employee certifications, sourced from the `Background_Certificates` > EntitySet. > > | Output field | Description | > | - | - | > | `backgroundElementId` | Background element ID for the certificate row | > | `userId` | The Employee's User ID | > | `perPersonUuid` | The Per Person UUID linking the certificate to the Employee | > | `name` | Name of the certification | > | `description` | Description of the certification | > | `startDate` | Date the certification was issued | > | `endDate` | Date the certification expires | > | `lastModifiedDate` | Timestamp of the last modification | > **Employee Courses** > > Employee course history, sourced from the `Background_Courses` EntitySet. > > | Output field | Description | > | - | - | > | `backgroundElementId` | Background element ID for the course row | > | `userId` | The Employee's User ID | > | `perPersonUuid` | The Per Person UUID linking the course to the Employee | > | `course` | Name of the course | > | `endDate` | End date of the course | > | `instructionType` | Localised label for the type of instruction | > | `length` | Localised label for the course length | > | `lastModifiedDate` | Timestamp of the last modification | > **Employee Education** > > Employee education history, sourced from the `Background_Education` > EntitySet. > > | Output field | Description | > | - | - | > | `backgroundElementId` | Background element ID for the education row | > | `userId` | The Employee's User ID | > | `perPersonUuid` | The Per Person UUID linking the education to the Employee | > | `school` | Name of the educational institution | > | `degree` | Localised label for the degree obtained | > | `major` | Localised label for the field of study | > | `startDate` | Start date of the education | > | `endDate` | End date of the education | > | `lastModifiedDate` | Timestamp of the last modification | > **External Work Experience** > > Employee external work history, sourced from the > `Background_OutsideWorkExperience` EntitySet. > > | Output field | Description | > | - | - | > | `backgroundElementId` | Background element ID for the work-experience row | > | `userId` | The Employee's User ID | > | `perPersonUuid` | The Per Person UUID linking the work experience to the Employee | > | `employer` | Name of the previous employer | > | `startTitle` | Job title at the previous employer | > | `startDate` | Start date of the position | > | `endDate` | End date of the position | > | `lastModifiedDate` | Timestamp of the last modification | > **Internal Work Experience** > > Employee internal staffing history, sourced from the `EmpJob` EntitySet. > The connector requests the full effective-dated history per Employee > (not only the current job). > > | Output field | Description | > | - | - | > | `userId` | The Employee's User ID | > | `perPersonUuid` | The Per Person UUID linking the job period to the Employee | > | `jobCode` | Job code of the position | > | `jobTitle` | Job title of the position | > | `startDate` | Start date of the job period | > | `endDate` | End date of the job period | > | `seqNumber` | Sequence number of the effective-dated row | > | `employmentStatus` | Employment status for this period | > | `lastModifiedDateTime` | Timestamp of the last modification | > **Job Families** > > Job Profile Builder families (job architecture, not per-Employee), sourced from > the `FamilyEntity` MDF object. `parentFamily` carries the family hierarchy. > > | Output field | Description | > | - | - | > | `externalCode` | External code of the family | > | `name_en_US` | Family name (en\_US locale) | > | `name_defaultValue` | Family name (creator-locale default) | > | `parentFamily` | External code of the immediate parent family (hierarchy) | > | `status` | Whether the family is active | > **Job Roles** > > Job Profile Builder roles (job architecture), sourced from the `RoleEntity` MDF > object. A single canonical job code is resolved from the role's job-code > mappings. > > | Output field | Description | > | - | - | > | `externalCode` | External code of the role | > | `name_en_US` | Role name (en\_US locale) | > | `name_defaultValue` | Role name (creator-locale default) | > | `family` | External code of the family this role belongs to | > | `job_code` | Canonical job code for the role (lowest job classification mapping) | > | `status` | Whether the role is active | > **Job Profiles** > > Job Profile Builder profiles — the readable description attached to a role — > sourced from the `JobProfile` MDF object. Section bodies are returned inline per > locale; only published profiles are included (drafts are excluded). > > | Output field | Description | > | - | - | > | `externalCode` | External code of the profile | > | `name_en_US` | Profile name (en\_US locale) | > | `name_defaultValue` | Profile name (creator-locale default) | > | `role` | External code of the role this profile describes | > | `headerEnUs` | Header section text (en\_US) | > | `headerDefault` | Header section text (creator-locale default) | > | `footerEnUs` | Footer section text (en\_US) | > | `footerDefault` | Footer section text (creator-locale default) | > | `longDescriptionEnUs` | Long description text (en\_US) | > | `longDescriptionDefault` | Long description text (creator-locale default) | > | `shortDescriptionEnUs` | Short description text (en\_US) | > | `shortDescriptionDefault` | Short description text (creator-locale default) | > | `status` | Whether the profile is active | > [!NOTE] > > Not all data types need to be enabled. Work with TechWolf to select the data > types that are relevant for your use case. SuccessFactors permissions only > need to be granted for the data types you choose to enable. ## Next steps > **[How It Works](/integrations/datasource-integrations/connectors/sap-btp/how-it-works)** > > Detailed walkthrough of the connector's flow, configuration, and > authentication model. > **[Installation](/integrations/datasource-integrations/connectors/sap-btp/installation)** > > Step-by-step guide to install the connector in your SAP BTP tenant and > grant the required SuccessFactors permissions. # Installation Source: https://developers.techwolf.ai/integrations/datasource-integrations/connectors/workday/installation Step-by-step guide to configure your Workday tenant for the Workday Data Source Connector. ## Prerequisites * A Workday tenant with the Workday Query Language (WQL) feature enabled. * Security administrator access in Workday. * An active TechWolf contract with SkillEngine API credentials. ## Workday configuration The setup consists of creating an Integration System User, granting the appropriate security permissions, and registering an API client. Follow each step in order. **1. Create an Integration System User (ISU)** 1. Search for **Create Integration System User** in the Workday search bar. 2. Create a new user (e.g. `TechWolf_Source_ISU`). 3. Set a password — it will not be used directly but is required by Workday. 4. Check **Do Not Allow UI Sessions** to restrict this user to API-only access. > [!WARNING] > > Store the ISU credentials securely. You will need the username when generating a refresh token. **2. Create an Integration Security Group** 1. Search for **Create Security Group**. 2. Choose **Integration System Security Group (Unconstrained)**. 3. Name it (e.g. `ISSG_TechWolf_Source`). 4. Add the ISU created in the previous step. > [!NOTE] > > If you want to limit the connector to a specific subset of workers (e.g. a particular country or business unit), create two security groups for the same ISU: > > * an **Integration System Security Group (Unconstrained)** for the **Workday Query Language** permission > * an **Integration System Security Group (Constrained)** for the worker data permissions > > On the constrained group, add the ISU, add the relevant organisation, and choose whether access applies only to that organisation or also to subordinate organisations. **3. Grant domain security permissions** 1. Search for **Maintain Permissions for Security Group** and select the security group created in the previous step. 2. Under **Integration Permissions**, add **View** access for the **Workday Query Language** domain. This is required for all data types. 3. Add the required permissions listed in the [permissions table](#permissions-per-data-type) below. The table separates **Get** and **View** domain access. 4. If the [permissions table](#permissions-per-data-type) lists Business Process Security Policies for your selected data types, give **View All** access on those Business Processes. 5. Search for **Activate Pending Security Policy Changes** and activate the changes. > [!NOTE] > > For a constrained setup, grant **Workday Query Language** on the unconstrained security group and grant the worker data domains on the constrained security group. Workday may not allow the **Workday Query Language** domain to be added directly to an Integration System Security Group (Constrained). > [!NOTE] > > You only need to grant permissions and API client scopes for the data types you plan to use. For example, if you only need Workers and Jobs, you do not need to grant access to Learning or Person Data domains. **4. Register an API Client for Integrations** 1. Search for **Register API Client for Integrations**. 2. Set a client name (e.g. `TechWolf Datasource Integration`). 3. Under **Scope (Functional Areas)**, add **System** and **Tenant Non-Configurable**. If you plan to use Feedback, also add **Performance Enablement**. 4. Check the following boxes: * **Non-Expiring Refresh Tokens** * **Include Workday Owned Scope** 5. After creation, securely store the **Client ID** and **Client Secret**. **5. Generate a refresh token** 1. Search for **View API Clients**. 2. Click the **API Clients for Integrations** tab. 3. Find the API client created in the previous step. 4. Select **API Client** > **Manage Refresh Tokens for Integrations**. 5. Under **Workday Account**, enter the ISU created in Step 1. 6. Check **Generate New Refresh Token** and confirm. 7. Securely store the refresh token. > [!WARNING] > > The refresh token is displayed only once. If you lose it, you must generate a new one. **6. Find base URL and tenant name** 1. Search for **View API Clients** in the Workday search bar. 2. Locate the **Workday REST API Endpoint** field. It will look like: ``` https://wd2-impl-services1.workday.com/ccx/api/v1/mycompany ``` 3. The **base URL** is the host portion: `https://wd2-impl-services1.workday.com` 4. The **tenant** is the last path segment after `/v1/`: `mycompany` > [!NOTE] > > The API URL can differ between implementation tenants and production tenants. Repeat this step for each tenant you want to connect. ## Share credentials with TechWolf Once the Workday configuration is complete, securely share the following credentials with TechWolf: | Credential | Description | | - | - | | Client ID | The API client ID from Step 4 | | Client secret | The API client secret from Step 4 | | Refresh token | The non-expiring refresh token from Step 5 | | Base URL | The Workday REST API host (e.g. `https://wd2-impl-services1.workday.com`) | | Tenant | The tenant name (e.g. `mycompany`) | TechWolf will validate that the ISU has the required permissions and that the credentials are correct. If any permissions are missing, the connector will report exactly which security domains need to be added. ## Permissions per data type Grant the domains below for every data type you plan to use. Entries marked "incremental only" are only needed when TechWolf configures incremental change detection for that data type. | Data type | Get | View | Business Process Security Policies | | - | - | - | - | | Workers | Worker Data: Current Staffing Information Worker Data: Current Job Profile Information Worker Data: Public Worker Reports | Workday Query Language | - | | Organisational Units | Manage: Supervisory Organization | Workday Query Language | - | | Jobs | Job Information | Workday Query Language | - | | Vacancies | Job Requisition Data | Workday Query Language | - | | External History | Worker Data: Current Staffing Information Person Data: Job History Worker Data: Public Worker Reports (incremental only) Business Process Administration (incremental only) | Workday Query Language | - | | Certificates | Worker Data: Current Staffing Information Person Data: Certifications Worker Data: Public Worker Reports (incremental only) Business Process Administration (incremental only) | Workday Query Language | - | | Education | Worker Data: Current Staffing Information Person Data: Education Worker Data: Public Worker Reports (incremental only) Business Process Administration (incremental only) | Workday Query Language | - | | Learning | Worker Data: Current Staffing Information Person Data: Learning | Workday Query Language | - | | Goals | Worker Data: Current Staffing Information Worker Data: Employee Goals Worker Data: Public Worker Reports (incremental only) | Workday Query Language | - | | Internal History | Worker Data: Current Staffing Information Worker Data: Historical Staffing Information Worker Data: Public Worker Reports (incremental only) | Workday Query Language | View All: Hire Change Job Termination Contract Contingent Worker Transfer Contingent Worker Inbound End Contingent Worker Contract | | Courses | Set Up: Learning Catalog Manage: Learning Content | Workday Query Language | - | | Performance Reviews | Worker Data: Current Staffing Information Worker Data: Employee Reviews Worker Data: Public Worker Reports (incremental only) Business Process Administration (incremental only) | Workday Query Language | - | | Feedback | Worker Data: Public Worker Reports Worker Data: Confidential Feedback (incremental only) Business Process Administration (incremental only) | Workday Query Language Worker Data: Anytime Feedback Worker Data: Role Requested Feedback Worker Data: Self Requested Feedback Worker Data: Confidential Feedback Worker Data: Private Feedback | - | | Job Families | Job Information | Workday Query Language | - | ## API client scopes Every API client must include **System** and **Tenant Non-Configurable**. Keep **Include Workday Owned Scope** selected. Add these additional scopes based on the data types enabled for the connector: | Enabled data types | Additional API client scopes | | - | - | | Feedback | Performance Enablement | > [!NOTE] > > Workday tenant configuration can hide scopes for products that are not enabled. If Performance Enablement is unavailable in your tenant but you want to use Feedback, share that during setup so TechWolf can validate the exact access against your Workday environment. > [!NOTE] > > **Business Process Administration** is a domain permission, not a Business > Process Security Policy. It is only needed for incremental change detection on > data types that resolve named Business Process identifiers. > [!WARNING] > > **Feedback** requires **View** permissions on the Feedback domains. Granting > only Get on those domains will result in empty data with no error message. ## TechWolf configuration After receiving the credentials, TechWolf will: 1. Validate the credentials and security permissions. 2. Configure the connector for the agreed-upon data types. 3. Set up the connector on a daily schedule. 4. Run an initial data extraction. 5. Confirm the integration is operational. No further action is required from your side unless permission issues are reported. # Overview Source: https://developers.techwolf.ai/integrations/datasource-integrations/connectors/workday/overview API-based connector that extracts HR data directly from Workday using the Workday Query Language (WQL). # Workday Data Source Connector The Workday Data Source Connector is an API-based integration that extracts HR data directly from your Workday tenant using the [Workday Query Language (WQL)](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/wql-reference/trh1644452418127.html) REST API. Unlike the [file-based Workday integration](/integrations/datasource-integrations/workday-datasource/overview), which relies on Enterprise Interface Builder (EIB) exports, the connector pulls data from Workday automatically on a scheduled basis — no file exports or transfer infrastructure required. ## Key benefits * **Fully automated** — TechWolf manages the connector end-to-end. No need to build, schedule, or monitor EIB exports. * **Broad data coverage** — Extracts up to 14 distinct data types from Workday, from basic worker information to learning enrollments, performance reviews, and goals. * **Permission validation** — The connector validates your Workday security configuration at setup time and reports exactly which permissions are missing, if any. ## How it works 1. You configure an Integration System User (ISU) in Workday with the necessary security permissions and register an API client. 2. You share the OAuth credentials with TechWolf. 3. TechWolf configures and operates the connector. 4. The connector authenticates with Workday, executes WQL queries against the configured data types, and loads the results into the SkillEngine API. > [!NOTE] > > The connector connects directly to the Workday REST API. No data passes through intermediate files or storage — it flows from Workday to the SkillEngine API. ## Available data types The connector supports up to 14 data types. Each accordion below shows the field mapping from Workday to TechWolf, the exact WQL query (or SOAP operation, for Feedback) issued by the connector, and any filter logic applied. Each data type requires specific Workday security domain permissions, detailed on the [Installation](/integrations/datasource-integrations/connectors/workday/installation) page. > [!NOTE] > > **Filtering:** Any optional `where` filter is applied to that data type's own WQL data source — not globally to workers. The `activeStatus` field exists only on `allWorkers`, so it can filter the **Workers** data type but not `learningEnrollments` (Learning), `learningContent` (Courses), or the job/requisition sources. Reference sub-fields (e.g. a learner's `activeStatus`) can be *selected* but not *filtered* on. To scope other data types to active workers, rely on the Workers feed rather than a per-connector filter. > **Workers** > > Basic Employee information: Employee ID, current Job Profile, Supervisory Organisation, and active status. > > **Source:** Workday WQL — `allWorkers`. **Permission domains:** Worker Data: Current Staffing Information; Worker Data: Current Job Profile Information; Worker Data: Public Reporting Items. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `employee_external_id` (external\_id) | Worker | Worker | `employeeID` | Required | Employee's Workday ID. External ID of the entity. | > | `assigned_position` | Worker | Job Profile | `ID` | Required | Job Profile ID of the Employee's current position. Called `assigned_position_id` in TechWolf; relates to Job Profiles in Workday, not Positions. | > | `organisational_unit_id` | Worker | Supervisory Organization | `orgUnitId` | Required | Supervisory Organisation reference ID. | > | `active` | Worker | Worker | `activeStatus` | | Whether the Employee is currently active. | > > WQL query: > > ```sql theme={null} > SELECT employeeID, jobProfile{ID, workdayID}, supervisoryOrganization{referenceID1}, > activeStatus, workdayID > FROM allWorkers > ``` > **Organisational Units** > > Supervisory Organisation hierarchy: name, reference ID, parent Organisation, and active status. > > **Source:** Workday WQL — `supervisoryOrganizations`. **Permission domain:** Manage: Supervisory Organization. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `organisational_unit_name` | Supervisory Organization | Supervisory Organization | `name` | Required | | > | `organisational_unit_id` (external\_id) | Supervisory Organization | Supervisory Organization | `referenceID1` | Required | External ID of the organisational unit. | > | `organisational_unit_active` | Supervisory Organization | Supervisory Organization | `inactive` | Required | Whether the Organisation is inactive. | > | `parent_organisational_unit_name` | Supervisory Organization | Superior Organization | `superiorOrganizationName` | | | > | `parent_organisational_unit_id` | Supervisory Organization | Superior Organization | `superiorOrganizationCode` | Required | | > > WQL query: > > ```sql theme={null} > SELECT name, referenceID1, superiorOrganizationName, superiorOrganizationCode, > inactive, workdayID > FROM supervisoryOrganizations > ``` > **Learning** > > Employee learning enrolments. Only completed enrolments of type Blended Course, Digital Course, or Lesson are emitted to TechWolf. > > **Source:** Workday WQL — `learningEnrollments`. **Permission domains:** Worker Data: Current Staffing Information; Person Data: Learning. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `learning_enrollment_id` | Learning Enrollment | Learning Enrollment | `workdayID` | Required | Workday ID of the learning enrolment. | > | `employee_id` | Learning Enrollment | Worker | `learner{employeeID}` | Required | The learner is a Worker reference on the enrolment. | > | `course_id` | Learning Enrollment | Enrolled Content | `enrolledContent{workdayID}` | Required | Workday ID extracted from the enrolled content reference. | > | `timestamp` | Learning Enrollment | Learning Enrollment | `completionDate` | Required | If empty, defaults to current date. | > | `completion_status` | Learning Enrollment | Learning Enrollment | `completionStatus` | | Used by the connector filter (see below). | > | `learning_content_type` | Learning Enrollment | Learning Enrollment | `learningContentType` | | e.g. Blended Course, Digital Course, Lesson. | > > WQL query: > > ```sql theme={null} > SELECT learner{employeeID}, enrolledContent{workdayID}, learningContentTitle, > completionDate, completionStatus, learningContentType, workdayID > FROM learningEnrollments > ``` > > Filter logic (applied by the connector after the WQL response): > > * `completionStatus` equals `Completed` > * `learningContentType` is one of `Blended Course`, `Digital Course`, or `Lesson` > **Internal History** > > Employee internal staffing history. Hire, position-change, and termination events are pulled and consolidated by the connector into job periods with a start and end date per role. Consecutive events with the same Job Code and Position are merged; `endDate` is empty when the Employee is still in the role. > > **Source:** Workday WQL — `allWorkers` (with `staffingHistory_All` subselection). **Permission domains:** Worker Data: Current Staffing Information; Worker Data: Historical Staffing Information. **BP Security Policies (View All):** Hire, Change Job, Termination, Contract Contingent Worker, Transfer Contingent Worker Inbound, End Contingent Worker Contract. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `employee_id` (employee.external\_id) | Worker | Worker | `employeeID` | Required | | > | `job_id` | Worker | Job Profile History | `jobCode` | Required | Job code of the position during this period. | > | `start_date` (& timestamp) | Worker | Job Profile History | `startDate` | Required | Start of the job period. | > | `end_date` | Worker | Job Profile History | `endDate` | Required | End of the job period. Empty if the Employee is still in this role. | > | `position` | Worker | Job Profile History | `position` | | Position identifier. | > > WQL query: > > ```sql theme={null} > SELECT employeeID, > staffingHistory_All{jobCode, effectiveDate, position, > isHireTransaction, > isPositionChangeTransaction, > isTerminationTransaction}, > workdayID > FROM allWorkers > WHERE ON staffingHistory_All > isHireTransaction = true > OR isPositionChangeTransaction = true > OR isTerminationTransaction = true > ``` > **External History** > > Previous (pre-current-employer) work history captured in the Worker profile. > > **Source:** Workday WQL — `allWorkers` (with `jobHistory_SkillsAndExperience` subselection). **Permission domains:** Worker Data: Current Staffing Information; Person Data: Job History. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `employee_id` | Worker | Worker | `employeeID` | Required | | > | `job_title` | Worker | Job History - Skills and Experience | `jobTitle` | Required | | > | `job_description` | Worker | Job History - Skills and Experience | `responsibilitiesAndAchievements` | Required | | > | `company` | Worker | Job History - Skills and Experience | `company` | | | > | `start_date` | Worker | Job History - Skills and Experience | `startDate` | Required | | > | `end_date` | Worker | Job History - Skills and Experience | `endDate` | Required | | > > WQL query: > > ```sql theme={null} > SELECT employeeID, > jobHistory_SkillsAndExperience{jobTitle, company, startDate, endDate, > responsibilitiesAndAchievements}, > workdayID > FROM allWorkers > ``` > **Certificates** > > Employee certifications with issue and expiration dates. > > **Source:** Workday WQL — `allWorkers` (with `certifications` subselection). **Permission domains:** Worker Data: Current Staffing Information; Person Data: Certifications. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `employee_id` (employee.external\_id) | Worker | Worker | `employeeID` | Required | | > | `certification_name` | Worker | Certifications | `certificationName` | Required | Certifications in Workday have no description. | > | `timestamp` | Worker | Certifications | `issuedDate` | Required | | > | `expiration_date` | Worker | Certifications | `expirationDate` | | | > > WQL query: > > ```sql theme={null} > SELECT employeeID, > certifications{certificationName, issuedDate, expirationDate}, > workdayID > FROM allWorkers > ``` > **Education** > > Employee education history. > > **Source:** Workday WQL — `allWorkers` (with `education` subselection). **Permission domains:** Worker Data: Current Staffing Information; Person Data: Education. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `employee_id` (employee.external\_id) | Worker | Worker | `employeeID` | Required | | > | `degree_name` | Worker | Education | `degree` | Required | | > | `field_of_study` | Worker | Education | `fieldOfStudy` | Required | | > | `start_date` | Worker | Education | `firstYearAttended` | Required | | > | `end_date` (& timestamp) | Worker | Education | `lastYearAttended` | Required | | > | `school` | Worker | Education | `schoolName` | | | > > WQL query: > > ```sql theme={null} > SELECT employeeID, > education{degree, schoolName, fieldOfStudy, > firstYearAttended, lastYearAttended}, > workdayID > FROM allWorkers > ``` > **Goals** > > Employee goals with name, description, completion date, and status. > > **Source:** Workday WQL — `allWorkers` (with `goals` subselection). **Permission domains:** Worker Data: Current Staffing Information; Worker Data: Employee Goals. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `employee_id` (employee.external\_id) | Worker | Worker | `employeeID` | Required | | > | `name` | Worker | Goals | `goalName` | Required | | > | `description` | Worker | Goals | `goalDescription` | Required | | > | `status` | Worker | Goals | `status` | Required | Only send relevant entries (e.g. `Completed`, `On Track`) — agree with TechWolf during onboarding so the appropriate filter is configured. | > | `timestamp` | Worker | Goals | `completedOn` | Required | | > > WQL query: > > ```sql theme={null} > SELECT employeeID, > goals{goalName, goalDescription, completedOn, status}, > workdayID > FROM allWorkers > ``` > **Performance Reviews** > > Performance review data: review name, manager and employee comments, type, and review period end date. > > **Source:** Workday WQL — `allWorkers` (with `reviews_AllStatuses` subselection). Requires the `Performance Enablement` API client scope. **Permission domains:** Worker Data: Current Staffing Information; Worker Data: Employee Reviews. **BP Security Policies (View All):** Complete Manager Evaluation for Performance Review, Complete Self Evaluation for Performance Review. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `employee_id` | Worker | Worker | `employeeID` | Required | | > | `title` | Worker | Performance Review | `title` | Required | Performance Review name. | > | `description` | Worker | Performance Review | `description` | Required | Manager overall comment, or feedback responses (depending on template). | > | `status` | Worker | Performance Review | `status` | | Only send relevant entries (e.g. `Completed`, `On Track`). | > | `type` | Worker | Performance Review | `type` | | | > | `timestamp` | Worker | Performance Review | `timestamp` | | Review period end date. | > > WQL query: > > ```sql theme={null} > SELECT employeeID, > reviews_AllStatuses{templateName, content_FeedbackResponses, > overallComment_Manager, overallComment_Employee, > evaluations_AllStatuses, reviewType, > eventCompleted, reviewPeriod_EndDate}, > workdayID > FROM allWorkers > ``` > **Feedback** > > Employee feedback: anytime feedback, self-requested feedback, and feedback requested by others. > > **Source:** Workday SOAP — `Get_Workers` (Human Resources service) with `Include_Feedback_Received` response group. Requires the `Performance Enablement` API client scope. **Permission domains (must be `View`, not `Get`):** Worker Data: Anytime Feedback; Worker Data: Role Requested Feedback; Worker Data: Self Requested Feedback; Worker Data: Confidential Feedback; Worker Data: Private Feedback. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `employee_id` (employee.external\_id) | Worker | Worker | `employeeID` | Required | | > | `timestamp` | Worker | Feedback | `timestamp` | Required | Date the feedback was given. | > | `source` | Worker | Feedback | `source` | Required | Feedback type — e.g. Anytime Feedback, Requested by Self, Requested by Others. | > | `description` | Worker | Feedback | `description` | Required | Combined feedback question + comment (HTML stripped). | > > > [!NOTE] > > > > Feedback is the only data type that uses SOAP rather than WQL. This is why Feedback requires `View` permissions (not `Get`) on the relevant Feedback domains, and why it is not visible via WQL even when WQL permission is granted. See the [Installation](/integrations/datasource-integrations/connectors/workday/installation) page for the full permission set. > **Jobs** > > Job Profile catalog: descriptions, Job Family information, and active status. > > **Source:** Workday WQL — `allJobProfiles`. **Permission domain:** Job Information. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `job_id` (external\_id) | Job Profile | Job Profile | `ID` | Required | External ID of the entity. Workday ID of the Job Profile. | > | `job_name` | Job Profile | Job Profile | `jobProfileName` | Required | | > | `job_description` | Job Profile | Job Profile | `jobProfileSummary` | Required | | > | `job_description` | Job Profile | Job Profile | `jobDescription` | Required | | > | `job_description` | Job Profile | Job Profile | `additionalJobDescription` | | Optional additional Job description text. | > | `active` | Job Profile | Job Profile | `inactive` | Required | Job assumed active if no value given. | > | `job_family_id` | Job Profile | Job Family | `jobFamilyID` | Required | Reference ID of the Job Family. A Job can be part of multiple families in Workday, but not in TechWolf. | > | `job_family_name` | Job Profile | Job Family | `jobFamilyName` | | Name of the linked Job Family. | > | `job_family_group_name` | Job Profile | Job Family Group | `jobFamilyGroupName` | | | > > WQL query: > > ```sql theme={null} > SELECT ID, jobProfileName, jobDescription, jobProfileSummary, > additionalJobDescription, > jobFamily{referenceID1, jobFamilyName}, > jobFamilyGroup{jobFamilyName}, > inactive, workdayID > FROM allJobProfiles > ``` > **Job Families** > > Job Family catalog, used when the Job Architecture is in scope. > > **Source:** Workday WQL — `allJobFamilies`. **Permission domain:** Job Information. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `job_family_id` (external\_id) | Job Family | Job Family | `referenceID1` | Required | External ID of the entity. | > | `job_family_name` | Job Family | Job Family | `jobFamilyName` | Required | | > | `job_family_summary` | Job Family | Job Family | `jobFamilySummary` | Required | | > | `active` | Job Family | Job Family | `inactive` | Required | Job Family assumed active if no value given. | > | `job_family_group_name` | Job Family | Job Family Group | `jobFamilyGroupName` | Required | A Job Family can be part of multiple groups in Workday, but not in TechWolf. | > | `job_family_group_summary` | Job Family | Job Family Group | `jobFamilyGroupSummary` | Required | | > > WQL query: > > ```sql theme={null} > SELECT referenceID1, jobFamilyName, jobFamilySummary, inactive, > jobFamilyGroup{jobFamilyName, jobFamilySummary}, > workdayID > FROM allJobFamilies > ``` > **Vacancies** > > Job Requisition data: posting title, descriptions, status, and linked Job Profiles. One output record is emitted per (Job Requisition, Job Profile) pair when multiple Job Profiles are linked to a Requisition. > > **Source:** Workday WQL — `allJobRequisitions`. **Permission domain:** Job Requisition Data. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `requisition_id` (external\_id) | Job Requisition | Job Requisition | `referenceID1` | Required | External ID of the vacancy. | > | `job_id` | Job Requisition | Job Profile | `jobProfileID` | Required | Job linked to the vacancy; used for skill inference. | > | `job_title` | Job Requisition | Job Requisition | `jobPostingTitle` | Required | | > | `job_description` | Job Requisition | Job Requisition | `jobDescription` | Required | | > | `job_description` | Job Requisition | Job Requisition | `jobDescriptionSummary` | Required | | > | `job_description` | Job Requisition | Job Requisition | `additionalJobDescription` | Required | | > | `active` | Job Requisition | Job Requisition | `jobRequisitionStatus` | Required | Vacancy assumed active if no value given. | > > WQL query: > > ```sql theme={null} > SELECT referenceID1, jobPostingTitle, jobDescriptionSummary, jobDescription, > additionalJobDescription, > jobRequisitionStatus{referenceID1}, > allJobProfiles{ID, workdayID}, > workdayID > FROM allJobRequisitions > ``` > **Courses** > > Learning content catalog: course titles, types, descriptions, and durations. > > **Source:** Workday WQL — `learningContent`. **Permission domains:** Set Up: Learning Catalog; Manage: Learning Content. > > | TechWolf Field | Primary Business Object | Business Object | WQL Output Field | Required | Notes | > | - | - | - | - | - | - | > | `course_id` (external\_id) | Learning Content | Learning Content | `courseID` | Required | Workday ID of the course. | > | `title` | Learning Content | Learning Content | `title` | Required | | > | `description` | Learning Content | Learning Content | `description` | Required | | > | `learning_content_type` | Learning Content | Learning Content | `learningContentType` | | | > | `active` | Learning Content | Learning Content | `activeStatus` | | | > | `duration_in_minutes` | Learning Content | Learning Content | `durationInMinutes` | | | > > WQL query: > > ```sql theme={null} > SELECT title, learningContentType, description, activeStatus, > durationInMinutes, workdayID > FROM learningContent > ``` > [!NOTE] > > Not all data types need to be enabled. Work with TechWolf to select the data types that are relevant for your use case. Security permissions only need to be granted for the data types you choose to enable. ## Next steps > **[Installation](/integrations/datasource-integrations/connectors/workday/installation)** > > Step-by-step guide to configure your Workday tenant and share credentials with TechWolf. # How To: build custom datasource integrations Source: https://developers.techwolf.ai/integrations/datasource-integrations/how-to-datasource-integration This document outlines how to build a custom datasource integration. Custom datasource integrations run outside TechWolf's infrastructure and are functionally unrelated to TechWolf's own products. Information enters TechWolf through the API. Custom datasource integrations are owned by the customer. You are responsible for building and maintaining the integration, using the TechWolf SkillEngine API. This page explains how to build datasource integrations by sharing how we approached this ourselves, the main tasks, and the challenges involved. This is guidance, not a strict prescription. If you have questions or feedback on this guide, please reach out to us at [support@techwolf.com](mailto:support@techwolf.com). ## Why File-based? In [Key concepts](/integrations/datasource-integrations/datasources-key-concepts), we explain the differences between file-based and API-based integrations, and provide a comparison of the two approaches. For TechWolf, we prefer to build file-based integrations for large data ingestions to optimize for coverage. API-based integrations require `O(n)` work where `n` is the number of APIs, plus ongoing maintenance for each integration. Additionally, working with files offers (1) built-in observability when things go wrong, (2) broad support in source systems for exporting data as files, and (3) the ability to trade immediacy for consistency, resilience, and completeness since most input data is not time-critical. This guide primarily focuses on file-based integrations, with notes applicable to API-based integrations. For API-based guidance, see the addendum: [Addendum: API-based datasource integrations](/integrations/datasource-integrations/how-to-datasource-integration#addendum-api-based-datasource-integrations). ## TL;DR - file-based datasource integration > **[Incremental file ingestion](#incremental-files)** > > Depending on data size, opt for incremental file ingestion (files > containing incremental updates). > **[Minimal updates](#minimal-updates)** > > Regardless of ingestion strategy, datasources can cause request storms > by requesting and updating all data. Implement a proper minimal-update > strategy to avoid running into global rate limits for your other > applications. > **[Sync consistently](#1-volume-of-data-and-considerations)** > > Datasources are not time-critical. A daily sync with 1–2 concurrent > requests should be fine, depending on the size of the dataset. > **[Eventual consistency](#1-volume-of-data-and-considerations)** > > Keep track of failed records, and retry them *slowly* (daily or slower) > until successful. Eventual consistency is your friend. > **[Strict format](#validation)** > > Use CSV files and validate for RFC 4180 (CSV RFC), or use Parquet or > other strict structured formats. > **[Entity dependencies](#3-entity-dependencies)** > > Entities that have dependencies can make you reach to custom > implementations per entity type. Do not fall for long-term ongoing > maintenance of keeping up with our API's entity dependencies, and > instead count on eventual consistency. An entity that could not load > today due to a dependency, might load tomorrow. > **[Prevent large deletes](#4-security-considerations)** > > Protect your integration against large deletes; let a human verify if > more than X% of a dataset is deleted. > **[Install alerting](#4-security-considerations)** > > Install alerting for non-running integrations. If not, something might > break, not run, and nobody will notice. ## 1. Volume of data and considerations Depending on the source, files can become very large. Think about files containing millions of records, each of which containing detailed Course descriptions or Employee feedback. Handling large files is challenging when processing rows individually or when performing complex transformations. To scale effectively, use **incremental files** and perform **minimal updates** to the destination API. ### Incremental files We distinguish between **incremental files** (we call them **diffs** or **deltas**) and **full dumps**. An incremental file contains only the changes since the last diff, while a full dump contains the entire dataset. Incremental files are typically generated by the source system and can contain a flag on each record indicating upsert or delete. Some systems output a register of timestamped updates. Such **transactional** files can be reduced to **incremental** files by applying updates in chronological order. Ingesting incremental files requires precise control on how you deal with failures. You can track what failed and retry at some point in the future until it works. We maintain a **ledger** of the desired state. It is a single file containing everything that *should* exist. When a new incremental file is ingested, we update the ledger rather than sending directly to the API. This allows us to retry failed records and re-ingest files after failures. This also enables point‑in‑time recovery using file‑based integrations, keeping the downstream API untouched, which is a powerful capability for customers and for TechWolf. See [Minimal updates](#minimal-updates) for how we update the downstream API. We live in an imperfect world, and sometimes things go wrong (e.g. DNS failures). The nature of incremental integrations in combination with retention policies prevents the full reconstruction of historical mistakes or when data needs to be loaded in differently. A new property on an employee can't be easily historically added to all previously loaded employees. Therefor, when the incremental file setup is chosen, TechWolf requires periodic reconciliation files. These files must be provided in a smaller window than the retention period, enabling the ability to *always* recover from an available checkpoint. That is, if your retention period is 30 days, you need to set up an automated full reconciliation file every 29 days or less. For information on file-naming conventions in this scenario, see [our file-naming guidelines](/integrations/reference/file-guidelines#incremental-files). ### Minimal updates Datasource ingestion is the heaviest use of the TechWolf API. To reduce load, we perform **minimal updates**. We calculate the set of items that must be created, updated, or deleted to reach the desired state (the **ledger**). These updates are also files, resulting in clear visibility into what is changing. We track what already exists in the API based on previous successful runs and recorded failures. That is the **state**. For a given incremental file, the minimal set of updates equals the difference between the current API state and the desired integration state (state vs. ledger). An additional benefit: each integration tracks its own state, so multiple integrations of the same type can run in parallel without coordinating. An example of what happens when not tracking state separately per integration: 1. You have one source system for Courses. You correctly fetch all Courses from it and load them into the TechWolf API. 2. You pull the TechWolf API daily, fetch all Courses, compare to the source system, and delete only what is not in the source system. 3. You onboard another datasource for Courses. 4. Both integrations run separately, but each wants to delete the set of Courses from the other system. The system is empty again. This setup however duplicates some information, since **state** mirrors the API. Drift can occur, so we periodically reconcile or resend the entire desired state. We accept this trade-off for the benefits of minimal updates and observability. ## 2. Preparing the data for ingestion Source data might not match the format required by the TechWolf API. Validation and transformation are recommended. ### Validation The most common issue is CSV formatting errors. We accept CSV files encoded per [RFC 4180](https://datatracker.ietf.org/doc/html/rfc4180); see [our CSV guidelines](/integrations/reference/file-guidelines#csv). Our advise would be to do the same, preventing any CSV formatting errors or preventing ingestion of wrongly formatted data. Validate input before sending data to the TechWolf API. Although API errors are clear, lightweight input-side business validation reduces time-to-resolution (e.g., preventing a 400 due to an empty field). ### Transformation Formatting data for the TechWolf API is key. Keep transformations simple and transform all first instead of transforming and sending each record individually. This improves observability and measurability of inputs. The transformed input can be inspected as a whole. ## 3. Entity dependencies Some entities depend on other entities. For example, a learning event, which indicates when an employee has completed a course, depends on the course and the employee being present in the TechWolf API. It may be appealing to load entities in dependency order (e.g., courses and employees before learning events). However, this increases complexity and can impact scheduling. Worst case scenario: you want to add a job as an event to an employee. The employee needs an organizational unit; the event needs the job and the employee; the job needs its job family and group, and job data; some job data might need a vacancy. ```mermaid theme={null} flowchart TD Group --> JobFamily["Job Family"] JobFamily --> JobFamilyData["Job Family Data"] JobFamilyData --> Job JobFamily --> Job Vacancy --> JobData["Job Data"] Job --> JobData JobData --> Event OrgUnit["Org unit"] --> Employee Employee --> Event ``` Instead, we recognize that much data changes infrequently and real-time loading is unnecessary. We attempt to load all data concurrently regardless of dependencies. If something fails due to a missing parent, we retry the next day. This applies to cross-entity and intra-entity dependencies. For example, load Custom Properties for an Employee via a separate integration if they originate from a different source file. This avoids ambiguity about whether the Employee loaded correctly versus whether the Custom Properties attached. Scheduling integrations with light dependency ordering can be a middle ground: most data and dependencies load on the first run, and the next load fixes most remaining issues. ## 4. Security considerations ### Authentication Sending data in bulk to the TechWolf API requires authentication. We use our OAuth 2.0 flow. Cache tokens and refresh them before they expire. ### Encryption When building a custom datasource integration, your data does not leave your company, so requirements may be less strict than for TechWolf-hosted integrations. Noteworthy considerations: * Encrypt data at rest. File-based processing interacts heavily with files, so this is essential. * Isolate integrations and files, and apply record-level isolation where possible. Limit operations on input data so one record cannot affect others. * Beyond input data and run derivatives, do not store, log, or emit datasource data. Persisting data is the responsibility of the destination system, if at all. * Prevent large deletes. This is often not what you want, and letting a human verify that it is okay that more than 10% of records will be deleted will prevent problems later on. * Detect anomalies in the system in general. Integrations that don't run, large ingestions, mass failures, or failures that keep happening. ## Addendum: API-based datasource integrations The following is a brief overview of considerations when building custom API-based datasource integrations. * Consider accepting \<100% data capture. If 0.3% of ticket data is missed due to network failures, that may be acceptable for certain scopes; provided the failure rate is uniformly distributed. Failures correlated with load spikes (e.g., specific time zones) are not acceptable, as they impact fairness. * Define a strategy for catastrophic failures (e.g., missing a month of updates). Plan for drift remediation. Checkpoints or full exports can aid recovery. * Consider falling back to file-based integrations where appropriate. # Courses Source: https://developers.techwolf.ai/integrations/datasource-integrations/non-standard-datasource-integrations/courses ## Courses datasource specification This page describes the file-based datasource specification for syncing **Courses** into TechWolf when no standardized connector (such as Workday or SAP SuccessFactors) is available. It defines the file TechWolf expects, the fields within it, and which fields are required. Use this specification when a customer exports Course data from any source system to flat files. Courses are also referenced by Employee Learning History (see the [Employees](/integrations/datasource-integrations/non-standard-datasource-integrations/employees) specification), so a Course referenced there must be synced through this file. For the broader picture of how file-based integrations work and how they compare to API-based connectors, see [Key concepts](/integrations/datasource-integrations/datasources-key-concepts). The delivery flow over SFTP and S3, the file locations, and how to read the field tables below are described in [Technical data flow](/integrations/datasource-integrations/non-standard-datasource-integrations/technical-data-flow). > **Course Information** > > The Course file. **Required.** Contains the Courses that TechWolf infers skills > for and that Employee Learning History records reference. > > File on S3: > `.../file_based/TechWolf_Course_Information/TechWolf_Course_Information_[yyyy][MM][dd]_[HH][mm][ss].csv` > > | TechWolf field | Required | Key | Max chars | Notes | > | - | - | - | - | - | > | course\_id | Required | Primary key | 100 | External ID of the file. | > | course\_title | Required | | 255 | | > | source | Recommended | | 255 | Added as a suffix. | > | course\_description | Required | | No limit | | > | course\_active | Recommended | | n/a | Course assumed to be active if no value is given. | > | course\_duration | Recommended | | n/a | | # Data checklist Source: https://developers.techwolf.ai/integrations/datasource-integrations/non-standard-datasource-integrations/data-checklist Every file delivered to TechWolf has to meet the requirements below before it can be processed. Each item is a formatting, content or structural requirement; all of them must be met before the integration can go live. Work through the list against a sample export before the first delivery. The file locations and the meaning of the field tables are described in [Technical data flow](/integrations/datasource-integrations/non-standard-datasource-integrations/technical-data-flow). ## File Format * File is provided in CSV format and complies with [RFC 4180](https://datatracker.ietf.org/doc/html/rfc4180). See the [File guidelines](/integrations/reference/file-guidelines) for the full set of formatting rules. Bad: ``` job_id, job_title, job_description 4352, Manager in Retail, Restaurants and Bars, This person needs so ... ``` Good: ``` job_id, job_title, job_description 4352, "Manager in Retail, Restaurants and Bars", "This person needs so ..." ``` * No custom or proprietary formats are used (e.g. custom EIB files) unless explicitly agreed. ## Columns & Structure * Column names are not duplicated and in line with the specification pages. Bad: ``` Reference ID, Reference ID, Reference ID ``` Good: ``` employee_id, org_unit_id, job_id ``` * Make sure that internal working history has 1 record per employee and job code. Bad: ``` employee_id, job_id, start_date, end_date 123, 123, 10/10/2014, 01/01/2015 123, 123, 02/01/2015, 31/12/2024 123, 123, 01/01/2025, BLANK ``` Good: ``` employee_id, job_id, start_date, end_date 123, 123, 10/10/2014, BLANK ``` ## Data Quality * Empty values are truly blank (not represented as `\N` or other placeholders). Bad: ``` job_id, job_description, job_summary 123, "", "This job needs to ..." ``` Good: ``` job_id, job_description, job_summary 123,, "This job needs to ..." ``` * All columns have valid values and format is in line with the specification pages (e.g. completion dates are filled when required). * No value exceeds the **Max chars** limit given for its field on the specification pages. Records that exceed it are rejected on ingest, so check the longest value per column against the limit before the first delivery. * Text formatting follows agreed rules (e.g. no unexpected escaped characters like double quotes). See the [File guidelines](/integrations/reference/file-guidelines). Bad: ``` job_id, job_description 123, "Manager, responsible for ""Customer Support""" ``` Good: ``` job_id, job_description 123, "Manager, responsible for Customer Support" ``` ## Identifiers & Scope * Each identifier (employee ID, job code, etc.) is unique and unambiguous. Bad: ``` course_id, course_description, type 123, "Python course for dummies", video 123, "Microsoft Excel", course ``` Good: ``` course_id, course_description, type 123-video, "Python course for dummies", video 123-course, "Microsoft Excel", course ``` * Only the agreed scope of data is included (employees, jobs, or codes). Employees and jobs not in scope are not sent. * Make sure no opted-out and terminated employee data is present in the files. * Inactive data is included for jobs and courses (relevant for learning/working history). Bad: ``` course_id, course_name, active 101, Safety Training, TRUE ``` Good: ``` course_id, course_name, active 101, Safety Training, TRUE 102, Old Certification, FALSE ``` * Make sure IDs are consistent across files, so records can be referenced. For example, `employee_id` in the employee file is the same as `employee_id` in the learning file. Bad: ``` Employee file: employee_id = 123 Learning file: emp_id = 321 ``` Good: ``` Employee file: employee_id = 123 Learning file: employee_id = 123 ``` # Employees Source: https://developers.techwolf.ai/integrations/datasource-integrations/non-standard-datasource-integrations/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](/integrations/datasource-integrations/non-standard-datasource-integrations/jobs) and [Courses](/integrations/datasource-integrations/non-standard-datasource-integrations/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](/integrations/datasource-integrations/datasources-key-concepts). The delivery flow over SFTP and S3, the file locations, and how to read the field tables below are described in [Technical data flow](/integrations/datasource-integrations/non-standard-datasource-integrations/technical-data-flow). 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 | Max chars | Notes | > | - | - | - | - | - | > | employee\_id | Required | Primary key | 100 | External ID of the file. ID of the Employee. | > | assigned\_position | Recommended | Foreign key | 100 | The Employee's current Job. Points to job\_id in Job Information. | > | organisational\_unit\_id | Recommended | Foreign key | 100 | Points to organisational\_unit\_id in Organisational Information. | > | active | Recommended | | n/a | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | organisational\_unit\_id | Required | Primary key | 100 | External ID of the file. | > | organisational\_unit\_name | Required | | 100 | | > | organisational\_unit\_active | Recommended | | n/a | | > | parent\_organisational\_unit\_id | Recommended | Foreign key | 100 | Points to the organisational\_unit\_id of the parent unit. | > | parent\_organisational\_unit\_name | Recommended | | 100 | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | course\_id | Required | Foreign key | 100 | Points to course\_id in Course Information. | > | timestamp | Recommended | | n/a | 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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | job\_id | Required | Foreign key | 100 | Points to job\_id in Job Information. | > | start\_date | Recommended | | n/a | Also used as the timestamp. | > | end\_date | Recommended | | n/a | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | job\_title | Required | | 256 | Title and description cannot both be empty. | > | job\_description | Recommended | | No limit | | > | company | Recommended | | 256 | | > | start\_date | Recommended | | n/a | | > | end\_date | Recommended | | n/a | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | certification\_name | Required | | 255 | Name and description cannot both be empty. | > | certificate\_description | Required | | No limit | | > | timestamp | Recommended | | n/a | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | degree\_name | Required | | No limit | Name and description cannot both be empty. | > | degree\_description | Required | | No limit | | > | start\_date | Recommended | | n/a | | > | end\_date | Recommended | | n/a | 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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | timestamp | Recommended | | n/a | | > | source | Recommended | | No limit | | > | description | Required | | No limit | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | project\_description | Required | | 10000 | | > | timestamp | Recommended | | n/a | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | ticket\_title | Required | | 1000 | | > | ticket\_description | Required | | 50000 | | > | ticket\_system | Recommended | | 100 | | > | ticket\_status | Recommended | | No limit | | > | ticket\_type | Recommended | | 1000 | | > | timestamp | Recommended | | n/a | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | title | Required | | 255 | | > | description | Required | | No limit | | > | status | Recommended | | No limit | Only send entries perceived as relevant (e.g. "Completed", "On Track"). | > | type | Recommended | | No limit | | > | timestamp | Recommended | | n/a | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | description | Required | | No limit | | > **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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | mimeType | Required | | n/a | Only application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, and text/plain are supported; other types are ignored. | > | base64Content | Required | | No limit | 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 | Max chars | Notes | > | - | - | - | - | - | > | external\_id | Recommended | Primary key | 100 | Share the ID from the source system if you have one. If it is not provided, TechWolf generates one. | > | employee\_id | Required | Foreign key | 100 | Mapped to the Employee based on the author of the commit message. | > | merge\_request\_title | Required | | 500 | | > | merge\_request\_description | Required | | 250000 | | > | commit\_message | Required | | 100000 | Each row contains a single commit message. | > | status | Recommended | | No limit | | > | timestamp | Recommended | | n/a | | # Jobs Source: https://developers.techwolf.ai/integrations/datasource-integrations/non-standard-datasource-integrations/jobs ## Jobs datasource specification This page describes the file-based datasource specification for syncing **Jobs** and their **Vacancies** into TechWolf when no standardized connector (such as Workday or SAP SuccessFactors) is available. It defines the files TechWolf expects, the fields within each file, and which fields are required. Use this specification when a customer exports Job data from any source system to flat files. As long as the data can be shaped into the files below, TechWolf can ingest it. Jobs are referenced by Employees: the Employee Baseline points to a Job through `assigned_position`, and Internal Work History points to a Job through `job_id` (see the [Employees](/integrations/datasource-integrations/non-standard-datasource-integrations/employees) specification). A Job referenced there must be synced through the Job Information file below. For the broader picture of how file-based integrations work and how they compare to API-based connectors, see [Key concepts](/integrations/datasource-integrations/datasources-key-concepts). The delivery flow over SFTP and S3, the file locations, and how to read the field tables below are described in [Technical data flow](/integrations/datasource-integrations/non-standard-datasource-integrations/technical-data-flow). > **Job Information** > > The baseline Job file. **Required.** Contains the Jobs (and their architecture > hierarchy) that TechWolf infers skills for. > > File on S3: > `.../file_based/TechWolf_Job_Information/TechWolf_Job_Information_[yyyy][MM][dd]_[HH][mm][ss].csv` > > | TechWolf field | Required | Key | Max chars | Notes | > | - | - | - | - | - | > | job\_id | Required | Primary key | 100 | External ID of the file. ID of the Job. | > | job\_title | Required | | 255 | | > | job\_description | Recommended | | No limit | | > | skill\_requirements | Recommended | | No limit | | > | job\_hierarchy\_level\_1 | Recommended | | 255 | Top level of the Job architecture. | > | job\_hierarchy\_level\_2 | Recommended | | 255 | | > | job\_hierarchy\_level\_2\_ID | Recommended | | 100 | | > | job\_hierarchy\_level\_2\_description | Recommended | | No limit | | > | active | Recommended | | n/a | Job assumed to be active if no value is given. | > **Job Vacancies** > > Open Vacancies (Job Requisitions) linked to Jobs. **Highly recommended.** > Vacancy text is a strong signal for skill inference. > > File on S3: > `.../file_based/TechWolf_Job_Requisition/TechWolf_Job_Requisition_[yyyy][MM][dd]_[HH][mm][ss].csv` > > | TechWolf field | Required | Key | Max chars | Notes | > | - | - | - | - | - | > | requisition\_id | Required | Primary key | 100 | External ID of the file. ID of the Vacancy. | > | job\_id | Recommended | Foreign key | 100 | Job linked to the Vacancy, used for skill inference. | > | job\_title | Required | | 255 | | > | job\_description | Required | | No limit | | > | job\_requisition\_inactive | Recommended | | n/a | | # Technical data flow Source: https://developers.techwolf.ai/integrations/datasource-integrations/non-standard-datasource-integrations/technical-data-flow This page covers the parts shared by every file-based datasource specification in this section: how files travel from the customer to TechWolf, where they land on S3, and how to read the field tables on the [Jobs](/integrations/datasource-integrations/non-standard-datasource-integrations/jobs), [Employees](/integrations/datasource-integrations/non-standard-datasource-integrations/employees) and [Courses](/integrations/datasource-integrations/non-standard-datasource-integrations/courses) pages. For the broader picture of how file-based integrations work and how they compare to API-based connectors, see [Key concepts](/integrations/datasource-integrations/datasources-key-concepts). ## Technical data flow The files described in the specification pages end up in the customer's TechWolf **AWS S3** bucket, under the file-based ingest prefix. The file-based integration reads them from there and syncs the data into the TechWolf SkillEngine API. How the files reach S3 depends on the delivery method agreed during implementation: * **TechWolf-hosted SFTP server.** The customer (or their source system) pushes the files to the TechWolf SFTP server. Each SFTP user's root directory maps to a directory in TechWolf's S3 infrastructure, so an upload lands on S3 directly. TechWolf provides the credentials. Server addresses and static IP addresses for allowlisting are listed under [SFTP: TechWolf-hosted SFTP server](/integrations/reference/sftp/sftp#techwolf-hosted-sftp-server). * **Customer-hosted SFTP server.** The customer exports the files to their own SFTP server. TechWolf connects to it on a schedule, pulls the files, and writes them to S3 according to the folder mappings configured in the Console. Setup is described in [Self-service SFTP setup](/integrations/reference/sftp/self-service-setup); pull behaviour (files are pulled once, default schedule every 30 minutes) in [SFTP: Behaviour of a customer-hosted connection](/integrations/reference/sftp/sftp#behaviour-of-a-customer-hosted-connection). Each file has a fixed location and naming pattern on S3, given in the specification pages. The base path is: ``` s3://techwolf-/production/external/input/integrations/file_based/ ``` > [!NOTE] > > During the testing phase, the `staging` environment path is used instead: > `s3://techwolf-/staging/external/input/integrations/file_based/`. Files must be written into the per-file subfolders given in the specification pages (for example `file_based/TechWolf_Job_Information/`), not into the root of the file-based path. For the wider S3 layout and the recommended folder structure on SFTP servers, see [File Organization](/integrations/reference/file-structure). ## 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. The **Required** column is `Required` or `Recommended`. A `Required` field must have a value on every row. A `Recommended` field can be left empty, but send it wherever the source system holds a value. The **Max chars** column gives the longest value the SkillEngine API accepts for that field. A row whose value exceeds the limit is rejected on ingest, so truncate or drop over-long values in the export rather than letting the integration reject the record. `No limit` means the API sets no maximum; `n/a` means the field is not free text (a date, a boolean or a number) and the Notes column describes the format instead. Limits are applied to the value that reaches the API, so they are measured after any transformation configured on the integration (for example the [Slugify](/integrations/datasource-integrations/data-integrator/how-to-set-up-integration) step applied to identifiers). # How To: Add an SSH Key to the Integration Center Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center Integration Center schedules connect to the TechWolf [SFTP server ](/integrations/reference/sftp/sftp) with either a username and password, or a username and SSH key. This guide covers the SSH key option: SAP SuccessFactors generates the key pair in the Security Center, you share the public key with TechWolf, and the Integration Center schedules authenticate with it. The private key never leaves SAP SuccessFactors. **1. Go to the Security Center** Enter `Security Center` in the search bar at the top of the screen and open it. Click the `Other Keys` tile. **2. Generate the key** Click `Add` at the top left of the key list and fill in the form: * Name: a recognisable name, e.g. `TechWolf SFTP Key` * Category: `Authentication Key (SSH)` * Key Size: `4096 bits` * Valid From and Valid Until: optional. When set, the schedules stop working after the `Valid Until` date, so set a reminder to rotate the key before it expires. Click `Generate and Save`. **3. Download the public key** Select the new key in the list and click `Download Public Key` at the top right. This downloads a `.pub` file. **4. Share the public key with TechWolf** Send the `.pub` file to your TechWolf representative. TechWolf registers the key on the SFTP server and sends back the SFTP user name linked to it. **5. Use the key in the Integration Center** When loading the [export ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions) or [import ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-import-integration-definitions) integration definitions, fill in the Destination Settings (exports) or Source Settings (imports) page as follows: * Authentication Type: `Certificate based Authentication` * SFTP User Name: the user name TechWolf sent back * Authentication Key: the key generated above, e.g. `TechWolf SFTP Key`. The dropdown only lists keys present in the Security Center. # How To: Load Export Integration Definitions Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions **1. Go to the Integration Center** To go to the Integration Center, enter `Integration Center` in the search bar at the top of the screen. **2. Import the integration definition** In the Integration Center, click `My Integrations`. In the resulting page, click the `Create` button at the top of the screen and select `Import an Integration Definition`. **3. Upload the desired integration definition** In the popup that opens, upload the correct `.icd` file containing the integration definition and click `upload`. If a warning pops up, click `OK`. **4. Leave the Options page, Configure Fields page and Filter and Sort pages as is** The Options page, Configure Fields page, and the Filter and Sort page should not be modified. **5. Fill in the destination settings** On the destination settings page, fill in the following: * Server details (Host and Port) can be found at [SFTP server ](/integrations/reference/sftp/sftp#server-details) * Authentication Type: `Basic Authentication` * SFTP User Name: SFTP User Name shared by TechWolf * SFTP Password: SFTP Password shared by TechWolf If TechWolf provided you with SFTP access by SSH key instead of a password, follow [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center) and fill in the authentication fields as described there. **6. Set schedule** Under Scheduling, select `Daily` in the dropdown menu. Then choose the appropriate time (e.g. 12:00 AM tomorrow) under `Start Time`. Note that the time of day of the start time will be the time of day for all future automatic integration runs. It is not required to set the `Ending On` field. If desired, set `Ending On` to a date far enough in the future and set up a reminder for yourself to extend the schedule when the expiry date is approaching. # How To: Load Import Integration Definitions Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-import-integration-definitions **1. Go to the Integration Center** To go to the Integration Center, enter `Integration Center` in the search bar at the top of the screen. **2. Import the integration definition** In the Integration Center, click `My Integrations`. In the resulting page, click the `Create` button at the top of the screen and select `Import an Integration Definition`. **3. Upload the desired integration definition** In the popup that opens, upload the correct `.icd` file containing the integration definition and click `upload`. If a warning pops up, click `OK`. **4. Leave the Options page and Configure Fields page as is** The Options page and Configure Fields page should not be modified. **5. Fill in the source settings** On the source settings page, fill in the following: * Server details (Host and Port) can be found at [SFTP server ](/integrations/reference/sftp/sftp#server-details) * Authentication Type: `Basic Authentication` * SFTP User Name: SFTP User Name shared by TechWolf * SFTP Password: SFTP Password shared by TechWolf If TechWolf provided you with SFTP access by SSH key instead of a password, follow [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center) and fill in the authentication fields as described there. **6. Set schedule** Under Scheduling, select `Daily` in the dropdown menu. Then choose 12:00 AM tomorrow under `Start Time`. It is not required to set the `Ending On` field. If desired, set `Ending On` to a date far enough in the future and set up a reminder for yourself to extend the schedule when the expiry date is approaching. # How To: Whitelist SFTP server in SAP Source: https://developers.techwolf.ai/integrations/datasource-integrations/sap-standard-input-integration/how-to-whitelist-sap-sftp-server Before beginning data transfers, you must request that SAP whitelists the SFTP server provided by TechWolf. The following step-by-step guide shows how to submit a support request to SAP with the details of your SFTP server to ensure secure connectivity. **1. Go to the Create an Incident page** To create an SAP support case, go to the [Create an Incident ](https://me.sap.com/app/casecreate) page. You will need to be logged in with a valid S-user account for this. The account should have the `Display Cloud Data` and `Cases` permissions. **2. Select your SAP system** You will need to fill in some basic information. Your customer number and name are already filled in. Select the SAP system that you want to enable the TechWolf integration for. After selecting the system, the `Product Area` should not be a required field anymore and should be greyed out. **3. Fill in the Description** Fill in the Subject and Description to request whitelisting the SFTP server. Below, we have drafted a Subject and Description which you can use. Make sure to fill in your SAP SF System and use the SFTP server details for your TechWolf region. | Region | Hostname | Static IP addresses | | - | - | - | | EU | eu3.sftp.techwolf.ai | 13.38.145.100, 15.188.45.53 | | US | us3.sftp.techwolf.ai | 52.203.212.226, 54.83.27.174 | **Subject:** ```text theme={null} Request FQDN whitelist for SFTP server ``` **Description:** ```text theme={null} Following this support page: https://me.sap.com/notes/3122406, we want to allowlist a TechWolf SFTP server on our tenant: - SFTP IP addresses: - SFTP Hostname (FQDN): - Port Number: 22 Business reason: We want to export HR core data to TechWolf. Is it possible to allowlist this SFTP server on our tenant please? Kind regards, ``` **4. Select the Subproduct** Select the relevant Subproduct for this request. Search for and select `LOD-SF-PLT-IPR` as this relates to IP management. **5. Review the Incident page** Scroll to the end of the page. The Attachments, Details, and Priority sections can be left as is. Click on `Review & Submit Incident` to give the page a final review. **6. Submit the Incident page** Scroll to the end of the page. Click on the `Submit Incident` button to submit the request. **7. Follow up on the request** The SFTP server should be whitelisted within a couple of working days. # Courses Source: https://developers.techwolf.ai/integrations/datasource-integrations/workday-datasource/courses ## Courses datasource specification This page describes the Workday EIB file for syncing **Courses** into TechWolf. It gives the S3 location, the fields TechWolf expects, and the Workday field each one comes from. Courses are referenced by Employee Learning History (see the [Employees](/integrations/datasource-integrations/workday-datasource/employees) specification), so a Course referenced there must be synced through this file. The rules shared by every Workday file (full dumps, dependencies, transformations and how to read the field tables) are described in the [EIB Specification](/integrations/datasource-integrations/workday-datasource/eib-specification). > **Course Information** > > The Course catalogue. **Required** when Employee Learning History is synced. > > File on S3: > `.../file_based/TechWolf_Course_Information/TechWolf_Course_Information_[yyyy][MM][dd]_[HH][mm][ss].csv` > > | TechWolf field | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | course\_id | Learning Content | Learning Content | CF EE Learning Content ID based on type | Required | Primary key | 100 | External ID of the file. Slugified. | > | course\_title | Learning Content | Learning Content | Title | Required | | 255 | | > | source | Learning Content | Learning Content | Learning Content Type | Recommended | | 255 | Added as a suffix. | > | course\_description | Learning Content | Learning Content | Description | Required | | No limit | | > | course\_active | Learning Content | Learning Content | Active Status | Recommended | | n/a | Course assumed to be active if no value is given. Sync inactive Courses too, so older Learning History records can be resolved. | > | course\_duration | Learning Content | Learning Content | Duration in minutes | Recommended | | n/a | Must be a positive integer. | > > > [!NOTE] > > > > TechWolf recommends filtering the Course export in Workday on **Learning > > Content Type** in the selection list `Blended Course`, `Digital Course`, > > `Lesson`. > > > > Mandatory Courses are best removed too. If they are included, they can be > > recommended to Employees who have not completed them yet. # EIB Specification Source: https://developers.techwolf.ai/integrations/datasource-integrations/workday-datasource/eib-specification This page covers the parts shared by every Workday EIB file: delivery, dependencies, transformations and how to read the field tables. The files themselves, with their fields and the Workday field each one comes from, are described on the [Jobs](/integrations/datasource-integrations/workday-datasource/jobs), [Employees](/integrations/datasource-integrations/workday-datasource/employees) and [Courses](/integrations/datasource-integrations/workday-datasource/courses) pages. ## General specifications The Workday EIB integration is file-based: Workday exports each file and delivers it to the customer's TechWolf **AWS S3** bucket, from where TechWolf reads it and syncs the data into the SkillEngine API. Setting up the custom report and the Outbound EIB that delivers it is described in [Installation](/integrations/datasource-integrations/workday-datasource/installation). The base path for every file is: ``` s3://techwolf-/production/external/input/integrations/file_based/ ``` > [!NOTE] > > During the testing phase, the `staging` environment path is used instead: > `s3://techwolf-/staging/external/input/integrations/file_based/`. Each file has its own subfolder and naming pattern under that base path, given per file on the Jobs, Employees and Courses pages. Files must be written into those subfolders, not into the root of the file-based path. For the wider S3 layout, see [File Organization](/integrations/reference/file-structure). The export **frequency is configured by the customer** and agreed with TechWolf during implementation. It is set on the EIB schedule. Each file is marked **Required**, **Highly recommended** or **Recommended**. Required files must be delivered for the integration to work; the others add skill-relevant signal and are delivered where the data exists. ## Shared rules The following rules apply to every Workday file: * All files are presumed to be full dumps, i.e. the state of all relevant entities is expected to be given in each export file, not just the changes compared to the last export. * Not all files are necessarily required, though existing dependencies must be respected. For example, if the basic information of employees (i.e. their existence) is already synced, it is optional whether to include e.g. employee goals as well; yet when employee goals are to be synced, the employee baseline sync must be included as well. An overview of the dependencies is given below: ```mermaid theme={null} erDiagram JOB_FAMILY["Job Family"] { string job_family_id PK } JOB["Job"] { string job_id PK string job_family_id FK } VACANCY["Vacancy (Job Requisition)"] { string requisition_id PK string job_id FK } COURSE["Course"] { string course_id PK } EMPLOYEE["Employee"] { string employee_id PK string assigned_position_id FK string organisational_unit_id FK } ORGANISATIONAL_UNIT["Organisational Unit"] { string organisational_unit_id PK string parent_organisational_unit_id FK } PERFORMANCE["Employee Performance"] { string employee_id FK } EXTERNAL_WORK_HISTORY["Employee External Work History"] { string employee_id FK } INTERNAL_WORK_HISTORY["Employee Internal Work History"] { string employee_id FK string job_id FK } EDUCATION_HISTORY["Employee Education History"] { string employee_id FK } CERTIFICATE["Employee Certification"] { string employee_id FK } FEEDBACK["Employee Feedback"] { string employee_id FK } GOAL["Employee Goal"] { string employee_id FK } LEARNING_HISTORY["Employee Learning History"] { string employee_id FK string course_id FK } RESUME["Employee Resume"] { string employee_id FK } JOB_FAMILY ||--o{ JOB : "" JOB ||--o{ VACANCY : "" JOB ||--o{ EMPLOYEE : "" JOB ||--o{ INTERNAL_WORK_HISTORY : "" COURSE ||--o{ LEARNING_HISTORY : "" EMPLOYEE ||--o{ EXTERNAL_WORK_HISTORY : "" EMPLOYEE ||--o{ INTERNAL_WORK_HISTORY : "" EMPLOYEE ||--o{ EDUCATION_HISTORY : "" EMPLOYEE ||--o{ CERTIFICATE : "" EMPLOYEE ||--o{ FEEDBACK : "" EMPLOYEE ||--o{ GOAL : "" EMPLOYEE ||--o{ LEARNING_HISTORY : "" EMPLOYEE ||--o{ RESUME : "" EMPLOYEE ||--o{ PERFORMANCE : "" ORGANISATIONAL_UNIT ||--o{ EMPLOYEE : "" ``` * All expected fields can be provided under another name, or split among different fields, as long as this division or rename is then used consistently (and is communicated to TechWolf). This applies to both the fields marked as "required" as those that are marked as "recommended". When multiple input fields are taken together to form one expected (or additional) field, the resulting field will consist of the values of the constituent fields, separated by a hyphen surrounded by spaces (" - "). Additionally, some field conversions are also supported; in particular, dates can be converted to the required format, and arbitrary string-to-string mappings can be configured, which can be particularly useful in combination with field filtering (mentioned below). Possible limitations specified on fields always apply after transformation. * Fields that are marked as "required" are generally expected to always be present (after transformation). However, there is also support for "default values", though this only applies to certain fields (marked with \*). Setting defaults should be avoided, since it makes data less informative, and should only be used in cases where it is unavoidable and doesn't cause unnecessary obfuscation or decreased informativeness. One use case could be to set all certificate descriptions to be "-" by default if no actual certificate descriptions are available, but the certificate titles are still informative enough to warrant syncing certificates. * The integrations support field filters: per input file, one field can be chosen to act as a filter (besides possibly also carrying information to be synced), where the input object (csv row, xlsx row, ...) is only processed if the value of the filter field is either contained in the given whitelist of values or not included in the given banlist of values. Note that filtering is completely optional and that filtering is applied after input transformation. Do note that TechWolf always prefers filtering at the EIB where possible, to prevent unnecessary data transfer and processing. > **slugify** > > Slug strings are strings consisting of only lowercase letters, uppercase > letters, numbers, underscores (\_) and dashes (-). > > When non-slug strings are slugified at TechWolf's side, we use a mapping as > defined in > [slugify](https://github.com/simov/slugify/blob/master/config/charmap.json), > except for the following mappings: > > * "/" becomes "\_SLASH\_" > * "(" becomes "\_OPENR\_" > * ")" becomes "\_CLOSER\_" > * "\[" becomes "\_OPENS\_" > * "]" becomes "\_CLOSES\_" > * "\{" becomes "\_OPENC\_" > * "}" becomes "\_CLOSEC\_" ## Reading the field tables Each file on the Jobs, Employees and Courses pages has one table, with one row per Workday field: * **TechWolf field** is the column name TechWolf expects in the file. * **Primary Business Object**, **Business Object** and **Workday field** give the full path to the field in Workday: the business object the report is built on, the related business object the field sits on, and the field itself. A field whose name starts with `CF` is a calculated field. * When a TechWolf field is listed on several rows, the Workday fields on those rows are joined into one value, separated by `" - "`. * **Required** is `Required` or `Recommended`. A `Required` field must have a value on every row. A `Recommended` field can be left empty, but send it wherever Workday holds a value. `Required*` means the field supports a default value (see the notes above). * **Key** marks the external ID of the file (`Primary key`) and fields that point to the primary key of another file (`Foreign key`). Fields without a Key are data fields used for skill inference or context. * **Max chars** gives the longest value the SkillEngine API accepts for that field, measured after transformation. A row whose value exceeds the limit is rejected on ingest, so over-long values should be truncated or dropped in the EIB rather than left for the integration to reject. `No limit` means the API sets no maximum; `n/a` means the field is not free text (a date, a boolean or a number). * `n/a` in the Workday columns means there is no default Workday field; the source, if any, is agreed with TechWolf during implementation. ## Profile data and custom properties Job Families and Jobs can be extended with an arbitrary amount of "profile data", which will be used for skill extraction. The profile data types available are: * Job Families: `job_family_description` * Jobs: `job_description`, `job_title`, `vacancy`, `skill_notes` For every profile data variant, we need the following information: * The name of the source field(s) in the input (and their ordering, in case of concatenation) * The profile data type * Whether the profile data should always be present (true or false) Job Families, Jobs, Vacancies, Courses and Employees can also be extended with an arbitrary amount of "custom properties", which will NOT be used for skill extraction, but might be useful for querying or other identification, grouping or disambiguation scenarios. For every custom property, we need the following information: * The name of the source field(s) in the input (and their ordering, in case of concatenation) * The name of the custom property (at least 1 and at most 100 characters; cannot contain "\_\_") * The data type of the custom property ("text", "number", "boolean", "list\[text]" or "datetime") * Whether the custom property should always be present (true or false) # Employees Source: https://developers.techwolf.ai/integrations/datasource-integrations/workday-datasource/employees ## Employees datasource specification This page describes the Workday EIB files for syncing **Employees** into TechWolf: the Employee baseline, the organisational structure, and every skill-relevant signal attached to an Employee. For each file it gives the S3 location, the fields TechWolf expects, and the Workday field each one comes from. 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](/integrations/datasource-integrations/workday-datasource/jobs) and [Courses](/integrations/datasource-integrations/workday-datasource/courses) specifications must be synced as well for those links to resolve. The rules shared by every Workday file (full dumps, dependencies, transformations and how to read the field tables) are described in the [EIB Specification](/integrations/datasource-integrations/workday-datasource/eib-specification). The files from Learning History onwards carry no identifier from Workday. TechWolf generates an `external_id` for each row as a hash of its content, so the EIB does not need to export one. > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Primary key | 100 | External ID of the file. Slugified. | > | assigned\_position | Worker | Job Profile | Reference ID | Recommended | Foreign key | 100 | The Employee's current Job. Points to job\_id in Job Information. This is the Job Profile in Workday, not the Position. | > | organisational\_unit\_id | Worker | Supervisory Organization | Reference ID | Recommended | Foreign key | 100 | Points to organisational\_unit\_id in Organisational Information. If given, an Organisational Unit with that id must exist. | > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | organisational\_unit\_id | Supervisory Organization | Supervisory Organization | Reference ID | Required | Primary key | 100 | External ID of the file. Slugified. | > | organisational\_unit\_name | Supervisory Organization | Supervisory Organization | Supervisory Organization | Required | | 100 | | > | organisational\_unit\_active | Supervisory Organization | Supervisory Organization | Active | Recommended | | n/a | The Organisational Unit is assumed to be active if no value is given. | > | parent\_organisational\_unit\_id | Supervisory Organization | Superior Organization | Reference ID | Recommended | Foreign key | 100 | Points to the organisational\_unit\_id of the parent unit. | > | parent\_organisational\_unit\_name | Supervisory Organization | Superior Organization | Superior Organization | Recommended | | 100 | | > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Learning Enrollment | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | course\_id | Learning Enrollment | Enrolled Content | CF EE Learning Content ID based on type | Required | Foreign key | 100 | Points to course\_id in Course Information. Use the same calculated field as the Course file. | > | timestamp | Learning Enrollment | Learning Enrollment | Completion Date | Recommended | | n/a | Defaults to the creation time of the related Skill Event within TechWolf. | > > > [!NOTE] > > > > TechWolf recommends applying these filters to the Learning History export in > > Workday, so the file only carries completed, skill-relevant learning: > > > > * **Completion Status** in the selection list: `Completed` > > * **Learning Content Type** in the selection list: `Blended Course`, > > `Digital Course`, `Lesson` > > > > Mandatory learning should be removed as well. > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | job\_id | Worker | Job Profile History | CF LRV Reference ID from Job Profile History | Required | Foreign key | 100 | Points to job\_id in Job Information. A calculated field you may still have to create: type Lookup Reference Value, on the Job Profile Snapshot Interface business object, for the field Reference ID. | > | start\_date | Worker | Job Profile History | Job Profile Change Start Date | Recommended | | n/a | Also used as the timestamp. | > | end\_date | Worker | Job Profile History | Job Profile Change End Date | Recommended | | n/a | Leave empty while the Job is ongoing. | > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | job\_title | Worker | Job History - Skills and Experience | External Job | Required | | 256 | | > | job\_description | Worker | Job History - Skills and Experience | Responsibility and Achievements | Recommended | | No limit | | > | company | Worker | Job History - Skills and Experience | Company | Recommended | | 256 | | > | start\_date | Worker | Job History - Skills and Experience | Start Date | Recommended | | n/a | | > | end\_date | Worker | Job History - Skills and Experience | End Date | Recommended | | n/a | Leave empty while the Job is ongoing. | > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | certification\_name | Worker | Certifications | Certification Name | Required\* | | 255 | | > | certificate\_description | n/a | n/a | n/a | Required\* | | No limit | Workday Certifications carry no description, so this field normally needs a default value agreed with TechWolf. | > | timestamp | Worker | Certifications | Issued Date | Recommended | | n/a | | > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | degree\_name | Worker | Education | Degree | Required | | No limit | Joined with Field of Study into one value. | > | degree\_name | Worker | Education | Field of Study | Required | | No limit | | > | school | Worker | Education | School | Recommended | | No limit | | > | start\_date | Worker | Education | First Day Attended | Recommended | | n/a | | > | end\_date | Worker | Education | Last Day Attended | Recommended | | n/a | 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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | timestamp | Worker | Feedback | Date | Recommended | | n/a | | > | source | Worker | Feedback | Feedback Type | Recommended | | No limit | | > | description | Worker | Feedback | Question | Required | | No limit | Joined with Comment into one value. | > | description | Worker | Feedback | Comment | Required | | No limit | | > **Goals** > > Goals set for the Employee. **Recommended.** > > File on S3: > `.../file_based/TechWolf_Goal/TechWolf_Goal_[yyyy][MM][dd]_[HH][mm][ss].csv` > > | TechWolf field | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | description | Worker | Goals | Goal | Required | | No limit | Joined with Goal Description into one value. | > | description | Worker | Goals | Goal Description | Required | | No limit | | > | timestamp | Worker | Goals | Completed on | Recommended | | n/a | | > > > [!NOTE] > > > > Only send Goals that carry a relevant **Status** in Workday, for example > > `Completed` and `On Track`. > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | title | Worker | Performance Review - Most Recent for Worker | Performance Review Name | Required | | 255 | | > | description | Worker | Performance Review - Most Recent for Worker | Content - Feedback Responses Overall Comment - Manager | Required | | No limit | | > | status | Worker | Performance Review - Most Recent for Worker | Status | Recommended | | No limit | Only send entries perceived as relevant (e.g. "Completed", "On Track"). | > | type | n/a | n/a | n/a | Recommended | | No limit | | > | timestamp | Worker | Performance Review - Most Recent for Worker | Date and Time Completed | Recommended | | n/a | | > **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 | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | employee\_id | Worker | Worker | Employee ID | Required | Foreign key | 100 | Points to employee\_id in Employee Baseline. | > | mimeType | Worker | Resume Attachments | Content Type | Required | | n/a | Only application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, and text/plain are supported; other types are ignored. | > | base64Content | Worker | Resume Attachments | Attachment | Required | | No limit | The document encoded as a base64 string. | # Installation Source: https://developers.techwolf.ai/integrations/datasource-integrations/workday-datasource/installation This page explains how to set up the Workday side of the Workday EIB datasource integration: creating the custom report that holds the data to be synced, and configuring an Outbound Enterprise Interface Builder (EIB) to deliver that report to the shared TechWolf S3 bucket. The exact fields, columns, file name, file path and schedule to use are defined in the integration documentation provided by your TechWolf delivery team, and must match the [EIB Specification](/integrations/datasource-integrations/workday-datasource/eib-specification) and the [Jobs](/integrations/datasource-integrations/workday-datasource/jobs), [Employees](/integrations/datasource-integrations/workday-datasource/employees) and [Courses](/integrations/datasource-integrations/workday-datasource/courses) pages, which give the Workday field behind every column. ## Prerequisites To have access to the Workday datasource integration, at least the following prerequisites must be met: * You have the appropriate TechWolf API licenses. * You have the appropriate SkillEngine API credentials, which include: * Tenant ID * Tenant secret * Tenant name * Region (Europe or United States) * You have a TechWolf API tenant set up that contains the relevant information for the requested output integration. * Both you and TechWolf have access to the agreed input location. ## What to agree with TechWolf Before building the exports, agree the following with TechWolf: * The cadence with which the exports are made and delivered. * The location at which the exports will be delivered to TechWolf (presumed to be a directory on your TechWolf S3 bucket). * The format in which the files will be delivered to TechWolf (CSV, xlsx, ...). * The exact way in which the exports correspond to the input required by TechWolf, insofar as the EIB setup does not match the default specification. > [!NOTE] > > Several of the linked Workday guides require a Workday Community account. If > a link is not publicly accessible, sign in with your Workday Community > credentials. ## Step 1: Create a Custom Report in Workday In this step you create the custom report that contains the data to be exported, following the integration documentation provided by your TechWolf delivery team. **1. Create the report** In Workday, create a new custom report and give it a name. **2. Enable it as a web service** Select **Advanced Report** and enable it as a web service. **3. Select the fields** Select the appropriate fields and columns for the report, as defined in the integration documentation from your TechWolf delivery team. For more detailed guidance, refer to the Workday documentation on [setting up custom reports](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/set-up-reports/dan1370797785951.html) (requires a Workday Community account). ## Step 2: Create an Outbound EIB In this step you set up the outbound integration that delivers the custom report to the shared TechWolf S3 bucket using a Workday Outbound EIB. **1. Reference the custom report** Create an Outbound EIB that references the custom report created in Step 1. **2. Configure the output format** Configure the EIB to generate output in CSV format. **3. Set the delivery method** Set the delivery method to Amazon Simple Storage Service (S3). **4. Select the bucket** Select your designated bucket (`techwolf-`), as specified in the received integration documentation. **5. Configure the file name and path** In Workday, the full file name is the combination of the file path and the file name. Set both to match the exact path and naming convention specified in the integration document provided by your TechWolf delivery team. Do not derive them from this page. Where that path or name includes a date, use a Workday [sequence generator](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/tenant-setup/id-definitions-and-sequence-generators/dan1370796358261.html?lang=en-us) (requires a Workday Community account) to insert it, following the format given in that same provided integration document. **6. Set the schedule** Set up the integration schedule according to the cadence defined in the integration documentation. By default, the cadence is daily. > [!WARNING] > > **Connection testing will fail. This is expected.** > > When testing the connection from Workday to the S3 bucket using the **Connect** > function, the test will fail. The credentials provided grant access only to a > specific file path, not to the entire bucket, whereas Workday's connection test > attempts to access the full bucket. > > To verify the setup, test file delivery directly instead of using the connection > test. A successful file delivery confirms that the integration is configured > correctly. For more detailed guidance, refer to the Workday documentation on [custom reports and integrations](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/set-up-reports/dan1370797785951.html) (requires a Workday Community account). # Jobs Source: https://developers.techwolf.ai/integrations/datasource-integrations/workday-datasource/jobs ## Jobs datasource specification This page describes the Workday EIB files for syncing **Jobs**, their **Job Families** and their **Vacancies** into TechWolf. For each file it gives the S3 location, the fields TechWolf expects, and the Workday field each one comes from. Jobs are referenced by Employees: the Employee Baseline points to a Job through `assigned_position`, and Internal Work History points to a Job through `job_id` (see the [Employees](/integrations/datasource-integrations/workday-datasource/employees) specification). A Job referenced there must be synced through the Job Information file below. The rules shared by every Workday file (full dumps, dependencies, transformations and how to read the field tables) are described in the [EIB Specification](/integrations/datasource-integrations/workday-datasource/eib-specification). > [!NOTE] > > Skills on Workday Job Profiles are not delivered through an EIB file. They > are synced through the [Workday Job Skill > Sync](/integrations/workday-skill-sync-integration/overview-jobs). > **Job Families** > > The Job Families that Jobs are grouped into. **Required.** > > File on S3: > `.../file_based/TechWolf_Job_Family/TechWolf_Job_Family_[yyyy][MM][dd]_[HH][mm][ss].csv` > > | TechWolf field | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | job\_family\_id | Job Family | Job Family | Reference ID | Required | Primary key | 100 | External ID of the file. Slugified. | > | job\_family\_name | Job Family | Job Family | Job Family Name | Required | | 255 | | > | job\_family\_summary | Job Family | Job Family | Job Family Summary | Recommended | | No limit | Job Family description, used for skill inference. | > | active | Job Family | Job Family | Active | Recommended | | n/a | Job Family assumed to be active if no value is given. | > | job\_family\_group\_id | Job Family | Job Family Groups for Job Family | Reference ID | Recommended | | 100 | Slugified. A Job Family can belong to several groups in Workday, but to one in TechWolf. | > | job\_family\_group\_name | Job Family | Job Family Groups for Job Family | Job Family or Group | Recommended | | 255 | | > | job\_family\_group\_summary | Job Family | Job Family Groups for Job Family | Job Family Summary | Recommended | | No limit | | > **Job Information (Job Profiles)** > > The baseline Job file. **Required.** Contains the Job Profiles that TechWolf > infers skills for. > > File on S3: > `.../file_based/TechWolf_Job_Information/TechWolf_Job_Information_[yyyy][MM][dd]_[HH][mm][ss].csv` > > | TechWolf field | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | job\_id | Job Profile | Job Profile | Reference ID | Required | Primary key | 100 | External ID of the file. Slugified. | > | job\_name | Job Profile | Job Profile | Job Profile Name | Required | | 255 | | > | job\_description | Job Profile | Job Profile | Job Profile Summary | Recommended | | No limit | Used for skill inference. Joined with Job Description into one value. | > | job\_description | Job Profile | Job Profile | Job Description | Recommended | | No limit | | > | active | Job Profile | Job Profile | Active | Recommended | | n/a | Job assumed to be active if no value is given. | > | job\_family\_id | Job Profile | Job Families on Job Profile | Reference ID | Recommended | Foreign key | 100 | Points to job\_family\_id in Job Families. A Job can be in several families in Workday, but in one in TechWolf. | > **Job Vacancies (Job Requisitions)** > > Open Vacancies linked to Jobs. **Highly recommended.** Vacancy text is a strong > signal for skill inference. > > File on S3: > `.../file_based/TechWolf_Job_Requisition/TechWolf_Job_Requisition_[yyyy][MM][dd]_[HH][mm][ss].csv` > > | TechWolf field | Primary Business Object | Business Object | Workday field | Required | Key | Max chars | Notes | > | - | - | - | - | - | - | - | - | > | requisition\_id | Job Requisition | Job Requisition | Reference ID | Required | Primary key | 100 | External ID of the file. Slugified. | > | job\_id | Job Requisition | Job Profile | Reference ID | Recommended | Foreign key | 100 | Job linked to the Vacancy, used for skill inference. Points to job\_id in Job Information. | > | job\_title | Job Requisition | Job Requisition | Job Posting Title | Required | | 255 | | > | job\_description | Job Requisition | Job Requisition | Job Description | Required\* | | No limit | The three Workday fields are joined into one value. | > | job\_description | Job Requisition | Job Requisition | Job Description Summary | Required\* | | No limit | | > | job\_description | Job Requisition | Job Requisition | Additional Job Description | Required\* | | No limit | | > | active | Job Requisition | Job Requisition | Job Requisition Status | Recommended | | n/a | Vacancy assumed to be active if no value is given. | # Overview Source: https://developers.techwolf.ai/integrations/datasource-integrations/workday-datasource/overview This page introduces the standard file-based datasource integration with Workday, in which Workday exports files through the Enterprise Interface Builder (EIB) for TechWolf to infer skills from. > **[Jobs](./jobs)** > > Job Families, Jobs and Vacancies. > **[Employees](./employees)** > > The Employee baseline and every Employee file. > **[Courses](./courses)** > > The Course catalogue. ## Integration Overview Workday is a cloud-based enterprise software platform that delivers human capital management (HCM), financial management, and analytics capabilities. Its HCM module is designed to streamline and unify core HR functions such as talent management, payroll, benefits, and workforce planning, providing real-time insights and automating many HR processes. As such, an enterprise's Workday HCM environment usually contains much if not all of the HR-related data of that customer enterprise. To export this data for uses external to Workday itself, Workday provides (among other solutions) the Enterprise Interface Builder (EIB), which can generate files of an arbitrary form, in one of many formats, containing only the data specified by the user, of only the objects specified by the user, in a user-specified format, on a configurable schedule. Since much of the data held in Workday HCM can be relevant for skill inference, we have therefore developed a standard file-based integration that can take in these EIB files and load their contents into the SkillEngine API. From this data, we can then infer the skills of or needed for the related Employees, Jobs, and more. These skills are then available in the TechWolf SkillEngine API, but can i.a. also be pushed back into Workday using the [Workday Skill Syncs](/integrations/workday-skill-sync-integration/). For the broader picture of how file-based integrations work and how they compare to API-based connectors, see [Key concepts](/integrations/datasource-integrations/datasources-key-concepts). # How It Works Source: https://developers.techwolf.ai/integrations/degreed-skill-sync-integration/how-it-works ## Data Flow * Employee Skills are synchronized based on the configured sync direction and trigger mechanisms. TechWolf → Degreed updates are synchronized in real-time using a push strategy. * Degreed → TechWolf updates are synced based on tenant configuration and system triggers. This means that all flows are initiated by TechWolf. Employee skills synced by the Degreed Integration are tracked using the `source` field in the [Employee Skill Profile Feedback endpoint ](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile) payload, tagged as `"degreed-integration"`. To retrieve these sources in an Employee's profile, use the query parameter `?include=sources` in the [Employee Skill Profile Feedback endpoint ](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile), which returns the Skill's `source_event` with `"event_type": "skill_profile_feedback"` and `"source": "degreed-integration"`. In summary: TechWolf will access Degreed's REST API v2 to retrieve and update skill data. TechWolf also synchronizes skill data from external sources and skills from external systems performing skill harmonization. ## Sync Direction Configuration The integration supports three sync direction options: ### Bidirectional Sync (Default) * **Direction**: `bidirectional` * **Behavior**: Two-way sync between TechWolf and Degreed ### Uni-directional Sync Options #### Degreed → TechWolf Only * **Direction**: `to_techwolf` * **Behavior**: Skills flow from Degreed to TechWolf only #### TechWolf → Degreed Only * **Direction**: `to_external` * **Behavior**: Skills flow from TechWolf to Degreed only ## Initial Load The initial load occurs after the Degreed API key credentials are shared and set up in TechWolf. The TechWolf team ensures the initial batch of data is loaded into both systems, starting a process on TechWolf's side. During the initial data load, customers can choose between three synchronization strategies: 1. **Merge Systems** (`merge_systems`): Combines skills from both Degreed and TechWolf systems. Skills present in Degreed but not in TechWolf will be synced to TechWolf, and vice versa. This preserves existing skill data in both systems. TechWolf takes precedence over Degreed in case of conflicting values. 2. **Push TechWolf** (`push_techwolf`): Replaces all skills in Degreed with the skill data from TechWolf. This strategy clears existing Degreed skills before importing TechWolf data. 3. **Push External** (`push_external`): Replaces all skills in TechWolf with the skill data from Degreed. This strategy clears existing TechWolf skills before importing Degreed data. These synchronization strategies are automatically applied to any new Employees that exist in both Degreed and TechWolf systems. ## Skill Validation in Degreed When an employee provides feedback in Degreed, for example, adds "Machine Learning" and removes "Data Analysis", the changes are reflected in TechWolf accordingly. The changes are synchronized based on the configured sync direction and trigger mechanisms. ## Proficiency Scale Configuration Degreed supports configurable proficiency scales: * **Default**: 8-point scale (1-8) * **Configurable**: N-point scale (1-N), where N is an integer corresponding to the customer's Degreed setup * **Configuration**: Set via `degreed_maximum_proficiency_level` tenant setting You can find out on what scale your Degreed environment is operating by doing the following steps: 1. Navigate to your own profile on Degreed; 2. Go to one of your skills and click on its proficiency level; 3. Click on e.g. self-rating, add rating; 4. Click on the change rating dropdown menu and scroll down; 5. The highest available proficiency level will now be visible. ## User Identifier Configuration The integration supports two user identifier types: * **Employee ID** (`employee-id`): Customer-defined identifier (default) * Uses the `employee_id` field from API responses * Customer-defined identifier that matches between systems * **User ID** (`user-id`): Degreed-generated identifier * Uses the `user_id` field from API responses * Degreed's internal user identifier This configuration determines how employees are matched between TechWolf and Degreed systems. # Installation Source: https://developers.techwolf.ai/integrations/degreed-skill-sync-integration/installation-employees ## System Requirements The TechWolf Skill Sync integration will make use of existing Degreed functionality. The customer will need a TechWolf contract with a live TechWolf tenant. This TechWolf tenant must be populated with (a subset of) the worker's entities in Degreed. ## Degreed Configuration A Degreed API key must be configured in the Degreed tenant with the appropriate scopes for skill synchronization. The integration follows the steps outlined in the [Degreed Getting Started with the API](https://developer.degreed.com/docs/getting-started-with-the-api) and [Authentication Guide](https://developer.degreed.com/docs/authentication) documentation. ## API URL Configuration The API base URL depends on your environment (betatest or production) and data center (US, EU, or CA): | Data Center | Environment | API Base URL | | - | - | - | | US | Betatest | `https://api.betatest.degreed.com/` | | US | Production | `https://api.degreed.com/` | | EU | Betatest | `https://api.eu.betatest.degreed.com/` | | EU | Production | `https://api.eu.degreed.com/` | | CA | Production | `https://api.ca.degreed.com/` | ## Token Endpoint Configuration The OAuth token endpoint URL depends on your environment and data center: ### degreed.com Domain | Data Center | Environment | Token URL | | - | - | - | | US | Betatest | `https://betatest.degreed.com/oauth/token` | | US | Production | `https://degreed.com/oauth/token` | | EU | Betatest | `https://eu.betatest.degreed.com/oauth/token` | | EU | Production | `https://eu.degreed.com/oauth/token` | | CA | Betatest | `https://ca.betatest.degreed.com/oauth/token` | | CA | Production | `https://ca.degreed.com/oauth/token` | ### degreed.app Domain | Data Center | Environment | Token URL | | - | - | - | | US | Betatest | `https://.beta.degreed.app/oauth/token` | | US | Production | `https://.degreed.app/oauth/token` | | EU | Betatest | `https://.eu.beta.degreed.app/oauth/token` | | EU | Production | `https://.eu.degreed.app/oauth/token` | | CA | Betatest | `https://.ca.beta.degreed.app/oauth/token` | | CA | Production | `https://.ca.degreed.app/oauth/token` | > [!WARNING] > > The access token base URL is not the same as the API base URL used to submit > requests. ## API Key Setup Follow these steps to create an API key for the TechWolf Skills integration. These steps follow the process outlined in the [Degreed Getting Started with the API](https://developer.degreed.com/docs/getting-started-with-the-api) documentation. > [!NOTE] > > You must be a Technical Admin with the "Manage API Keys" permission to > create API keys in Degreed. If you don't have this permission, contact your > Degreed Technical Solutions Specialist. ### 1. Log in to Degreed Access your Degreed tenant using your administrator credentials. ### 2. Access Admin View In the left sidebar menu at the bottom, press "Show admin view" to access administrative functions. ![Show Admin View](https://mintcdn.com/techwolf/w68oYDhSey0cgE3F/integrations/degreed-skill-sync-integration/images/degreed-home.png?fit=max\&auto=format\&n=w68oYDhSey0cgE3F\&q=85\&s=4a234292514ec1f6c023c3e6f2e06e94) ### 3. Navigate to API Keys In the integrations menu item, go to "API keys" to access the API key management interface. ![Integrations API Keys](https://mintcdn.com/techwolf/w68oYDhSey0cgE3F/integrations/degreed-skill-sync-integration/images/degreed-integrations-api-keys.png?fit=max\&auto=format\&n=w68oYDhSey0cgE3F\&q=85\&s=3142456aacd03f77e8e0769cc4b40e80) ### 4. Create New API Key Press "Create new" to start the API key creation process. ![Create New API Key](https://mintcdn.com/techwolf/w68oYDhSey0cgE3F/integrations/degreed-skill-sync-integration/images/degreed-api-keys.png?fit=max\&auto=format\&n=w68oYDhSey0cgE3F\&q=85\&s=4216ca71a8e60d1a57455016d0cdf9a9) ### 5. Configure API Key Give your API key a memorable name and select the scopes required for this integration to work: * `user_skills:read` * `user_skills:write` * `skill_ratings:read` * `skill_ratings:write` ![API Key Configuration 1](https://mintcdn.com/techwolf/w68oYDhSey0cgE3F/integrations/degreed-skill-sync-integration/images/degreed-new-api-key-1.png?fit=max\&auto=format\&n=w68oYDhSey0cgE3F\&q=85\&s=f0319cd5e48f16dbfe208fe0c7b8de5f) ![API Key Configuration 2](https://mintcdn.com/techwolf/w68oYDhSey0cgE3F/integrations/degreed-skill-sync-integration/images/degreed-new-api-key-2.png?fit=max\&auto=format\&n=w68oYDhSey0cgE3F\&q=85\&s=2ffcd5646db046f427f90e84f659be11) > [!WARNING] > > When creating API keys, use minimal viable scopes. These scopes indicate the > endpoints accessible to access tokens created with the API key. As a general > data security principle, Degreed recommends using a minimal number of scopes > to enable your integration work to succeed. ### 6. Secure Credentials Note down the client secret securely - you will only be able to see this once. Also note down the client ID for future reference. ![API Key Credentials](https://mintcdn.com/techwolf/w68oYDhSey0cgE3F/integrations/degreed-skill-sync-integration/images/degreed-api-key-details.png?fit=max\&auto=format\&n=w68oYDhSey0cgE3F\&q=85\&s=537f2e920e64ccd10fb01e75adce75c5) > [!WARNING] > > The client secret is only displayed once during API key creation. Make sure > to store it securely as it cannot be retrieved later. If lost, you will need > to create a new API key. ## TechWolf Configuration The TechWolf tenant will be configured by TechWolf itself. 1. In the integration service on the TechWolf side, TechWolf adds the credentials of the customer-created API key. For this, the customer will need to share the following values with TechWolf: * The API base URL (see the API URL Configuration section) * The OAuth token endpoint URL (see the Token Endpoint Configuration section) * The client ID and client secret of the API key (see Step 6 of the API Key Setup section) * A test Employee ID for validation testing 2. TechWolf adds TechWolf API credentials with correct scopes to have access to the TechWolf API and links that TechWolf tenant to the Degreed tenant. 3. TechWolf validates API access by adding and removing a skill and proficiency for the test Employee. 4. TechWolf runs an initial sync of user profiles with the TechWolf API and sets up the tenant configuration to start the sync process. ## Routing Through an API Gateway If your organisation fronts the Degreed APIs with an API gateway, the integration can call the gateway instead of the vendor host directly. Two settings are available, both configured by TechWolf together with the credentials: * **Custom URL**: instead of the vendor API URL, share the gateway URL that proxies it. The integration keeps appending the same vendor API paths to it, so the gateway must forward requests to Degreed unchanged. * **Custom headers**: any number of extra HTTP headers (for example an API key or a correlation ID required by the gateway) that are sent on every request the integration makes. > [!NOTE] > > Both settings are pass-through only. TechWolf sends the values as configured > and does not perform any gateway-specific authentication, signing, or token > refresh; the gateway is expected to forward the integration's own > credentials to Degreed. Reserved headers (e.g. `Authorization`, > `Content-Type`) are managed by the integration and cannot be set as custom > headers. ## Configuration Options ### Sync Direction Settings The integration supports three sync direction options: * **Bidirectional** (`bidirectional`): Two-way sync between TechWolf and Degreed (default) * **To TechWolf** (`to_techwolf`): Skills flow from Degreed to TechWolf only * **To External** (`to_external`): Skills flow from TechWolf to Degreed only ### Merge Strategy Options * **Merge Systems** (`merge_systems`): Combines skills from both systems, TechWolf takes precedence * **Push TechWolf** (`push_techwolf`): Replaces all Degreed skills with TechWolf data * **Push External** (`push_external`): Replaces all TechWolf skills with Degreed data ### Proficiency Scale Configuration * **Configurable**: N-point scale (1-N), where N is an integer corresponding to the customer's Degreed setup * **Setting**: `degreed_maximum_proficiency_level` tenant configuration * **Note**: Scales always start at 1, not at 0 ### User Identifier Types * **Employee ID** (`employee-id`): Customer-defined identifier (default) * Uses the `employee_id` field from API responses * Customer-defined identifier that matches between systems * **User ID** (`user-id`): Degreed-generated identifier * Uses the `user_id` field from API responses * Degreed's internal user identifier ## Deployment Tasks & Responsibilities 1. **TechWolf**: Setup Skill Sync environment and tenant requirements 2. **Customer**: Create API key based on workflow described above. 3. **Customer**: Share API key credentials with TechWolf: * Client ID * Client Secret * Token URL (OAuth endpoint) * API URL (API base URL) * Test Employee ID (for validation testing) 4. **TechWolf**: Validate API access by adding and removing a skill and proficiency for the test Employee 5. **TechWolf**: Run initial sync of user profiles with TechWolf API. 6. **TechWolf**: Setup tenant configuration and start sync process based on configured direction. 7. **Customer**: Check end-user test scenarios. # Overview Source: https://developers.techwolf.ai/integrations/degreed-skill-sync-integration/overview-employees # Employee Skill Sync Integration with Degreed This Deployment Guide provides instructions that will assist in the process of deploying the Degreed - TechWolf Employee Skill Sync Integration, including detail on the configuration and deployment of the integration in the customer's Degreed tenant. The intended audience for this document is the Integration Implementer. ## Integration The Integration has been designed, developed, tested, documented, and deployed by TechWolf with Degreed's guidance and oversight. The integration facilitates the flow of validated employee skill data between Degreed and TechWolf. It is not intended to address every use case a customer may be interested in. The customer benefits by receiving pre-built, pre-tested, documented, partner-maintained integrations that minimize implementer's effort as compared to custom integrations for the specific use case(s) addressed. ## Functional Objective TechWolf and Degreed are partnering to enhance skill management within organizations. TechWolf leverages data from various sources, including business systems, to infer Skills. These inferred Skills are seamlessly integrated into Degreed Skill Profiles, providing a comprehensive and real-time view of Employees' Skills. The integration also enables profile synchronization between TechWolf and Degreed, ensuring that both platforms' updates are consistently reflected. This can be further facilitated with the use of the [TechWolf Skill Assistant ](/integrations/skill-assistant/overview), where employees can either be notified of or validate newly suggested skills. This integration does not depend on the Skill Assistant; any other skill validation approach can be used. The integration is agnostic to the skill validation. **Key benefits:** * TechWolf synchronizes Employee Skill Profiles across all relevant systems, harmonizing Skills across all systems * The accurate and up-to-date skill data in Degreed can be used for downstream purposes in the system, e.g. Learning Paths and Skill Development * As TechWolf does not rely on manual assessments, we increase Employee adoption to your learning platform with automated skill profiles ## Reference Material Reference materials and documentation can be found at: * TechWolf developer documentation: [https://developers.techwolf.ai/ ](https://developers.techwolf.ai/) * TechWolf Skill Sync source IP addresses: [IP Addresses ](/integrations/reference/ip-addresses) * Degreed API documentation: [https://developer.degreed.com/ ](https://developer.degreed.com/) * Used Degreed Web Service operations: * `GET /api/v2/users/:user-id/user-skills` ([Degreed API ](https://developer.degreed.com/reference/get_api-v2-users-id-user-skills)) * `POST /api/v2/user-skills` ([Degreed API ](https://developer.degreed.com/reference/post_api-v2-user-skills)) * `DELETE /api/v2/user-skills/:user-skill-id` ([Degreed API ](https://developer.degreed.com/reference/delete_api-v2-user-skills-userskillid)) * `GET /api/v2/users/:user-id/skill-ratings` ([Degreed API ](https://developer.degreed.com/reference/get_api-v2-users-id-skill-ratings)) * `POST /api/v2/skill-ratings` ([Degreed API ](https://developer.degreed.com/reference/post_api-v2-skill-ratings)) * `DELETE /api/v2/skill-ratings/:user-skill-rating-id` ([Degreed API ](https://developer.degreed.com/reference/delete_api-v2-skill-ratings-userskillratingid)) ## Glossary of Terms * **API Key**: A unique identifier used to authenticate API requests to Degreed. Contains both a client ID and client secret for secure access. * **Scopes**: Specific permissions that define what data and operations the API key can access. Required scopes for this integration are limited to: * `user_skills:read` - Read access to user skill data * `user_skills:write` - Write access to user skill data * `skill_ratings:read` - Read access to skill rating data * `skill_ratings:write` - Write access to skill rating data * **Client ID**: A public identifier for the API key that can be safely shared. * **Client Secret**: A private credential that must be kept secure and is only shown once during API key creation. * **Skills Library**: Degreed's centralized repository of skills available across the platform. * **User Skills**: Individual skill assignments to users in Degreed. * **Skill Ratings**: Proficiency levels assigned to user skills (1-N scale, where N is an integer corresponding to the customer's Degreed setup). * **Proficiency Scale**: Numerical range representing skill competency levels. * **Bidirectional Sync**: Two-way synchronization between systems. * **Uni-directional Sync**: One-way synchronization from source to target system. # File-based output integrations Source: https://developers.techwolf.ai/integrations/file-based-output/overview We provide a host of [standard exports in our API](/reference/latest/Export/ExportEmployeesSkillClusters/overview) to return useful information in bulk. These API exports have the following properties: * The data contained in the API export is a reflection of the data at the time of the request (i.e., live data). * The output will always be given in the default JSON format of the API. * Most exports use pagination, returning the data piece by piece instead of in bulk. * Especially when working with large amounts of data, the export API requests can often take some time to complete. As an alternative to these API exports, we provide a similar host of file-based exports. These standard file-based output exports are triggered according to a configurable schedule (e.g. daily), transform the data to a desired format (e.g. CSV) and are uploaded to a desired, easily accessible location (e.g. S3). As such, these export integrations have the following advantages: * No time-consuming live generation required: the last export is always readily available on the desired location (i.e. S3, SFTP server). * No need to handle data tranformation. * No need to handle pagination. > [!NOTE] > > We prefer CSV files in a specific format. See [our formatting > reference](/integrations/reference/file-guidelines#csv) for more info. ## Prerequisites To have access to the file-based output integrations, regardless of type, at least the following prerequisites must be met: * You have the appropriate TechWolf API licenses. * You have the appropriate SkillEngine API credentials, which include: * Tenant ID * Tenant secret * Tenant name * Region (Europe or United States) * You have a TechWolf API tenant set up that contains the relevant information for the requested output integration. * Both you and TechWolf have access to the agreed output location. ## Supported output formats Currently supported output formats for all exports are * CSV * XLSX * Parquet > [!NOTE] > > The XLSX format supports a maximum of **1,048,576 rows per worksheet**, including the header row. > > When the export exceeds this limit: > > * The data is split across multiple worksheets in the same XLSX file. > * Each worksheet includes the header row, followed by up to 1,048,575 data rows. > * This ensures large datasets are fully exported across multiple sheets in the same XLSX file, without data loss. ## Supported export types See [Standard exports](/integrations/file-based-output/standard-exports) and [Visier exports](/integrations/file-based-output/visier-exports) for more information. ## Supported output locations ### AWS Simple Storage Service (S3) We support the use of [Amazon S3 buckets](https://aws.amazon.com/s3/) as the location the above-mentioned output integrations can be shared. These buckets are owned and managed by TechWolf, but will be made accessible to you to fetch the export files. Export output files will be located on your bucket, named `techwolf-`, under the `//output/exports` directory (this directory can slightly alter in some cases). The names of the files can be configured per file type. It is possible to include the date at which they were created in one of the supported date formats. For compatibility reasons, names cannot contain semicolons (':') or periods ('.'). #### Replication support To easily integrate with our customers who use AWS, we support replication of the export files to your own AWS S3 bucket. This way, you can fetch the export files from your own bucket, with replication being handled securily by AWS. To set up replication, you will need to provide the following details: * The destination bucket name * The region of the destination bucket * The AWS account ID where the bucket lives We will create an IAM role with the necessary permissions to access the source bucket and replicate the files to your own bucket. We will provide you with the ARN of this IAM role, which you can then allow access to in your own AWS account. ### TechWolf SFTP server We support the use of the [TechWolf SFTP server](/integrations/reference/sftp/sftp) as the location the above-mentioned output integrations can be shared. These buckets are owned and managed by TechWolf, but will be made accessible to you to fetch the export files. See [TechWolf SFTP server](/integrations/reference/sftp/sftp) for more information. ### Private SFTP server We also support the use of a private SFTP server to share the above-mentioned output integrations. You are free to set up and manage an SFTP server on your end, and you may specify the destinition folder where the integration files should be stored. To establish the connection with your SFTP server, please provide the following details: * **Host** (servername or IP address) * **Username** for authentication * **Destination folder** for placing the files We support two authentication methods: * **Password authentication**: You provide the password associated with the specified username. * **Key-based authentication**: We will generate and store a private SSH key securely within our system and provide you with the corresponding public SSH key. You will need to install this public key on your SFTP server (e.g., in the authorized\_keys file) to enable access. ## Encryption The exports can be PGP (Pretty Good Privacy) encrypted. To enable this, provide your TechWolf representative with the public key and passphrase. ## Standard export relation diagram The full entity-relationship diagram across every standard export is too wide to render usefully inline. Open it in a new tab to pan and zoom freely. For field-level detail per export, see [Standard exports](/integrations/file-based-output/standard-exports). > **[Open the standard exports ERD](./images/standard-exports-erd.png)** > > Full entity-relationship diagram, opens in a new tab. Scroll to pan, use > Cmd/Ctrl + scroll (or browser zoom) to zoom. # Standard exports Source: https://developers.techwolf.ai/integrations/file-based-output/standard-exports Below we list the available export types. Some export types are configurable and can be configured in the TechWolf's Console via the export builder or by your TechWolf representative. If no configuration options are specified, this export type is not configurable. When no configuration is specified by the user, the default settings are used. Every export configuration also sets the file name. Put `{{date}}` in the file name to include the generation timestamp, written in the date format you pick: `YYYY-MM-DD`, `YYYYMMDD`, `DD-MM-YYYY`, `YYYY-MM-DD_HH-mm-ss`, `YYYY-MM-DDTHH:mm:ss`, `YYYYMMDDHHmmss`, `DDMMYYYYHHmmss` or `unix` (epoch seconds). For example, `job_skills_{{date}}` with `YYYY-MM-DD` produces `job_skills_2026-09-24.csv`. ### Employee Info Provides an overview of all Employees and their fields, including their current position, organisational unit, and data availability status. > **View Employee Info export details** > > The Employee info export provides an overview of all Employees and their fields. > > Each export file represents a two-dimensional matrix, containing one row for > every Employee. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | external\_id | The external ID of the Employee in TechWolf. | > | low\_data\_availability | Flag indicating whether sufficient data is available for qualitative Skill inference for the given Employee. | > | active | Flag indicating whether the Employee will be used in matching. This is useful if an Employee is being phased out. | > | last\_updated | Timestamp of the last update to this entity. | > | assigned\_position | The title of the Job the Employee is currently assigned to. | > | assigned\_position\_id | The external ID of the Job the Employee is currently assigned to. | > | organisational\_unit\_X | The Organisational Unit of the Employee. Column organisational\_unit\_0 is the top-level Organisational Unit, column organisational\_unit\_1 the second-level etc. | > > Currently supported configurations are: > > * Mask `external_id`: mask the Employee's external ID to protect privacy. > * Include > [Custom Properties](https://developers.techwolf.ai/reference/latest/Custom%20Properties/CustomPropertiesDefinitions/overview): > the selected Custom properties will be added as a column to every row. If the > Employee does not have this Custom Property, the field will be empty. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_META_DATA["Your Employee Metadata"] { string employee_id FK any meta_data } EMPLOYEE_INFO { string external_id PK boolean low_data_availability boolean active datetime last_updated string assigned_position string assigned_position_id string organisational_unit_X } EMPLOYEE_SKILL_PROFILE { string employee_id FK string skill_id FK } EMPLOYEE_SKILL_GAP { string employee_id FK string job_id FK } EMPLOYEE_SKILL_GAP_EXPLAINED { string employee_id FK string job_id FK } INTERNAL_MOBILITY { string employee_id FK string job_id FK } INTERNAL_MOBILITY_EXPLAINED { string employee_id FK string job_id FK } EMPLOYEE_META_DATA |o--o| EMPLOYEE_INFO : "" EMPLOYEE_INFO ||--o{ EMPLOYEE_SKILL_PROFILE : "" EMPLOYEE_INFO ||--o{ EMPLOYEE_SKILL_GAP : "" EMPLOYEE_INFO ||--o{ EMPLOYEE_SKILL_GAP_EXPLAINED : "" EMPLOYEE_INFO ||--o{ INTERNAL_MOBILITY : "" EMPLOYEE_INFO ||--o{ INTERNAL_MOBILITY_EXPLAINED : "" ``` ### Job Info Provides an overview of all Jobs and their fields, including Job Family information, data availability status, and active status. > **View Job Info export details** > > The Job info export provides an overview of all Jobs and their fields. > > Each export file represents a two-dimensional matrix, containing one row for every Job. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | external\_id | The external ID of the Job in TechWolf. | > | job\_name | The name of the Job in TechWolf. | > | job\_family | The Job Family to which this Job belongs. | > | job\_family\_group | The Job Family group to which this Job belongs | > | job\_description | The description of the Job. Only included when `include_job_description` is enabled. | > | low\_data\_availability | Flag indicating whether sufficient data is available for qualitative Skill inference for the given Job. | > | active | Flag indicating whether the Job will be used in matching. This is useful when a Job is being phased out. | > | last\_updated | Timestamp of the last update to this entity. | > > Currently supported configurations are: > > * `include_job_description`: when enabled, adds a `job_description` column to every row containing the description of the Job. Defaults to `false`. > * Include [Custom Properties](https://developers.techwolf.ai/reference/latest/Custom%20Properties/CustomPropertiesDefinitions/overview): the selected Custom properties will be added as a column to every row. If the Job does not have this Custom Property, the field will be empty. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_META_DATA["Your Job Metadata"] { string job_id FK any meta_data } JOB_INFO { string external_id PK string job_name string job_family string job_family_group string job_description boolean low_data_availability boolean active datetime last_updated } JOB_SKILL_PROFILE { string job_id FK string skill_id FK } EMPLOYEE_SKILL_GAP { string job_id FK string employee_id FK } EMPLOYEE_SKILL_GAP_EXPLAINED { string job_id FK string employee_id FK } INTERNAL_MOBILITY { string job_id FK string employee_id FK } INTERNAL_MOBILITY_EXPLAINED { string job_id FK string employee_id FK } MARKET_SKILL_PROFILE { string job_id FK string peer_group FK } MARKET_COMPARISON { string job_id FK string peer_group FK } MARKET_COMPARISON_EXPLAINED { string job_id FK string peer_group FK } JOB_META_DATA |o--o| JOB_INFO : "" JOB_INFO ||--o{ JOB_SKILL_PROFILE : "" JOB_INFO ||--o{ EMPLOYEE_SKILL_GAP : "" JOB_INFO ||--o{ EMPLOYEE_SKILL_GAP_EXPLAINED : "" JOB_INFO ||--o{ INTERNAL_MOBILITY : "" JOB_INFO ||--o{ INTERNAL_MOBILITY_EXPLAINED : "" JOB_INFO ||--o{ MARKET_SKILL_PROFILE : "" JOB_INFO ||--o{ MARKET_COMPARISON : "" JOB_INFO ||--o{ MARKET_COMPARISON_EXPLAINED : "" ``` ### Course Info Provides an overview of all available Courses, including their titles and source systems. > **View Course Info export details** > > The Course info export provides an overview of all the available Courses. > > Each export file contains one row for every Course. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | course\_id | The external ID of the Course in TechWolf. | > | course\_title | The title of the Course in TechWolf. | > | course\_description | The description of the Course. Only included when `include_course_description` is enabled. | > | source | The LMS from which the Course originates. | > | active | Flag indicating whether the Course will be used in matching. Only included when `include_active` is enabled. | > > Currently supported configurations are: > > * `include_course_description`: when enabled, adds a `course_description` column to every row containing the description of the Course. Defaults to `false`. > * `include_active`: when enabled, adds an `active` column to every row, flagging whether the Course will be used in matching. Defaults to `false`. **Entity Relationships:** ```mermaid theme={null} erDiagram COURSE_META_DATA["Your Course Metadata"] { string course_id FK any meta_data } COURSE_INFO { string course_id PK string course_title string source } COURSE_SKILL_PROFILE { string course_id FK string skill_id FK } COURSE_META_DATA |o--o| COURSE_INFO : "" COURSE_INFO ||--o{ COURSE_SKILL_PROFILE : "" ``` ### Vacancy Info Provides an overview of all available Vacancies, including their job titles and optionally job descriptions. > **View Vacancy Info export details** > > The Vacancy info export provides an overview of all the available Vacancies. > > Each export file contains one row for every Vacancy. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | vacancy\_id | The external ID of the Vacancy in TechWolf. | > | job\_title | The job title of the Vacancy. | > | job\_description | The job description of the Vacancy. Only included when `include_job_description` is enabled. | > | active | Flag indicating whether the Vacancy will be used in matching. Only included when `include_active` is enabled. | > > Currently supported configurations are: > > * `include_job_description`: when enabled, adds a `job_description` column to every row containing the description of the Vacancy. Defaults to `false`. > * `include_active`: when enabled, adds an `active` column to every row, flagging whether the Vacancy will be used in matching. Defaults to `false`. **Entity Relationships:** ```mermaid theme={null} erDiagram VACANCY_META_DATA["Your Vacancy Metadata"] { string vacancy_id FK any meta_data } VACANCY_INFO { string vacancy_id PK string job_title string job_description } VACANCY_SKILL_PROFILE { string vacancy_id FK string skill_id FK } VACANCY_META_DATA |o--o| VACANCY_INFO : "" VACANCY_INFO ||--o{ VACANCY_SKILL_PROFILE : "" ``` ### Course Skill Profiles *(Course to Skill)* Maps the relationship between Courses and their associated Skills, showing which Skills are taught in each Course. > **View Course Skill Profiles export details** > > The Course Skill Profile export provides an overview of all the Skills of > every Course. > > Each export file represents a two-dimensional matrix, containing one row for > every Skill of every Course, with Courses without Skills not being represented. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | course\_id | The external ID of the Course with the Skill in TechWolf. | > | skill\_id | The external ID of the Skill in TechWolf. | > | skill | The name of the Skill in TechWolf. | > > Currently supported configurations are: > > * `vocab_language`: the language of the Skill names in the file. Defaults to > English. **Entity Relationships:** ```mermaid theme={null} erDiagram COURSE_INFO { string course_id PK } COURSE_SKILL_PROFILE { string course_id FK string skill_id FK string skill } SKILL_INFO { string skill_id PK } COURSE_INFO ||--o{ COURSE_SKILL_PROFILE : "" COURSE_SKILL_PROFILE }o--o{ SKILL_INFO : "" ``` ### Vacancy Skill Profiles *(Vacancy to Skill)* Maps the relationship between Vacancies and their associated Skills, showing which Skills are inferred from each Vacancy's job title and description. > **View Vacancy Skill Profiles export details** > > The Vacancy Skill Profile export provides an overview of all the Skills of > every Vacancy. > > Each export file represents a two-dimensional matrix, containing one row for > every Skill of every Vacancy, with Vacancies without Skills not being represented. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | vacancy\_id | The external ID of the Vacancy with the Skill in TechWolf. | > | skill\_id | The external ID of the Skill in TechWolf. | > | skill | The name of the Skill in TechWolf. | > > Currently supported configurations are: > > * `vocab_language`: the language of the Skill names in the file. Defaults to > English. **Entity Relationships:** ```mermaid theme={null} erDiagram VACANCY_INFO { string vacancy_id PK } VACANCY_SKILL_PROFILE { string vacancy_id FK string skill_id FK string skill } SKILL_INFO { string skill_id PK } VACANCY_INFO ||--o{ VACANCY_SKILL_PROFILE : "" VACANCY_SKILL_PROFILE }o--o{ SKILL_INFO : "" ``` ### Employee Skill Profiles *(Employee to Skill)* Maps the relationship between Employees and their Skills, including validation states and sources of skill inference. > **View Employee Skill Profiles export details** > > The Employee Skill Profile export provides an overview of all the Skills of > every Employee. > > Each export file represents a two-dimensional matrix, containing one or more rows for every Skill of every Employee (every Skill has > one row for each of its sources if it has any, and one row otherwise), with > Employees without Skills not being represented. > > The matrix has eight columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee with the Skill in TechWolf. | > | skill\_id | The external ID of the Skill in TechWolf. | > | skill | The name of the Skill in TechWolf. | > | validation\_state | The validation state of the Skill; one of "validated", "suggested", "rejected". | > | skill\_source | The event type from which the Skill is inferred for this Employee (e.g. "working\_history"). | > | skill\_event\_source | The source of the Skill event from which the Skill is inferred (e.g. "Workday" or "Degreed"). | > | self\_rated\_proficiency\_level | The proficiency level that the Employee indicates they have for this Skill. | > | suggested\_proficiency\_level | The proficiency level of the Employee for the Skill suggested by TechWolf. | > > The columns are fixed: no configuration option adds or removes one. > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Include rejected Skills: add the Skills an Employee rejected, as rows with > `validation_state` set to `rejected`. Off by default. > * `output_skills_sorting`: sort the Skills of every Employee either > `alphabetical`ly by name, or by `confidence` (highest first). Defaults to > `alphabetical`. > * `limit_skills`: keep only the first N suggested Skills per Employee, in the > `output_skills_sorting` order. Validated Skills, and rejected Skills when > those are included, are always kept. Set to `0` to drop every suggested Skill. > Unset by default, which keeps them all. > * `vocab_language`: the language of the Skill names in the file. Defaults to > English. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } EMPLOYEE_SKILL_PROFILE { string employee_id FK string skill_id FK string skill string validation_state string skill_source string skill_event_source int suggested_proficiency_level int self_rated_proficiency_level } SKILL_INFO { string skill_id PK } EMPLOYEE_INFO ||--o{ EMPLOYEE_SKILL_PROFILE : "" EMPLOYEE_SKILL_PROFILE }o--o{ SKILL_INFO : "" ``` ### Job Skill Profiles *(Job to Skill)* Maps the relationship between Jobs and their required Skills, including skill types, validation states, and proficiency levels. > **View Job Skill Profiles export details** > > The Job Skill Profile export provides an overview of all the Skills of every > Job. Note that only the governed Skill Profiles are taken into account, not the > suggested Skill Profiles. > > Each export file represents a two-dimensional matrix, containing one or more rows for every Skill of every Job (every Skill has one > row for each of its Skill types), with Job without Skills not being represented. > > The matrix has the following columns for every row (in order). > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the Job with the Skill in TechWolf. | > | skill\_id | The external ID of the Skill in TechWolf. | > | skill | The name of the Skill in TechWolf. | > | skill\_type | The type of the Skill; one of "Job-Specific", "Family-Specific". | > | validation\_state | The validation state of the Skill; one of "validated", "suggested". | > | validated\_proficiency\_level | The required Skill proficiency level for this Job, validated by the customer. | > | suggested\_proficiency\_level | The required Skill proficiency level for this Job, suggested by TechWolf. | > | critical | Whether the Skill is critical for the Job (`true` or `false`), as validated by the customer. | > | suggested\_critical | Whether the Skill is critical for the Job (`true` or `false`), as suggested by TechWolf. | > > Currently supported configurations are: > > * `output_skills_sorting`: sort the Skills of every Job either `alphabetical`ly by name, or by `confidence` (highest first). Defaults to `alphabetical`. > * `vocab_language`: the language of the Skill names in the file. Defaults to > English. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } JOB_SKILL_PROFILE { string job_id FK string skill_id FK string skill string skill_type string validation_state int validated_proficiency_level int suggested_proficiency_level boolean critical boolean suggested_critical } SKILL_INFO { string skill_id PK } JOB_INFO ||--o{ JOB_SKILL_PROFILE : "" JOB_SKILL_PROFILE }o--o{ SKILL_INFO : "" ``` ### Skill Info Provides comprehensive information about all Skills, including descriptions. This export covers the full Skill vocabulary, including Skills that are not placed in your Taxonomy. For Taxonomy information, the [Taxonomy Info](#taxonomy-info) export can be used. > **View Skill Info export details** > > The Skill info export provides an overview of all Skills and their description. > > Each export file represents a two-dimensional matrix, containing a row for every Skill. > > The matrix has three columns by default, containing the following fields for > every row (in order): > > | Field name | Field description | > | - | - | > | skill\_id | The external ID of the Skill. | > | skill\_name | The name of the Skill. | > | skill\_description | The description of the Skill. | > > Two optional columns can be added through configuration. They are appended after > the columns above, in the order listed here: > > | Field name | Field description | > | - | - | > | skill\_source | Whether the Skill is a custom Skill or a Skill from the default vocabulary. | > | techwolf\_domain | The default Domain provided by TechWolf; empty if the Skill has none. | > > Currently supported configurations are: > > * Set `include_skill_source`: when set to `true`, the `skill_source` column is > included in the export. When set to `false`, the column is omitted. > * Set `include_techwolf_domain`: when set to `true`, the `techwolf_domain` > column is included in the export. When set to `false`, the column is omitted. > * `vocab_language`: the language of the Skill names and descriptions in the > file. Defaults to English. **Entity Relationships:** ```mermaid theme={null} erDiagram SKILL_INFO { string skill_id PK string skill_name string skill_description string skill_source string techwolf_domain } EMPLOYEE_SKILL_PROFILE { string skill_id FK } JOB_SKILL_PROFILE { string skill_id FK } COURSE_SKILL_PROFILE { string skill_id FK } EMPLOYEE_SKILL_GAP_EXPLAINED { string skill_id FK } INTERNAL_MOBILITY_EXPLAINED { string skill_id FK } MARKET_SKILL_PROFILE { string skill_id FK } MARKET_COMPARISON_EXPLAINED { string skill_id FK } EMPLOYEE_SKILL_PROFILE }o--o{ SKILL_INFO : "" JOB_SKILL_PROFILE }o--o{ SKILL_INFO : "" COURSE_SKILL_PROFILE }o--o{ SKILL_INFO : "" EMPLOYEE_SKILL_GAP_EXPLAINED }o--o{ SKILL_INFO : "" INTERNAL_MOBILITY_EXPLAINED }o--o{ SKILL_INFO : "" MARKET_SKILL_PROFILE }o--o{ SKILL_INFO : "" MARKET_COMPARISON_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Taxonomy Info Provides the full Taxonomy structure, listing every placement of Skills across domains, subdomains, and clusters. By default this export also lists Skills that are not part of your Taxonomy, with empty `taxonomy_*` fields; set `only_taxonomy_skills` to limit it to Skills that are placed in the Taxonomy. To get an overview of all Skills, the [Skill Info](#skill-info) export can be used. > **View Taxonomy Info export details** > > The Taxonomy info export provides the full Taxonomy structure. > > Each export file represents a two-dimensional matrix, containing one row for every Skill-Taxonomy assignment. > > The matrix has eleven columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | skill\_id | The external ID of the Skill. | > | skill\_name | The name of the Skill. | > | skill\_description | The description of the Skill. | > | techwolf\_domain | The default Domain provided by TechWolf. | > | taxonomy\_domain\_id | The external ID of the top-level Domain the Skill belongs to; empty for Skills that are not part of the Taxonomy. | > | taxonomy\_domain\_name | The name of the top-level Domain the Skill belongs to; empty for Skills that are not part of the Taxonomy. | > | taxonomy\_subdomain\_id | The external ID of the Subdomain the Skill belongs to; empty for Skills that are not part of the Taxonomy; only relevant for four-level Taxonomies, always empty for three-level Taxonomies. | > | taxonomy\_subdomain\_name | The name of the Subdomain the Skill belongs to; empty for Skills that are not part of the Taxonomy; only relevant for four-level Taxonomies, always empty for three-level Taxonomies. | > | taxonomy\_skill\_cluster\_id | The external ID of the Cluster the Skill belongs to; empty for Skills that are not part of the Taxonomy. | > | taxonomy\_skill\_cluster\_name | The name of the Cluster the Skill belongs to; empty for Skills that are not part of the Taxonomy | > | business\_relevant | Whether the Skill is marked as business relevant. | > > Currently supported configurations are: > > * Set `include_business_relevant`: when set to `true`, the `business_relevant` > column is included in the export. When set to `false`, the column is omitted. > * Set `only_taxonomy_skills`: when set to `true`, the export is limited to > Skills that are placed in your Taxonomy, and Skills without a Cluster are > omitted. When set to `false`, every Skill in the vocabulary is included, with > empty `taxonomy_*` fields for the Skills that are not part of the Taxonomy. > * `vocab_language`: the language of the Skill names and descriptions in the > file. Defaults to English. **Entity Relationships:** ```mermaid theme={null} erDiagram TAXONOMY_INFO { string skill_id PK string taxonomy_domain_id PK string taxonomy_subdomain_id PK string taxonomy_skill_cluster_id PK string skill_name string skill_description string techwolf_domain string taxonomy_skill_cluster_name string taxonomy_subdomain_name string taxonomy_domain_name boolean business_relevant } EMPLOYEE_SKILL_PROFILE { string skill_id FK } JOB_SKILL_PROFILE { string skill_id FK } COURSE_SKILL_PROFILE { string skill_id FK } EMPLOYEE_SKILL_GAP_EXPLAINED { string skill_id FK } INTERNAL_MOBILITY_EXPLAINED { string skill_id FK } MARKET_SKILL_PROFILE { string skill_id FK } MARKET_COMPARISON_EXPLAINED { string skill_id FK } EMPLOYEE_SKILL_PROFILE }o--o{ TAXONOMY_INFO : "" JOB_SKILL_PROFILE }o--o{ TAXONOMY_INFO : "" COURSE_SKILL_PROFILE }o--o{ TAXONOMY_INFO : "" EMPLOYEE_SKILL_GAP_EXPLAINED }o--o{ TAXONOMY_INFO : "" INTERNAL_MOBILITY_EXPLAINED }o--o{ TAXONOMY_INFO : "" MARKET_SKILL_PROFILE }o--o{ TAXONOMY_INFO : "" MARKET_COMPARISON_EXPLAINED }o--o{ TAXONOMY_INFO : "" ``` ### Task Info Provides an overview of all Tasks, including their name, AI impact assessment, and position in the work taxonomy. > **View Task Info export details** > > The Task info export provides an overview of all Tasks. > > Each export file represents a two-dimensional matrix, containing one row for > every Task. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | task\_id | The unique ID of the Task. | > | task | The name/description of the Task. | > | ai\_impact\_level | AI impact level expressed as a Human Agency Scale (HAS) level (H1-H5). | > | ai\_impact\_rationale | Explanation of the AI impact level for this Task. | > | hierarchy\_domain\_name | Name of the work taxonomy domain; empty if the Task is not placed in the taxonomy. | > | hierarchy\_domain\_id | Stable id of the work taxonomy domain; empty if the Task is not placed in the taxonomy. | > | hierarchy\_subdomain\_name | Name of the work taxonomy subdomain; empty if the Task is not placed in the taxonomy. | > | hierarchy\_subdomain\_id | Stable id of the work taxonomy subdomain; empty if the Task is not placed in the taxonomy. | > | hierarchy\_cluster\_name | Name of the work taxonomy cluster; empty if the Task is not placed in the taxonomy. | > | hierarchy\_cluster\_id | Stable id of the work taxonomy cluster; empty if the Task is not placed in the taxonomy. | > | hierarchy\_canonical\_task\_name | Name of the canonical task in the work taxonomy; empty if not placed in the taxonomy. | > | hierarchy\_canonical\_task\_id | Stable id of the canonical task in the work taxonomy; empty if not placed in the taxonomy. | > | task\_source | Origin of the Task: `vocabulary` (work taxonomy) or `custom` (tenant-authored). | **Entity Relationships:** ```mermaid theme={null} erDiagram TASK_INFO { string task_id PK string task string ai_impact_level string ai_impact_rationale string hierarchy_domain_name string hierarchy_domain_id string hierarchy_subdomain_name string hierarchy_subdomain_id string hierarchy_cluster_name string hierarchy_cluster_id string hierarchy_canonical_task_name string hierarchy_canonical_task_id string task_source } EMPLOYEE_TO_TASK { string task_id FK } JOB_TO_TASK { string task_id FK } EMPLOYEE_TASK_TO_SKILL { string task_id FK } JOB_TASK_TO_SKILL { string task_id FK } TASK_INFO ||--o{ EMPLOYEE_TO_TASK : "" TASK_INFO ||--o{ JOB_TO_TASK : "" TASK_INFO ||--o{ EMPLOYEE_TASK_TO_SKILL : "" TASK_INFO ||--o{ JOB_TASK_TO_SKILL : "" ``` ### Employee to Task Maps the relationship between Employees and their Tasks, including validation states. > **View Employee to Task export details** > > The Employee to Task export provides an overview of all the Tasks of every > Employee. > > Each export file represents a two-dimensional matrix, containing one row for > every Task of every Employee, with Employees without Tasks not being > represented. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | employee\_id | The unique ID of the Employee. | > | task\_id | The unique ID of the Task. | > | task | The name/description of the Task. | > | validation\_state | The validation state of the Task; one of "validated", "suggested", "rejected". | > | weekly\_hours | Estimated number of hours spent on this Task per week. | **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } EMPLOYEE_TO_TASK { string employee_id FK string task_id FK string task string validation_state int weekly_hours } TASK_INFO { string task_id PK } EMPLOYEE_INFO ||--o{ EMPLOYEE_TO_TASK : "" EMPLOYEE_TO_TASK }o--o{ TASK_INFO : "" ``` ### Employee Task to Skill Maps the relationship between Employee Tasks and their associated Skills, showing which Skills are linked to each Task for every Employee. > **View Employee Task to Skill export details** > > The Employee Task to Skill export provides an overview of the Skills linked to > every Task of every Employee. > > Each export file represents a two-dimensional matrix, containing one row for > every Skill of every Task of every Employee, with Employees or Tasks without > linked Skills not being represented. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | employee\_id | The unique ID of the Employee. | > | task\_id | The unique ID of the Task. | > | task | The name/description of the Task. | > | skill\_id | The unique ID of the Skill linked to the Task. | > | skill | The name of the Skill linked to the Task. | **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } TASK_INFO { string task_id PK } SKILL_INFO { string skill_id PK } EMPLOYEE_TASK_TO_SKILL { string employee_id FK string task_id FK string task string skill_id FK string skill } EMPLOYEE_INFO ||--o{ EMPLOYEE_TASK_TO_SKILL : "" EMPLOYEE_TASK_TO_SKILL }o--o{ TASK_INFO : "" EMPLOYEE_TASK_TO_SKILL }o--o{ SKILL_INFO : "" ``` ### Job to Task Maps the relationship between Jobs and their Tasks, including validation states. > **View Job to Task export details** > > The Job to Task export provides an overview of all the Tasks of every Job. > > Each export file represents a two-dimensional matrix, containing one row for > every Task of every Job, with Jobs without Tasks not being represented. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | job\_id | The unique ID of the Job. | > | task\_id | The unique ID of the Task. | > | task | The name/description of the Task. | > | validation\_state | The validation state of the Task; one of "validated", "suggested", "rejected". | > | weekly\_hours | Estimated number of hours spent on this Task per week. | **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } JOB_TO_TASK { string job_id FK string task_id FK string task string validation_state int weekly_hours } TASK_INFO { string task_id PK } JOB_INFO ||--o{ JOB_TO_TASK : "" JOB_TO_TASK }o--o{ TASK_INFO : "" ``` ### Job Task to Skill Maps the relationship between Job Tasks and their associated Skills, showing which Skills are linked to each Task for every Job. > **View Job Task to Skill export details** > > The Job Task to Skill export provides an overview of the Skills linked to every > Task of every Job. > > Each export file represents a two-dimensional matrix, containing one row for > every Skill of every Task of every Job, with Jobs or Tasks without linked Skills > not being represented. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | job\_id | The unique ID of the Job. | > | task\_id | The unique ID of the Task. | > | task | The name/description of the Task. | > | skill\_id | The unique ID of the Skill linked to the Task. | > | skill | The name of the Skill linked to the Task. | **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } TASK_INFO { string task_id PK } SKILL_INFO { string skill_id PK } JOB_TASK_TO_SKILL { string job_id FK string task_id FK string task string skill_id FK string skill } JOB_INFO ||--o{ JOB_TASK_TO_SKILL : "" JOB_TASK_TO_SKILL }o--o{ TASK_INFO : "" JOB_TASK_TO_SKILL }o--o{ SKILL_INFO : "" ``` ### Employee AI Goals Provides an overview of AI Goals generated for every Employee, including all historical versions. One row per AI Goal version per Employee. > **View Employee AI Goals export details** > > The Employee AI Goals export provides an overview of the AI development goals > for every Employee, written to `employee_ai_goals.csv`. > > Each export file represents a two-dimensional matrix, containing one row for > every version of every Employee's AI Goal. Each row is uniquely identified by > the `(employee_id, version)` pair. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | employee\_id | The unique ID of the Employee the AI Goal belongs to. | > | version | Monotonically increasing version of the AI Goal for this Employee. | > | goal | The AI development goal text. | > | description | Detailed description of the goal. | > | job\_id | The unique ID of the target Job, or empty if no specific Job is targeted. | > | created\_on | ISO 8601 timestamp for when this version of the goal was created. | > | last\_updated | ISO 8601 timestamp for the most recent update to this version. | > > This export type requires the **Work Intelligence** feature, and additionally > requires AI Goals to be enabled on the tenant. If Work Intelligence is enabled > but AI Goals is not, the export type is listed but generation will fail. > > Currently supported destinations are SFTP, Visier and Crunchr. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } EMPLOYEE_AI_GOALS { string employee_id PK int version PK string goal string description string job_id FK datetime created_on datetime last_updated } EMPLOYEE_INFO ||--o{ EMPLOYEE_AI_GOALS : "" EMPLOYEE_AI_GOALS }o--o| JOB_INFO : "" ``` ### Employee Skill Gap Shows the match score between Employees and their assigned positions, helping identify Skill gaps. > **View Employee Skill Gap export details** > > The Employee Skill Gap export provides an overview of the match score between Employees and their assigned position. > > Each export file represents a two-dimensional matrix, containing a row for every Employee-Job match. > > The matrix has 3 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | job\_id | The external ID of the Job that the Employee is assigned to. If the Employee has no assigned position, the field is left blank. | > | score | The match score between the Employee and the Job, expressed as a number between 0 and 1. If the Employee has no assigned position, this value is set to `0.0`. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } EMPLOYEE_SKILL_GAP { string employee_id FK string job_id FK float score } EMPLOYEE_INFO ||--o{ EMPLOYEE_SKILL_GAP : "" JOB_INFO ||--o{ EMPLOYEE_SKILL_GAP : "" ``` ### Employee Skill Gap Explained Provides detailed analysis of Skill gaps between Employees and their positions, including adjacent Skills and alignment scores. > **View Employee Skill Gap Explained export details** > > The Skill Gap Explained export provides a detailed information of the match score between Employees and their assigned positions, including adjacent Skills and how closely they align with the required Skills for their assigned position. > > Each export file represents a two-dimensional matrix, containing a row for every Skill for every Employee-Job match. > > The matrix has 6 columns (10 if matching with skill properties is enabled), > containing the following fields for every row (in order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | job\_id | The external ID of the Job that the Employee is assigned to. | > | status | The current status of the match (e.g., "present", "missing"). | > | skill\_id | The external ID of the required Skill. | > | skill\_proficiency | *(Optional)* The proficiency level required for the Skill by the Job. Only available if proficiency matching is enabled on the tenant. | > | critical | *(Optional)* Indicates whether the Skill is critical for the Job. Only available if criticality matching is enabled on the tenant. | > | adjacent\_skill\_id | The external ID of the most similar adjacent Skill that the Employee has. | > | adjacent\_skill\_proficiency | *(Optional)* The proficiency level of the adjacent Skill. Only available if proficiency matching is enabled on the tenant. | > | adjacency\_score | The adjacency score between the required Skill and the adjacent Skill, expressed as a number between 0 and 1. | > | gap\_impact | *(Optional)* The impact of the skill gap on the match score. Possible values: `none`, `low`, `medium`, `high`. Only available if proficiency matching is enabled on the tenant. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } SKILL_INFO { string skill_id PK } EMPLOYEE_SKILL_GAP_EXPLAINED { string employee_id FK string job_id FK string status string skill_id FK string adjacent_skill_id FK float adjacency_score } EMPLOYEE_INFO ||--o{ EMPLOYEE_SKILL_GAP_EXPLAINED : "" JOB_INFO ||--o{ EMPLOYEE_SKILL_GAP_EXPLAINED : "" EMPLOYEE_SKILL_GAP_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Internal Mobility Deprecated Shows potential matches between Employees and Jobs within the organisation, with match scores. > **View Internal Mobility export details** > > The internal mobility export provides an overview of potential matches between Employees and Jobs within the organisation, with their match score. > It contains both the best matching Employees for each Job and the best matching Jobs for each Employee. Only active Jobs and Employees are included in the export. > When matching Employees for a Job, Employees that have this Job assigned are excluded from the results. When matching Jobs for an Employee, the Employee's current Job is excluded from the results. > > Each export file represents a two-dimensional matrix, containing a row for every Employee-Job match. > > The matrix has 3 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | job\_id | The external ID of the Job within the organisation. | > | score | The match score between the Employee and the Job, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } INTERNAL_MOBILITY { string employee_id FK string job_id FK float score } EMPLOYEE_INFO ||--o{ INTERNAL_MOBILITY : "" JOB_INFO ||--o{ INTERNAL_MOBILITY : "" ``` ### Internal Mobility Explained Deprecated Provides detailed analysis of potential matches between Employees and Jobs, including Skill-level comparisons. > **View Internal Mobility Explained export details** > > The internal mobility explained export provides an overview of potential matches between Employees and Jobs within the organisation, including adjacent Skills and how closely they align with the required Skills for the job. > This export contains both the best matching Employees for each Job and the best matching Jobs for each Employee. Only active Jobs and Employees are included in the export. > When matching Employees for a Job, Employees that have this Job assigned are excluded from the results. When matching Jobs for an Employee, the Employee's current Job is excluded from the results. > > Each export file represents a two-dimensional matrix, containing a row for every Skill of every Employee-Job match. > > The matrix has 6 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | job\_id | The external ID of the Job within the organisation. | > | status | The current status of the Internal Mobility match (e.g., "present", "missing"). | > | skill\_id | The external ID of the required Skill. | > | adjacent\_skill\_id | The external ID of the most similar adjacent Skill that the Employee has. | > | adjacency\_score | The adjacency score between the required Skill and the adjacent Skill, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } INTERNAL_MOBILITY_EXPLAINED { string employee_id FK string job_id FK string status string skill_id FK string adjacent_skill_id FK float adjacency_score } SKILL_INFO["Skill Info"] { string skill_id PK } EMPLOYEE_INFO ||--o{ INTERNAL_MOBILITY_EXPLAINED : "" JOB_INFO ||--o{ INTERNAL_MOBILITY_EXPLAINED : "" INTERNAL_MOBILITY_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Matching Employees for Job Shows the best suited Employees for every Job within the organisation, with match scores. > **View Matching Employees for Job export details** > > The Matching Employees for Job export provides an overview of the best suited Employees for every Job within the organisation, with their match score. Only active Jobs and Employees are included in the export. > The Employees that have the Job assigned are excluded from the results. > > Each export file represents a two-dimensional matrix, containing a row for every Employee-Job match. > > The matrix has 3 columns (4 if proficiency matching is enabled), containing the > following fields for every row (in order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | job\_id | The external ID of the Job within the organisation. | > | score | The match score between the Employee and the Job, expressed as a number between 0 and 1. | > | overqualified | *(Optional)* Indicates whether the Employee is over-qualified for the Job. This is `true` when the Employee's skill level significantly exceeds the requirements. Only available if proficiency matching is enabled on the tenant. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Set the `score_min_threshold`: only include Employees with a match score above > this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching Employees are shown > for each Job. Higher numbers give you more options but significantly increases > data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#parameter-limit) > is used. > * Set > [`include_overqualified`](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#parameter-include-overqualified): > when set to `true`, includes matches where the Employee is overqualified for > the Job. Overqualified matches are those where the Employee's skill level > significantly exceeds the requirements. Default is `true`. This filter will > only work if proficiency matching is enabled on the tenant. > * Set > [`min_critical_skills_match_ratio`](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#parameter-one-of-0): > the minimum ratio of critical skills that must be matched. Only matches > meeting or exceeding this ratio will be returned. When `null`, no critical > skills ratio filtering is applied. Required range: 0 ≤ x ≤ 1. This filter will > only work if criticality matching is enabled. > * Set `exclude_low_data_available_entities`: when set to `true`, Employees with > low data availability are excluded from the matching results. > * Set `mapping_filter`: only keep rows where Employee and Job Custom Properties > match the configured mapping. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#custom-property) > filter: filter out all Employees for which the given Custom Property does > not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#custom-property-equal) > filter: filter out all Employees for which the Custom Property is not > equal to the Custom Property of the Job. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#custom-property-is-in) > filter: filter out all Employees for which the `list` Custom Property does > not contain the Custom Property of the Job. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } MATCHING_EMPLOYEES_FOR_JOB { string employee_id FK string job_id FK float score } EMPLOYEE_INFO ||--o{ MATCHING_EMPLOYEES_FOR_JOB : "" JOB_INFO ||--o{ MATCHING_EMPLOYEES_FOR_JOB : "" ``` ### Matching Employees for Job Explained Provides detailed analysis of the best suited Employees for every Job within the organisation, including Skill-level comparisons. > **View Matching Employees for Job Explained export details** > > The Matching Employees for Job Explained export provides an overview of the best suited Employees for every Job within the organisation, including adjacent Skills and how closely they align with the required Skills for the job. > Only active Jobs and Employees are included in the export. The Employees that have the Job assigned are excluded from the results. > > Each export file represents a two-dimensional matrix, containing a row for every Skill of every Employee-Job match. > > The matrix has 6 columns (10 if matching with skill properties is enabled), > containing the following fields for every row (in order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | job\_id | The external ID of the Job within the organisation. | > | status | The current status of the Internal Mobility match (e.g., "present", "missing"). | > | skill\_id | The external ID of the required Skill. | > | skill\_proficiency | *(Optional)* The proficiency level required for the Skill by the Job. Only available if proficiency matching is enabled on the tenant. | > | critical | *(Optional)* Indicates whether the Skill is critical for the Job. Only available if criticality matching is enabled on the tenant. | > | adjacent\_skill\_id | The external ID of the most similar adjacent Skill that the Employee has. | > | adjacent\_skill\_proficiency | *(Optional)* The proficiency level of the adjacent Skill. Only available if proficiency matching is enabled on the tenant. | > | adjacency\_score | The adjacency score between the required Skill and the adjacent Skill, expressed as a number between 0 and 1. | > | gap\_impact | *(Optional)* The impact of the skill gap on the match score. Possible values: `none`, `low`, `medium`, `high`. Only available if matching with skill properties is enabled on the tenant. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Set the `score_min_threshold`: only include Employees with a match score above > this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching Employees are shown > for each Job. Higher numbers give you more options but significantly increases > data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#parameter-limit) > is used. > * Set > [`include_overqualified`](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#parameter-include-overqualified): > when set to `true`, includes matches where the Employee is overqualified for > the Job. Overqualified matches are those where the Employee's skill level > significantly exceeds the requirements. Default is `true`. This filter will > only work if proficiency matching is enabled on the tenant. > * Set > [`min_critical_skills_match_ratio`](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#parameter-one-of-0): > the minimum ratio of critical skills that must be matched. Only matches > meeting or exceeding this ratio will be returned. When `null`, no critical > skills ratio filtering is applied. Required range: 0 ≤ x ≤ 1. This filter will > only work if criticality matching is enabled. > * Set `exclude_low_data_available_entities`: when set to `true`, Employees with > low data availability are excluded from the matching results. > * Set `mapping_filter`: only keep rows where Employee and Job Custom Properties > match the configured mapping. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#custom-property) > filter: filter out all Employees for which the given Custom Property does > not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#custom-property-equal) > filter: filter out all Employees for which the Custom Property is not > equal to the Custom Property of the Job. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-employees#custom-property-is-in) > filter: filter out all Employees for which the `list` Custom Property does > not contain the Custom Property of the Job. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } MATCHING_EMPLOYEES_FOR_JOB_EXPLAINED { string employee_id FK string job_id FK string status string skill_id FK string adjacent_skill_id FK float adjacency_score } SKILL_INFO["Skill Info"] { string skill_id PK } EMPLOYEE_INFO ||--o{ MATCHING_EMPLOYEES_FOR_JOB_EXPLAINED : "" JOB_INFO ||--o{ MATCHING_EMPLOYEES_FOR_JOB_EXPLAINED : "" MATCHING_EMPLOYEES_FOR_JOB_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Matching Jobs for Employee Shows the best suited Jobs for every Employee within the organisation, with match scores. > **View Matching Jobs for Employee export details** > > The Matching Jobs for Employee export provides an overview of the best suited Jobs for every Employee within the organisation, with their match score. > Only active Jobs and Employees are included in the export. The Employee's current Job is excluded from the results. > > Each export file represents a two-dimensional matrix, containing a row for every Employee-Job match. > > The matrix has 3 columns (4 if proficiency matching is enabled), containing the > following fields for every row (in order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | job\_id | The external ID of the Job within the organisation. | > | score | The match score between the Employee and the Job, expressed as a number between 0 and 1. | > | overqualified | *(Optional)* Indicates whether the Employee is over-qualified for the Job. This is `true` when the Employee's skill level significantly exceeds the requirements. Only available if proficiency matching is enabled on the tenant. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Set the `score_min_threshold`: only include Jobs with a match score above this > threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching Jobs are shown for > each Employee. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#parameter-limit) > is used. > * Set > [`include_overqualified`](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#parameter-include-overqualified): > when set to `true`, includes matches where the Employee is overqualified for > the Job. Overqualified matches are those where the Employee's skill level > significantly exceeds the requirements. Default is `true`. This filter will > only work if proficiency matching is enabled on the tenant. > * Set > [`min_critical_skills_match_ratio`](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#parameter-one-of-0): > the minimum ratio of critical skills that must be matched. Only matches > meeting or exceeding this ratio will be returned. When `null`, no critical > skills ratio filtering is applied. Required range: 0 ≤ x ≤ 1. This filter will > only work if criticality matching is enabled. > * Set `exclude_low_data_available_entities`: when set to `true`, Jobs with low > data availability are excluded from the matching results. > * Set `mapping_filter`: only keep rows where Employee and Job Custom Properties > match the configured mapping. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#custom-property) > filter: filter out all Jobs for which the given Custom Property does not > match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#custom-property-equal) > filter: filter out all Jobs for which the Custom Property is not equal to > the Custom Property of the Employee. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#custom-property-is-in) > filter: filter out all Jobs for which the `list` Custom Property does not > contain the Custom Property of the Employee. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } MATCHING_JOBS_FOR_EMPLOYEE { string employee_id FK string job_id FK float score } EMPLOYEE_INFO ||--o{ MATCHING_JOBS_FOR_EMPLOYEE : "" JOB_INFO ||--o{ MATCHING_JOBS_FOR_EMPLOYEE : "" ``` ### Matching Jobs for Employees Explained Provides detailed analysis of the best suited Jobs for every Employee within the organisation, including Skill-level comparisons. > **View Matching Jobs for Employee Explained export details** > > The Matching Jobs for Employee Explained export provides an overview of the best suited Jobs for every Employee within the organisation, including adjacent Skills and how closely they align with the required Skills for the job. > Only active Jobs and Employees are included in the export. The Employee's current Job is excluded from the results. > > Each export file represents a two-dimensional matrix, containing a row for every Skill of every Employee-Job match. > > The matrix has 6 columns (10 if matching with skill properties is enabled), > containing the following fields for every row (in order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | job\_id | The external ID of the Job within the organisation. | > | status | The current status of the Internal Mobility match (e.g., "present", "missing"). | > | skill\_id | The external ID of the required Skill. | > | skill\_proficiency | *(Optional)* The proficiency level required for the Skill by the Job. Only available if proficiency matching is enabled on the tenant. | > | critical | *(Optional)* Indicates whether the Skill is critical for the Job. Only available if criticality matching is enabled on the tenant. | > | adjacent\_skill\_id | The external ID of the most similar adjacent Skill that the Employee has. | > | adjacent\_skill\_proficiency | *(Optional)* The proficiency level of the adjacent Skill. Only available if proficiency matching is enabled on the tenant. | > | adjacency\_score | The adjacency score between the required Skill and the adjacent Skill, expressed as a number between 0 and 1. | > | gap\_impact | *(Optional)* The impact of the skill gap on the match score. Possible values: `none`, `low`, `medium`, `high`. Only available if matching with skill properties is enabled on the tenant. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Set the `score_min_threshold`: only include Jobs with a match score above this > threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching Jobs are shown for > each Employee. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#parameter-limit) > is used. > * Set > [`include_overqualified`](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#parameter-include-overqualified): > when set to `true`, includes matches where the Employee is overqualified for > the Job. Overqualified matches are those where the Employee's skill level > significantly exceeds the requirements. Default is `true`. This filter will > only work if proficiency matching is enabled on the tenant. > * Set > [`min_critical_skills_match_ratio`](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#parameter-one-of-0): > the minimum ratio of critical skills that must be matched. Only matches > meeting or exceeding this ratio will be returned. When `null`, no critical > skills ratio filtering is applied. Required range: 0 ≤ x ≤ 1. This filter will > only work if criticality matching is enabled. > * Set `exclude_low_data_available_entities`: when set to `true`, Jobs with low > data availability are excluded from the matching results. > * Set `mapping_filter`: only keep rows where Employee and Job Custom Properties > match the configured mapping. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#custom-property) > filter: filter out all Jobs for which the given Custom Property does not > match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#custom-property-equal) > filter: filter out all Jobs for which the Custom Property is not equal to > the Custom Property of the Employee. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-employees-external-id-matching-jobs#custom-property-is-in) > filter: filter out all Jobs for which the `list` Custom Property does not > contain the Custom Property of the Employee. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } JOB_INFO { string external_id PK } MATCHING_JOBS_FOR_EMPLOYEE_EXPLAINED { string employee_id FK string job_id FK string status string skill_id FK string adjacent_skill_id FK float adjacency_score } SKILL_INFO["Skill Info"] { string skill_id PK } EMPLOYEE_INFO ||--o{ MATCHING_JOBS_FOR_EMPLOYEE_EXPLAINED : "" JOB_INFO ||--o{ MATCHING_JOBS_FOR_EMPLOYEE_EXPLAINED : "" MATCHING_JOBS_FOR_EMPLOYEE_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Matching source Jobs for Jobs Shows the most relevant Jobs from which potential candidates can be hired to fill a given Job's Skill requirements, with match scores. This helps identify which existing Jobs within your organisation could serve as talent pools for filling open positions. > **View Matching source Jobs for Jobs export details** > > The Matching source Jobs for Jobs export provides an overview of the most relevant Jobs from > which potential candidates can be hired to fill a given Job's Skill requirements for every Job > within the organisation, with their match score. Only active Jobs are considered as potential > source Jobs. A given Job cannot be a source Job for itself. > > Each export file represents a two-dimensional matrix, containing a row for every match between Job and source Job. > > The matrix has 3 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the Job. | > | source\_job\_id | The external ID of the source Job from which potential candidates can be hired. | > | score | The matching score between the Job and the source Job, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Set the `score_min_threshold`: only include source Jobs with a match score > above this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching source Jobs are > shown for each Job. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#parameter-limit) > is used. > * Set `exclude_low_data_available_entities`: when set to `true`, Jobs with low > data availability are excluded from the matching results. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#custom-property) > filter: filter out all source Jobs for which the given Custom Property > does not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#custom-property-equal) > filter: filter out all source Jobs for which the Custom Property is not > equal to the Custom Property of the Job. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#custom-property-is-in) > filter: filter out all source Jobs for which the `list` Custom Property > does not contain the Custom Property of the Job. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MATCHING_SOURCE_JOBS { string job_id FK string source_job_id FK float adjacency_score } JOB_INFO }o--o{ MATCHING_SOURCE_JOBS : "" ``` ### Matching source Jobs for Jobs explained Provides detailed analysis of the most relevant Jobs from which potential candidates can be hired to fill a given Job's Skill requirements, including Skill-level comparisons. This helps identify which existing Jobs within your organisation could serve as talent pools for filling open positions. > **View Matching source Jobs for Jobs explained export details** > > The Matching source Jobs for Jobs explained export provides detailed analysis of the most > relevant Jobs from which potential candidates can be hired to fill a given Job's Skill > requirements, including adjacent Skills and how closely they align with the required Skills. > Only active Jobs are considered as potential source Jobs. A given Job cannot be a source Job > for itself. > > Each export file represents a two-dimensional matrix, containing a row for every match between Job and source Job. > > The matrix has 6 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the Job. | > | source\_job\_id | The external ID of the source Job from which potential candidates can be hired. | > | skill\_id | Universally unique ID of the Skill required by the Job. | > | status | Can be "missing" or "present". If "missing", the Skill is required by the Job, but is missing from the source Job. | > | adjacent\_skill\_id | If status is "present", this field indicates the universally unique Skill ID of the Skill adjacent to the required Skill. | > | adjacency\_score | The adjacency score between the Skill and the adjacent Skill, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Set the `score_min_threshold`: only include source Jobs with a match score > above this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching source Jobs are > shown for each Job. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#parameter-limit) > is used. > * Set `exclude_low_data_available_entities`: when set to `true`, Jobs with low > data availability are excluded from the matching results. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#custom-property) > filter: filter out all source Jobs for which the given Custom Property > does not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#custom-property-equal) > filter: filter out all source Jobs for which the Custom Property is not > equal to the Custom Property of the Job. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-source-jobs#custom-property-is-in) > filter: filter out all source Jobs for which the `list` Custom Property > does not contain the Custom Property of the Job. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MATCHING_SOURCE_JOBS_EXPLAINED { string job_id FK string source_job_id FK string skill_id FK string status string adjacent_skill_id FK float adjacency_score } SKILL_INFO { string skill_id PK } JOB_INFO }o--o{ MATCHING_SOURCE_JOBS_EXPLAINED : "" MATCHING_SOURCE_JOBS_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Matching target Jobs for Jobs Shows the most relevant Jobs to which Employees in a Job can be moved based on Job Skill requirements for each Job of the organisation, with match scores. This helps identify potential career paths for Employees currently in specific Jobs. > **View Matching target Jobs for Jobs export details** > > The Matching target Jobs for Jobs export provides an overview of the most relevant Jobs to > which Employees in a Job can be moved based on Job Skill requirements for each Job of the > organisation, with their match score. Only active Jobs are considered as potential > target Jobs. A given Job cannot be a target Job for itself. > > Each export file represents a two-dimensional matrix, containing a row for every match between Job and target Job. > > The matrix has 3 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the Job. | > | target\_job\_id | The external ID of the target Job to which employees in the given Job can be moved. | > | score | The matching score between the Job and the target Job, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Set the `score_min_threshold`: only include target Jobs with a match score > above this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching target Jobs are > shown for each Job. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#parameter-limit) > is used. > * Set `exclude_low_data_available_entities`: when set to `true`, Jobs with low > data availability are excluded from the matching results. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#custom-property) > filter: filter out all target Jobs for which the given Custom Property > does not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#custom-property-equal) > filter: filter out all target Jobs for which the Custom Property is not > equal to the Custom Property of the Job. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#custom-property-is-in) > filter: filter out all target Jobs for which the `list` Custom Property > does not contain the Custom Property of the Job. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MATCHING_TARGET_JOBS { string job_id FK string target_job_id FK float adjacency_score } JOB_INFO }o--o{ MATCHING_TARGET_JOBS : "" ``` ### Matching target Jobs for Jobs explained Provides detailed analysis of the most relevant Jobs to which Employees in a Job can be moved based on Job Skill requirements for each Job of the organisation, including Skill-level comparisons. This helps identify potential career paths for Employees currently in specific Jobs. > **View Matching target Jobs for Jobs explained export details** > > The Matching target Jobs for Jobs Explained export provides an overview of the most > relevant Jobs to which Employees in a Job can be moved based on Job Skill requirements > for each Job of the organisation, including adjacent Skills and how closely they align > with the required Skills. Only active Jobs are considered as potential target Jobs. A > given Job cannot be a target Job for itself. > > Each export file represents a two-dimensional matrix, containing a row for every match between Job and target Job. > > The matrix has 6 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the Job. | > | target\_job\_id | The external ID of the target Job to which employees in the Job can be moved based on Job Skill requirements. | > | skill\_id | Universally unique ID of the Skill required by the target Job. | > | status | Can be "missing" or "present". If "missing", the Skill is required by the target Job, but is missing from the Job. | > | adjacent\_skill\_id | If status is "present", this field indicates the universally unique Skill ID of the Skill adjacent to the required Skill. | > | adjacency\_score | The adjacency score between the Skill and the adjacent Skill, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Set the `score_min_threshold`: only include target Jobs with a match score > above this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching target Jobs are > shown for each Job. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#parameter-limit) > is used. > * Set `exclude_low_data_available_entities`: when set to `true`, Jobs with low > data availability are excluded from the matching results. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#custom-property) > filter: filter out all target Jobs for which the given Custom Property > does not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#custom-property-equal) > filter: filter out all target Jobs for which the Custom Property is not > equal to the Custom Property of the Job. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-external-id-matching-target-jobs#custom-property-is-in) > filter: filter out all target Jobs for which the `list` Custom Property > does not contain the Custom Property of the Job. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MATCHING_TARGET_JOBS_EXPLAINED { string job_id FK string target_job_id FK string skill_id FK string status string adjacent_skill_id FK float adjacency_score } SKILL_INFO { string skill_id PK } JOB_INFO }o--o{ MATCHING_TARGET_JOBS_EXPLAINED : "" MATCHING_TARGET_JOBS_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Matching Jobs by Tasks Shows the most relevant Jobs to each Job based on the Tasks they share, with match scores. Unlike the Skill-based Job matching exports, this export compares Jobs on their Task profiles, making it useful for task-based role design and internal mobility. > **View Matching Jobs by Tasks export details** > > The Matching Jobs by Tasks export provides the top task-based matching Jobs for every > Job within the organisation, with their match score. The score is symmetric: a single > score is returned per Job pair. Because the result limit is applied per source Job, both > the (A, B) and (B, A) rows can appear if both Jobs rank each other within their limit. > Only active Jobs are included in the results. A given Job cannot match itself. > > Matches are subject to a minimum quality score: Job pairs scoring below 0.30 are > excluded. This means a source Job whose best match scores below the floor has no > rows in the export at all. This is intentional: a Job with no genuinely similar > counterpart returns no matches rather than a weak, potentially misleading > ranking. The floor is not configurable on this export. > > This export is part of TechWolf's Work Intelligence offering and requires Work > Intelligence to be enabled on the tenant. > > Each export file represents a two-dimensional matrix, containing a row for every match between Job and matching Job. > > The matrix has 3 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the source Job. | > | target\_job\_id | The external ID of one of its top task-based matching Jobs. | > | score | The symmetric task-based match score between the two Jobs, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Set the `max_matches_per_entity`: limit how many matching Jobs are shown for > each source Job. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks#parameter-limit) > is used. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks#custom-property) > filter: filter out all matching Jobs for which the given Custom Property > does not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks#custom-property-equal) > filter: filter out all matching Jobs for which the Custom Property is not > equal to the Custom Property of the Job. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks#custom-property-is-in) > filter: filter out all matching Jobs for which the `list` Custom Property > does not contain the Custom Property of the Job. > > These are the only filter types this export accepts. Matching is automatically > restricted to active Jobs (the `is_active` filter is applied for you), so > `is_active` is not a configurable filter here. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MATCHING_JOBS_BY_TASKS { string job_id FK string target_job_id FK float score } JOB_INFO }o--o{ MATCHING_JOBS_BY_TASKS : "" ``` ### Matching Jobs by Tasks explained Provides a per-Task breakdown of the task-based Job-to-Job matches, showing for each Job pair which Tasks contributed to the match and which Tasks had no sufficiently similar counterpart. This helps explain why two Jobs are considered task-relevant to each other. > **View Matching Jobs by Tasks explained export details** > > The Matching Jobs by Tasks explained export expands every Job pair from the Matching > Jobs by Tasks export into one row per Task per direction. Because the match is symmetric, > each pair is evaluated in both directions: `source_to_target` covers the Tasks on the > source Job (`job_id`) matched against the target Job, and `target_to_source` covers the > Tasks on the target Job (`target_job_id`) matched against the source Job. A Task is > marked `present` when it has a sufficiently similar Task on the other side (its adjacent > Task), or `missing` when it does not. Only active Jobs are included, and a given Job > cannot match itself. > > This export is produced from the same matching call as the Matching Jobs by Tasks export > (it uses `response_format=explained`), so both files describe the same Job pairs. It also > applies the same minimum quality score: Job pairs scoring below 0.30 are excluded, and a > source Job with no match at or above the floor is absent from both files. > > This export is part of TechWolf's Work Intelligence offering and requires Work > Intelligence to be enabled on the tenant. > > Each export file represents a two-dimensional matrix, containing a row for every Task on either side of every Job pair. > > The matrix has 10 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the source Job. | > | target\_job\_id | The external ID of the matching Job. | > | task\_id | The unique ID of the Task on the side indicated by `direction`. | > | task\_name | The name of the Task. | > | status | Either "present" (the Task has a sufficiently similar Task on the other Job) or "missing" (it does not, so it contributes nothing to the match). | > | direction | Either "source\_to\_target" (the Task is on the source Job) or "target\_to\_source" (the Task is on the target Job). | > | adjacent\_task\_id | The unique ID of the most similar Task on the other Job, against which the Task was matched. Empty for "missing" rows. | > | adjacent\_task\_name | The name of the adjacent Task. Empty for "missing" rows. | > | adjacency\_score | The similarity between the Task and its adjacent Task, expressed as a number between 0 and 1. Empty for "missing" rows. | > | hours\_share | The Task's share of its direction's weighted-hours total, expressed as a number between 0 and 1. Empty for "missing" rows. | > > Currently supported configurations are: > > * Set the `max_matches_per_entity`: limit how many matching Jobs are shown for > each source Job. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks#parameter-limit) > is used. > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks#custom-property) > filter: filter out all matching Jobs for which the given Custom Property > does not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks#custom-property-equal) > filter: filter out all matching Jobs for which the Custom Property is not > equal to the Custom Property of the Job. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Job%20Matching/post-job-architecture-jobs-job-external-id-matching-jobs-by-tasks#custom-property-is-in) > filter: filter out all matching Jobs for which the `list` Custom Property > does not contain the Custom Property of the Job. > > These are the only filter types this export accepts. Matching is automatically > restricted to active Jobs (the `is_active` filter is applied for you), so > `is_active` is not a configurable filter here. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MATCHING_JOBS_BY_TASKS_EXPLAINED { string job_id FK string target_job_id FK string task_id string task_name string status string direction string adjacent_task_id string adjacent_task_name float adjacency_score float hours_share } JOB_INFO }o--o{ MATCHING_JOBS_BY_TASKS_EXPLAINED : "" ``` ### Matching Vacancies for Employee Shows the best suited Vacancies for every Employee within the organisation, with match scores. > **View Matching Vacancies for Employee export details** > > The Matching Vacancies for Employee export provides an overview of the best suited Vacancies for every Employee within the organisation, with their match score. > Only active Vacancies and Employees are included in the export. > > Each export file represents a two-dimensional matrix, containing a row for every Employee-Vacancy match. > > The matrix has 3 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | vacancy\_id | The external ID of the Vacancy within the organisation. | > | score | The match score between the Employee and the Vacancy, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Set the `score_min_threshold`: only include Vacancies with a match score above > this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching Vacancies are shown > for each Employee. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#parameter-limit) > is used. > * Set `exclude_low_data_available_entities`: when set to `true`, Vacancies with > low data availability are excluded from the matching results. > * Weights: configure weights to influence the matching score. Supported weights > are `skills_match`, `desired_functions`, and `geo_distance` (with > `full_score_distance` and `zero_score_distance` parameters). > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#custom-property) > filter: filter out all Vacancies for which the given Custom Property does > not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#custom-property-equal) > filter: filter out all Vacancies for which the Custom Property is not > equal to the Custom Property of the Employee. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#custom-property-is-in) > filter: filter out all Vacancies for which the `list` Custom Property does > not contain the Custom Property of the Employee. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } MATCHING_VACANCIES_FOR_EMPLOYEE { string employee_id FK string vacancy_id float score } EMPLOYEE_INFO ||--o{ MATCHING_VACANCIES_FOR_EMPLOYEE : "" ``` ### Matching Vacancies for Employee Explained Provides detailed analysis of the best suited Vacancies for every Employee within the organisation, including Skill-level comparisons. > **View Matching Vacancies for Employee Explained export details** > > The Matching Vacancies for Employee Explained export provides an overview of the best suited Vacancies for every Employee within the organisation, including adjacent Skills and how closely they align with the required Skills for the Vacancy. > Only active Vacancies and Employees are included in the export. > > Each export file represents a two-dimensional matrix, containing a row for every Skill of every Employee-Vacancy match. > > The matrix has 6 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | vacancy\_id | The external ID of the Vacancy within the organisation. | > | status | The current status of the match (e.g., "present", "missing"). | > | skill\_id | The external ID of the required Skill. | > | adjacent\_skill\_id | The external ID of the most similar adjacent Skill that the Employee has. | > | adjacency\_score | The adjacency score between the required Skill and the adjacent Skill, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Set the `score_min_threshold`: only include Vacancies with a match score above > this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching Vacancies are shown > for each Employee. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#parameter-limit) > is used. > * Set `exclude_low_data_available_entities`: when set to `true`, Vacancies with > low data availability are excluded from the matching results. > * Weights: configure weights to influence the matching score. Supported weights > are `skills_match`, `desired_functions`, and `geo_distance` (with > `full_score_distance` and `zero_score_distance` parameters). > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#custom-property) > filter: filter out all Vacancies for which the given Custom Property does > not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#custom-property-equal) > filter: filter out all Vacancies for which the Custom Property is not > equal to the Custom Property of the Employee. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-employees-external-id-matching-vacancies#custom-property-is-in) > filter: filter out all Vacancies for which the `list` Custom Property does > not contain the Custom Property of the Employee. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } MATCHING_VACANCIES_FOR_EMPLOYEE_EXPLAINED { string employee_id FK string vacancy_id string status string skill_id FK string adjacent_skill_id FK float adjacency_score } SKILL_INFO["Skill Info"] { string skill_id PK } EMPLOYEE_INFO ||--o{ MATCHING_VACANCIES_FOR_EMPLOYEE_EXPLAINED : "" MATCHING_VACANCIES_FOR_EMPLOYEE_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Matching Employees for Vacancy Shows the best suited Employees for every Vacancy within the organisation, with match scores. > **View Matching Employees for Vacancy export details** > > The Matching Employees for Vacancy export provides an overview of the best suited Employees for every Vacancy within the organisation, with their match score. Only active Vacancies and Employees are included in the export. > > Each export file represents a two-dimensional matrix, containing a row for every Employee-Vacancy match. > > The matrix has 3 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | vacancy\_id | The external ID of the Vacancy within the organisation. | > | score | The match score between the Employee and the Vacancy, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Set the `score_min_threshold`: only include Employees with a match score above > this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching Employees are shown > for each Vacancy. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#parameter-limit) > is used. > * Set `exclude_low_data_available_entities`: when set to `true`, Employees with > low data availability are excluded from the matching results. > * Weights: configure weights to influence the matching score. Supported weights > are `skills_match`, `desired_functions`, and `geo_distance` (with > `full_score_distance` and `zero_score_distance` parameters). > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#custom-property) > filter: filter out all Employees for which the given Custom Property does > not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#custom-property-equal) > filter: filter out all Employees for which the Custom Property is not > equal to the Custom Property of the Vacancy. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#custom-property-is-in) > filter: filter out all Employees for which the `list` Custom Property does > not contain the Custom Property of the Vacancy. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } MATCHING_EMPLOYEES_FOR_VACANCY { string employee_id FK string vacancy_id float score } EMPLOYEE_INFO ||--o{ MATCHING_EMPLOYEES_FOR_VACANCY : "" ``` ### Matching Employees for Vacancy Explained Provides detailed analysis of the best suited Employees for every Vacancy within the organisation, including Skill-level comparisons. > **View Matching Employees for Vacancy Explained export details** > > The Matching Employees for Vacancy Explained export provides an overview of the best suited Employees for every Vacancy within the organisation, including adjacent Skills and how closely they align with the required Skills for the Vacancy. > Only active Vacancies and Employees are included in the export. > > Each export file represents a two-dimensional matrix, containing a row for every Skill of every Employee-Vacancy match. > > The matrix has 6 columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | employee\_id | The external ID of the Employee. | > | vacancy\_id | The external ID of the Vacancy within the organisation. | > | status | The current status of the match (e.g., "present", "missing"). | > | skill\_id | The external ID of the required Skill. | > | adjacent\_skill\_id | The external ID of the most similar adjacent Skill that the Employee has. | > | adjacency\_score | The adjacency score between the required Skill and the adjacent Skill, expressed as a number between 0 and 1. | > > Currently supported configurations are: > > * Mask `employee_id`: mask the Employee's external ID to protect privacy. > * Set the `score_min_threshold`: only include Employees with a match score above > this threshold, higher values mean stricter matching. When not set, the > [default](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#parameter-score-min-threshold) > is used. > * Set the `max_matches_per_entity`: limit how many matching Employees are shown > for each Vacancy. Higher numbers give you more options but significantly > increases data size. When not set, the > [default limit](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#parameter-limit) > is used. > * Set `exclude_low_data_available_entities`: when set to `true`, Employees with > low data availability are excluded from the matching results. > * Weights: configure weights to influence the matching score. Supported weights > are `skills_match`, `desired_functions`, and `geo_distance` (with > `full_score_distance` and `zero_score_distance` parameters). > * Filters: add custom filters on Custom Properties to further refine the > results. We currently support 3 types of filters: > * [Custom Property](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#custom-property) > filter: filter out all Employees for which the given Custom Property does > not match the condition defined by an operator and a value. > * [Custom Property equal](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#custom-property-equal) > filter: filter out all Employees for which the Custom Property is not > equal to the Custom Property of the Vacancy. > * [Custom Property is in](https://developers.techwolf.ai/reference/latest/Matchmaking/Vacancy%20Matching/post-vacancies-external-id-matching-employees#custom-property-is-in) > filter: filter out all Employees for which the `list` Custom Property does > not contain the Custom Property of the Vacancy. **Entity Relationships:** ```mermaid theme={null} erDiagram EMPLOYEE_INFO { string external_id PK } MATCHING_EMPLOYEES_FOR_VACANCY_EXPLAINED { string employee_id FK string vacancy_id string status string skill_id FK string adjacent_skill_id FK float adjacency_score } SKILL_INFO["Skill Info"] { string skill_id PK } EMPLOYEE_INFO ||--o{ MATCHING_EMPLOYEES_FOR_VACANCY_EXPLAINED : "" MATCHING_EMPLOYEES_FOR_VACANCY_EXPLAINED }o--o{ SKILL_INFO : "" ``` ### Market Info Shows the configuration of peer groups and their member companies. > **View Market Info export details** > > The Market info export provides an overview of the different peer groups that are configured, and which companies are in each peer group. > A peer group consists of a list of companies used to create external market Skill Profiles for Jobs. > > Each export file represents a two-dimensional matrix, containing one row for > every company of every peer group. > > The following values indicate the contents of every column (in order): > > | Field name | Field description | > | - | - | > | peer\_group | The name of the peer group in TechWolf. | > | company | The name of the company within the peer group. | **Entity Relationships:** ```mermaid theme={null} erDiagram MARKET_INFO { string peer_group PK string company PK } MARKET_SKILL_PROFILE { string peer_group FK string job_id FK } MARKET_COMPARISON { string peer_group FK string job_id FK } MARKET_COMPARISON_EXPLAINED { string peer_group FK string job_id FK } MARKET_INFO }o--o{ MARKET_SKILL_PROFILE : "" MARKET_INFO }o--o{ MARKET_COMPARISON : "" MARKET_INFO }o--o{ MARKET_COMPARISON_EXPLAINED : "" ``` ### Market Skill Profiles *(Market to Skill)* Shows the Skills required by companies in different peer groups for each Job. > **View Market Skill Profiles export details** > > The Market Skill Profiles export provides an overview of all Skills required by the companies in the different > peer groups, for every Job. > > Each export file represents a two-dimensional matrix, containing one row for > every market Skill of every Job-peer group combination, with Job-peer group > combinations without market Skills not being represented. > > The matrix has four columns, containing the following fields for every row (in > order) > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the Job with the Skill in TechWolf. | > | peer\_group | The name of the peer group in TechWolf. | > | skill\_id | The external ID of the Skill in TechWolf. | > | skill | The name of the Skill in TechWolf. | > > Currently supported configurations are: > > * `vocab_language`: the language of the Skill names in the file. Defaults to > English. **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MARKET_INFO { string peer_group PK } SKILL_INFO { string skill_id PK } MARKET_SKILL_PROFILE { string job_id FK string peer_group FK string skill_id FK string skill } JOB_INFO ||--o{ MARKET_SKILL_PROFILE : "" MARKET_INFO }o--o{ MARKET_SKILL_PROFILE : "" MARKET_SKILL_PROFILE }o--o{ SKILL_INFO : "" ``` ### Market Comparison Shows alignment scores between Jobs and their peer group market Skill Profiles, in both directions. > **View Market Comparison export details** > > The Market Comparison export provides an overview of alignment scores between Jobs and their peer group market Skill Profiles, including both Job to market (how well the Job covers peer requirements) and market to Job (how well peers cover Job requirements) alignment scores. > > Each export file represents a two-dimensional matrix, containing one row for > every Job-peer group combination. > > The matrix has four columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the Job in TechWolf. | > | peer\_group | The name of the peer group in TechWolf. | > | job\_to\_peer\_score | The Job to market alignment score, indicating how well the Job Skill Profile covers the Skill requirements of the peer Skill Profile. | > | peer\_to\_job\_score | The market to Job alignment score, indicating how well the peer Skill Profile covers the Skill requirements of the Job Skill Profile. | **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MARKET_INFO { string peer_group PK } MARKET_COMPARISON { string job_id FK string peer_group FK float job_to_peer_score float peer_to_job_score } JOB_INFO ||--o{ MARKET_COMPARISON : "" MARKET_INFO }o--o{ MARKET_COMPARISON : "" ``` ### Market Comparison Explained Provides detailed analysis of alignment between Jobs and peer group Skill Profiles, including Skill-level comparisons. > **View Market Comparison Explained export details** > > The Market Comparison Explained export provides detailed alignment analysis between Jobs and their peer group market Skill Profiles, including comprehensive breakdowns of how well Job Skill Profiles match peer requirements and vice versa, with detailed Skill-level comparisons and gap analysis. > > Each export file represents a two-dimensional matrix, containing one row for > every Skill of every Job-peer group combination. > > The matrix has eight columns, containing the following fields for every row (in > order): > > | Field name | Field description | > | - | - | > | job\_id | The external ID of the Job in TechWolf. | > | peer\_group | The name of the peer group in TechWolf. | > | skill\_id | The external ID of a Skill in TechWolf, that is present in the Job Skill Profile and/or peer Skill profile. | > | skill\_status | The current status of the Skill in the profile (e.g., "literal\_overlap", "peer\_skill\_covered\_by\_adjacent\_job\_skill", "job\_skill\_covered\_by\_adjacent\_peer\_skill", "peer\_skill\_missing\_in\_job\_profile", "job\_skill\_missing\_in\_peer\_profile"). Indicates whether the Skill is present in both the Job and peer Skill Profile, sufficiently covered by an adjacent Skill, or missing in one of the Skill Profiles. | > | job\_adjacent\_skill\_id | The external ID of the most similar adjacent Skill in the Job Skill Profile. | > | peer\_adjacent\_skill\_id | The external ID of the most similar adjacent Skill in the peer Skill Profile. | > | job\_adjacency\_score | The adjacency score between the Skill and the adjacent Job Skill. | > | peer\_adjacency\_score | The adjacency score between the Skill and the adjacent peer Skill. | **Entity Relationships:** ```mermaid theme={null} erDiagram JOB_INFO { string external_id PK } MARKET_INFO { string peer_group PK } SKILL_INFO { string skill_id PK } MARKET_COMPARISON_EXPLAINED { string job_id FK string peer_group FK string skill_id FK string skill_status string job_adjacent_skill_id FK string peer_adjacent_skill_id FK float job_adjacency_score float peer_adjacency_score } JOB_INFO ||--o{ MARKET_COMPARISON_EXPLAINED : "" MARKET_INFO }o--o{ MARKET_COMPARISON_EXPLAINED : "" MARKET_COMPARISON_EXPLAINED }o--o{ SKILL_INFO : "" ``` # Visier exports Source: https://developers.techwolf.ai/integrations/file-based-output/visier-exports Below we list all export types available for the Visier integration. Each export is delivered as a CSV file with a naming convention of `tw__{YYYYMM}_{YYYYMMDD}.csv`. ### Skill Vocabulary TechWolf syncs data regarding the Skills Vocabulary and your unique Skills Taxonomy to Visier in order to enable insights on Skill Cluster, and Skill (sub) Domain level. > **View Skill Vocabulary export details** > > The Skill Vocabulary export (`tw_skills_profile_{YYYYMM}_{YYYYMMDD}.csv`) > provides an overview of all Skills and their classification within the Taxonomy. > > The CSV contains one row for every Skill. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Skill ID | Uses ID of vocabulary that is enabled. | > | Skill Name | Uses Skill name of vocabulary that is enabled. | > | Skill Category | Skills Taxonomy Skill Domain if the Skill is in the Skills Taxonomy; else "Skills outside of the Taxonomy". | > | Skill Category ID | Skills Taxonomy Skill Domain ID if the Skill is in the Skills Taxonomy; else empty. | > | Skill Sub-Category | Skills Taxonomy Skill Subdomain if the Skill is in the Skills Taxonomy; else default TechWolf Skill Domain. | > | Skill Sub-Category ID | Skills Taxonomy Skill Subdomain ID if the Skill is in the Skills Taxonomy; else empty. | > | Skill Group | Skills Taxonomy Skill Cluster if the Skill is in the Skills Taxonomy; else empty. | > | Skill Group ID | Skills Taxonomy Skill Cluster ID if the Skill is in the Skills Taxonomy; else empty. | > | Skill Data Source | "TechWolf". | > | Skill Description | Uses Skill description of vocabulary that is enabled. | ### Employee Info TechWolf syncs some metadata on the Employee to Visier, including a Job Skill Match Score for each Employee to enable Skill gap related insights. > **View Employee Info export details** > > The Employee Info export (`tw_employee_{YYYYMM}_{YYYYMMDD}.csv`) provides an > overview of all Employees. > > The CSV contains one row for every Employee. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Employee ID | | > | Job ID | The unique ID of the Job the Employee is currently assigned to. Empty when the Employee has no assigned position. | > | Low Skill Data | Indicates whether or not the Employee has sufficient qualitative input data to build a Skill profile (and to include in data analysis). | > | Current Job Skill Match Score | Indicates the match score of the Employee with their current assigned position. This enables Skill gap related insights. | ### Employee Skills TechWolf syncs all your Employee Skill profiles to Visier. On top of that, we can also sync the Skills these Employees are expected to have based on their current assigned Job, alongside proficiency levels from multiple sources, whether or not these Skills are critical for the Job, the sources from which the Skill was inferred, and whether it was inferred from Employee data. > **View Employee Skills export details** > > The Employee Skills export (`tw_employee_skills_{YYYYMM}_{YYYYMMDD}.csv`) > provides detailed Skill data for every Employee-Skill combination. > > The CSV contains one row for every Employee-Skill pair. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Date Recognized | | > | Employee ID | | > | Job ID | | > | Skill ID | | > | Employee Skill ID | Format: \[employee\_id]-\[skill\_id]. | > | Employee Skill State | "Validated"; "Suggested"; "N/A" if the Skill only exists on the Job side. | > | Job Skill State | "Validated"; "Suggested"; "N/A" if the Skill only exists on the Employee side. | > | Employee Suggested Skill Level Code | Skill level inferred by TechWolf (numeric value); -1 if no inference was possible or Skill is not applicable. | > | Employee Suggested Skill Level Name | Mapped label for the suggested level. | > | Employee Self-rated Skill Level Code | Skill level self-rated by the Employee (numeric value); 0 if not set/validated; -1 if Skill is not applicable. | > | Employee Self-rated Skill Level Name | Mapped label for the self-rated level. | > | Employee Manager-rated Skill Level Code | Skill level rated by a N+1 (numeric value); 0 if not set/validated; -1 if Skill is not applicable. | > | Employee Manager-rated Skill Level Name | Mapped label for the manager-rated level. | > | Employee Peer-rated Skill Level Code | Skill level rated by a peer (numeric value); 0 if not set/validated; -1 if Skill is not applicable. | > | Employee Peer-rated Skill Level Name | Mapped label for the peer-rated level. | > | Employee Assessed Skill Level Code | Skill level rated via an assessment tool (numeric value); 0 if not set/validated; -1 if Skill is not applicable. | > | Employee Assessed Skill Level Name | Mapped label for the assessed level. | > | Employee Acquired Skill Level Code | Final computed Skill level; calculation based on client's preference; -1 if Skill is not applicable. | > | Employee Acquired Skill Level Name | Mapped label for the acquired level. | > | Job Expected Skill Level Code | Required Skill level for the Job, sourced from the Job's Skill profile. Per-customer setting picks the source: validated (governed Skill level only) or suggested (governed value; falls back to TechWolf-inferred when no governed value is set). -1 if no value is available. | > | Job Expected Skill Level Name | Mapped label for the expected level. | > | Critical Skill | Whether the Skill is marked as "Critical" for the Job; 2 when critical, else 0. The same per-customer setting that drives Job Expected Skill Level Code picks the source: validated (governed Critical only) or suggested (governed value; falls back to inferred when no governed value is set). | > | Sources | Lists the sources from which the Skill was inferred. | > | Inferred from Employee Data | Indicates whether the Skill was inferred from Employee data or solely based on validation (feedback). | ### Matching Jobs for Employee TechWolf syncs internal mobility data to Visier. This includes data on which Jobs are best suited for Employees. The simple file shows the matching scores. > **View Matching Jobs for Employee export details** > > The Matching Jobs for Employee export > (`tw_matching_jobs_{YYYYMM}_{YYYYMMDD}.csv`) provides match scores between > Employees and Jobs. > > The CSV contains one row for every Employee-Job match. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Employee ID | | > | Job ID | | > | Matching Score | Indicates the match score between the Employee and a certain Job. | > > Currently supported configurations are: > > * Set the `score_min_threshold`: only include matches with a score above this > threshold, higher values mean stricter matching. > * Set the `max_matches_per_entity`: limit how many matching Jobs are shown for > each Employee. > * Set `exclude_low_data_available_entities`: when set to `true`, Jobs with low > data availability are excluded from the matching results. > * Set `mapping_filter`: only keep rows where Employee and Job Custom Properties > match the configured mapping. > * Filters: add custom filters on Custom Properties to further refine the > results. ### Matching Jobs for Employee Explained The explained file goes deeper into these matches and shows which Skills are present, covered, or missing. > **View Matching Jobs for Employee Explained export details** > > The Matching Jobs for Employee Explained export > (`tw_matching_jobs_explained_{YYYYMM}_{YYYYMMDD}.csv`) provides a Skill-level > explanation of Employee-Job matches. > > The CSV contains one row for every Skill in each Employee-Job match. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Employee ID | | > | Job ID | | > | Status | Indicates the status of the match: "present" when the Adjacent Skill ID equals the Skill ID, "covered" when the Adjacent Skill ID does not equal the Skill ID, and "missing" when there is no Adjacent Skill ID. | > | Skill ID | Skill that the Job has. | > | Adjacent Skill ID | The most similar adjacent Skill that the Employee has; empty if the Skill is missing. | > | Adjacency Score | Indicates the adjacency score between the required Skill and the adjacent Skill. | > > Currently supported configurations are: > > * Set the `score_min_threshold`: only include matches with a score above this > threshold, higher values mean stricter matching. > * Set the `max_matches_per_entity`: limit how many matching Jobs are shown for > each Employee. > * Set `exclude_low_data_available_entities`: when set to `true`, Jobs with low > data availability are excluded from the matching results. > * Set `mapping_filter`: only keep rows where Employee and Job Custom Properties > match the configured mapping. > * Filters: add custom filters on Custom Properties to further refine the > results. ### Matching Employees for Job Provides matching scores between Jobs and Employees, indicating how well Employees match a given Job's requirements. Uses the same schema as [Matching Jobs for Employee](#matching-jobs-for-employee) but from the Job's perspective. > **View Matching Employees for Job export details** > > The Matching Employees for Job export > (`tw_matching_employees_{YYYYMM}_{YYYYMMDD}.csv`) provides match scores between > Jobs and Employees. > > The CSV contains one row for every Job-Employee match. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Employee ID | | > | Job ID | | > | Matching Score | Indicates the match score between the Job and a certain Employee. | > > Currently supported configurations are: > > * Set the `score_min_threshold`: only include matches with a score above this > threshold, higher values mean stricter matching. > * Set the `max_matches_per_entity`: limit how many matching Employees are shown > for each Job. > * Set `exclude_low_data_available_entities`: when set to `true`, Employees with > low data availability are excluded from the matching results. > * Set `mapping_filter`: only keep rows where Employee and Job Custom Properties > match the configured mapping. > * Filters: add custom filters on Custom Properties to further refine the > results. ### Matching Employees for Job Explained Provides a Skill-level breakdown of Job-Employee matches. Uses the same schema as [Matching Jobs for Employee Explained](#matching-jobs-for-employee-explained) but from the Job's perspective. > **View Matching Employees for Job Explained export details** > > The Matching Employees for Job Explained export > (`tw_matching_employees_explained_{YYYYMM}_{YYYYMMDD}.csv`) provides a > Skill-level explanation of Job-Employee matches. > > The CSV contains one row for every Skill in each Job-Employee match. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Employee ID | | > | Job ID | | > | Status | Indicates the current status of the match: "present" when the Adjacent Skill ID equals the Skill ID, "covered" when the Adjacent Skill ID does not equal the Skill ID, and "missing" when there is no Adjacent Skill ID. | > | Skill ID | Skill that the Job has. | > | Adjacent Skill ID | Adjacent Skill in the Employee's Skill profile. | > | Adjacency Score | Indicates the adjacency score between the required Skill and the adjacent Skill. | > > Currently supported configurations are: > > * Set the `score_min_threshold`: only include matches with a score above this > threshold, higher values mean stricter matching. > * Set the `max_matches_per_entity`: limit how many matching Employees are shown > for each Job. > * Set `exclude_low_data_available_entities`: when set to `true`, Employees with > low data availability are excluded from the matching results. > * Set `mapping_filter`: only keep rows where Employee and Job Custom Properties > match the configured mapping. > * Filters: add custom filters on Custom Properties to further refine the > results. ### Job Info TechWolf syncs data regarding the Jobs and their fields. > **View Job Info export details** > > The Job Info export (`tw_job_info_{YYYYMM}_{YYYYMMDD}.csv`) provides an overview > of all Jobs. > > The CSV contains one row for every Job. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Job ID | | > | Job Name | | > | Job Family | | > | Job Family Group | | > | Low Data Availability | Indicates whether or not the Job has sufficient qualitative input data to build a Skill profile (and to include in data analysis). | > | Active | Indicates whether the Job will be used in internal mobility. It will not be used in matching if it is False. This is useful when a Job is being phased out. | > | Last Updated | | ### Job Skills Provides detailed Skill information for each Job, including proficiency levels from different rating sources and the Skill's state. > **View Job Skills export details** > > The Job Skills export (`tw_job_skills_{YYYYMM}_{YYYYMMDD}.csv`) provides > detailed Skill data for every Job-Skill combination. > > The CSV contains one row for every Job-Skill pair. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Date Recognized | | > | Job ID | | > | Skill ID | | > | Job Skill ID | Format: \[job\_id]-\[skill\_id]. | > | Job Skill State | "Validated"; "Suggested". | > | Job Suggested Skill Level Code | Skill level inferred by TechWolf (numeric value); -1 if no inference was possible. | > | Job Suggested Skill Level Name | Mapped label for the suggested level. | > | Job Validated Skill Level Code | Skill level validated in the TechWolf Console; 0 if not validated. | > | Job Validated Skill Level Name | Mapped label for the validated level. | > | Job Expected Skill Level Code | Required Skill level for the Job. Per-customer setting picks the source: validated (governed Skill level only) or suggested (governed value; falls back to TechWolf-inferred when no governed value is set). -1 if no value is available. | > | Job Expected Skill Level Name | Mapped label for the expected level. | > | Job Validated Critical Skill Value | Whether the Skill is marked as "Critical" for the Job based on the governed (validated) value; 2 when critical, else 0. | > | Job Suggested Critical Skill Value | Whether the Skill is inferred as "Critical" for the Job by TechWolf; 2 when critical, else 0. | ### Work Intelligence exports The following exports are only available when the Work Intelligence feature is enabled. They provide Task-level data for Jobs, including AI impact metrics. #### Task Info Master table containing unique Task information, including Task hierarchy and AI impact classification. > **View Task Info export details** > > The Task Info export (`tw_task_info_{YYYYMM}_{YYYYMMDD}.csv`) provides an > overview of all Tasks. > > The CSV contains one row per unique Task across all Jobs. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Task | Raw Task description as identified in Job. | > | Task ID | Unique identifier for the Task. | > | Canonical Task | Standardized/canonical version of the Task (level 4); empty is labeled as "Not Classified". | > | Canonical Task ID | Unique identifier for the Canonical Task; empty when the Task is not classified. | > | Cluster | Task Cluster in hierarchy (level 3); empty is labeled as "Not Classified". | > | Cluster ID | Unique identifier for the Cluster; empty when the Task is not classified. | > | Subdomain | Task Subdomain in hierarchy (level 2); empty is labeled as "Not Classified". | > | Subdomain ID | Unique identifier for the Subdomain; empty when the Task is not classified. | > | Domain | Task Domain in hierarchy (level 1); empty is labeled as "Not Classified". | > | Domain ID | Unique identifier for the Domain; empty when the Task is not classified. | > | AI Impact | AI impact classification: "automatable", "augmentable", or "human". | > | HAS\_level | HAS (Human-AI Spectrum) level: "H1", "H2", "H3", "H4", or "H5". | > | AI Impact Rationale | Explanation for the AI impact classification. | > | task\_source | Origin of the Task: `vocabulary` (work taxonomy) or `custom` (tenant-authored). | #### Job Task Junction table linking Jobs to their constituent Tasks with time allocation. > **View Job Task export details** > > The Job Task export (`tw_job_task_{YYYYMM}_{YYYYMMDD}.csv`) provides the > relationship between Jobs and Tasks. > > The CSV contains one row per Job-Task relationship. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Job ID | External identifier for the Job. | > | Job Title | Title of the Job. | > | Task | Raw Task description. | > | Task ID | Unique identifier for the Task (FK to Task Info). | > | Weekly Hours | Number of hours per week spent on this Task. | > | Validation State | Validation state in the governance cycle: "suggested", "rejected", or "validated". | #### Job Task Skill Junction table linking Jobs and Tasks to the Skills required to perform them. > **View Job Task Skill export details** > > The Job Task Skill export (`tw_job_task_skill_{YYYYMM}_{YYYYMMDD}.csv`) provides > the Skills linked to each Job-Task combination. > > The CSV contains one row per Job-Task-Skill relationship. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Job ID | External identifier for the Job. | > | Job Title | Title of the Job. | > | Task | Raw Task description. | > | Task ID | Unique identifier for the Task (FK to Task Info). | > | Linked Skills ID | Unique identifier for the Skill. | > | Linked Skills | Name of the Skill. | > | Validation State | Validation state in the governance cycle: "suggested", "rejected", or "validated". | #### Job Info (Work Intelligence) Master table containing Job metadata and aggregated AI impact metrics. > **View Job Info (Work Intelligence) export details** > > The Job Info Work Intelligence export > (`tw_job_info_wi_{YYYYMM}_{YYYYMMDD}.csv`) provides Job data enriched with AI > impact scores. > > The CSV contains one row per unique Job. > > Business rules: > > * `augmentable` + `automatable` + `human` = 1.00 (always sum to exactly 1.00). > * Proportions are calculated by weighting Task-level AI impact by > `weekly_hours`. > * Overall potential is the category with the highest proportion. > > | Field | Note | > | - | - | > | Snapshot Date | Format: YYYY-MM-DD. | > | Job ID | External identifier for the Job. | > | Job Name | Title/name of the Job. | > | Job Family | Job Family classification. | > | Job Family Group | Job Family Group classification. | > | Augmentable | Proportion of Job that is augmentable by AI (decimal, 0.00-1.00). | > | Automatable | Proportion of Job that is automatable by AI (decimal, 0.00-1.00). | > | Human | Proportion of Job requiring human-only work (decimal, 0.00-1.00). | > | Overall potential | Dominant AI impact category for the Job: "augmentable", "automatable", or "human". | > | Low Data Availability | Flag indicating low data quality for this Job. | > | Active | Whether the Job is currently active. | > | Last Updated | Date Job information was last updated. | # FAQ Source: https://developers.techwolf.ai/integrations/mcp-connector/faq ## Does the connector connect to our HR system directly? No. The connector reads only from your TechWolf instance, with no direct connection to your HR system. Many HR systems offer a similar MCP server, which you can add alongside this one to work over both TechWolf data and core HR data in the same assistant. ## Does the connector work through our own MCP gateway? Yes, as long as your gateway forwards each user's own login. TechWolf checks compatibility with your specific gateway before rollout; see [Security](./security). ## Does connecting through Copilot give TechWolf access to our other Microsoft 365 data? No. The connector reaches only your TechWolf instance. Whatever else Copilot can see — SharePoint, Teams, email — stays outside TechWolf's reach. ## If we connect third-party tools to the connector, do those tools get access to our TechWolf data? Any third-party tool that uses the TechWolf MCP connector can process the data it retrieves. The scope of that data depends on the prompt of the user driving the tool and on that user's TechWolf data access. ## Can the connector change our TechWolf data? No. The connector is read-only and cannot modify or delete any skill or task data. If your question is not answered here, reach out to us at [support@techwolf.ai](mailto:support@techwolf.ai). # What is the TechWolf MCP Connector? Source: https://developers.techwolf.ai/integrations/mcp-connector/overview Model Context Protocol (MCP) is an open standard that lets AI assistants call outside data sources directly. The TechWolf MCP connector is an MCP server that lets AI assistants such as Copilot, Claude, or any other MCP-compatible tool read your organization's TechWolf data. Connecting TechWolf to your AI assistant gets you three things: * **Flexible retrieval and reasoning** over TechWolf data, using the intelligence of the AI assistant you already use. * **TechWolf data inside your daily tools** — documents, spreadsheets, presentations. * **Combined insights across systems:** adding MCP connections to other workforce data sources (HCM, financial systems, contingency platforms) lets your assistant reason over those systems and TechWolf data together. This supports strategic HR use cases such as talent development, redeployment, strategic workforce planning, and work redesign. ## What it can and can't do The connector reads from the three TechWolf data products held for your organization — Skill Intelligence, Work Intelligence, and Market Intelligence. It adds no new data sources. * **Read-only.** The connector cannot modify or delete any skill or task data. * **Centralized access.** A user can only access data they explicitly have access to, as configured in the TechWolf Console. ## Who can use it Access is managed in the TechWolf Console. A user needs a Console account on your organization to connect, and what they see through the connector is exactly what their Console permissions allow — removing access takes effect on their next call. Most customers scope access to HR business partners or a dedicated transformation team; your own administrators manage this in the Console. ## Connecting Your organization's admin adds the connector once per AI assistant, using the connector URL TechWolf provides during onboarding. After that, each user connects individually: they sign in through your own identity provider (the same single sign-on as the TechWolf Console) and approve a consent screen. No passwords or API keys are shared with the assistant. The connector also works behind an organization-wide MCP gateway; see [Security](./security) for the requirements. ## How is this different from the TechWolf Analyst Agent? The [Analyst Agent](../analyst-agent/overview) is an AI assistant hosted by TechWolf that answers workforce questions out of the box, in the Console or as a custom agent in Copilot, on a credit system. The MCP connector works inside AI assistants you already use. It reaches your TechWolf data inside your daily tools, and can be combined with other MCP connectors in the same assistant. ## Availability Early access is opening now; general availability is targeted for November 1, 2026. Reach out to your TechWolf contact to join the early access program. ## In this section * [Security](./security): authentication, hosting, retention, gateway compatibility, and certifications — written for your IT and security review. * [FAQ](./faq): common questions about scope, access, and risk. If you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please reach out to us at [support@techwolf.ai](mailto:support@techwolf.ai). # Security Source: https://developers.techwolf.ai/integrations/mcp-connector/security This page summarizes the connector for security, IT, and procurement review. ## Authentication * **Identity:** single sign-on via your SAML 2.0 or OIDC-compliant identity provider — the same directory your TechWolf Console users sign in with. * **Connector auth:** OAuth 2.1 with PKCE, short-lived tokens scoped to your organization. * **Access changes:** every call is checked against Console permissions, so removing a user's access takes effect on their next call. ## The server The connector serves data only, holds nothing between calls, and runs no AI model. Reasoning happens in your own AI assistant, under your contract with that provider. ## Hosting * **Region:** pinned to a single AWS region, matched to your data residency requirement. * **Network:** outbound traffic is limited to AWS services, the named sub-processors listed in the DPA, and TechWolf's data products. * **Encryption:** TLS 1.2+ in transit, AES-256 at rest. ## Retention * **Workforce data:** kept for the life of your contract, deletable on request. * **Chat history:** governed by your own agreement with your AI assistant's provider. * **Operational logs** (caller, tool, reason): aggregate use only. ## MCP gateways Some organizations route their AI assistants' MCP connections through a central proxy, an MCP gateway, to keep control over which connections exist and who uses them. The connector is a standard remote MCP endpoint — streamable HTTP with OAuth 2.1, PKCE, and Dynamic Client Registration — and is designed to work behind any gateway that forwards each user's own login rather than a shared service credential. The identity the gateway forwards must come from the same directory your TechWolf Console users sign in with, since permissions are keyed on that identity. TechWolf confirms compatibility with your specific gateway before rollout. ## Prompt injection The connector is read-only and every tool has a fixed destination inside TechWolf. No tool can fetch an arbitrary URL, send data, or change anything, so an injected prompt has nothing to modify and no way to move data out through the connector. ## Certifications and compliance * **Certifications:** ISO/IEC 42001, ISO/IEC 27001 (public certificate at [techwolf.ai/iso-certificate](https://techwolf.ai/iso-certificate)), SOC 2. * **Compliance:** GDPR, CCPA, nFADP. * **Trust center:** [trust.techwolf.ai](https://trust.techwolf.ai) # File guidelines Source: https://developers.techwolf.ai/integrations/reference/file-guidelines ## Input file naming When uploading files to the TechWolf platform, the following naming conventions should be followed. > [!NOTE] > > We recommend following this format as much as possible, as this allows for the > most fluent integrations. However, even some of our standard integrations may > diverge from this format due to limitations of the source system. ### Dynamic files Dynamic files are files containing entity information at a certain point in time. Dynamic files of the same type, meaning that they represent the same entity, are distinguished by their filename date or time. The components are of the format `_.`, where: * `prefix` is a descriptive name of the file. For all files representing the same entities but on different dates, the prefix should be equal. * `datetime` is the date in the format: * `YYYYMMDD` (`20011231` for the 31st of December, 2001). * `YYYYMMDD_HHMMss` (`20011231_235959` for the 31st of December, 2001 at 23:59:59). * `extension` is the file extension. `.csv` is preferred. A dynamic filename could look as follows: ```text theme={null} TechWolf_Employee_Information_20220101.csv TechWolf_Learning_Data_20250110_193000.csv ``` #### Incremental files When providing incremental files for our datasource integrations, the prefix should contain information on what is being provided. We use the following setup, building on the setup above: ```text theme={null} __. ``` or ```text theme={null} TechWolf_Learning_Data_20250110_193000_full.csv TechWolf_Learning_Data_20250110_193000_delta.csv ``` If no `full|delta` is provided, we will treat files for integrations configured as differential to be of the `delta` type. ## CSV CSV (comma-separated values) files are encoded as per the specifications of [RFC 4180](https://datatracker.ietf.org/doc/html/rfc4180). In particular: * Records (i.e. rows) are separated by a line break (CRLF, '\r\n') (cfr. RFC 4180 §2.1) * Fields within records are separated by commas (',') (cfr. RFC 4180 §2.4) * Each field is enclosed in double quotes (as allowed by RFC 4180 §2.5 - §2.6) * Double quotes inside fields (which, as detailed above, are already enclosed in double quotes in their entirety) are escaped by being preceded with another double quote. Additionally, fields that would normally start with a '=', '-', '+' or '@' symbol (or a *Tab* (0x09, \t) or *Carriage return* (0x0D, \r) character) are escaped with a '\`' character. This is since many CSV-based programs such as Microsoft Excel or LibreOffice Calc automatically interpret any field that starts with one of these symbols as a formula and try to evaluate it instead of simply showing the field as is (cfr. [OWASP - Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Injection_Prevention_Cheat_Sheet.html)). # How SFTP works Source: https://developers.techwolf.ai/integrations/reference/sftp/how-sftp-works A short, non-technical explanation of how SFTP secures file transfer and where each part of the trust model lives in the TechWolf flow. For full specifications, see [RFC 4251](https://datatracker.ietf.org/doc/html/rfc4251) (SSH Protocol Architecture) and [RFC 4252](https://datatracker.ietf.org/doc/html/rfc4252) (SSH Authentication Protocol). The [SSH.com SFTP overview](https://www.ssh.com/academy/ssh/sftp-ssh-file-transfer-protocol) is a good visual primer. # What SFTP is SFTP (SSH File Transfer Protocol) carries file operations over a single encrypted SSH channel on TCP port 22. The same channel handles authentication, listing, reading, and writing. # Keys: who holds what An SSH keypair has two halves: * The **private key** proves identity. It must never leave the system that owns it. * The **public key** is not a secret. It can be shared freely. It lets a server recognise an inbound private key without revealing anything sensitive. In the TechWolf self-service flow: * TechWolf **generates the keypair** in the Console, on the **Keys** tab of a server. * TechWolf **keeps the private key** in its database. The private key is never exported and never displayed. * The customer receives the **public key** and installs it in the `authorized_keys` file of the configured user on the SFTP server. * On every connection, TechWolf signs a server challenge with the private key. The customer's SFTP server verifies that signature with the public key it has on file. The private key crosses the network only as a signature, never as the key material itself. # Host key: server identity The customer's SFTP server has its own keypair, separate from the client's. The server presents its **public host key** every time a client connects. On the first successful connection, TechWolf captures the SHA256 fingerprint of that host key and pins it on the connection. Every later connection must present the same fingerprint, or TechWolf aborts the connection before any credentials are sent. This protects against man-in-the-middle attacks: even with valid client credentials, an attacker cannot impersonate the customer's SFTP server without also holding the matching host private key. # The connection flow ```text theme={null} TechWolf SFTP worker Customer SFTP server (client) (server) | | | 1. TCP connect on port 22 | | -----------------------------------------------> | | | | 2. Server presents its public host key | | <----------------------------------------------- | | Client compares SHA256 fingerprint against | | the pinned value. Mismatch -> abort. | | | | 3. Client authenticates | | -----------------------------------------------> | | Signs a challenge with its private key, | | or sends a password. | | | | 4. LIST remote folder | | <----------------------------------------------> | | | | 5. GET file, upload to TechWolf storage | | <----------------------------------------------- | | | ``` # Further reading * [RFC 4251: SSH Protocol Architecture](https://datatracker.ietf.org/doc/html/rfc4251) * [RFC 4252: SSH Authentication Protocol](https://datatracker.ietf.org/doc/html/rfc4252) * [OpenSSH `authorized_keys` format](https://man.openbsd.org/sshd.8#AUTHORIZED_KEYS_FILE_FORMAT) # Security Source: https://developers.techwolf.ai/integrations/reference/sftp/security Security principles that apply to self-service SFTP connections. For background on how the keys and host-key pinning work, see [How SFTP works](/integrations/reference/sftp/how-sftp-works). # Host-key pinning The first successful connection to a customer SFTP server captures the SHA256 fingerprint of the server's host key. The fingerprint is then locked on the connection. Every later connection compares the server's presented host key against the pinned fingerprint. A mismatch aborts the connection before any credentials are sent. A legitimate host-key change (a server reinstall, a planned key rotation) requires an operator to re-test the connection and re-lock the new fingerprint from the **Setup** tab of the server. # SSH key preferred over password SSH-key authentication uses a cryptographic signature. The private key never leaves the system that owns it, and the public key on the server reveals nothing exploitable. Password authentication transmits the secret on every connection, even over the encrypted SSH channel. It is more vulnerable to credential reuse, weak passwords, and slow leaks. TechWolf strongly recommends SSH-key authentication for all production servers. Password authentication is provided only for legacy SFTP servers that cannot accept public keys. # Key rotation without downtime Multiple active SSH keys per server are supported. A safe rotation flow: 1. Generate a new keypair from the **Keys** tab of the server. Install the new public key on the SFTP server alongside the existing one. 2. Wait one scheduler tick and confirm the server is **Healthy** on the overview. 3. Revoke the old key from the **Keys** tab. The connection keeps working throughout the rotation. # Path safety Folder mappings reject any path segment equal to `..`. Mappings cannot escape the declared remote path on the SFTP server. # Audit trail Every successful file pull is logged with its filename and timestamp. The log is visible on the **History** tab of each server, and is the source of the read-once guarantee described in [Behaviour](/integrations/reference/sftp/sftp#behaviour-of-a-customer-hosted-connection). # SFTP Source: https://developers.techwolf.ai/integrations/reference/sftp/sftp TechWolf supports SFTP for file-based integrations: a TechWolf-hosted server, and customer-hosted servers. This page covers both, and describes the behaviour of customer-hosted connections configured in the Console. # TechWolf-hosted SFTP server TechWolf operates an SFTP server that maps each user's root directory to a directory in TechWolf's S3 infrastructure. Several integrations use it to exchange files with TechWolf. ## Server details | Region | Server address | Static IP addresses | Port | | - | - | - | - | | EU | eu3.sftp.techwolf.ai | 13.38.145.100, 15.188.45.53 | 22 | | US | us3.sftp.techwolf.ai | 52.203.212.226, 54.83.27.174 | 22 | Use the static IP addresses for allowlisting when a customer's source system requires network-level access rules. ## Access Customers can request access from TechWolf. TechWolf provides credentials specific to the integration, either a username and password or a username and SSH key, depending on the integration's security requirements. For SAP SuccessFactors Integration Center schedules, the SSH key is generated in SAP. See [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center). # Customer-hosted SFTP server A customer can use their own SFTP server. It is configured from the **SFTP Configuration** page in the Console by the customer, an implementation partner, or TechWolf Professional Services. This configuration flow currently applies only to **input** integrations on **customer-hosted** servers. It does not cover the TechWolf-hosted SFTP server above, nor file-based [exports](/integrations/file-based-output/overview). ![SFTP Configuration overview with one connected server](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/10-overview-with-card.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=7bfa4622616f8abd4836632ef8b59f4f) For background on how SFTP works (keys, host-key pinning, connection flow), see [How SFTP works](/integrations/reference/sftp/how-sftp-works). For the trust model and recommended practices, see [Security](/integrations/reference/sftp/security). For step-by-step setup instructions, see [Self-service SFTP setup](/integrations/reference/sftp/self-service-setup). # Behaviour of a customer-hosted connection The points below describe behaviour that affects day-to-day use of a customer-hosted SFTP connection configured in the Console. * **Files are pulled once.** Each filename is pulled at most one time per server and recorded in the pull log. Re-uploading the same content under a new filename is required if a re-pull is needed. * **TechWolf never deletes files on the customer SFTP server.** Retention of data on the SFTP server is the customer's responsibility. * **Schedule.** Pulls run on a cron schedule, evaluated in UTC. The default is every 30 minutes (`*/30 * * * *`). After a missed tick (for example after a worker outage), the next tick fires as soon as possible rather than waiting another full interval. * **Host-key pinning is enforced.** Once a connection's host-key fingerprint is locked, a mismatching fingerprint on the server side aborts every future connection until an operator re-tests and re-locks. * **Folder mappings** route a remote path on the SFTP server to a destination subpath that file-based input integrations consume. See [File Organization](/integrations/reference/file-structure). * **Disable versus delete.** Disabling a server pauses all pulls but keeps mappings, keys, and history. Deleting a server is irreversible and removes its pull history. * **Per-mapping toggle.** Mappings can be paused individually without touching the rest of the connection. * **The file browser is read-only and independent of the scheduler.** Browsing a remote folder never marks files as pulled. * **Pull history.** Each successful pull is logged with its filename and timestamp, and is available on the **History** tab of the server. # How It Works Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/how-it-works ## Data Flow * The SAP BTP Skill Sync brokers all communication between TechWolf and SAP SuccessFactors through three Integration Flows deployed in the customer's SAP Integration Suite. Every request passes through a customer-owned iFlow, so TechWolf never calls SuccessFactors APIs directly. * The iFlows authenticate to SuccessFactors using an OAuth 2 SAML Bearer Assertion, backed by a customer-managed X.509 certificate stored in the BTP Keystore. TechWolf authenticates to the iFlows using OAuth 2 Client Credentials, backed by the Process Integration Runtime service key created during installation ([Employees ](/integrations/sap-btp-skill-sync/installation-employees) / [Jobs ](/integrations/sap-btp-skill-sync/installation-jobs)). * Employee and Job Skills are synchronized in a bidirectional flow, where Employee and Job Skill data updates in the TechWolf SkillEngine API are synchronized in real-time to SAP SuccessFactors using the iFlows, following a push strategy. * TechWolf-originated Employee Skill Profile updates are pushed to SAP SuccessFactors Growth Portfolios using the **Update Employee Growth Portfolio** Integration Flow. * TechWolf-originated Job Skill Profile updates are pushed to SAP SuccessFactors Job Role Skill Mappings using the **Update RoleSkillMappingEntity** Integration Flow. * SAP SuccessFactors updates to Job Skill Profiles are synced at regular intervals to the SkillEngine API using a TechWolf-initiated pull strategy. * The frequency by which SAP SuccessFactors Skills are synchronized to TechWolf is configurable, but bi-hourly by default. * TechWolf pulls the current state of the Job Role Skill Mappings from SAP SuccessFactors using the **Query RoleSkillMappingEntity** Integration Flow. * Job Skills synced by the SAP BTP Skill Sync are tracked using the `source` field in the [Job Skill Profile Feedback endpoint ](/reference/latest/Jobs/JobProfile/patch-job-architecture-jobs-job-external-id-skill-profile) payload, tagged as `"sap-integration"`. To retrieve these sources from a Job, use the [List Job Profile Data endpoint ](). Items with `"data_type": "skill_profile_feedback"` and `"source": "sap-integration"` indicate Skills synced by the SAP BTP Skill Sync. * Employee Skills synced by the SAP BTP Skill Sync are tracked using the `source` field in the [Employee Skill Profile Feedback endpoint ](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile) payload, tagged as `"sap-integration"`. To retrieve these sources in an Employee's profile, use the query parameter `?include=sources` in the [Employee Skill Profile Feedback endpoint ](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile), which returns the Skill's `source_event` with `"event_type": "skill_profile_feedback"` and `"source": "sap-integration"`. * Every iFlow-brokered call carries the TechWolf **AIR key** in its request header so SAP SuccessFactors can attribute traffic to the TechWolf Skill Sync partner solution. In summary: TechWolf uses the three iFlows in your SAP Integration Suite as the single integration surface to SuccessFactors. Job Skill Profiles sync bidirectionally (real-time push from TechWolf, bi-hourly pull into TechWolf). Employee Skill Profiles sync in near-real time from TechWolf to SuccessFactors via the Talent Intelligence Hub REST API. The latest state of the Employee Growth Portfolios is also propagated to TechWolf through a file-based sync. All file-based integrations are managed through the SAP Integration Center. ## Configuration Options ### Sync Direction The integration supports three sync direction options, specifying which data flow directions are allowed: 1. **TechWolf - SAP Bidirectional Sync** (default): Two-way sync between TechWolf and SAP SuccessFactors; changes made in TechWolf Skill Profiles are synchronized to their corresponding SAP SuccessFactors Skill Profiles, and vice versa. 2. **TechWolf to SAP Unidirectional Sync**: Skills flow from TechWolf to SAP SuccessFactors only; changes made in TechWolf Skill Profiles are copied to their corresponding SAP SuccessFactors Skill Profiles, while changes made in SAP SuccessFactors are discarded and overwritten with the state of the TechWolf Skill Profiles. 3. **SAP to TechWolf Unidirectional Sync**: Skills flow from SAP SuccessFactors to TechWolf only; changes made in SAP SuccessFactors Skill Profiles are copied to their corresponding TechWolf Skill Profiles, while changes made in TechWolf are discarded and overwritten with the state of the SAP SuccessFactors Skill Profiles. ### Initial Load Merge Strategy For the correct functioning of the normal operation of the integration, the Skill Profiles in both systems should be initially aligned. The integration will do this initial alignment itself automatically when the integration is first enabled, or when it is re-enabled after having been paused, or when it encounters an entity it had no knowledge about yet. The initial alignment can happen in different ways; we support three such merge strategy options: 1. **Merge Systems**: Combines Skills from both SAP SuccessFactors and TechWolf systems. Skills present in SAP SuccessFactors but not in TechWolf will be synced to TechWolf, and vice versa. This preserves existing Skill data in both systems. TechWolf takes precedence over SAP SuccessFactors in case of conflicting values (e.g. conflicting proficiency levels). 2. **Push TechWolf**: Replaces all Skills in SAP SuccessFactors with the Skill data from TechWolf. This strategy clears existing SAP SuccessFactors Skills before importing TechWolf data. 3. **Push SAP**: Replaces all Skills in TechWolf with the Skill data from SAP SuccessFactors. This strategy clears existing TechWolf Skills before importing SAP SuccessFactors data. # How To: Find the SAP identifier for a skill Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/how-to-find-a-skill-id **1. Navigate to the Attributes Library** Search for `Manage Talent Intelligence Hub`, and navigate to the Attributes tab. This is the default starting tab when navigating to the Talent Intelligence Hub management view. ![Attributes Library: Navigate to the Attributes tab](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_skills.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=7089dd98165c29b9a2a50b09fc68373d) **2. Find the skill** In the list of attributes, find the desired skill. This can be made easier by using the filters at the top of the page: * The `Search` field can be used to search for a skill by name. * The `Attribute Type` filter can be used to only show skills (`Skill`). * The `Status` filter can be used to only show active attributes (`Active`). After configuring the filters, click on `Go` to apply them. > [!NOTE] > > When selecting an arbitrary skill attribute for testing, ensure it is indeed a skill (`Attribute Type` is `Skill`) and it is active (`Status` is `Active`). **3. Find the relevant identifier for the skill** Attributes in SAP SuccessFactors can be uniquely identified in three separate ways: their Name, their External Code, and their ID. Different situations will require the use of different identifiers: * For the Employee Skill Sync, the External Code is used. * For the Job Skill Sync, the ID is used (this ID is also referred to as the `WSM ID`). * For the Skills Taxonomy Sync, all three identifiers are used, with the Name being used as the primary identifier. ![Attributes Library: Skill Details](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_skill_details.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=247bcb68787c6e481928a9ff77e324c6) # How To: Find the SAP SuccessFactors Company ID and API URL Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/how-to-find-company-id-and-api-url This guide walks through locating the Company ID and API URL of your SAP SuccessFactors environment. You will need the API URL when configuring the Token Service URL and iFlow Address values in SAP Integration Suite. ### 1. Find out the correct SAP SuccessFactors Company ID * As an SAP administrator, log into the SAP SuccessFactors environment you want to configure the integration for. * Click on your profile icon in the top right corner and select "Show version information". ![Show version information](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/show_version_information.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=d00d6d291c06ba2610cd40c3245b197e) * The Company ID will be shown in the resulting window. ![Version Information](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/version_information.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=d3ec199eed78d611677d741fe3aff130) ### 2. Find out the correct SAP SuccessFactors API URL * As an SAP administrator, go to [SAP for Me ](https://me.sap.com/systemsprovisioning/systems) (if you have multiple credentials, sign in with your S-User credentials). * In the *Public Cloud Systems* table, find the system you want to configure the integration for. * This system should have the value "SAP SuccessFactors HCM" in the `Cloud Service` column. * The `Data Center` column will show the location of the data center of the system, e.g. "Netherlands: Eemshaven". ![List of Systems](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/list_of_systems.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=9e6a58a485c0abcb25f291722cc9c975) * Go to the [List of SAP SuccessFactors API Servers ](https://help.sap.com/docs/successfactors-platform/it-landscape-requirements-for-sap-successfactors/list-of-sap-successfactors-api-servers) * In the *API Servers* table, find your Data Center. * This Data Center should have the previously determined data center location as the value of the `Location` column. Note that the location name might differ in format from the location name in the previous step, e.g. "Eemshaven, The Netherlands" vs "Netherlands: Eemshaven". Among all rows with this location, find the row with the appropriate value for the `Environment` column. * The `API Server` column will show the API URL for the API Server. ![List of API Servers](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/list_of_api_servers.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=1dec8af8effbbce0046f867c5d4b1343) # How To: Manage the Skill Proficiency Rating Scale in SAP SuccessFactors Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/how-to-manage-proficiency-rating-scale ## Viewing the Skill Proficiency Rating Scale **1. Navigate to the rating scales in the Attributes Library** Search for `Manage Talent Intelligence Hub`, and navigate to Proficiency Settings > Rating Scale. ![Attributes Library: Navigate to Proficiency Settings > Rating Scale](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_rating_scale.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=445b9694eeceff434e64fe0161c0866b) **2. Filter the rating scales for the skill attribute type** In the filters at the top of the page, find the `Attribute Type` filter. Click the icon in the filter box to open the dropdown menu, and select `Skill`. Click on `Go` to apply the filter. The rating scales for the skill attribute type will now be visible. Ensure that the rating scale is active. ![Skill proficiency rating scale](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/skill_proficiency_rating_scale.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=b4ec673a31307a1ccdcbcd2fe38964ab) ## Creating a new Skill Proficiency Rating Scale > [!WARNING] > > Proficiency rating scales cannot be deleted once created, only deactivated. > We advise against creating a new scale unless you are sure you need it. **1. Navigate to the rating scales in the Attributes Library** Search for `Manage Talent Intelligence Hub`, and navigate to Proficiency Settings > Rating Scale. ![Attributes Library: Navigate to Proficiency Settings > Rating Scale](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_rating_scale.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=445b9694eeceff434e64fe0161c0866b) **2. Create a new proficiency rating scale** Click on the `Create` button in the top right corner of the Rating Scale table. Fill in required fields and select the required options: * Name: The name of the proficiency rating scale. * Description: The description of the proficiency rating scale. * Include `Too new to rate` (`Yes` or `No`): Check this option if you want to include a level for skills that are too new to rate. Note that this is not natively supported by the TechWolf integration, so we recommend setting this to `No`. * Number of Levels (`1` - `10`): The number of levels in the proficiency rating scale. * Lowest Level Value (`0` or `1`): The value of the lowest level in the proficiency rating scale. * Status (`Active` or `Inactive`): The status of the proficiency rating scale. When creating a new scale to use in the integration, you should use the `Active` status. Additionally, you can give a name and an optional description to each level. Once you have filled in the required fields, click on the `Create` button in the bottom right corner of the page. ![Create proficiency rating scale](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/create_proficiency_rating_scale.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=ee4322d9844e78f1482e50e1210b906d) **3. Associate the proficiency rating scale to the skill attribute type** Navigate to the Attribute Types with the Talent Intelligence Hub management view. In the filters at the top of the page, enter `Skill` in the default, left-most field. Click on `Go` to apply the filter. Find the `Skill` attribute type, and select it. A new tab should open to the side, showing the details of the attribute type. Click the `Edit` button in the top right corner of this tab. ![Attribute Library: Skill Attribute Type](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_attribute_type.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=52ac3d370b7489d929f1a6d76311f30f) In the resulting edit page, find the `Proficiency Level Scale` field, and select the proficiency rating scale you just created from the dropdown menu. Click the `Save` button in the bottom right corner of the page to save the changes. ![Associate proficiency rating scale with skill attribute type](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/associate_rating_scale_with_skills.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=38a55527a6dd21d5b4a2499d74892f07) # How To: Register TechWolf as a Trusted Data Source in SAP SuccessFactors Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/how-to-register-data-source This guide walks through the one-time configuration required to enable TechWolf as a data source, link the integration user to it, and mark the TechWolf data source as trusted, so the TechWolf - SAP SuccessFactors integrations run end-to-end without a manual review step for every update. More information can be found in the [SAP Help Portal ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/talent-intelligence-hub?locale=en-US). > [!NOTE] > > If your SAP SuccessFactors tenant does not expose the **Manage Data > Sources** task or a **Manage Skills Governance** section under **Manage > Talent Intelligence Hub**, your release predates these controls and no > additional setup is needed for now. This setup may still become required in > future releases. ## Prerequisites * You have already created the `TechWolf_TIH_GP` integration user and the OAuth2 Client Application, and assigned the base Permission Role to the user (see the **Installation** guide for your integration). * The SAP administrator performing this setup has, or can be granted, permissions to manage Talent Intelligence Hub settings. See the SAP Help Portal page on [Permissions Required for Using Talent Intelligence Hub ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/permissions-required-for-using-talent-intelligence-hub?locale=en-US) for the complete list. In practice, granting all permissions under **Administrator Permissions** → **Manage Talent Intelligence Hub Settings** covers everything needed for the steps below. ## Steps **1. Activate the TechWolf data source** In the search bar at the top of SAP SuccessFactors, enter **Manage Data Sources** and open the task. In the list of registered data sources, locate the **TechWolf** entry and set its status to **Active**. Other data sources in the list can remain inactive; only the TechWolf data source needs to be active for this integration. See [Managing Data Sources ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/managing-data-sources?locale=en-US) on the SAP Help Portal for reference. **2. Assign the integration user to the TechWolf data source** In the search bar at the top of SAP SuccessFactors, enter **Manage Talent Intelligence Hub** and open the task. Navigate to **General Configurations** → **Settings** → **Manage Users for Data Sources**. For the **TechWolf** data source, click **Add** and search for the `TechWolf_TIH_GP` user. Select it and save. See [Settings Page ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/settings-page?locale=en-US) on the SAP Help Portal for reference. **3. Mark TechWolf as a trusted data source** Still on the **Manage Talent Intelligence Hub** page, open **General Configurations** → **Settings** → **Manage Skills Governance**. Mark the **TechWolf** data source as **trusted**. With this flag set, skill updates coming from TechWolf don't require additional manual review within SAP. See [Settings Page ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/settings-page?locale=en-US) on the SAP Help Portal for reference. # Installation Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/installation-employees ### Prerequisites Before continuing, ensure you have the following: * A valid TechWolf contract and access to a **live TechWolf tenant**. * This tenant must contain Employees corresponding to the Per Person entities present in SAP SuccessFactors. This can be achieved by either: * Using the Standard [Employee Data Input Integration ](/integrations/datasource-integrations/sap-standard-input-integration/overview). * Creating custom input integrations. When doing this, ensure the TechWolf SkillEngine API Employees are linked with their SAP Per Person counterparts by using the Per Person UUID (`perPersonUuid`) as the TechWolf Employee ID (`external_id`). Additionally, each TechWolf Employee should have a custom property called `person_id_external` with as value the `Person External ID` of the corresponding PerPerson entity in SAP SuccessFactors. More information on custom properties can be found in the [API Reference ](https://developers.techwolf.ai/reference/latest/Custom%20Properties/CustomPropertiesDefinitions/overview). * A working **SAP SuccessFactors** environment with [Talent Intelligence Hub ](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/e15477b0414b4b25b224a97ad52c12ec/ec345d8396d64bd0936a3cc8280098e0.html) enabled. * An SAP SuccessFactors administrator user with permission to **Manage OAuth 2 Client Applications** and to import employee data. * An SAP SuccessFactors user with the Integration Center permissions listed in Step 11, required to set up the Employee Growth Portfolio export schedule in the Integration Center. Preferably, this is a dedicated technical user. * A working **SAP BTP** tenant with **SAP Integration Suite** provisioned, including the *Build Integration Scenarios* capability. Your user must have the `PI_Administrator` and `PI_Integration_Developer` roles. For more information on setting up Integration Suite, refer to [the SAP community guide ](https://community.sap.com/t5/technology-blog-posts-by-members/step-by-step-guide-create-trial-account-for-sap-integration-suite-2025-amp/ba-p/14002055). * An **AIR key**, provided by your TechWolf representative. * The **Integration Suite Content Package** zip file, provided by your TechWolf representative. * Access to the TechWolf [SFTP server ](/integrations/reference/sftp/sftp) to host the Employee Growth Portfolio export files, with a password or an SSH key. See [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center). * A successful SAP support case to [whitelist the TechWolf SFTP server ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-whitelist-sap-sftp-server). > [!NOTE] > > The AIR key (Application Interface Register key) is an identifier SAP issues > to certified PartnerEdge partners. The iFlows pass it in the header of every > SuccessFactors API call so SAP can attribute traffic to the TechWolf Skill > Sync partner solution. It is an identifier, not a secret credential. > [!WARNING] > > The technical user ID `TechWolf_TIH_GP` is hardcoded. It must be used > verbatim in three places: as the Common Name (CN) of the certificate created > in Step 1, as the User ID of the SuccessFactors technical user created in > Step 2, and as the User ID bound to the OAuth 2 Client Application created > in Step 3. The SAML Bearer flow only succeeds if all three values match > exactly. > [!NOTE] > > If you already configured the > [SAP BTP Job Skill Sync ](/integrations/sap-btp-skill-sync/installation-jobs) > in the same BTP tenant, the shared BTP/SuccessFactors setup (Steps 1-3 and > Steps 5-9) is already in place. You can skip to Step 4 to add the > Employee-specific permissions, Step 10 to configure the Employee iFlow, and > Step 11 to set up the Employee Growth Portfolio export schedule. ## SAP BTP and SuccessFactors Configuration TechWolf has already pre-configured some parts of the integration. The following ZIP archive contains the necessary files that will be used in the subsequent steps to configure the integration in SAP BTP and SAP SuccessFactors. > **[Required files](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/skill-sync-integrations/sap-employee-skill-sync-required-files.zip)** > > Required files for the SAP BTP Employee Skill Sync Integration ### 1. Create a Certificate for authenticating to SuccessFactors * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > Keystore**, then click **Create > Key Pair**. * Set **Alias** to a value you will remember for Step 5 (e.g. `techwolf_skillsync_successfactors`). * Set **Common Name** to `TechWolf_TIH_GP` (hardcoded, see the warning above). * Set **Country** to the two-letter ISO 3166-1 alpha-2 code for your country (e.g. `BE` for Belgium, `US` for the United States). [List of ISO 3166-1 alpha-2 codes ](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). * (Optional) Change **Valid Until** to a date of your choice. * Leave all other fields on their default values. ![Create Key Pair form with Alias, Common Name, and Country filled in](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/create-key-pair-form.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=37c3a1362120aa4cad6ff1f1a168cc90) * Click **Create**. The new key pair appears in the Keystore overview. ![Keystore overview showing the newly created key pair](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/key-pair-created.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=3b1aa62f53e96e04fc18daa497ce051e) * Click the new key pair, then click **Download > Certificate**. Keep the downloaded certificate file available; you will paste its contents into SuccessFactors in Step 3. ### 2. Create the TechWolf integration user in SuccessFactors * In the search bar at the top right of SAP SuccessFactors, enter `Import Employee Data`. * In the resulting window, under the `Select an entity` dropdown, choose "Basic Import". In the `Choose File` field, upload the `techwolf_api_user_definition.csv` file from the required-files zip downloaded above. ![Import API user definition](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/import_api_user_definition.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=fc722e49183f6cd26475b71c4b24c5d7) * Leave the other fields unchanged and click `Validate Import File Data`. If the validation is successful, click `Import`. > [!NOTE] > > If you already created a TechWolf User for another TechWolf - SAP > SuccessFactors integration, this step can be skipped. ### 3. Configure the permissions for the TechWolf user The `TechWolf_TIH_GP` user needs a Permission Group and a Permission Role to run the Skill Sync. > [!NOTE] > > If another TechWolf - SAP SuccessFactors integration using the > `TechWolf_TIH_GP` user has already been configured in this tenant, the > Permission Group and Permission Role already exist. Skip the group creation > and role assignment steps below and only **add the missing permissions** > from the table to the existing Permission Role. * **Create a Permission Group** * In the search bar at the top, enter `Manage Permission Groups` and open it. * Click `Create New`. * Name the group `TechWolf_TIH_GP`. * Pick the `Username` filter and set it equal to `TechWolf_TIH_GP`. * Click `Done`. ![Create Permission Group](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/permission_group_creation.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=8a11b0ab859fb51da11843cba3790c10) * **Create a Permission Role** * In the search bar at the top, enter `Manage Permission Roles` and open it. * Create a new Role with user type `Employee`. * Under `User Permissions` → `Growth Portfolio`, grant the following: | Permission | Access | | - | - | | Attribute | View | | Growth Portfolio | View, Edit, Create, Delete, Edit Proficiency Level, Mark as passionate | | Proficiency Level Scale | View | ![Growth Portfolio](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/permission_role_user_permissions_employee.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=a342df6e4f19a170f2a984170a866044) * Under `Administrator Permissions` → `Manage Talent Intelligence Hub Settings`, grant the following: | Permission | | - | | Import/Export Talent Intelligence Hub and Growth Portfolio Data | ![Manage Talent Intelligence Hub Settings](https://mintcdn.com/techwolf/XjYy6ojjLYiImuAD/integrations/sap-skill-sync-integration/images/permission_role_admin_permissions_employee.png?fit=max\&auto=format\&n=XjYy6ojjLYiImuAD\&q=85\&s=7582026930e818bfb1af117d69acf981) * Save the Permission Role. * **Assign the Permission Role to the Permission Group** * On the saved Permission Role, click `Add Role Assignments`. * Click `Next`. * On the `Grant Access To` page, select `From Groups`. * Click `Select Groups` and pick the `TechWolf_TIH_GP` group created above. * Click `Next`, then `Next` again, and save the Role Assignment. ![Role Assignment](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/role_assignment_groups.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=b960b0b2cf3026ad6ceb7c97b70f78c5) > [!NOTE] > > On recent SAP SuccessFactors releases, the Talent Intelligence Hub adds data > source governance for external skill providers. If your tenant exposes the > **Manage Data Sources** task or a **Manage Skills Governance** section under > **Manage Talent Intelligence Hub**, complete > [How To: Register TechWolf as a Trusted Data Source ](/integrations/sap-btp-skill-sync/how-to-register-data-source) > so Growth Portfolio updates from TechWolf flow through without additional > manual review. ### 4. Set up an OAuth 2 Client Application in SuccessFactors * In SuccessFactors, in the search bar at the top right, enter `Manage OAuth 2 Client Applications` and press enter. * Click **Register Client Application**. * Fill in the following fields: * **Application Name**: any value (e.g. `techwolf_skillsync_successfactors`). * **Application URL**: any valid URL (e.g. `https://www.techwolf.ai`). * **Bind to Users**: check the checkbox. * **User IDs**: `TechWolf_TIH_GP`. * **X.509 Certificate**: paste the contents of the certificate downloaded in Step 1. Remove the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` guards if present, and strip any line breaks so the value is a single continuous string. ![Register Client Application form with the required fields filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/oauth-client-register-form.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=e36e9a5e8dffb2674f7f00e62572d5b7) * Click **Register**. The Client Application appears in the overview. ![Manage OAuth 2 Client Applications overview showing the registered application](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/oauth-client-created.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=d8cc2bff4ca56653b4edd74467ca4ccb) * Click **View** on the new Client Application and copy the **API Key**. You will need it in Step 5. ![Client Application detail view showing the API Key](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/oauth-client-api-key.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=fca1c7b6c3b630228c087de924c2a5e4) ### 5. Configure the API credentials in SAP Integration Suite * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > Security Material** and click **Create > OAuth 2 SAML Bearer Assertion**. * Set **Name** to a value you will remember for Step 10 (e.g. `techwolf_skillsync_successfactors`). * Set **Audience** to `www.successfactors.com`. * Set **Client Key** to the API Key copied in Step 3. * Set **Token Service URL** to the base URL of your SuccessFactors tenant, appended with `oauth/token`. See [How To: Find the SAP SuccessFactors Company ID and API URL ](/integrations/sap-btp-skill-sync/how-to-find-company-id-and-api-url) for how to look up the base URL. * Set **User ID** to **Key pair Common Name (CN)**. * Set **Key Pair Alias** to the alias of the key pair created in Step 1 (e.g. `techwolf_skillsync_successfactors`). ![Create OAuth 2 SAML Bearer Assertion form with all fields filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/saml-bearer-assertion-form.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=8d710cb16a2748acf9b9d91e519cd81b) * Click **Deploy**. ### 6. Create a User Role for the integration In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > User Roles**, then click **Add**. Enter a **Name** that you will remember for Step 7 and Step 10 (e.g. `TechWolfSkillSync.send`) and click **Add**. ![Add User Role dialog with a role name filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/user-role-add.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=6f73d8deb05680b92a82879c8fe9d03b) ### 7. Create a Process Integration Runtime instance In SAP BTP, create a new instance of the **Process Integration Runtime** service with the `integration-flow` plan. * Check *"I understand that enabling a service might result in costs, depending on the plan selected."* * **Runtime Environment**: Cloud Foundry. * **Space**: the Cloud Foundry space you're deploying in. * **Instance Name**: a CLI-friendly name (e.g. `techwolf-skillsync-integration-runtime`). ![Process Integration Runtime Basic Info step](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/process-integration-runtime-basic-info.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=643a0d74706311082dca84890edc396f) * Click **Next** to continue to the Parameters step. * In **Parameters**, set the role to the one created in Step 6 (e.g. `TechWolfSkillSync.send`). * **Grant-types**: `Client Credentials`. * Leave all other fields on their default values. ![Process Integration Runtime Parameters step with role and grant-type set](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/process-integration-runtime-params.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=ea4e1af6d74950b5f52a6dd2d76f217f) Click **Create**. ### 8. Create a Service Key on the instance Find the newly created Process Integration Runtime instance. Click the three dots on the right, then click **Create Service Key**. * **Service Key Name**: any value (e.g. `TechWolfSkillSync`). * **Key Type**: `ClientId/Secret`. * Leave all other fields on their default values. Click **Create**. On the instance, go to **Service Keys** and wait for the key to be created. ![Service Keys tab showing the newly created key](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/service-key-created.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=487919d2939cd78a9fdbfa3df0e0ded1) Click the service key, then click **Download**. ![Service Key detail view with Download button highlighted](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/service-key-download.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=6ce66b9abc99df23a262fd87f8952f1c) > [!WARNING] > > The service key file contains credentials that grant access to invoke your > iFlows. Store it securely and share it with your TechWolf representative via > 1Password (or another agreed secure channel). **Never share it over email or > chat.** ### 9. Import the Content Package In SAP Integration Suite, go to **Design > Integrations and APIs** and click **Import**. ![Design > Integrations and APIs screen with Import button highlighted](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/import-content-package.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=1a772e7e33a859b84e6a233d5c85860f) In the file picker, select the Content Package zip file provided by your TechWolf representative. ### 10. Configure the externalized parameters on the iFlow Open the imported package and go to **Artifacts**. ![Imported package Artifacts tab listing the three iFlows](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/artifacts-overview.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=d5e5b8fba575da35434bf2de26400705) For the **Update Employee Growth Portfolio** iFlow, click the three dots on the right and select **Configure**, then fill in the fields as described below. > [!NOTE] > > **Finding the SuccessFactors datacenter URL**: in the **Address** field, > click **Select** to see the list of valid SAP SuccessFactors data centers > and pick the one matching your tenant (e.g. > `https://apisalesdemo2.successfactors.eu`). See > [How To: Find the SAP SuccessFactors Company ID and API URL ](/integrations/sap-btp-skill-sync/how-to-find-company-id-and-api-url) > for how to look up this URL. After configuring the iFlow, click **Deploy**, then **Yes**. ![Deploy confirmation dialog](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/iflow-deploy-confirm.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=9a5db53b489dd45312d40bc4e65077b3) #### Update Employee Growth Portfolio in SAP SuccessFactors > [!WARNING] > > For this iFlow, the **Address** lives in **Tab More** rather than **Tab > Receiver**. This is by design; do not confuse it with the layout of the > iFlows for the Job Skill Sync integration. * **Tab Sender**: set **User Role** to the role created in Step 6 (e.g. `TechWolfSkillSync.send`). ![Update Employee Growth Portfolio: Sender tab with User Role filled in](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/iflow-update-employee-sender.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=a16ea986fe98e4eddc7f9c5605d14aab) * **Tab Receiver**: set **Credential Name** to the OAuth 2 SAML Bearer Assertion created in Step 5. ![Update Employee Growth Portfolio: Receiver tab with Credential Name filled in](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/iflow-update-employee-receiver.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=60b8360a5f187f82ee8e821e75d60599) * **Tab More**: set **Address** to the URL of your SuccessFactors datacenter, and **AIR\_key** to the AIR key provided by your TechWolf representative. ![Update Employee Growth Portfolio: More tab with Address and AIR\_key filled in](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/iflow-update-employee-more.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=4dc3edece1fb710f402bb8858f75b89f) ### 11. Create Employee Growth Portfolio Export Schedule Integration Center schedules run under the account of the user that creates them. Ensure this user has all permissions listed below before setting up the schedules. > [!NOTE] > > We recommend setting up the schedules with a dedicated technical user > rather than a named administrator account. Schedules created by a named > account break when that account is deactivated. An administrator creates > the technical user, grants it the permissions below, and proxies as it > while creating the schedules. Setting up the schedules directly as an > administrator with these permissions also works. The account used to set up the schedules must have at least the following permissions: * Under `User Permissions` → `Talent Intelligence Hub`: | Permission | Access | | - | - | | Attribute | View, Edit, Create | | Attribute Type | View, Edit, Create | | Growth Portfolio | View, Edit, Create, Edit Proficiency Level, Mark as passionate | | Proficiency Level Scale | View, Edit, Create | | Tag | View, Edit, Create | * Under `Administrator Permissions`: | Category | Permission | | - | - | | Admin Center Permissions | Read Execution Manager Events | | Admin Center Permissions | Read Execution Manager Event Payload or Event Report | | Manage Integration Tools | Allow Admin to Access OData API through Basic Authentication | | Manage Integration Tools | Access to Integration Center | | Manage Security Center | Access to Other Keys: View | | Manage Talent Intelligence Hub Settings | View Manage Talent Intelligence Hub Settings | | Manage Talent Intelligence Hub Settings | Import/Export Talent Intelligence Hub and Growth Portfolio Data | | Manage Talent Intelligence Hub Settings | Enable Growth Portfolio | | Manage Talent Intelligence Hub Settings | Change Proficiency Level Scale | | Manage Talent Intelligence Hub Settings | Growth Portfolio Rating Precedence | | Metadata Framework | Admin access to MDF OData API | SAP requires a target population for the Growth Portfolio permission, and target criteria for the Attribute Type and Tag permissions. Define these to cover all data in scope of the integration. As a user with the necessary permissions, follow the steps in [How To: Load Export Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions) to create a new export integration definition that will create an export of Employee Growth Portfolios. Use the values from the table below when setting up the integration definition. Preferably, the time of day of the `Start Time` of the schedule is set to be some time (e.g. one hour) after the time of day of the `Start Time` of the Attribute Import Schedule (Step 1) of the [Skills Taxonomy Sync ](/integrations/sap-skill-sync-integration/installation-skills-taxonomy). | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_employee_growth_portfolio_export_definition.icd` | | **File Name Prefix** | `EmployeeGrowthPortfolioExport` | | **Date Suffix Format** | `yyMMddHHmmssZ` | | **File Folder** | `/tih/exports/employee_growth_portfolio` | **Base ICD**: [Talent Intelligence Hub Growth Portfolio Export ](https://api.sap.com/package/TalentIntelligenceHubGrowthPortfolioExportTemplate/icd) > [!NOTE] > > The ICDs provided by TechWolf are based on the default integration definitions by SAP, as indicated by the **Base ICD** mentioned. > These have been pre-filled with some necessary values such as the file name prefix for your convenience, to ease the setup process. > TechWolf is committed to keeping these integration definitions up to date with the latest SAP SuccessFactors releases, but cannot guarantee full alignment with the SAP SuccessFactors release schedule. > Should issues arise when using these integration definitions, please contact [support@techwolf.ai](mailto:support@techwolf.ai). ### Verify the deployment * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Integration Content** and confirm that all deployed iFlows show the **Started** status. * Go to **Monitor > Integrations and APIs > Monitor Message Processing** to watch messages as TechWolf triggers the iFlows. Failed messages include the HTTP response from SuccessFactors, which is the fastest way to diagnose authentication or permission issues (e.g. expired certificate, missing SuccessFactors permission, incorrect AIR key). ## TechWolf Configuration The TechWolf tenant will be configured by TechWolf itself. To complete the setup, share the following values with your TechWolf representative: * The downloaded **service key file** from Step 8 (via 1Password or another agreed secure channel). TechWolf will then link your SAP Integration Suite to your TechWolf tenant, enable the schedule to consume the SAP SuccessFactors Growth Portfolio export files from the SFTP server, and start the initial sync. ## Routing Through an API Gateway If your organisation fronts the SAP BTP APIs with an API gateway, the integration can call the gateway instead of the vendor host directly. Two settings are available, both configured by TechWolf together with the credentials: * **Custom URL**: instead of the vendor API URL, share the gateway URL that proxies it. The integration keeps appending the same vendor API paths to it, so the gateway must forward requests to SAP BTP unchanged. * **Custom headers**: any number of extra HTTP headers (for example an API key or a correlation ID required by the gateway) that are sent on every request the integration makes. > [!NOTE] > > Both settings are pass-through only. TechWolf sends the values as configured > and does not perform any gateway-specific authentication, signing, or token > refresh; the gateway is expected to forward the integration's own > credentials to SAP BTP. Reserved headers (e.g. `Authorization`, > `Content-Type`) are managed by the integration and cannot be set as custom > headers. ## Configuration Options ### Sync Direction Settings The integration supports three sync direction options: * **Bidirectional** (default): Two-way sync between TechWolf and SAP SuccessFactors; changes made in TechWolf Employee Skill Profiles are synchronized to their corresponding SAP SuccessFactors Growth Portfolios, and vice versa. * **TechWolf to SAP Only**: Skills flow from TechWolf to SAP SuccessFactors only; changes made in TechWolf Employee Skill Profiles are copied to their corresponding SAP SuccessFactors Growth Portfolios, while changes made in SAP SuccessFactors are discarded and overwritten with the state of the TechWolf Employee Skill Profiles. * **SAP to TechWolf Only**: Skills flow from SAP SuccessFactors to TechWolf only; changes made in SAP SuccessFactors Growth Portfolios are copied to their corresponding TechWolf Employee Skill Profiles, while changes made in TechWolf are discarded and overwritten with the state of the SAP SuccessFactors Growth Portfolios. ### Merge Strategy Options For the correct functioning of the normal operation of the integration, the Employee Skill Profiles in both systems should be initially aligned. The integration will do this initial alignment itself automatically when the integration is first enabled, or when it is re-enabled after having been paused, or when it encounters an Employee it had no knowledge about yet. The initial alignment can happen in different ways; the integration supports three such merge strategy options: * **Merge Systems**: Combines Skills from both systems. In case of metadata conflicts for Skills present in both systems (e.g. conflicting proficiency levels), the values from TechWolf will be used. * **Push TechWolf**: Uses the TechWolf Employee Skill Profile as the initial source of truth, and will align the SAP SuccessFactors Growth Portfolio with it. Any Skills initially present in the SAP SuccessFactors Growth Portfolio but not in the TechWolf Employee Skill Profile will be removed from the SAP SuccessFactors Growth Portfolio. * **Push SAP**: Uses the SAP SuccessFactors Growth Portfolio as the initial source of truth, and will align the TechWolf Employee Skill Profile with it. Any Skills initially present in the TechWolf Employee Skill Profile but not in the SAP SuccessFactors Growth Portfolio will be removed from the TechWolf Employee Skill Profile. ## Deployment Tasks & Responsibilities 1. **TechWolf**: Setup Skill Sync environment and tenant requirements. 2. **Customer**: Configure SAP BTP and SAP SuccessFactors as described above. 3. **Customer**: Share the necessary values with TechWolf: * The service key file from Step 8. 4. **TechWolf**: Validate API access by calling the iFlow end-to-end. 5. **TechWolf**: Enable the schedule to consume the SAP SuccessFactors Growth Portfolio export files from the SFTP server. 6. **TechWolf**: Run the initial sync of Employee Skill Profiles with the TechWolf API. 7. **TechWolf**: Setup tenant configuration and start the sync process based on the configured direction. 8. **Customer**: Check end-user test scenarios. # Installation Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/installation-jobs ### Prerequisites Before continuing, ensure you have the following: * A valid TechWolf contract and access to a **live TechWolf tenant**. * This tenant must contain Jobs corresponding to the Job Roles present in SAP SuccessFactors. This can be achieved by either: * Using the [Standard Job Data Input Integration ](/integrations/datasource-integrations/sap-standard-input-integration/overview). * Writing custom input integrations. When doing this, ensure the TechWolf SkillEngine API Jobs are linked with their SAP SuccessFactors Job Role counterparts by using the SAP Job Role ID (`Role_GUID`) as the TechWolf Job ID (`external_id`). * A working **SAP SuccessFactors** environment with [Talent Intelligence Hub ](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/e15477b0414b4b25b224a97ad52c12ec/ec345d8396d64bd0936a3cc8280098e0.html) and [Job Profile Builder ](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/70097a1a469d47a0ae08809e4a240f98/172d1e58be474b8ab4c268c918b9d56c.html) enabled. * An SAP SuccessFactors administrator user with permission to **Manage OAuth 2 Client Applications** and to import employee data. * A working **SAP BTP** tenant with **SAP Integration Suite** provisioned, including the *Build Integration Scenarios* capability. Your user must have the `PI_Administrator` and `PI_Integration_Developer` roles. For more information on setting up Integration Suite, refer to [the SAP community guide ](https://community.sap.com/t5/technology-blog-posts-by-members/step-by-step-guide-create-trial-account-for-sap-integration-suite-2025-amp/ba-p/14002055). * An **AIR key**, provided by your TechWolf representative. * The **Integration Suite Content Package** zip file, provided by your TechWolf representative. > [!NOTE] > > The AIR key (Application Interface Register key) is an identifier SAP issues > to certified PartnerEdge partners. The iFlows pass it in the header of every > SuccessFactors API call so SAP can attribute traffic to the TechWolf Skill > Sync partner solution. It is an identifier, not a secret credential. > [!WARNING] > > The technical user ID `TechWolf_TIH_GP` is hardcoded. It must be used > verbatim in three places: as the Common Name (CN) of the certificate created > in Step 1, as the User ID of the SuccessFactors technical user created in > Step 2, and as the User ID bound to the OAuth 2 Client Application created > in Step 3. The SAML Bearer flow only succeeds if all three values match > exactly. > [!NOTE] > > If you already configured the > [SAP BTP Employee Skill Sync ](/integrations/sap-btp-skill-sync/installation-employees) > in the same BTP tenant, the shared BTP/SuccessFactors setup (Steps 1-3 and > Steps 5-9) is already in place. You can skip to Step 4 to add the > Job-specific permissions, and then Step 10 to configure the Job iFlows. ## SAP BTP and SuccessFactors Configuration TechWolf has already pre-configured some parts of the integration. The following ZIP archive contains the necessary files that will be used in the subsequent steps to configure the integration in SAP BTP and SAP SuccessFactors. > **[Required files](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/skill-sync-integrations/sap-job-skill-sync-required-files.zip)** > > Required files for the SAP BTP Job Skill Sync Integration ### 1. Create a Certificate for authenticating to SuccessFactors * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > Keystore**, then click **Create > Key Pair**. * Set **Alias** to a value you will remember for Step 5 (e.g. `techwolf_skillsync_successfactors`). * Set **Common Name** to `TechWolf_TIH_GP` (hardcoded, see the warning above). * Set **Country** to the two-letter ISO 3166-1 alpha-2 code for your country (e.g. `BE` for Belgium, `US` for the United States). [List of ISO 3166-1 alpha-2 codes ](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). * (Optional) Change **Valid Until** to a date of your choice. * Leave all other fields on their default values. ![Create Key Pair form with Alias, Common Name, and Country filled in](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/create-key-pair-form.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=37c3a1362120aa4cad6ff1f1a168cc90) * Click **Create**. The new key pair appears in the Keystore overview. ![Keystore overview showing the newly created key pair](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/key-pair-created.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=3b1aa62f53e96e04fc18daa497ce051e) * Click the new key pair, then click **Download > Certificate**. Keep the downloaded certificate file available; you will paste its contents into SuccessFactors in Step 3. ### 2. Create the TechWolf integration user in SuccessFactors * In the search bar at the top right of SAP SuccessFactors, enter `Import Employee Data`. * In the resulting window, under the `Select an entity` dropdown, choose "Basic Import". In the `Choose File` field, upload the `techwolf_api_user_definition.csv` file from the required-files zip downloaded above. ![Import API user definition](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/import_api_user_definition.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=fc722e49183f6cd26475b71c4b24c5d7) * Leave the other fields unchanged and click `Validate Import File Data`. If the validation is successful, click `Import`. > [!NOTE] > > If you already created a TechWolf User for another TechWolf - SAP > SuccessFactors integration, this step can be skipped. ### 3. Configure the permissions for the TechWolf user The `TechWolf_TIH_GP` user needs a Permission Group and a Permission Role to run the Skill Sync. > [!NOTE] > > If another TechWolf - SAP SuccessFactors integration using the > `TechWolf_TIH_GP` user has already been configured in this tenant, the > Permission Group and Permission Role already exist. Skip the group creation > and role assignment steps below and only **add the missing permissions** from > the table to the existing Permission Role. * **Create a Permission Group** * In the search bar at the top, enter `Manage Permission Groups` and open it. * Click `Create New`. * Name the group `TechWolf_TIH_GP`. * Pick the `Username` filter and set it equal to `TechWolf_TIH_GP`. * Click `Done`. ![Create Permission Group](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/permission_group_creation.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=8a11b0ab859fb51da11843cba3790c10) * **Create a Permission Role** * In the search bar at the top, enter `Manage Permission Roles` and open it. * Create a new Role with user type `Employee`. * Under `Administrator Permissions` → `Manage Job & Skill Profile Visibility`, grant the following: | Permission | Access | | - | - | | Role | View, Edit | | Role.Mapped Skills (Role & Skill Mapping) | View, Correct, Create, Adjust Order, Delete | ![Manage Job & Skill Profile Visibility](https://mintcdn.com/techwolf/G7qK2vmhB0nzflmv/integrations/sap-skill-sync-integration/images/permission_role_admin_permissions_manage_job_skill_profile_visibility.png?fit=max\&auto=format\&n=G7qK2vmhB0nzflmv\&q=85\&s=acaf363934c52d12b96f2d5f96d4e3f3) * Save the Permission Role. * **Assign the Permission Role to the Permission Group** * On the saved Permission Role, click `Add Role Assignments`. * Click `Next`. * On the `Grant Access To` page, select `From Groups`. * Click `Select Groups` and pick the `TechWolf_TIH_GP` group created above. * Click `Next`, then `Next` again, and save the Role Assignment. ![Role Assignment](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/role_assignment_groups.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=b960b0b2cf3026ad6ceb7c97b70f78c5) > [!NOTE] > > If the `Role` or `Role & Skill Mapping` permissions are not visible in > your tenant, enable separate security permissions for the `RoleEntity` > and `RoleSkillMappingEntity` object definitions: > > * In the search bar at the top, enter `Configure Object Definitions` > and open it. > * Search for `Object Definition` → `Role`. > * Use `Take Action` → `Make Correction`. > > ![Object Definition security settings](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/configure_object_definitions_overview.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=ec8d9002ba38f83a09cf95c114e86d2d) > > * Configure the `Security` section according to the following screenshot. Click the "+" button in case the fields are missing. > > ![Object Definition security settings](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/configure_object_definitions_make_correction.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=4426da4a478419ea6f9f339d7a6eee4f) > > * Scroll to the bottom of the page and click `Save`. > * Repeat the above steps for `Object Definition` → `Role & Skill Mapping`. > [!NOTE] > > On recent SAP SuccessFactors releases, the Talent Intelligence Hub adds data > source governance for external skill providers. If your tenant exposes the > **Manage Data Sources** task or a **Manage Skills Governance** section under > **Manage Talent Intelligence Hub**, complete > [How To: Register TechWolf as a Trusted Data Source ](/integrations/sap-btp-skill-sync/how-to-register-data-source) > so Job Role skill updates from TechWolf flow through without additional > manual review. ### 4. Set up an OAuth 2 Client Application in SuccessFactors * In SuccessFactors, in the search bar at the top right, enter `Manage OAuth 2 Client Applications` and press enter. * Click **Register Client Application**. * Fill in the following fields: * **Application Name**: any value (e.g. `techwolf_skillsync_successfactors`). * **Application URL**: any valid URL (e.g. `https://www.techwolf.ai`). * **Bind to Users**: check the checkbox. * **User IDs**: `TechWolf_TIH_GP`. * **X.509 Certificate**: paste the contents of the certificate downloaded in Step 1. Remove the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` guards if present, and strip any line breaks so the value is a single continuous string. ![Register Client Application form with the required fields filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/oauth-client-register-form.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=e36e9a5e8dffb2674f7f00e62572d5b7) * Click **Register**. The Client Application appears in the overview. ![Manage OAuth 2 Client Applications overview showing the registered application](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/oauth-client-created.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=d8cc2bff4ca56653b4edd74467ca4ccb) * Click **View** on the new Client Application and copy the **API Key**. You will need it in Step 5. ![Client Application detail view showing the API Key](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/oauth-client-api-key.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=fca1c7b6c3b630228c087de924c2a5e4) ### 5. Configure the API credentials in SAP Integration Suite * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > Security Material** and click **Create > OAuth 2 SAML Bearer Assertion**. * Set **Name** to a value you will remember for Step 10 (e.g. `techwolf_skillsync_successfactors`). * Set **Audience** to `www.successfactors.com`. * Set **Client Key** to the API Key copied in Step 3. * Set **Token Service URL** to the base URL of your SuccessFactors tenant, appended with `oauth/token`. See [How To: Find the SAP SuccessFactors Company ID and API URL ](/integrations/sap-btp-skill-sync/how-to-find-company-id-and-api-url) for how to look up the base URL. * Set **User ID** to **Key pair Common Name (CN)**. * Set **Key Pair Alias** to the alias of the key pair created in Step 1 (e.g. `techwolf_skillsync_successfactors`). ![Create OAuth 2 SAML Bearer Assertion form with all fields filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/saml-bearer-assertion-form.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=8d710cb16a2748acf9b9d91e519cd81b) * Click **Deploy**. ### 6. Create a User Role for the integration In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Security > User Roles**, then click **Add**. Enter a **Name** that you will remember for Step 7 and Step 10 (e.g. `TechWolfSkillSync.send`) and click **Add**. ![Add User Role dialog with a role name filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/user-role-add.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=6f73d8deb05680b92a82879c8fe9d03b) ### 7. Create a Process Integration Runtime instance In SAP BTP, create a new instance of the **Process Integration Runtime** service with the `integration-flow` plan. * Check *"I understand that enabling a service might result in costs, depending on the plan selected."* * **Runtime Environment**: Cloud Foundry. * **Space**: the Cloud Foundry space you're deploying in. * **Instance Name**: a CLI-friendly name (e.g. `techwolf-skillsync-integration-runtime`). ![Process Integration Runtime Basic Info step](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/process-integration-runtime-basic-info.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=643a0d74706311082dca84890edc396f) * Click **Next** to continue to the Parameters step. * In **Parameters**, set the role to the one created in Step 6 (e.g. `TechWolfSkillSync.send`). * **Grant-types**: `Client Credentials`. * Leave all other fields on their default values. ![Process Integration Runtime Parameters step with role and grant-type set](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/process-integration-runtime-params.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=ea4e1af6d74950b5f52a6dd2d76f217f) Click **Create**. ### 8. Create a Service Key on the instance Find the newly created Process Integration Runtime instance. Click the three dots on the right, then click **Create Service Key**. * **Service Key Name**: any value (e.g. `TechWolfSkillSync`). * **Key Type**: `ClientId/Secret`. * Leave all other fields on their default values. Click **Create**. On the instance, go to **Service Keys** and wait for the key to be created. ![Service Keys tab showing the newly created key](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/service-key-created.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=487919d2939cd78a9fdbfa3df0e0ded1) Click the service key, then click **Download**. ![Service Key detail view with Download button highlighted](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/service-key-download.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=6ce66b9abc99df23a262fd87f8952f1c) > [!WARNING] > > The service key file contains credentials that grant access to invoke your > iFlows. Store it securely and share it with your TechWolf representative via > 1Password (or another agreed secure channel). **Never share it over email or > chat.** ### 9. Import the Content Package In SAP Integration Suite, go to **Design > Integrations and APIs** and click **Import**. ![Design > Integrations and APIs screen with Import button highlighted](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/import-content-package.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=1a772e7e33a859b84e6a233d5c85860f) In the file picker, select the Content Package zip file provided by your TechWolf representative. ### 10. Configure the externalized parameters on each iFlow Open the imported package and go to **Artifacts**. ![Imported package Artifacts tab listing the three iFlows](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/artifacts-overview.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=d5e5b8fba575da35434bf2de26400705) For each of the two Job iFlows (**Query RoleSkillMappingEntity** and **Update RoleSkillMappingEntity**), click the three dots on the right and select **Configure**, then fill in the fields as described in the sub-sections below. > [!NOTE] > > **Finding the SuccessFactors datacenter URL**: in the **Address** field, > click **Select** to see the list of valid SAP SuccessFactors data centers > and pick the one matching your tenant (e.g. > `https://apisalesdemo2.successfactors.eu`). See > [How To: Find the SAP SuccessFactors Company ID and API URL ](/integrations/sap-btp-skill-sync/how-to-find-company-id-and-api-url) > for how to look up this URL. After configuring each iFlow, click **Deploy**, then **Yes**. ![Deploy confirmation dialog](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/iflow-deploy-confirm.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=9a5db53b489dd45312d40bc4e65077b3) #### Query RoleSkillMappingEntity in SAP SuccessFactors * **Tab Sender**: set **User Role** to the role created in Step 6 (e.g. `TechWolfSkillSync.send`). ![Query RoleSkillMappingEntity: Sender tab with User Role filled in](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/iflow-query-role-skill-sender.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=1434dd99d9cbe0bd52561b6284c94af0) * **Tab Receiver**: set **Address** to the URL of your SuccessFactors datacenter and **Credential Name** to the OAuth 2 SAML Bearer Assertion created in Step 5. ![Query RoleSkillMappingEntity: Receiver tab with Address and Credential Name filled in](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/iflow-query-role-skill-receiver.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=d4c1c604ebfed85b4de24b14d354968b) * **Tab More**: set **AIR\_key** to the AIR key provided by your TechWolf representative. ![Query RoleSkillMappingEntity: More tab with AIR\_key filled in](https://mintcdn.com/techwolf/GuXHBKhy7B92r6Xu/integrations/sap-btp-skill-sync/images/iflow-query-role-skill-more.png?fit=max\&auto=format\&n=GuXHBKhy7B92r6Xu\&q=85\&s=a419165509b748c11948cc8a4be9e791) #### Update RoleSkillMappingEntity in SAP SuccessFactors * **Tab Sender**: set **User Role** to the role created in Step 6 (e.g. `TechWolfSkillSync.send`). ![Update RoleSkillMappingEntity: Sender tab with User Role filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/iflow-update-role-skill-sender.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=38c341a05398f12b9428a4eba5daad56) * **Tab Receiver**: set **Address** to the URL of your SuccessFactors datacenter and **Credential Name** to the OAuth 2 SAML Bearer Assertion created in Step 5. ![Update RoleSkillMappingEntity: Receiver tab with Address and Credential Name filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/iflow-update-role-skill-receiver.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=4e2c3f6d74dac2c5c2996243d1f23c8d) * **Tab More**: set **AIR\_key** to the AIR key provided by your TechWolf representative. ![Update RoleSkillMappingEntity: More tab with AIR\_key filled in](https://mintcdn.com/techwolf/F3zMHvKiIiwZ-tCm/integrations/sap-btp-skill-sync/images/iflow-update-role-skill-more.png?fit=max\&auto=format\&n=F3zMHvKiIiwZ-tCm\&q=85\&s=699156142bff0c452fd4d2b3414cd6c2) ### Verify the deployment * In SAP Integration Suite, go to **Monitor > Integrations and APIs > Manage Integration Content** and confirm that all deployed iFlows show the **Started** status. * Go to **Monitor > Integrations and APIs > Monitor Message Processing** to watch messages as TechWolf triggers the iFlows. Failed messages include the HTTP response from SuccessFactors, which is the fastest way to diagnose authentication or permission issues (e.g. expired certificate, missing SuccessFactors permission, incorrect AIR key). ## TechWolf Configuration The TechWolf tenant will be configured by TechWolf itself. To complete the setup, share the following values with your TechWolf representative: * The downloaded **service key file** from Step 8 (via 1Password or another agreed secure channel). TechWolf will then link your SAP Integration Suite to your TechWolf tenant and start the initial sync. ## Routing Through an API Gateway If your organisation fronts the SAP BTP APIs with an API gateway, the integration can call the gateway instead of the vendor host directly. Two settings are available, both configured by TechWolf together with the credentials: * **Custom URL**: instead of the vendor API URL, share the gateway URL that proxies it. The integration keeps appending the same vendor API paths to it, so the gateway must forward requests to SAP BTP unchanged. * **Custom headers**: any number of extra HTTP headers (for example an API key or a correlation ID required by the gateway) that are sent on every request the integration makes. > [!NOTE] > > Both settings are pass-through only. TechWolf sends the values as configured > and does not perform any gateway-specific authentication, signing, or token > refresh; the gateway is expected to forward the integration's own > credentials to SAP BTP. Reserved headers (e.g. `Authorization`, > `Content-Type`) are managed by the integration and cannot be set as custom > headers. ## Configuration Options ### Sync Direction Settings The integration supports three sync direction options: * **Bidirectional** (default): Two-way sync between TechWolf and SAP SuccessFactors; changes made in TechWolf Job Skill Profiles are synchronized to their corresponding SAP SuccessFactors Job Skill Profiles, and vice versa. * **TechWolf to SAP Only**: Skills flow from TechWolf to SAP SuccessFactors only; changes made in TechWolf Job Skill Profiles are copied to their corresponding SAP SuccessFactors Job Skill Profiles, while changes made in SAP SuccessFactors are discarded and overwritten with the state of the TechWolf Job Skill Profiles. * **SAP to TechWolf Only**: Skills flow from SAP SuccessFactors to TechWolf only; changes made in SAP SuccessFactors Job Skill Profiles are copied to their corresponding TechWolf Job Skill Profiles, while changes made in TechWolf are discarded and overwritten with the state of the SAP SuccessFactors Job Skill Profiles. ### Merge Strategy Options For the correct functioning of the normal operation of the integration, the Job Skill Profiles in both systems should be initially aligned. The integration will do this initial alignment itself automatically when the integration is first enabled, or when it is re-enabled after having been paused, or when it encounters a Job it had no knowledge about yet. The initial alignment can happen in different ways; the integration supports three such merge strategy options: * **Merge Systems**: Combines Skills from both systems. In case of metadata conflicts for Skills present in both systems (e.g. conflicting proficiency levels), the values from TechWolf will be used. * **Push TechWolf**: Uses the TechWolf Job Skill Profile as the initial source of truth, and will align the SAP SuccessFactors Job Skill Profile with it. Any Skills initially present in the SAP SuccessFactors Job Skill Profile but not in the TechWolf Job Skill Profile will be removed from the SAP SuccessFactors Job Skill Profile. * **Push SAP**: Uses the SAP SuccessFactors Job Skill Profile as the initial source of truth, and will align the TechWolf Job Skill Profile with it. Any Skills initially present in the TechWolf Job Skill Profile but not in the SAP SuccessFactors Job Skill Profile will be removed from the TechWolf Job Skill Profile. ## Deployment Tasks & Responsibilities 1. **TechWolf**: Setup Skill Sync environment and tenant requirements. 2. **Customer**: Configure SAP BTP and SAP SuccessFactors as described above. 3. **Customer**: Share the necessary values with TechWolf: * The service key file from Step 8. 4. **TechWolf**: Validate API access by calling each iFlow end-to-end. 5. **TechWolf**: Run the initial sync of Job Skill Profiles with the TechWolf API. 6. **TechWolf**: Setup tenant configuration and start the sync process based on the configured direction. 7. **Customer**: Check end-user test scenarios. # Overview Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/overview-employees # Employee Skill Sync Integration with SAP BTP This Deployment Guide provides instructions that will assist in the process of deploying the SAP BTP - TechWolf Employee Skill Sync Integration, including detail on the configuration and deployment of the integration in the customer's SAP BTP tenant and SAP SuccessFactors tenant. The intended audience for this document is the Integration Implementer. ## Integration The Integration has been designed, developed, tested, documented, and deployed by TechWolf with SAP's guidance and oversight. The integration facilitates the flow of validated Employee skill data between SAP SuccessFactors and TechWolf, using an Integration Flow deployed in the customer's SAP Integration Suite. It is not intended to address every use case a customer may be interested in. The customer benefits by receiving pre-built, pre-tested, documented, partner-maintained integrations that minimize implementer's effort as compared to custom integrations for the specific use case(s) addressed. > [!NOTE] > > This is a **distinct integration** from the direct-API [SAP SuccessFactors > Employee Skill Sync > ](/integrations/sap-skill-sync-integration/overview-employees). Customers > choose one or the other depending on their deployment model: the SAP > SuccessFactors Skill Sync calls SAP SuccessFactors APIs directly from > TechWolf. The SAP BTP Skill Sync uses the SAP Integration Suite running in > the customer's own SAP BTP tenant. ## Functional Objective TechWolf and SAP are partnering to enhance skill management within organizations. TechWolf leverages data from various sources, including business systems, to infer skills. These inferred skills are seamlessly integrated into SAP SuccessFactors Employee Growth Portfolios, providing a comprehensive and real-time view of Employees' skills. The integration also enables profile synchronization between TechWolf and SAP, ensuring that both platforms' updates are consistently reflected. Note that TechWolf **Employees** are linked to SAP **Per Person** entities. This can be further facilitated with the use of the [TechWolf Skill Assistant ](/integrations/skill-assistant/overview), where Employees can be notified of newly suggested Skills and validate them. This integration does not depend on the Skill Assistant; any other Skill validation approach can be used. The integration is agnostic to the Skill validation. Besides Skill presence or absence, the integration also synchronizes the proficiency of the Employees' Skills. These proficiency levels can be set by the Employee themselves in the TechWolf Skill Assistant. Changes that are made to the Employee Skill Profile within TechWolf are synchronized to SAP SuccessFactors instantaneously through the Integration Flow. Changes made to Employee Growth Portfolios within SAP SuccessFactors are reflected back to TechWolf through a file-based pull: SAP SuccessFactors pushes Employee Growth Portfolio export files to the TechWolf SFTP server on a customer-defined schedule in the SAP Integration Center, and TechWolf pulls from the SFTP server on a separate schedule (daily by default). **Key benefits:** * TechWolf synchronizes Employee Skill Profiles across all relevant systems, harmonizing Skills across all systems. * The accurate and up-to-date Skill data in SAP SuccessFactors can be used for downstream purposes within SAP. * As TechWolf does not rely on manual assessments (only validation), we increase employee adoption to your talent marketplace with automated Skill Profiles. * Customer-owned infrastructure: every call to SuccessFactors is performed in the customer's BTP tenant, giving the customer full visibility via BTP's Monitor Message Processing view and keeping SuccessFactors credentials inside the customer's BTP keystore. > [!NOTE] > > Within SAP, Employees assigned to Job Roles automatically inherit all Skills > of those Job Roles, on top of any other Skills they may have. To align the > behavior, the Skill Assistant will also block the removal of these inherited > Skills from the Employee's Skill Profile. ## The Integration Flow The Content Package contains the **Update Employee Growth Portfolio** iFlow, deployed in the customer's SAP Integration Suite. TechWolf calls this iFlow to push Employee Skill Profile changes to SuccessFactors in near-real time, using the Talent Intelligence Hub REST API. The iFlow authenticates to SuccessFactors using an OAuth 2 SAML Bearer Assertion backed by a customer-managed X.509 certificate, and carries the TechWolf AIR key in its request header so SuccessFactors can attribute traffic to the TechWolf Skill Sync partner solution. The reverse direction (SuccessFactors → TechWolf) is handled outside the iFlow via a file-based pull. An Employee Growth Portfolio export schedule configured in the SAP Integration Center pushes export files to the TechWolf SFTP server, which TechWolf consumes on a separate schedule. ## Reference Material Reference materials and documentation can be found at: * TechWolf developer documentation: [https://developers.techwolf.ai/ ](https://developers.techwolf.ai/) * TechWolf Skill Sync source IP addresses: [IP Addresses ](/integrations/reference/ip-addresses) * SAP SuccessFactors Talent Intelligence Hub documentation: [Talent Intelligence Hub ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/talent-intelligence-hub) * SAP Integration Suite / Cloud Integration documentation: [SAP Integration Suite ](https://help.sap.com/docs/integration-suite) * Used SAP SuccessFactors Talent Intelligence Hub REST API endpoints: * `PATCH /rest/ecosystem/wholeself/v1/growthPortfolios` ([REST API to Import Growth Portfolio Data ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/rest-api-to-import-growth-portfolio-data)) * Used SAP SuccessFactors Integration Center Definitions: * See [Installation - Employees ](/integrations/sap-btp-skill-sync/installation-employees) for the integration definitions. These are based on the default integration definitions by SAP, cfr. [Importing and Exporting of Talent Intelligence Hub Entities ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/importing-and-exporting-of-talent-intelligence-hub-entities) To deploy the integration, follow the [Installation ](/integrations/sap-btp-skill-sync/installation-employees) guide. # Overview Source: https://developers.techwolf.ai/integrations/sap-btp-skill-sync/overview-jobs # Job Skill Sync Integration with SAP BTP This Deployment Guide provides instructions that will assist in the process of deploying the SAP BTP - TechWolf Job Skill Sync Integration, including detail on the configuration and deployment of the integration in the customer's SAP BTP tenant and SAP SuccessFactors tenant. The intended audience for this document is the Integration Implementer. ## Integration The Integration has been designed, developed, tested, documented, and deployed by TechWolf with SAP's guidance and oversight. The integration facilitates the flow of validated Job skill data between SAP SuccessFactors and TechWolf, using Integration Flows deployed in the customer's SAP Integration Suite. It is not intended to address every use case a customer may be interested in. The customer benefits by receiving pre-built, pre-tested, documented, partner-maintained integrations that minimize implementer's effort as compared to custom integrations for the specific use case(s) addressed. > [!NOTE] > > This is a **distinct integration** from the direct-API [SAP SuccessFactors > Job Skill Sync > ](/integrations/sap-skill-sync-integration/overview-jobs). Customers choose > one or the other depending on their deployment model: the SAP SuccessFactors > Skill Sync calls SAP SuccessFactors APIs directly from TechWolf. The SAP BTP > Skill Sync uses the SAP Integration Suite running in the customer's own SAP > BTP tenant. ## Functional Objective TechWolf and SAP are partnering to enhance skill management within organizations. TechWolf leverages data from various sources, including business systems, to infer skills. These inferred skills are seamlessly integrated into SAP SuccessFactors Job Skill Profiles, providing a comprehensive and real-time view of Jobs' skills. The integration also enables profile synchronization between TechWolf and SAP, ensuring that both platforms' updates are consistently reflected. Note that TechWolf **Jobs** are linked to SAP **Job Roles**. Besides Skill presence or absence, the integration also synchronizes the proficiency of the Jobs' Skills. These proficiency levels can be set in the Job Governance interface in the TechWolf Console. Changes that are made to the Job Skill Profile within TechWolf are synchronized to SAP SuccessFactors instantaneously through the Integration Flows. Changes that are made to Job Skill Profiles within SAP SuccessFactors are reflected back to the TechWolf SkillEngine API on a regular basis (bi-hourly by default). **Key benefits:** * Effortless skill identification: the integration streamlines Skill identification for Job profiles by automatically extracting data from various sources (incl. SAP SuccessFactors) and leveraging TechWolf's labor market data to infer and structure Skills into profiles, eliminating manual efforts. * Governance & maintenance made simple: oversee and control Job Skill Profiles within your Job catalog through the TechWolf Console's Job Governance interface, with collaborative ownership and tailored access for different user groups. * Skill synchronization: TechWolf synchronizes Job Skill Profiles across all relevant systems, harmonizing Skills across all systems. * Enriched downstream use cases: the accurate and up-to-date Skill data in SAP SuccessFactors can be used for downstream purposes within SAP. * Customer-owned infrastructure: every call to SuccessFactors is performed in the customer's BTP tenant, giving the customer full visibility via BTP's Monitor Message Processing view and keeping SuccessFactors credentials inside the customer's BTP keystore. ## The Integration Flows The Content Package contains two Job-related Integration Flows, each deployed in the customer's SAP Integration Suite: * **Query RoleSkillMappingEntity** (SAP → TechWolf): TechWolf polls this iFlow on a regular schedule (bi-hourly by default) to fetch the current state of Job Role skill mappings from SuccessFactors. * **Update RoleSkillMappingEntity** (TechWolf → SAP): TechWolf calls this iFlow to push Job Skill Profile changes to SuccessFactors in near-real time. Both iFlows authenticate to SuccessFactors using an OAuth 2 SAML Bearer Assertion backed by a customer-managed X.509 certificate, and carry the TechWolf AIR key in their request header so SuccessFactors can attribute traffic to the TechWolf Skill Sync partner solution. ## Reference Material Reference materials and documentation can be found at: * TechWolf developer documentation: [https://developers.techwolf.ai/ ](https://developers.techwolf.ai/) * TechWolf Skill Sync source IP addresses: [IP Addresses ](/integrations/reference/ip-addresses) * SAP SuccessFactors Talent Intelligence Hub documentation: [Talent Intelligence Hub ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/talent-intelligence-hub) * SAP Integration Suite / Cloud Integration documentation: [SAP Integration Suite ](https://help.sap.com/docs/integration-suite) * Used SAP SuccessFactors Talent Intelligence Hub OData calls: * `POST /odata/v2/upsert` for the `RoleSkillMappingEntity` (to add Skills to a Job Role) * `DELETE /odata/v2/RoleSkillMappingEntity(RoleEntity_externalCode='', externalCode='')` (to remove Skills from a Job Role) * `GET /odata/v2/RoleSkillMappingEntity?$filter=RoleEntity_externalCode eq ''` (to get the Skills for a Job Role) * `GET /odata/v2/RoleEntity?$filter=externalCode in ''` (to check if a Job in TechWolf exists as a Job Role in SAP) To deploy the integration, follow the [Installation ](/integrations/sap-btp-skill-sync/installation-jobs) guide. # How It Works Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/how-it-works ## Data Flow * The SAP SuccessFactors Skill Sync integrations rely on the use of a shared set of skills between TechWolf and SAP SuccessFactors. This shared set of skills is managed by the Skills Taxonomy Sync integration. * The Skills Taxonomy Sync synchronizes skills bidirectionally between TechWolf and SAP SuccessFactors, and pushes the hierarchical structure of the Skills Taxonomy from TechWolf to SAP SuccessFactors. Updates are propagated between these two systems on a hybrid push/pull strategy. SAP will push files with the latest Attributes Library data to an SFTP server following a customer-defined schedule in the SAP Integration Center. TechWolf will then pull these files from the SFTP server on a separate schedule. TechWolf will ensure files with the most up-to-date Skills Taxonomy information are always present on the SFTP server, available for import into the Attributes Library in SAP SuccessFactors, according to other customer-defined schedules in the SAP Integration Center. * Employee and Job Skills are synchronized in a bidirectional flow, where Employee and Job skill data updates in the SkillEngine API are synchronized in real-time to SAP SuccessFactors using API endpoints, following a push strategy. * Employee Growth Portfolios are updated using the SAP REST API, cfr. [Overview - Employees ](/integrations/sap-skill-sync-integration/overview-employees#reference-material) * Job skills are updated using the SAP OData API, cfr. [Overview - Jobs ](/integrations/sap-skill-sync-integration/overview-jobs#reference-material) * SAP SuccessFactors updates to Employee Skill Profiles are synced at regular intervals to the SkillEngine API using a hybrid push/pull strategy. SAP will push files with the latest Employee Growth Portfolio data to an SFTP server following a customer-defined schedule in the SAP Integration Center, that TechWolf will pull from on a separate schedule. * The frequency with which TechWolf processes the SAP SuccessFactors Employee Growth Portfolio data is configurable, but daily by default. * Employee skills synced by the SAP SuccessFactors Integration are tracked using the `source` field in the [Employee Skill Profile Feedback endpoint ](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile) payload, tagged as `"sap-integration"`. To retrieve these sources in an Employee's profile, use the query parameter `?include=sources` in the [Employee Skill Profile Feedback endpoint ](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile), which returns the Skill's `source_event` with `"event_type": "skill_profile_feedback"` and `"source": "sap-integration"`. * SAP SuccessFactors updates to Job Skill Profiles are synced at regular intervals to the SkillEngine API using a pull strategy. This means that all flows are all initiated by TechWolf. * The frequency by which SAP SuccessFactors skills are synchronized to TechWolf is configurable, but bi-hourly by default. * SAP SuccessFactors Job Skill Profiles are fetched using the SAP OData API, cfr. [Overview - Jobs ](/integrations/sap-skill-sync-integration/overview-jobs#reference-material) * Job skills synced by the SAP SuccessFactors Integration are tracked using the `source` field in the [Job Skill Profile Feedback endpoint ](/reference/latest/Jobs/JobProfile/patch-job-architecture-jobs-job-external-id-skill-profile) payload, tagged as `"sap-integration"`. To retrieve these sources from a Job, use the [List Job Profile Data endpoint ](). Items with `"data_type": "skill_profile_feedback"` and `"source": "sap-integration"` indicate skills synced by the SAP SuccessFactors Integration. In summary: TechWolf uses API endpoints where available, to ensure near instantaneous synchronization of skill profile updates from TechWolf to SAP SuccessFactors. Management of the Skills Taxonomy in TechWolf and Attributes Library in SAP SuccessFactors is done through file-based synchronization. The latest state of the Employee Growth Portfolios is also propagated to TechWolf through a file-based sync. All file-based integrations are managed through the SAP Integration Center. ## Configuration Options ### Sync Direction The integration supports three sync direction options, specifying which data flow directions are allowed: 1. **TechWolf - SAP Bidirectional Sync** (default): Two-way sync between TechWolf and SAP SuccessFactors; changes made in TechWolf Skill Profiles are synchronized to their corresponding SAP SuccessFactors Skill Profiles, and vice versa. 2. **TechWolf to SAP Unidirectional Sync**: Skills flow from TechWolf to SAP SuccessFactors only; changes made in TechWolf Skill Profiles are copied to their corresponding SAP SuccessFactors Skill Profiles, while changes made in SAP SuccessFactors are discarded and overwritten with the state of the TechWolf Skill Profiles. 3. **SAP to TechWolf Unidirectional Sync**: Skills flow from SAP SuccessFactors to TechWolf only; changes made in SAP SuccessFactors Skill Profiles are copied to their corresponding TechWolf Skill Profiles, while changes made in TechWolf are discarded and overwritten with the state of the SAP SuccessFactors Skill Profiles. ### Initial Load Merge Strategy For the correct functioning of the normal operation of the integration, the skill profiles in both systems should be initially aligned. The integration will do this initial alignment itself automatically when the integration is first enabled, or when it is re-enabled after having been paused, or when it encounters an entity it had no knowledge about yet. The initial alignment can happen in different ways; we support three such merge strategy options: 1. **Merge Systems**: Combines skills from both SAP SuccessFactors and TechWolf systems. Skills present in SAP SuccessFactors but not in TechWolf will be synced to TechWolf, and vice versa. This preserves existing skill data in both systems. TechWolf takes precedence over SAP SuccessFactors in case of conflicting values (e.g. conflicting proficiency levels). 2. **Push TechWolf**: Replaces all skills in SAP SuccessFactors with the skill data from TechWolf. This strategy clears existing SAP SuccessFactors skills before importing TechWolf data. 3. **Push SAP**: Replaces all skills in TechWolf with the skill data from SAP SuccessFactors. This strategy clears existing TechWolf skills before importing SAP SuccessFactors data. # How To: Find the SAP identifier for a skill Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/how-to-find-a-skill-id **1. Navigate to the Attributes Library** Search for `Manage Talent Intelligence Hub`, and navigate to the Attributes tab. This is the default starting tab when navigating to the Talent Intelligence Hub management view. ![Attributes Library: Navigate to the Attributes tab](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_skills.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=7089dd98165c29b9a2a50b09fc68373d) **2. Find the skill** In the list of attributes, find the desired skill. This can be made easier by using the filters at the top of the page: * The `Search` field can be used to search for a skill by name. * The `Attribute Type` filter can be used to only show skills (`Skill`). * The `Status` filter can be used to only show active attributes (`Active`). After configuring the filters, click on `Go` to apply them. > [!NOTE] > > When selecting an arbitrary skill attribute for testing, ensure it is indeed a skill (`Attribute Type` is `Skill`) and it is active (`Status` is `Active`). **3. Find the relevant identifier for the skill** Attributes in SAP SuccessFactors can be uniquely identified in three separate ways: their Name, their External Code, and their ID. Different situations will require the use of different identifiers: * For the Employee Skill Sync, the External Code is used. * For the Job Skill Sync, the ID is used (this ID is also referred to as the `WSM ID`). * For the Skills Taxonomy Sync, all three identifiers are used, with the Name being used as the primary identifier. ![Attributes Library: Skill Details](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_skill_details.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=247bcb68787c6e481928a9ff77e324c6) # How To: Find the SAP SuccessFactors Company ID and API URL Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/how-to-find-company-id-and-api-url This guide walks through locating the Company ID and API URL of your SAP SuccessFactors environment. You will need both values when sharing credentials with TechWolf to configure the integration. ### 1. Find out the correct SAP SuccessFactors Company ID * As an SAP administrator, log into the SAP SuccessFactors environment you want to configure the integration for. * Click on your profile icon in the top right corner and select "Show version information". ![Show version information](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/show_version_information.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=d00d6d291c06ba2610cd40c3245b197e) * The Company ID will be shown in the resulting window. ![Version Information](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/version_information.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=d3ec199eed78d611677d741fe3aff130) ### 2. Find out the correct SAP SuccessFactors API URL * As an SAP administrator, go to [SAP for Me ](https://me.sap.com/systemsprovisioning/systems) (if you have multiple credentials, sign in with your S-User credentials). * In the *Public Cloud Systems* table, find the system you want to configure the integration for. * This system should have the value "SAP SuccessFactors HCM" in the `Cloud Service` column. * The `Data Center` column will show the location of the data center of the system, e.g. "Netherlands: Eemshaven". ![List of Systems](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/list_of_systems.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=9e6a58a485c0abcb25f291722cc9c975) * Go to the [List of SAP SuccessFactors API Servers ](https://help.sap.com/docs/successfactors-platform/it-landscape-requirements-for-sap-successfactors/list-of-sap-successfactors-api-servers) * In the *API Servers* table, find your Data Center. * This Data Center should have the previously determined data center location as the value of the `Location` column. Note that the location name might differ in format from the location name in the previous step, e.g. "Eemshaven, The Netherlands" vs "Netherlands: Eemshaven". Among all rows with this location, find the row with the appropriate value for the `Environment` column. * The `API Server` column will show the API URL for the API Server. ![List of API Servers](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/list_of_api_servers.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=1dec8af8effbbce0046f867c5d4b1343) # How To: Manage the Skill Proficiency Rating Scale in SAP SuccessFactors Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/how-to-manage-proficiency-rating-scale ## Viewing the Skill Proficiency Rating Scale **1. Navigate to the rating scales in the Attributes Library** Search for `Manage Talent Intelligence Hub`, and navigate to Proficiency Settings > Rating Scale. ![Attributes Library: Navigate to Proficiency Settings > Rating Scale](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_rating_scale.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=445b9694eeceff434e64fe0161c0866b) **2. Filter the rating scales for the skill attribute type** In the filters at the top of the page, find the `Attribute Type` filter. Click the icon in the filter box to open the dropdown menu, and select `Skill`. Click on `Go` to apply the filter. The rating scales for the skill attribute type will now be visible. Ensure that the rating scale is active. ![Skill proficiency rating scale](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/skill_proficiency_rating_scale.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=b4ec673a31307a1ccdcbcd2fe38964ab) ## Creating a new Skill Proficiency Rating Scale > [!WARNING] > > Proficiency rating scales cannot be deleted once created, only deactivated. > We advise against creating a new scale unless you are sure you need it. **1. Navigate to the rating scales in the Attributes Library** Search for `Manage Talent Intelligence Hub`, and navigate to Proficiency Settings > Rating Scale. ![Attributes Library: Navigate to Proficiency Settings > Rating Scale](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_rating_scale.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=445b9694eeceff434e64fe0161c0866b) **2. Create a new proficiency rating scale** Click on the `Create` button in the top right corner of the Rating Scale table. Fill in required fields and select the required options: * Name: The name of the proficiency rating scale. * Description: The description of the proficiency rating scale. * Include `Too new to rate` (`Yes` or `No`): Check this option if you want to include a level for skills that are too new to rate. Note that this is not natively supported by the TechWolf integration, so we recommend setting this to `No`. * Number of Levels (`1` - `10`): The number of levels in the proficiency rating scale. * Lowest Level Value (`0` or `1`): The value of the lowest level in the proficiency rating scale. * Status (`Active` or `Inactive`): The status of the proficiency rating scale. When creating a new scale to use in the integration, you should use the `Active` status. Additionally, you can give a name and an optional description to each level. Once you have filled in the required fields, click on the `Create` button in the bottom right corner of the page. ![Create proficiency rating scale](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/create_proficiency_rating_scale.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=ee4322d9844e78f1482e50e1210b906d) **3. Associate the proficiency rating scale to the skill attribute type** Navigate to the Attribute Types with the Talent Intelligence Hub management view. In the filters at the top of the page, enter `Skill` in the default, left-most field. Click on `Go` to apply the filter. Find the `Skill` attribute type, and select it. A new tab should open to the side, showing the details of the attribute type. Click the `Edit` button in the top right corner of this tab. ![Attribute Library: Skill Attribute Type](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/attribute_library_attribute_type.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=52ac3d370b7489d929f1a6d76311f30f) In the resulting edit page, find the `Proficiency Level Scale` field, and select the proficiency rating scale you just created from the dropdown menu. Click the `Save` button in the bottom right corner of the page to save the changes. ![Associate proficiency rating scale with skill attribute type](https://mintcdn.com/techwolf/wKUmGwV_kCWzmwEL/snippets/images/associate_rating_scale_with_skills.png?fit=max\&auto=format\&n=wKUmGwV_kCWzmwEL\&q=85\&s=38a55527a6dd21d5b4a2499d74892f07) # How To: Register TechWolf as a Trusted Data Source in SAP SuccessFactors Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/how-to-register-data-source This guide walks through the one-time configuration required to enable TechWolf as a data source, link the integration user to it, and mark the TechWolf data source as trusted, so the TechWolf - SAP SuccessFactors integrations run end-to-end without a manual review step for every update. More information can be found in the [SAP Help Portal ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/talent-intelligence-hub?locale=en-US). > [!NOTE] > > If your SAP SuccessFactors tenant does not expose the **Manage Data > Sources** task or a **Manage Skills Governance** section under **Manage > Talent Intelligence Hub**, your release predates these controls and no > additional setup is needed for now. This setup may still become required in > future releases. ## Prerequisites * You have already created the `TechWolf_TIH_GP` integration user and the OAuth2 Client Application, and assigned the base Permission Role to the user (see the **Installation** guide for your integration). * The SAP administrator performing this setup has, or can be granted, permissions to manage Talent Intelligence Hub settings. See the SAP Help Portal page on [Permissions Required for Using Talent Intelligence Hub ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/permissions-required-for-using-talent-intelligence-hub?locale=en-US) for the complete list. In practice, granting all permissions under **Administrator Permissions** → **Manage Talent Intelligence Hub Settings** covers everything needed for the steps below. ## Steps **1. Activate the TechWolf data source** In the search bar at the top of SAP SuccessFactors, enter **Manage Data Sources** and open the task. In the list of registered data sources, locate the **TechWolf** entry and set its status to **Active**. Other data sources in the list can remain inactive; only the TechWolf data source needs to be active for this integration. See [Managing Data Sources ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/managing-data-sources?locale=en-US) on the SAP Help Portal for reference. **2. Assign the integration user to the TechWolf data source** In the search bar at the top of SAP SuccessFactors, enter **Manage Talent Intelligence Hub** and open the task. Navigate to **General Configurations** → **Settings** → **Manage Users for Data Sources**. For the **TechWolf** data source, click **Add** and search for the `TechWolf_TIH_GP` user. Select it and save. See [Settings Page ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/settings-page?locale=en-US) on the SAP Help Portal for reference. **3. Mark TechWolf as a trusted data source** Still on the **Manage Talent Intelligence Hub** page, open **General Configurations** → **Settings** → **Manage Skills Governance**. Mark the **TechWolf** data source as **trusted**. With this flag set, skill updates coming from TechWolf don't require additional manual review within SAP. See [Settings Page ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/settings-page?locale=en-US) on the SAP Help Portal for reference. # Installation Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/installation-employees ### Prerequisites Before continuing, ensure you have the following: * A valid TechWolf contract and access to a **live TechWolf tenant**. * This tenant must contain Employees corresponding to the PerPerson entities present in SAP SuccessFactors. This can be achieved by either: * Using the Standard [Employee Data Input Integration ](/integrations/datasource-integrations/sap-standard-input-integration/overview). * Creating custom input integrations. When doing this, ensure the TechWolf SkillEngine API Employees are linked with their SAP PerPerson counterparts by using the Per Person UUID (`perPersonUuid`) as the TechWolf Employee ID (`external_id`). Additionally, each TechWolf Employee should have a custom property called `person_id_external` with as value the `Person External ID` of the corresponding PerPerson entity in SAP SuccessFactors. More information on custom properties can be found in the [API Reference ](https://developers.techwolf.ai/reference/latest/Custom%20Properties/CustomPropertiesDefinitions/overview). * An SAP SuccessFactors environment with **Talent Intelligence Hub** implemented. * Access to the TechWolf [SFTP server ](/integrations/reference/sftp/sftp) to host the integration files, with a password or an SSH key. See [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center). * A successful SAP support case to [whitelist the TechWolf SFTP server ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-whitelist-sap-sftp-server). * An SAP SuccessFactors user with the Integration Center permissions listed in Step 6, required to set up the Employee Growth Portfolio export schedule in the Integration Center. Preferably, this is a dedicated technical user. * The necessary setup of the Attributes Library in SAP SuccessFactors. * This includes at least the following: * A proficiency rating scale of your choice, aligned with the one configured for SAP in TechWolf. Preferably, the default TechWolf proficiency scale (1-5) is used. Contact your TechWolf representative for the current configuration, or to update the configuration. See [How To: Manage the Skill Proficiency Rating Scale ](/integrations/sap-skill-sync-integration/how-to-manage-proficiency-rating-scale) for more information on how to manage the proficiency rating scale in SAP SuccessFactors. * The desired set of TechWolf skills present and active in your SAP Attributes Library, as Attributes of the default "Skill" iconType * More information on the Attributes Library and the maintenance of the Attributes Library in SAP SuccessFactors can be found in the [Skills Taxonomy Sync ](/integrations/sap-skill-sync-integration/installation-skills-taxonomy) installation guide. ## SAP SuccessFactors Configuration TechWolf has already pre-configured some parts of the integration. The following ZIP archive contains the necessary files that will be used in the subsequent steps to configure the integration in SAP SuccessFactors. > **[Required files](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/skill-sync-integrations/sap-employee-skill-sync-required-files.zip)** > > Required files for the SAP Employee Skill Sync Integration ### 1. Find out the correct SAP SuccessFactors Company ID * As an SAP administrator, log into the SAP SuccessFactors environment you want to configure the integration for. * Click on your profile icon in the top right corner and select "Show version information". ![Show version information](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/show_version_information.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=d00d6d291c06ba2610cd40c3245b197e) * The Company ID will be shown in the resulting window. ![Version Information](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/version_information.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=d3ec199eed78d611677d741fe3aff130) ### 2. Find out the correct SAP SuccessFactors API URL * As an SAP administrator, go to [SAP for Me ](https://me.sap.com/systemsprovisioning/systems) (if you have multiple credentials, sign in with your S-User credentials). * In the *Public Cloud Systems* table, find the system you want to configure the integration for. * This system should have the value "SAP SuccessFactors HCM" in the `Cloud Service` column. * The `Data Center` column will show the location of the data center of the system, e.g. "Netherlands: Eemshaven". ![List of Systems](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/list_of_systems.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=9e6a58a485c0abcb25f291722cc9c975) * Go to the [List of SAP SuccessFactors API Servers ](https://help.sap.com/docs/successfactors-platform/it-landscape-requirements-for-sap-successfactors/list-of-sap-successfactors-api-servers) * In the *API Servers* table, find your Data Center. * This Data Center should have the previously determined data center location as the value of the `Location` column. Note that the location name might differ in format from the location name in the previous step, e.g. "Eemshaven, The Netherlands" vs "Netherlands: Eemshaven". Among all rows with this location, find the row with the appropriate value for the `Environment` column. * The `API Server` column will show the API URL for the API Server. ![List of API Servers](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/list_of_api_servers.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=1dec8af8effbbce0046f867c5d4b1343) ### 3. Create a TechWolf User in your SAP SuccessFactors environment * In the search bar at the top right of SAP SuccessFactors, enter `Import Employee Data`. * In the resulting window, under the `Select an entity` dropdown, choose "Basic Import". In the `Choose File` field, upload the `techwolf_api_user_definition.csv` file from the required-files zip downloaded above. ![Import API user definition](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/import_api_user_definition.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=fc722e49183f6cd26475b71c4b24c5d7) * Leave the other fields unchanged and click `Validate Import File Data`. If the validation is successful, click `Import`. > [!NOTE] > > If you already created a TechWolf User for another TechWolf - SAP > SuccessFactors integration, this step can be skipped. ### 4. Create a new OAuth2 Client Application * In the search bar at the top right of the screen, enter `Manage OAuth2 Client Applications` and press enter. * In the window that opens, click `Register Client Application`. ![Manage OAuth2 Client Applications Screen](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/oath2_client_applications_landing_page.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=b9613925371f886968f21f578464556a) * In the resulting page, the following fields must be filled in: * `Application Name`: "TechWolf Skill Sync" * `Application URL`: "[https://techwolf.ai](https://techwolf.ai)" * `Bind to Users`: Check the checkbox * `User IDs`: `TechWolf_TIH_GP` (refers to the user created in the previous step) * `X.509 Certificate`: Go to your TechWolf point of contact to request the certificate file. Once you received the file, open it. It will have the following text guards around it: "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----". Copy all the text in between these guards and paste it into the `X.509 Certificate` field. ![Client Application Details](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/client_application_details.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=55e033afe9dc871c32d9776867288cf2) * Now, click `Register`. * Once the Client Application is registered, go back to the `Manage OAuth2 Client Applications` page and find the application you just created. Click `View` on it. * On this view, you can see the `API Key` you will need for the integration configuration. ![View OAuth2 Application](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/view_oauth2_application.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=1c4b98f007a602f7997cb847035a68e6) ### 5. Configure the permissions for the TechWolf user The `TechWolf_TIH_GP` user needs a Permission Group and a Permission Role to run the Skill Sync. > [!NOTE] > > If another TechWolf - SAP SuccessFactors integration using the > `TechWolf_TIH_GP` user has already been configured in this tenant, the > Permission Group and Permission Role already exist. Skip the group creation > and role assignment steps below and only **add the missing permissions** > from the table to the existing Permission Role. * **Create a Permission Group** * In the search bar at the top, enter `Manage Permission Groups` and open it. * Click `Create New`. * Name the group `TechWolf_TIH_GP`. * Pick the `Username` filter and set it equal to `TechWolf_TIH_GP`. * Click `Done`. ![Create Permission Group](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/permission_group_creation.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=8a11b0ab859fb51da11843cba3790c10) * **Create a Permission Role** * In the search bar at the top, enter `Manage Permission Roles` and open it. * Create a new Role with user type `Employee`. * Under `User Permissions` → `Growth Portfolio`, grant the following: | Permission | Access | | - | - | | Attribute | View | | Growth Portfolio | View, Edit, Create, Delete, Edit Proficiency Level, Mark as passionate | | Proficiency Level Scale | View | ![Growth Portfolio](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/permission_role_user_permissions_employee.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=a342df6e4f19a170f2a984170a866044) * Under `Administrator Permissions` → `Manage Talent Intelligence Hub Settings`, grant the following: | Permission | | - | | Import/Export Talent Intelligence Hub and Growth Portfolio Data | ![Manage Talent Intelligence Hub Settings](https://mintcdn.com/techwolf/XjYy6ojjLYiImuAD/integrations/sap-skill-sync-integration/images/permission_role_admin_permissions_employee.png?fit=max\&auto=format\&n=XjYy6ojjLYiImuAD\&q=85\&s=7582026930e818bfb1af117d69acf981) * Save the Permission Role. * **Assign the Permission Role to the Permission Group** * On the saved Permission Role, click `Add Role Assignments`. * Click `Next`. * On the `Grant Access To` page, select `From Groups`. * Click `Select Groups` and pick the `TechWolf_TIH_GP` group created above. * Click `Next`, then `Next` again, and save the Role Assignment. ![Role Assignment](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/role_assignment_groups.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=b960b0b2cf3026ad6ceb7c97b70f78c5) > [!NOTE] > > On recent SAP SuccessFactors releases, the Talent Intelligence Hub adds data > source governance for external skill providers. If your tenant exposes the > **Manage Data Sources** task or a **Manage Skills Governance** section under > **Manage Talent Intelligence Hub**, complete > [How To: Register TechWolf as a Trusted Data Source ](/integrations/sap-skill-sync-integration/how-to-register-data-source) > so Growth Portfolio updates from TechWolf flow through without additional > manual review. ### 6. Create Employee Growth Portfolio Export Schedule Integration Center schedules run under the account of the user that creates them. Ensure this user has all permissions listed below before setting up the schedules. > [!NOTE] > > We recommend setting up the schedules with a dedicated technical user > rather than a named administrator account. Schedules created by a named > account break when that account is deactivated. An administrator creates > the technical user, grants it the permissions below, and proxies as it > while creating the schedules. Setting up the schedules directly as an > administrator with these permissions also works. The account used to set up the schedules must have at least the following permissions: * Under `User Permissions` → `Talent Intelligence Hub`: | Permission | Access | | - | - | | Attribute | View, Edit, Create | | Attribute Type | View, Edit, Create | | Growth Portfolio | View, Edit, Create, Edit Proficiency Level, Mark as passionate | | Proficiency Level Scale | View, Edit, Create | | Tag | View, Edit, Create | * Under `Administrator Permissions`: | Category | Permission | | - | - | | Admin Center Permissions | Read Execution Manager Events | | Admin Center Permissions | Read Execution Manager Event Payload or Event Report | | Manage Integration Tools | Allow Admin to Access OData API through Basic Authentication | | Manage Integration Tools | Access to Integration Center | | Manage Security Center | Access to Other Keys: View | | Manage Talent Intelligence Hub Settings | View Manage Talent Intelligence Hub Settings | | Manage Talent Intelligence Hub Settings | Import/Export Talent Intelligence Hub and Growth Portfolio Data | | Manage Talent Intelligence Hub Settings | Enable Growth Portfolio | | Manage Talent Intelligence Hub Settings | Change Proficiency Level Scale | | Manage Talent Intelligence Hub Settings | Growth Portfolio Rating Precedence | | Metadata Framework | Admin access to MDF OData API | SAP requires a target population for the Growth Portfolio permission, and target criteria for the Attribute Type and Tag permissions. Define these to cover all data in scope of the integration. As a user with the necessary permissions, follow the steps in [How To: Load Export Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions) to create a new export integration definition that will create an export of Employee Growth Portfolios. Use the values from the table below when setting up the integration definition. Preferably, the time of day of the `Start Time` of the schedule is set to be some time (e.g. one hour) after the time of day of the `Start Time` of the Attribute Import Schedule (Step 1) of the [Skills Taxonomy Sync ](/integrations/sap-skill-sync-integration/installation-skills-taxonomy). | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_employee_growth_portfolio_export_definition.icd` | | **File Name Prefix** | `EmployeeGrowthPortfolioExport` | | **Date Suffix Format** | `yyMMddHHmmssZ` | | **File Folder** | `/tih/exports/employee_growth_portfolio` | **Base ICD**: [Talent Intelligence Hub Growth Portfolio Export ](https://api.sap.com/package/TalentIntelligenceHubGrowthPortfolioExportTemplate/icd) > [!NOTE] > > The ICDs provided by TechWolf are based on the default integration definitions by SAP, as indicated by the **Base ICD** mentioned. > These have been pre-filled with some necessary values such as the file name prefix for your convenience, to ease the setup process. > TechWolf is committed to keeping these integration definitions up to date with the latest SAP SuccessFactors releases, but cannot guarantee full alignment with the SAP SuccessFactors release schedule. > Should issues arise when using these integration definitions, please contact [support@techwolf.ai](mailto:support@techwolf.ai). ## TechWolf Configuration The TechWolf tenant will be configured by TechWolf itself. 1. In the integration service on the TechWolf side, TechWolf adds the credentials of the customer-created integration user. For this, the customer will need to share the following values with TechWolf: * The Company ID of the SAP SuccessFactors environment (see Step 1 of the SAP SuccessFactors Configuration section) * The API URL of the SAP SuccessFactors environment (see Step 2 of the SAP SuccessFactors Configuration section) * Username of the integration user (see Step 3 & 4 of the SAP SuccessFactors Configuration section, must be `TechWolf_TIH_GP`) * The API Key of the OAuth2 Client Application (see Step 4 of the SAP SuccessFactors Configuration section) Additionally, the customer will need to share the following configuration settings with TechWolf: * The minimum proficiency level for skill attributes in SAP SuccessFactors (see [How To: Manage the Skill Proficiency Rating Scale ](/integrations/sap-skill-sync-integration/how-to-manage-proficiency-rating-scale)) * The number of proficiency levels for skill attributes in SAP SuccessFactors (see [How To: Manage the Skill Proficiency Rating Scale ](/integrations/sap-skill-sync-integration/how-to-manage-proficiency-rating-scale)) 2. TechWolf adds TechWolf API credentials with correct scopes to have access to the TechWolf API and links that TechWolf tenant to the SAP SuccessFactors tenant. 3. TechWolf enables the schedule to consume the SAP SuccessFactors Growth Portfolio export files on TechWolf's side. ## Routing Through an API Gateway If your organisation fronts the SAP SuccessFactors APIs with an API gateway, the integration can call the gateway instead of the vendor host directly. Two settings are available, both configured by TechWolf together with the credentials: * **Custom URL**: instead of the vendor API URL, share the gateway URL that proxies it. The integration keeps appending the same vendor API paths to it, so the gateway must forward requests to SAP SuccessFactors unchanged. * **Custom headers**: any number of extra HTTP headers (for example an API key or a correlation ID required by the gateway) that are sent on every request the integration makes. > [!NOTE] > > Both settings are pass-through only. TechWolf sends the values as configured > and does not perform any gateway-specific authentication, signing, or token > refresh; the gateway is expected to forward the integration's own > credentials to SAP SuccessFactors. Reserved headers (e.g. `Authorization`, > `Content-Type`) are managed by the integration and cannot be set as custom > headers. ## Configuration Options The integration supports multiple configuration options to fine-tune the integration to the customer's needs. More information on the configuration options can be found in the [How It Works ](/integrations/sap-skill-sync-integration/how-it-works) section. ### Sync Direction The integration supports three sync direction options: * **Bidirectional** (default): Two-way sync between TechWolf and SAP SuccessFactors. * **TechWolf to SAP Only**: Skills flow from TechWolf to SAP SuccessFactors only. * **SAP to TechWolf Only**: Skills flow from SAP SuccessFactors to TechWolf only. ### Merge Strategy The integration supports three options for the construction of the initial profile of each entity after the integration is first enabled, or when it is re-enabled after having been paused, or when it encounters an entity it had no knowledge about yet: * **Merge Systems**: Combines skills from both systems, i.e. the resulting skill profile in both systems will contain all skills that were present in either system initially. * **Push TechWolf**: Uses the TechWolf Employee Skill Profile as the initial source of truth, and will align the SAP SuccessFactors Employee Growth Portfolio with it. * **Push SAP**: Uses the SAP SuccessFactors Employee Growth Portfolio as the initial source of truth, and will align the TechWolf Employee Skill Profile with it. ## Deployment Tasks & Responsibilities 1. **TechWolf**: Setup Skill Sync environment and tenant requirements. 2. **Customer**: Configure SAP SuccessFactors as described above. 3. **Customer**: Share nessary SAP SuccessFactors information and credentials with TechWolf: * Company ID * API URL * Username of the integration user * API Key of the OAuth2 Client Application 4. **TechWolf**: Validate API access by attempting the addition, update and removal of a skill in the Employee Growth Portfolio of the integration user. 5. **TechWolf**: Run initial sync of user profiles with TechWolf API. 6. **TechWolf**: Setup tenant configuration and start sync process based on configured direction. 7. **Customer**: Check end-user test scenarios. # Installation Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/installation-jobs ### Prerequisites Before continuing, ensure you have the following: * A valid TechWolf contract and access to a **live TechWolf tenant**. * This tenant must contain Jobs corresponding to the Job Roles present in SAP SuccessFactors. This can be achieved by either: * Using the [Standard Job Data Input Integration ](/integrations/datasource-integrations/sap-standard-input-integration/overview). * Writing custom input integrations. When doing this, ensure the TechWolf SkillEngine API Jobs are linked with their SAP SuccessFactors Job Role counterparts by using the SAP Job Role ID (`Role_GUID`) as the TechWolf Job ID (`external_id`). * An SAP SuccessFactors environment with **Talent Intelligence Hub** and **Job Profile Builder** implemented. * The necessary setup of the Attributes Library in SAP SuccessFactors. * This includes at least the following: * A proficiency rating scale of your choice, aligned with the one configured for SAP in TechWolf. Preferably, the default TechWolf proficiency scale (1-5) is used. Contact your TechWolf representative for the current configuration, or to update the configuration. See [How To: Manage the Skill Proficiency Rating Scale ](/integrations/sap-skill-sync-integration/how-to-manage-proficiency-rating-scale) for more information on how to manage the proficiency rating scale in SAP SuccessFactors. * The desired set of TechWolf skills present and active in your SAP Attributes Library, as Attributes of the default "Skill" iconType * More information on the Attributes Library and the maintenance of the Attributes Library in SAP SuccessFactors can be found in the [Skills Taxonomy Sync ](/integrations/sap-skill-sync-integration/installation-skills-taxonomy) installation guide. ## SAP SuccessFactors Configuration TechWolf has already pre-configured some parts of the integration. The following ZIP archive contains the necessary files that will be used in the subsequent steps to configure the integration in SAP SuccessFactors. > **[Required files](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/skill-sync-integrations/sap-job-skill-sync-required-files.zip)** > > Required files for the SAP Job Skill Sync Integration ### 1. Find out the correct SAP SuccessFactors Company ID * As an SAP administrator, log into the SAP SuccessFactors environment you want to configure the integration for. * Click on your profile icon in the top right corner and select "Show version information". ![Show version information](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/show_version_information.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=d00d6d291c06ba2610cd40c3245b197e) * The Company ID will be shown in the resulting window. ![Version Information](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/version_information.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=d3ec199eed78d611677d741fe3aff130) ### 2. Find out the correct SAP SuccessFactors API URL * As an SAP administrator, go to [SAP for Me ](https://me.sap.com/systemsprovisioning/systems) (if you have multiple credentials, sign in with your S-User credentials). * In the *Public Cloud Systems* table, find the system you want to configure the integration for. * This system should have the value "SAP SuccessFactors HCM" in the `Cloud Service` column. * The `Data Center` column will show the location of the data center of the system, e.g. "Netherlands: Eemshaven". ![List of Systems](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/list_of_systems.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=9e6a58a485c0abcb25f291722cc9c975) * Go to the [List of SAP SuccessFactors API Servers ](https://help.sap.com/docs/successfactors-platform/it-landscape-requirements-for-sap-successfactors/list-of-sap-successfactors-api-servers) * In the *API Servers* table, find your Data Center. * This Data Center should have the previously determined data center location as the value of the `Location` column. Note that the location name might differ in format from the location name in the previous step, e.g. "Eemshaven, The Netherlands" vs "Netherlands: Eemshaven". Among all rows with this location, find the row with the appropriate value for the `Environment` column. * The `API Server` column will show the API URL for the API Server. ![List of API Servers](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/list_of_api_servers.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=1dec8af8effbbce0046f867c5d4b1343) ### 3. Create a TechWolf User in your SAP SuccessFactors environment * In the search bar at the top right of SAP SuccessFactors, enter `Import Employee Data`. * In the resulting window, under the `Select an entity` dropdown, choose "Basic Import". In the `Choose File` field, upload the `techwolf_api_user_definition.csv` file from the required-files zip downloaded above. ![Import API user definition](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/import_api_user_definition.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=fc722e49183f6cd26475b71c4b24c5d7) * Leave the other fields unchanged and click `Validate Import File Data`. If the validation is successful, click `Import`. > [!NOTE] > > If you already created a TechWolf User for another TechWolf - SAP > SuccessFactors integration, this step can be skipped. ### 4. Create a new OAuth2 Client Application * In the search bar at the top right of the screen, enter `Manage OAuth2 Client Applications` and press enter. * In the window that opens, click `Register Client Application`. ![Manage OAuth2 Client Applications Screen](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/oath2_client_applications_landing_page.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=b9613925371f886968f21f578464556a) * In the resulting page, the following fields must be filled in: * `Application Name`: "TechWolf Skill Sync" * `Application URL`: "[https://techwolf.ai](https://techwolf.ai)" * `Bind to Users`: Check the checkbox * `User IDs`: `TechWolf_TIH_GP` (refers to the user created in the previous step) * `X.509 Certificate`: Go to your TechWolf point of contact to request the certificate file. Once you received the file, open it. It will have the following text guards around it: "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----". Copy all the text in between these guards and paste it into the `X.509 Certificate` field. ![Client Application Details](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/client_application_details.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=55e033afe9dc871c32d9776867288cf2) * Now, click `Register`. * Once the Client Application is registered, go back to the `Manage OAuth2 Client Applications` page and find the application you just created. Click `View` on it. * On this view, you can see the `API Key` you will need for the integration configuration. ![View OAuth2 Application](https://mintcdn.com/techwolf/U7KDKuLgNYCJwTYn/integrations/sap-skill-sync-integration/images/view_oauth2_application.png?fit=max\&auto=format\&n=U7KDKuLgNYCJwTYn\&q=85\&s=1c4b98f007a602f7997cb847035a68e6) ### 5. Configure the permissions for the TechWolf user The `TechWolf_TIH_GP` user needs a Permission Group and a Permission Role to run the Skill Sync. > [!NOTE] > > If another TechWolf - SAP SuccessFactors integration using the > `TechWolf_TIH_GP` user has already been configured in this tenant, the > Permission Group and Permission Role already exist. Skip the group creation > and role assignment steps below and only **add the missing permissions** from > the table to the existing Permission Role. * **Create a Permission Group** * In the search bar at the top, enter `Manage Permission Groups` and open it. * Click `Create New`. * Name the group `TechWolf_TIH_GP`. * Pick the `Username` filter and set it equal to `TechWolf_TIH_GP`. * Click `Done`. ![Create Permission Group](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/permission_group_creation.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=8a11b0ab859fb51da11843cba3790c10) * **Create a Permission Role** * In the search bar at the top, enter `Manage Permission Roles` and open it. * Create a new Role with user type `Employee`. * Under `Administrator Permissions` → `Manage Job & Skill Profile Visibility`, grant the following: | Permission | Access | | - | - | | Role | View, Edit | | Role.Mapped Skills (Role & Skill Mapping) | View, Correct, Create, Adjust Order, Delete | ![Manage Job & Skill Profile Visibility](https://mintcdn.com/techwolf/G7qK2vmhB0nzflmv/integrations/sap-skill-sync-integration/images/permission_role_admin_permissions_manage_job_skill_profile_visibility.png?fit=max\&auto=format\&n=G7qK2vmhB0nzflmv\&q=85\&s=acaf363934c52d12b96f2d5f96d4e3f3) * Save the Permission Role. * **Assign the Permission Role to the Permission Group** * On the saved Permission Role, click `Add Role Assignments`. * Click `Next`. * On the `Grant Access To` page, select `From Groups`. * Click `Select Groups` and pick the `TechWolf_TIH_GP` group created above. * Click `Next`, then `Next` again, and save the Role Assignment. ![Role Assignment](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/role_assignment_groups.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=b960b0b2cf3026ad6ceb7c97b70f78c5) > [!NOTE] > > If the `Role` or `Role & Skill Mapping` permissions are not visible in > your tenant, enable separate security permissions for the `RoleEntity` > and `RoleSkillMappingEntity` object definitions: > > * In the search bar at the top, enter `Configure Object Definitions` > and open it. > * Search for `Object Definition` → `Role`. > * Use `Take Action` → `Make Correction`. > > ![Object Definition security settings](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/configure_object_definitions_overview.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=ec8d9002ba38f83a09cf95c114e86d2d) > > * Configure the `Security` section according to the following screenshot. Click the "+" button in case the fields are missing. > > ![Object Definition security settings](https://mintcdn.com/techwolf/DzhiuB8jW-7AoTeC/integrations/sap-skill-sync-integration/images/configure_object_definitions_make_correction.png?fit=max\&auto=format\&n=DzhiuB8jW-7AoTeC\&q=85\&s=4426da4a478419ea6f9f339d7a6eee4f) > > * Scroll to the bottom of the page and click `Save`. > * Repeat the above steps for `Object Definition` → `Role & Skill Mapping`. > [!NOTE] > > On recent SAP SuccessFactors releases, the Talent Intelligence Hub adds data > source governance for external skill providers. If your tenant exposes the > **Manage Data Sources** task or a **Manage Skills Governance** section under > **Manage Talent Intelligence Hub**, complete > [How To: Register TechWolf as a Trusted Data Source ](/integrations/sap-skill-sync-integration/how-to-register-data-source) > so Job Role skill updates from TechWolf flow through without additional > manual review. ## TechWolf Configuration The TechWolf tenant will be configured by TechWolf itself. 1. In the integration service on the TechWolf side, TechWolf adds the credentials of the customer-created integration user. For this, the customer will need to share the following values with TechWolf: * The Company ID of the SAP SuccessFactors environment (see Step 1 of the SAP SuccessFactors Configuration section) * The API URL of the SAP SuccessFactors environment (see Step 2 of the SAP SuccessFactors Configuration section) * Username of the integration user (see Step 3 & 4 of the SAP SuccessFactors Configuration section, should be `TechWolf_TIH_GP`) * The API Key of the OAuth2 Client Application (see Step 4 of the SAP SuccessFactors Configuration section) Additionally, the customer will need to share the following configuration settings with TechWolf: * The minimum proficiency level for skill attributes in SAP SuccessFactors (see [How To: Manage the Skill Proficiency Rating Scale ](/integrations/sap-skill-sync-integration/how-to-manage-proficiency-rating-scale)) * The number of proficiency levels for skill attributes in SAP SuccessFactors (see [How To: Manage the Skill Proficiency Rating Scale ](/integrations/sap-skill-sync-integration/how-to-manage-proficiency-rating-scale)) 2. TechWolf adds TechWolf API credentials with correct scopes to have access to the TechWolf API and links that TechWolf tenant to the SAP SuccessFactors tenant. ## Routing Through an API Gateway If your organisation fronts the SAP SuccessFactors APIs with an API gateway, the integration can call the gateway instead of the vendor host directly. Two settings are available, both configured by TechWolf together with the credentials: * **Custom URL**: instead of the vendor API URL, share the gateway URL that proxies it. The integration keeps appending the same vendor API paths to it, so the gateway must forward requests to SAP SuccessFactors unchanged. * **Custom headers**: any number of extra HTTP headers (for example an API key or a correlation ID required by the gateway) that are sent on every request the integration makes. > [!NOTE] > > Both settings are pass-through only. TechWolf sends the values as configured > and does not perform any gateway-specific authentication, signing, or token > refresh; the gateway is expected to forward the integration's own > credentials to SAP SuccessFactors. Reserved headers (e.g. `Authorization`, > `Content-Type`) are managed by the integration and cannot be set as custom > headers. ## Configuration Options ### Sync Direction Settings The integration supports three sync direction options: * **Bidirectional** (default): Two-way sync between TechWolf and SAP SuccessFactors. * **TechWolf to SAP Only**: Skills flow from TechWolf to SAP SuccessFactors only. * **SAP to TechWolf Only**: Skills flow from SAP SuccessFactors to TechWolf only. ### Merge Strategy Options For the correct functioning of the normal operation of the integration, the skill profiles in both systems should be initially aligned. The integration will do this initial alignment itself automatically when the integration is first enabled, or when it is re-enabled after having been paused, or when it encounters a Job it had no knowledge about yet. The initial alignment can happen in different ways; the integration supports three such merge strategy options: * **Merge Systems**: Combines skills from both systems, i.e. the resulting skill profile in both systems will contain all skills that were present in either system initially. * **Push TechWolf**: Uses the TechWolf Job Skill Profile as the initial source of truth, and will align the SAP SuccessFactors Job Skill Profile with it. * **Push SAP**: Uses the SAP SuccessFactors Job Skill Profile as the initial source of truth, and will align the TechWolf Job Skill Profile with it. ## Deployment Tasks & Responsibilities 1. **TechWolf**: Setup Skill Sync environment and tenant requirements. 2. **Customer**: Configure SAP SuccessFactors as described above. 3. **Customer**: Share nessary SAP SuccessFactors information and credentials with TechWolf: * Company ID * API URL * Username of the integration user * API Key of the OAuth2 Client Application 4. **TechWolf**: Validate API access by attempting the addition, update and removal of a skill in the Job Skill Profile of the integration user. 5. **TechWolf**: Run initial sync of Job Skill Profiles with TechWolf API. 6. **TechWolf**: Setup tenant configuration and start sync process based on configured direction. 7. **Customer**: Check end-user test scenarios. # Installation Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/installation-skills-taxonomy ### Prerequisites Before continuing, ensure you have the following: * A valid TechWolf contract and access to a **live TechWolf tenant**. * An SAP SuccessFactors environment with **Talent Intelligence Hub** implemented. > [!NOTE] > > Enabling [Talent Intelligence Hub > ](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/e15477b0414b4b25b224a97ad52c12ec/ec345d8396d64bd0936a3cc8280098e0.html) > activates the Attributes Library. This adds supports for using TechWolf > skills in your SuccessFactors environment. * Access to the TechWolf [SFTP server ](/integrations/reference/sftp/sftp) to host the integration files, with a password or an SSH key. See [How To: Add an SSH Key to the Integration Center ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-add-ssh-key-integration-center). * An SAP support case to [whitelist the TechWolf SFTP server ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-whitelist-sap-sftp-server). * An SAP SuccessFactors user with the permissions listed in [Integration Center Permissions](#integration-center-permissions), required to set up the import and export schedules in the Integration Center. Preferably, this is a dedicated technical user. ## SAP SuccessFactors Configuration TechWolf has already pre-configured some parts of the integration. The following ZIP archive contains the necessary files that will be used in the subsequent steps to configure the integration in SAP SuccessFactors. > **[Required files](https://techwolf-docs-public-access.s3.eu-west-3.amazonaws.com/integrations/skill-sync-integrations/sap-skills-taxonomy-sync-required-files.zip)** > > Required files for the SAP Skills Taxonomy Sync Integration The setup in SAP SuccessFactors consists of loading, configuring and scheduling a collection of import and export integrations in the Integration Center. ### Integration Center Permissions Integration Center schedules run under the account of the user that creates them. Ensure this user has all permissions listed below before setting up the schedules. > [!NOTE] > > We recommend setting up the schedules with a dedicated technical user > rather than a named administrator account. Schedules created by a named > account break when that account is deactivated. An administrator creates > the technical user, grants it the permissions below, and proxies as it > while creating the schedules. Setting up the schedules directly as an > administrator with these permissions also works. The account used to set up the schedules must have at least the following permissions: * Under `User Permissions` → `Talent Intelligence Hub`: | Permission | Access | | - | - | | Attribute | View, Edit, Create | | Attribute Type | View, Edit, Create | | Growth Portfolio | View, Edit, Create, Edit Proficiency Level, Mark as passionate | | Proficiency Level Scale | View, Edit, Create | | Tag | View, Edit, Create | * Under `Administrator Permissions`: | Category | Permission | | - | - | | Admin Center Permissions | Read Execution Manager Events | | Admin Center Permissions | Read Execution Manager Event Payload or Event Report | | Manage Integration Tools | Allow Admin to Access OData API through Basic Authentication | | Manage Integration Tools | Access to Integration Center | | Manage Security Center | Access to Other Keys: View | | Manage Talent Intelligence Hub Settings | View Manage Talent Intelligence Hub Settings | | Manage Talent Intelligence Hub Settings | Import/Export Talent Intelligence Hub and Growth Portfolio Data | | Manage Talent Intelligence Hub Settings | Enable Growth Portfolio | | Manage Talent Intelligence Hub Settings | Change Proficiency Level Scale | | Manage Talent Intelligence Hub Settings | Growth Portfolio Rating Precedence | | Metadata Framework | Admin access to MDF OData API | SAP requires a target population for the Growth Portfolio permission, and target criteria for the Attribute Type and Tag permissions. Define these to cover all data in scope of the integration. ### Import and Export Schedules The schedules of these integrations must align with the SAP Skills Taxonomy Sync operations that run on TechWolf's side: schedule the export tasks at **00:30 UTC daily** and the import tasks starting at **02:00 UTC daily**. > [!NOTE] > > The **Start Time** field in the Integration Center's **Scheduling** step > expects a date and time in your local timezone. Convert the UTC times above > to your timezone when filling in the schedules. 1. **Create the TechWolf Attribute Import Schedule** Follow the steps in [How To: Load Import Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-import-integration-definitions) to create a new integration definition that will load the TechWolf skills as attributes into SAP SuccessFactors. Use the values from the table below when setting up the integration definition. | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_attribute_import_definition.icd` | | **File Name Prefix** | `TechWolfAttributeImport` | | **Date Suffix Format** | `yyyyMMdd` | | **File Folder** | `/tih/imports/attributes` | | **Occurs** | Daily | | **Start Time** | 02:00 UTC | **Base ICD**: [Talent Intelligence Hub Attribute Import ](https://api.sap.com/package/SuccessFactorsTalentIntelligenceHubAdminImportTemplates/icd) 2. **Create the TechWolf Attribute Export Schedule** Follow the steps in [How To: Load Export Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions) to create a new integration definition that will export the SAP counterparts of the previously loaded in TechWolf skills out of SAP SuccessFactors. Use the values from the table below when setting up the integration definition. | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_attribute_export_definition.icd` | | **File Name Prefix** | `TechWolfAttributeExport` | | **Date Suffix Format** | `yyMMddHHmmssZ` | | **File Folder** | `/tih/exports/attributes` | | **Occurs** | Daily | | **Start Time** | 00:30 UTC | **Base ICD**: [Talent Intelligence Hub Attribute Export ](https://api.sap.com/package/SuccessFactorsTalentIntelligenceHubAdminExportTemplates/icd) 3. **Create the TechWolf Tag Import Schedule** Follow the steps in [How To: Load Import Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-import-integration-definitions) to create a new integration definition that will load the TechWolf skill clusters as tags into SAP SuccessFactors. Use the values from the table below when setting up the integration definition. | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_tag_import_definition.icd` | | **File Name Prefix** | `TechWolfTagImport` | | **Date Suffix Format** | `yyyyMMdd` | | **File Folder** | `/tih/imports/tags` | | **Processing Folder** | `/tih/processed/tags` | | **Occurs** | Daily | | **Start Time** | 02:00 UTC | **Base ICD**: [Talent Intelligence Hub Tag Import ](https://api.sap.com/package/SuccessFactorsTalentIntelligenceHubAdminImportTemplates/icd) 4. **Create the TechWolf Tag Export Schedule** Follow the steps in [How To: Load Export Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions) to create a new integration definition that will export the SAP tag counterparts of the previously loaded in TechWolf skill clusters out of SAP SuccessFactors. Use the values from the table below when setting up the integration definition. | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_tag_export_definition.icd` | | **File Name Prefix** | `TechWolfTagExport` | | **Date Suffix Format** | `yyMMddHHmmssZ` | | **File Folder** | `/tih/exports/tags` | | **Occurs** | Daily | | **Start Time** | 00:30 UTC | **Base ICD**: [Talent Intelligence Hub Tag Export ](https://api.sap.com/package/SuccessFactorsTalentIntelligenceHubAdminExportTemplates/icd) 5. **Create the TechWolf Attribute-Tag Mapping Import Schedule** Follow the steps in [How To: Load Import Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-import-integration-definitions) to create a new integration definition that will load the mapping between TechWolf skills (attributes in SAP) and TechWolf skill clusters (tags in SAP) into SAP SuccessFactors. Use the values from the table below when setting up the integration definition. For optimal operation, this integration only runs after the related runs of the Attribute Import (Step 1) and the Tag Import (Step 3) are completed. Therefore, the time of day of the `Start Time` of the schedule should be set to be some time (e.g. one hour) after the time of day of those import schedules. | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_attribute_tag_mapping_import_definition.icd` | | **File Name Prefix** | `TechWolfAttributeTagMappingImport` | | **Date Suffix Format** | `yyyyMMdd` | | **File Folder** | `/tih/imports/attribute_tag_mapping` | | **Processing Folder** | `/tih/processed/attribute_tag_mapping` | | **Occurs** | Daily | | **Start Time** | 03:00 UTC | **Base ICD**: [Talent Intelligence Hub Attribute Tag Mapping Import ](https://api.sap.com/package/SuccessFactorsTalentIntelligenceHubAdminImportTemplates/icd) 6. **Create the TechWolf Attribute Text Import Schedule** Only required when skills are synchronized in more than one language. Follow the steps in [How To: Load Import Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-import-integration-definitions) to create a new integration definition that will load the translated skill names and descriptions into SAP SuccessFactors. Use the values from the table below when setting up the integration definition. This integration only adds translations to attributes that already exist, so the time of day of its `Start Time` should be set to be some time (e.g. one hour) after that of the Attribute Import (Step 1). | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_attribute_text_import_definition.icd` | | **File Name Prefix** | `TechWolfAttributeTextImport` | | **Date Suffix Format** | `yyyyMMdd` | | **File Folder** | `/tih/imports/attribute_texts` | | **Processing Folder** | `/tih/processed/attribute_texts` | | **Occurs** | Daily | | **Start Time** | 03:00 UTC | **Base ICD**: [Talent Intelligence Hub Attribute Import ](https://api.sap.com/package/SuccessFactorsTalentIntelligenceHubAdminImportTemplates/icd) 7. **Create the TechWolf Attribute Text Export Schedule** Only required when skills are synchronized in more than one language. Follow the steps in [How To: Load Export Integration Definitions ](/integrations/datasource-integrations/sap-standard-input-integration/how-to-load-export-integration-definitions) to create a new integration definition that will export the translations held in SAP SuccessFactors back out. Use the values from the table below when setting up the integration definition. | **Configuration Item** | **Value** | | - | - | | **Integration Definition** | `techwolf_attribute_text_export_definition.icd` | | **File Name Prefix** | `TechWolfAttributeTextExport` | | **Date Suffix Format** | `yyMMddHHmmssZ` | | **File Folder** | `/tih/exports/attribute_texts` | | **Occurs** | Daily | | **Start Time** | 00:30 UTC | **Base ICD**: [Talent Intelligence Hub Attribute Export ](https://api.sap.com/package/SuccessFactorsTalentIntelligenceHubAdminExportTemplates/icd) > [!NOTE] > > The ICDs provided by TechWolf are based on the default integration definitions by SAP, as indicated by the **Base ICD** mentioned. > These have been pre-filled with some necessary values such as the file name prefix for your convenience, to ease the setup process. > TechWolf is committed to keeping these integration definitions up to date with the latest SAP SuccessFactors releases, but cannot guarantee full alignment with the SAP SuccessFactors release schedule. > Should issues arise when using these integration definitions, please contact [support@techwolf.ai](mailto:support@techwolf.ai). > [!NOTE] > > To make sure the skills added to the Attributes Library are recognized by the intelligent systems within SAP, > the **Standardization Process** must be executed for these skills. > This is a manual process that must be executed by your SAP administrator. > > It is not process-critical for *all* skills to be standardized, > so the standardization process can be executed on a periodic basis, > less frequently than the daily synchronization of the Attributes Library, e.g. quarterly. > It is highly recommended to execute the standardization process at least once after the > initial setup of the integration and initial population of the Attributes Library. ## TechWolf Configuration The TechWolf tenant will be configured by TechWolf itself. 1. TechWolf adds TechWolf API credentials with correct scopes to have access to the TechWolf API and links that TechWolf tenant to the SAP SuccessFactors tenant. 2. TechWolf enables the schedule to create and consume the SAP SuccessFactors Attributes Library import and export files, respectively, on TechWolf's side. 3. TechWolf configures the languages the skills are synchronized in. `en_US` is always synchronized; additional languages can be added on request, and require the Attribute Text schedules from Steps 6 and 7. ## Routing Through an API Gateway If your organisation fronts the SAP SuccessFactors APIs with an API gateway, the integration can call the gateway instead of the vendor host directly. Two settings are available, both configured by TechWolf together with the credentials: * **Custom URL**: instead of the vendor API URL, share the gateway URL that proxies it. The integration keeps appending the same vendor API paths to it, so the gateway must forward requests to SAP SuccessFactors unchanged. * **Custom headers**: any number of extra HTTP headers (for example an API key or a correlation ID required by the gateway) that are sent on every request the integration makes. > [!NOTE] > > Both settings are pass-through only. TechWolf sends the values as configured > and does not perform any gateway-specific authentication, signing, or token > refresh; the gateway is expected to forward the integration's own > credentials to SAP SuccessFactors. Reserved headers (e.g. `Authorization`, > `Content-Type`) are managed by the integration and cannot be set as custom > headers. # Overview Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/overview-employees # Employee Skill Sync Integration with SAP SuccessFactors This Deployment Guide provides instructions that will assist in the process of deploying the SAP SuccessFactors - TechWolf Employee Skill Sync Integration, including detail on the configuration and deployment of the integration in the customer's SAP SuccessFactors tenant. The intended audience for this document is the Integration Implementer. ## Integration The Integration has been designed, developed, tested, documented, and deployed by TechWolf with SAP's guidance and oversight. The integration facilitates the flow of validated employee skill data between SAP SuccessFactors and TechWolf. It is not intended to address every use case a customer may be interested in. The customer benefits by receiving pre-built, pre-tested, documented, partner-maintained integrations that minimize implementer's effort as compared to custom integrations for the specific use case(s) addressed. ## Functional Objective TechWolf and SAP are partnering to enhance skill management within organizations. TechWolf leverages data from various sources, including business systems, to infer skills. These inferred skills are seamlessly integrated into SAP SuccessFactors Growth Portfolios, providing a comprehensive and real-time view of employees' skills. The integration also enables profile synchronization between TechWolf and SAP, ensuring that both platforms' updates are consistently reflected. Note that TechWolf **Employees** are linked to SAP **Per Person** entities. This can be further facilitated with the use of the [TechWolf Skill Assistant ](/integrations/skill-assistant/overview), where employees can be notified of newly suggested skills and validate them. This integration does not depend on the Skill Assistant; any other skill validation approach can be used. The integration is agnostic to the skill validation. Besides skill presence or absence, the integration also synchronizes the proficiency of the employees' skills. These proficiency levels can be set by the employee themselves in the TechWolf Skill Assistant. Changes that are made to the employee skill profile within TechWolf are synchronized to SAP SuccessFactors instantaneously. Changes that are made to the employee growth portfolio within SAP SuccessFactors are reflected back to the TechWolf SkillEngine API on a regular basis (daily, weekly, ..., as requested). **Key benefits:** * TechWolf synchronizes employee skill profiles across all relevant systems, harmonizing skills across all systems. * The accurate and up-to-date skill data in SAP SuccessFactors can be used for downstream purposes within SAP. * As TechWolf does not rely on manual assessments (only validation), we increase employee adoption to your talent marketplace with automated skill profiles. > [!NOTE] > > Within SAP, employees assigned to job roles automatically inherit all skills > of those job roles, on top of any other skills they may have. To align the > behavior, the Skill Assistant will also block the removal of these inherited > skills from the employee's skill profile. ## Reference Material Reference materials and documentation can be found at: * TechWolf developer documentation: [https://developers.techwolf.ai/ ](https://developers.techwolf.ai/) * TechWolf Skill Sync source IP addresses: [IP Addresses ](/integrations/reference/ip-addresses) * SAP SuccessFactors Talent Intelligence Hub documentation: [Talent Intelligence Hub ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/talent-intelligence-hub) * Used SAP SuccessFactors Talent Intelligence Hub REST API endpoints: * `PATCH /rest/ecosystem/wholeself/v1/growthPortfolios` ([REST API to Import Growth Portfolio Data ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/rest-api-to-import-growth-portfolio-data)) * Used SAP SuccessFactors Integration Center Definitions: * See [Installation - Employees ](/integrations/sap-skill-sync-integration/installation-employees) for the integration definitions. These are based on the default integration definitions by SAP, cfr. [Importing and Exporting of Talent Intelligence Hub Entities ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/importing-and-exporting-of-talent-intelligence-hub-entities) # Overview Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/overview-jobs # Job Skill Sync Integration with SAP SuccessFactors This Deployment Guide provides instructions that will assist in the process of deploying the SAP SuccessFactors - TechWolf Job Skill Sync Integration, including detail on the configuration and deployment of the integration in the customer's SAP SuccessFactors tenant. The intended audience for this document is the Integration Implementer. ## Integration The Integration has been designed, developed, tested, documented, and deployed by TechWolf with SAP's guidance and oversight. The integration facilitates the flow of validated Job skill data between SAP SuccessFactors and TechWolf. It is not intended to address every use case a customer may be interested in. The customer benefits by receiving pre-built, pre-tested, documented, partner-maintained integrations that minimize implementer's effort as compared to custom integrations for the specific use case(s) addressed. ## Functional Objective TechWolf and SAP are partnering to enhance skill management within organizations. TechWolf leverages data from various sources, including business systems, to infer skills. These inferred skills are seamlessly integrated into SAP SuccessFactors Job skill profiles, providing a comprehensive and real-time view of Jobs' skills. The integration also enables profile synchronization between TechWolf and SAP, ensuring that both platforms' updates are consistently reflected. Note that TechWolf **Jobs** are linked to SAP **Job Roles**. Besides skill presence or absence, the integration also synchronizes the proficiency of the Jobs' skills. These proficiency levels can be set in the Job Governance interface in the TechWolf Console. Changes that are made to the Job skill profile within TechWolf are synchronized to SAP SuccessFactors instantaneously. Changes that are made to the Job skill profile within SAP SuccessFactors are reflected back to the TechWolf SkillEngine API on a regular basis (at least daily). **Key benefits:** * Effortless skill identification: Our solution streamlines skill identification for Job profiles by automatically extracting data from various sources (incl. SAP SuccessFactors) and leveraging our labor market data to infer and structure skills into profiles, eliminating manual efforts. * Governance & maintenance made simple: Easily oversee and control your Job skill profiles within your Job catalog through an intuitive interface. This setup supports collaborative efforts among multiple owners simultaneously, while providing tailored access to various user groups, ensuring a strong and effective governance framework. * Skill synchronization: TechWolf synchronizes Job skill profiles across all relevant systems. * Enriched downstream use cases: The accurate and up-to-date skill data in SAP SuccessFactors can be used for downstream purposes within SAP. ## Reference Material Reference materials and documentation can be found at: * TechWolf developer documentation: [https://developers.techwolf.ai/ ](https://developers.techwolf.ai/) * TechWolf Skill Sync source IP addresses: [IP Addresses ](/integrations/reference/ip-addresses) * SAP SuccessFactors Talent Intelligence Hub documentation: [Talent Intelligence Hub ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/talent-intelligence-hub) * Used SAP SuccessFactors Talent Intelligence Hub OData calls: * `POST /odata/v2/upsert` for the `RoleSkillMappingEntity` (to add skills to a Job Role) * `DELETE /odata/v2/RoleSkillMappingEntity(RoleEntity_externalCode='', externalCode='')` (to remove skills from a Job Role) * `GET /odata/v2/RoleSkillMappingEntity?$filter=RoleEntity_externalCode eq ''` (to get the skills for a Job Role) * `GET /odata/v2/RoleEntity?$filter=externalCode in ''` (to check if a Job in TechWolf exists as a Job Role in SAP) # Overview Source: https://developers.techwolf.ai/integrations/sap-skill-sync-integration/overview-skills-taxonomy # Skills Taxonomy Sync Integration with SAP SuccessFactors This Deployment Guide provides instructions that will assist in the process of deploying the SAP SuccessFactors - TechWolf Skills Taxonomy Sync Integration, including detail on the configuration and deployment of the integration in the customer's SAP SuccessFactors tenant. The intended audience for this document is the Integration Implementer. ## Integration The Integration has been designed, developed, tested, documented, and deployed by TechWolf with SAP's guidance and oversight. The integration facilitates the flow of skill data between SAP SuccessFactors and TechWolf. It is not intended to address every use case a customer may be interested in. The customer benefits by receiving pre-built, pre-tested, documented, partner-maintained integrations that minimize implementer's effort as compared to custom integrations for the specific use case(s) addressed. ## Functional Objective TechWolf and SAP are partnering to enhance skill management within organizations. TechWolf leverages data from various sources, including business systems, to infer skills for employees and jobs. To provide a comprehensive and structured view of skills, TechWolf provides the feature to create a custom Skills Taxonomy, tailored to your business needs. This taxonomy provides a hierarchical structure of only the business-relevant skills for easy management and use. Likewise, the Talent Intelligence Hub module in SAP SuccessFactors provides the ability to create a custom Attributes Library, also containing only the business-relevant skills. This integration enables the synchronization of the TechWolf Skills Taxonomy with the SAP SuccessFactors Attributes Library. It ensures that the skills in both systems are the same and up-to-date. This enables the use of the subset of the skills in the TechWolf Vocabulary that is important for your business to also be used in SAP SuccessFactors, and conversely, any additional skills tracked in SAP SuccessFactors that are not part of the TechWolf Vocabulary can also be managed and used in TechWolf. Additionally, the integration tags the skills in the Attributes Library with the appropriate skill clusters from the TechWolf Skills Taxonomy. This provides extra structure and context to the Attributes Library and the skills therein. This integration serves as a critical enabler of the SAP - TechWolf Employee Skill Sync integration and SAP - TechWolf Job Skill Sync integration, as these rely on the presence of a shared skills vocabulary between both systems. Changes that are made to the TechWolf Skills Taxonomy are synchronized to SAP SuccessFactors on a regular basis (daily, weekly, ..., as requested). Changes that are made to SAP SuccessFactors Attributes Library are also reflected back to TechWolf on a similar schedule. **Key benefits:** * TechWolf synchronizes the set of used skills between both systems, ensuring all business-relevant skills are available in both systems. * The accurate and up-to-date skill data in SAP SuccessFactors can be used for downstream purposes within SAP. * Having a unified set of skills in both systems enables the skill profiles of employees and jobs in SAP SuccessFactors and TechWolf to be synchronized seamlessly, using the [Employee Skill Sync ](/integrations/sap-skill-sync-integration/overview-employees) and [Job Skill Sync ](/integrations/sap-skill-sync-integration/overview-jobs) integrations. ## Multilingual Skills Skill names and descriptions can be synchronized in more than one language. The integration always synchronizes `en_US`, the default language of the SAP SuccessFactors Attributes Library. Translations are opt-in: TechWolf configures the set of additional languages for your tenant on request. > [!NOTE] > > To make sure the skills added to the Attributes Library are recognized by the intelligent systems within SAP, > the **Standardization Process** must be executed for these skills. > This is a manual process that must be executed by your SAP administrator. > > It is not process-critical for *all* skills to be standardized, > so the standardization process can be executed on a periodic basis, > less frequently than the daily synchronization of the Attributes Library, e.g. quarterly. > It is highly recommended to execute the standardization process at least once after the > initial setup of the integration and initial population of the Attributes Library. ## Reference Material Reference materials and documentation can be found at: * TechWolf developer documentation: [https://developers.techwolf.ai/ ](https://developers.techwolf.ai/) * TechWolf Taxonomy Sync source IP addresses: [IP Addresses ](/integrations/reference/ip-addresses) * SAP SuccessFactors Talent Intelligence Hub documentation: [Talent Intelligence Hub ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/talent-intelligence-hub) * Used SAP SuccessFactors Integration Center Definitions: * See [Installation - Skills Taxonomy ](/integrations/sap-skill-sync-integration/installation-skills-taxonomy) for the integration definitions. These are based on the default integration definitions by SAP, cfr. [Importing and Exporting of Talent Intelligence Hub Entities ](https://help.sap.com/docs/successfactors-platform/using-talent-intelligence-hub/importing-and-exporting-of-talent-intelligence-hub-entities) # Customizations Source: https://developers.techwolf.ai/integrations/skill-assistant/degreed/customizations # Customize the scheduling of suggestions The TechWolf Skill Assistant sends suggestions to users on a regular basis. This scheduling of the suggestions can be customized to fit your company's needs. The following attributes can be customized: * How often suggestions are sent. The options are daily, weekly, monthly, quarterly (every 3 months), biannually (every 6 months), or yearly. By default, daily sends every weekday, weekly sends every Monday, and monthly, quarterly, biannually, and yearly send on the first Monday of the relevant month. * For weekly and longer frequencies, the day on which suggestions are sent can be customized in one of two ways: * By weekday: pick a specific weekday (Monday–Friday). For monthly, quarterly, biannually, and yearly frequencies, you also pick which occurrence of that weekday within the month (first, second, third, or fourth — for example, the third Wednesday). * By date: pick a fixed day of the month (1–28). If that date falls on a weekend, sending shifts to the next Monday. This option applies to monthly and longer frequencies. * For quarterly, biannually, and yearly frequencies, the starting month can be configured. For example, quarterly starting in February sends in February, May, August, and November. * The time when suggestions begin sending. This process may take some time. You can set it to a specific time of day, either on the hour or the half-hour. * A minimum number of Skills that must be available before suggestions are sent to an Employee. * A maximum number of Skills that will be sent to the an Employee at a time. These customizations are configured by TechWolf. Let us know what you would like to change and we will make the necessary adjustments. # How It Looks Source: https://developers.techwolf.ai/integrations/skill-assistant/degreed/how-it-looks # Notifications Users are notified when new Skill suggestions are available. Clicking the notification redirects the user to the profile overview. ![Notifications](https://mintcdn.com/techwolf/A6lmV68eoBxdOoGx/integrations/skill-assistant/degreed/images/degreed-notifications.png?fit=max\&auto=format\&n=A6lmV68eoBxdOoGx\&q=85\&s=c0f8c7297d8ec3e072f61178db32a992) # Suggestions Suggestions can be viewed on the profile overview. ![Suggestions](https://mintcdn.com/techwolf/A6lmV68eoBxdOoGx/integrations/skill-assistant/degreed/images/degreed-inferred-suggestions.png?fit=max\&auto=format\&n=A6lmV68eoBxdOoGx\&q=85\&s=8946f1c1fd0d8fd2fbc2223b973714e4) # Skills When Skill suggestions are accepted, they are added to the user's Skills profile. ![Skills](https://mintcdn.com/techwolf/A6lmV68eoBxdOoGx/integrations/skill-assistant/degreed/images/degreed-skill-profile.png?fit=max\&auto=format\&n=A6lmV68eoBxdOoGx\&q=85\&s=4fbc6a825065b00b8f0ff74b0ce21c4e) # How It Works Source: https://developers.techwolf.ai/integrations/skill-assistant/degreed/how-it-works # Suggestions ![Suggestions](https://mintcdn.com/techwolf/T4HCiIUpM3mvk2op/integrations/skill-assistant/degreed/images/degreed-suggestions.png?fit=max\&auto=format\&n=T4HCiIUpM3mvk2op\&q=85\&s=5332a1e8dbf0166caea1784046127008) 1. **Scheduled trigger**: We send out suggestions at specific time intervals. On such an interval cycle, we trigger the TechWolf Skill Assistant. The interval can be changed depending on your needs. 2. **Fetch suggestions**: To get those suggestions, we fetch them from our own API. More specifically, from the [Suggestions Skill Profile](/reference/latest/Employees/EmployeeSuggestions/post-employees-suggestions-skills) endpoint, for all employees that are part of the **TechWolf Skill Assistant** group. 3. **Send suggestions**: We send out the suggestions to the Degreed platform. 4. **Users receive the Skill Suggestions and Notifications**: The Degreed platform delivers the Skill Suggestions to the correct user. ### How the Skill Engine API max skills setting affects suggestions The Skill Engine API uses the `max_skills` setting to return the top ranked Skills for an Employee based on their data. This setting does not directly mean that an Employee will only ever see that number of suggestions over time. The ranking is based on the Employee Skill Profile and includes Skills that were already accepted or rejected. The Skill Engine API then filters out already validated Skills before suggestions are shown in the Skill Assistant. #### What happens near the limit Rejected Skills can still influence the top `max_skills` ranking through an indirect effect. A rejection acts as feedback for the recommendation model and can change the confidence scores of related Skills. When an Employee is close to the limit, this recalculation can reorder the Employee Skill Profile and cause a different Skill to enter the top `max_skills`. 1. The Skill Engine API returns the top `max_skills` Skills from the Employee Skill Profile. 2. The Employee validates suggestions (for example, accepts 6 and rejects 4). 3. The recommendation scores are recalculated based on the new feedback, including the rejection signal, which can change nearby Skill rankings. 4. If this recalculation pulls another Skill into the top `max_skills`, that Skill can appear as a new suggestion. #### What happens when data changes When new Skill Events are added, probabilities can change and different Skills can enter the top `max_skills` ranking. This can create new suggestions for the Employee. ![Employee Skill Profile states after new Skill Events](https://mintcdn.com/techwolf/JdUJW5PN6MYJZDA8/snippets/skill-assistant/images/max-skills-profiles-after-new-events.png?fit=max\&auto=format\&n=JdUJW5PN6MYJZDA8\&q=85\&s=5f5c9f960f5630cdf02e45f60501179d) 1. New Skill Events are added for the Employee. 2. New inferred Skills are scored and compared against the current top `max_skills` ranking. 3. Only the new Skills that enter the top `max_skills` become visible suggestions. 4. Repeating this process over time can lead to more than `max_skills` validated Skills on an Employee profile. # Feedback on Skill Suggestions When users add Skills to their profile in Degreed, this feedback is synced back to TechWolf using the Degreed Skill Sync. This means the Skill Assistant only sends out suggestions from TechWolf to Degreed and that the Degreed Skill Sync retrieves the feedback from Degreed and syncs it back to TechWolf. You can find more information in the developer documentation for the [Degreed Skill Sync](https://developers.techwolf.ai/integrations/degreed-skill-sync-integration/overview-employees) # Linking Degreed users and employee profiles in TechWolf To link Degreed users to employee profiles in TechWolf, Degreed users should be added to the Group called `TechWolf Skill Assistant` in Degreed. Users that are added to this Group, will be installed by automatically linking their employee ID to TechWolf and will receive Skill Suggestions. # Data flows ### General overview ![Data Flow Overview](https://mintcdn.com/techwolf/A6lmV68eoBxdOoGx/integrations/skill-assistant/degreed/images/degreed-overview-dataflow.png?fit=max\&auto=format\&n=A6lmV68eoBxdOoGx\&q=85\&s=210e87882bfacd9c4580fbd0e08490d4) #### Components **Degreed** The Degreed environment used by the customer. **AWS infrastructure** TechWolf utilizes AWS infrastructure to facilitate communication between Degreed and the Skill Assistant. This infrastructure comprises: * **Scheduling infrastructure (EventBridge + SQS + Lambda) + Batch**: This scheduler triggers the suggestion flow at defined intervals using a queue and jobs running in AWS Batch, which includes caching, processing skill suggestions from the SEAPI and sending them out. **Skill Assistant** TechWolf's backend system responsible for sending skill suggestions to Degreed. It handles scheduling and configuration of the suggestion flow. **Skill Engine API** The main TechWolf product. Handles skill-related data processing and integration. Generates skill suggestions for employees. #### Data processing **Types of data that is processed** * **Skill Suggestions**: Automatically inferred skills for an employee, retrieved from the Skill Engine API. * **Degreed User Data**: Employee details retrieved from Degreed systems, including name. **Data Processing Overview** | | **Managed by** | **Suggestions** | **Feedback** | **Degreed User Data** | | - | - | - | - | - | | **Degreed** | Customer | X | X | X | | **AWS: Scheduling infrastructure** | TechWolf | | | | | **AWS: Batch** | TechWolf | X | | X | | **Skill Assistant** | TechWolf | X | | X | | **Skill Engine API** | TechWolf | X | X | X | #### Data storage **Overview of Data Storage Locations** | | **Managed by** | **Suggestions** | **Feedback** | **Degreed User Data** | | - | - | - | - | - | | **Degreed** | Customer | X | X | X | | **AWS: Scheduling infrastructure** | TechWolf | | | | | **AWS: Batch** | TechWolf | | | | | **Skill Assistant** | TechWolf | X | | X *(No personal identifiable information stored)* | | **Skill Engine API** | TechWolf | X | X | X *(No personal identifiable information stored)* | #### **Communication Protocols** All data exchanges occur over REST APIs secured by **TLS 1.2** or higher. ### Suggesting Skills ![Suggesting Skills](https://mintcdn.com/techwolf/T4HCiIUpM3mvk2op/integrations/skill-assistant/degreed/images/suggesting-skills-dataflow-degreed.png?fit=max\&auto=format\&n=T4HCiIUpM3mvk2op\&q=85\&s=7114735c2eafc17c7ac971842183ad0b) **Process** 1. **Fetch suggestions**: On a regular basis, the Skill Assistant will fetch suggestions generated by the API. 2. **Sending the suggestion**: The suggestion is sent by the Skill Assistant to the customer Degreed tenant. **Data Involved** 1. Degreed ID, Internal ID, Suggestion 2. Degreed ID, Suggestion # Installation Source: https://developers.techwolf.ai/integrations/skill-assistant/degreed/installation # Required Roles for Degreed Installation The required roles for the Degreed installation are: * **Degreed Admin**: A user with administrative privileges who can manage integrations, create API keys, and create and manage Groups. * **Customer Contact with TechWolf**: A designated representative who coordinates with TechWolf's team to facilitate the integration process, provide necessary information, and ensure successful integration of the TechWolf Skill Assistant in your Degreed environment. # Required API Key Scopes The API Key that will be used for the integration with the TechWolf Skill Assistant requires the following Scopes: * Users: read * Skill\_suggestions: write * groups: read # Installation steps The installation consists of several steps, which are described in detail below. **1. Make sure the Degreed Skill Sync is configured and working.** Make sure the Degreed Skill Sync is configured and working. You can find more information on the Degreed Skill Sync [here](https://developers.techwolf.ai/integrations/degreed-skill-sync-integration/installation-employees). **2. Share your API Key credentials with TechWolf.** Create a new API Key with the correct [Scopes](#required-api-key-scopes). Make sure to copy the Client Secret and save it somewhere safe. Share the **Client Id**, **Client Secret**, **Auth URL** and **API URL** of the new API Key with TechWolf. You can find a guide to create an API Key [in this Degreed Documentation](https://developer.degreed.com/docs/authentication). **3. Create a new Group** Create a new **Administrative Group** with the name `TechWolf Skill Assistant`. It is very important that you copy this exact Group name. Only users that are part of this Group will receive Skill Suggestions from TechWolf. You can find a guide to create a Group [in this Degreed Documentation](https://degreed.zendesk.com/hc/en-us/articles/5063217502876-Create-a-New-Group). **4. Add People to the new Group** People that should receive Skill Suggestions from TechWolf, should be added to the newly created Group. You can find a guide to add people to a Group [in this Degreed Documentation](https://degreed.zendesk.com/hc/en-us/articles/5063250744476-Edit-an-Existing-Group). # What is the Skill Assistant? Source: https://developers.techwolf.ai/integrations/skill-assistant/overview # TechWolf Skill Assistant We designed the TechWolf Skill Assistant to bring skills closer to the employee. The Skill Assistant allows employees to validate skills suggested by TechWolf. The Skill Assistant currently supports Microsoft Teams, Slack, Workday and Degreed. This documentation describes the installation, operation and configuration of the Skill Assistant. It is intended for anyone who wants to gain insight in how the system works, and for those who install the Skill Assistant. If you are mostly interested in how this works, and not about the installation specifics, feel free to skip ahead to the `How It Works` sections. If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please reach out to us to report a documentation issue at [support@techwolf.ai](mailto:support@techwolf.ai). # Customizations Source: https://developers.techwolf.ai/integrations/skill-assistant/slack/customizations # Branding ## What can and cannot be customized? **What can be customized?** * The name of the Skill Assistant can be customized in the Slack app settings. **What cannot be customized?** Some branding cannot be customized in Slack, because Slack does not support it: * The icon of the Skill Assistant. * The description of the Skill Assistant app. Additionally, the following is a list of customizations that can be made in the App Home: * The labels of the self-rated Skill proficiency levels ## How to customize the application in Slack? You can customize the name of the Slack Skill Assistant by following these steps: **Step 1** Open Slack and click on "+ Add apps". **Step 2** Search for "Skill Assistant" and select the Skill Assistant app. ![Search for Skill Assistant](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/searchslackapp.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=a4b84316bb65ae9d7f9199e28e4cc8da) **Step 3** Click on the "About" tab **Step 4** Click on the "Configuration" button. This will open the configuration page of the Skill Assistant app. ![Configuration button](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slackconfigurationbutton.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=8b12ba1fb01d705f1f32b9283abdde66) **Step 5** Scroll down to the "Bot User" section **Step 6** Click on the "Edit" button. This will open a dialog to change the name of the Skill Assistant app. ![Edit button](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/editslackname.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=3ecd7f9a2297c73905df65564f919c87) **Step 7** Change the name of the Skill Assistant app to the name you want to use. **Step 8** Click on the "Save Changes" button to save the changes. # Customize the content of messages The content of the messages that are sent by the TechWolf Skill Assistant can be customized to better fit your company's needs. The following attributes can be customized: * The wording of the messages can be changed to better fit your company's culture. More information can be found in the [wording section](#customize-the-wording-of-messages). * The language of the messages. More information can be found in the [language section](#customize-the-language-of-messages). * The skill vocabulary used to display the skills. This can be TechWolf skills or Workday skills. * The amount of skills that are suggested per message. For Slack, the maximum is 10. * The grouping of the skills in the suggestions. Skills can be grouped by Skill Cluster or have no grouping. For skills grouped by Skill Cluster, the maximum number of skills per cluster can be set. * The option to show the sources of the skills in the suggestions. This can be set to show the source of the skills or not. * The option to show the skill descriptions of the suggestions. This can only be used when using the TechWolf or Workday skill vocabulary. These customizations are configured by TechWolf. Let us know what you would like to change and we will make the necessary adjustments. ### Customize the language of messages The TechWolf Skill Assistant sends messages to users in the language that is set by the user in their app. This is only the case if the language is one of the allowed languages, otherwise English is used. You can customize in which languages your employees are allowed to use. If one of your employees uses a language we support, but that is not allowed, they will also default to English. The allowed languages of the messages can be set to a subset of the following languages: English, French, German and Dutch. The allowed languages of skills in TechWolf vocabulary are: English, French, German and Dutch. The allowed languages of skills in other vocabularies are: English. ### Customize the wording of messages Messages can also be changed from their default messaging. Those messages can contain: * A link that is not personalized. * Any text of course. The following lists all possible messages and their default text. We highly recommend customizing these messages to your company to greatly improve user experience * **Installation message**: The first message the user receives. > Hello! > > I'm the Skill Assistant, here to help you keep your skills profile accurate and > up to date. Here's how I can assist you: > >
    >
  • I'll send you skill suggestions that you can review and validate.
    • >
  • You can manage your skill profile in the **Skill Profile** tab.
    • >
> > If you have any questions or need assistance, contact us at \[[support@techwolf.ai](mailto:support@techwolf.ai)]\(mailto:[support@techwolf.ai](mailto:support@techwolf.ai)). * **Hello message**: The Skill Assistant's answer to a message containing `hello` or a similar word in other languages. > Hello! I'm the Skill Assistant, here to help you keep your skills profile > accurate and up to date. I'll send you skill suggestions that you can review > and validate to ensure your profile reflects your expertise. You can manage > your own skill profile in the Skill Profile tab. * **Help message**: The Skill Assistant's answer to a message containing `Help`. > Hello! I'm the Skill Assistant, here to help you keep your skills profile > accurate and up to date. I'll send you skill suggestions that you can review > and validate to ensure your profile reflects your expertise. You can manage > your own skill profile in the Skill Profile tab. * **Hello/Help message for unlinked users**: The Skill Assistant's answer to a message containing `hello` or `help` or a similar word in other languages when the user is not linked to an Employee in the TechWolf system. > Hello! I'm the Skill Assistant, here to help you keep your skills > profile accurate and up to date. > > You currently do not have access. Contact your HR department to get > access. * **Timed suggestion message**: The text above a suggestion message that is sent on the configured interval. There were no open suggestions before this one. > Hi, below you can find a number of suggested skills for you. Deselect skills > that you feel you do not have. * **Validate more message**: The text above new suggestions when the user requested more suggestions on the previous set. > Hi, below you can find a number of additional suggested skills for you. > Deselect skills that you feel you do not have. * **Reminder message**: The text above a suggestion message that is sent on the configured interval. There were open suggestions before this one. > Hi, this is a reminder. Below you can find a number of suggested skills for > you. Deselect skills that you feel you do not have. * **No more skills message**: When the user wants to validate more, but there are no more suggestions for now. > There are no more skills to validate at this time!Good work 🥳 * **Submitted message**: When the user submits their suggestions, the text on that card changes. > Your response has been successfully submitted. * **Outdated message**: Previous unsubmitted suggestions are closed, and new suggestions are sent. This is the text that is shown on the old suggestions. This only happens when the next reminder or new skill suggestions are sent — there is no time-based trigger that marks a message outdated on its own. > This request no longer exists. A more recent reminder has been sent with a > list of skills for you to validate. * **SAP Growth Profile link**: The message on top of the Skill Profile tab that contains the link to the Employee's SAP Growth Portfolio. By default, no message is displayed. # Customize the scheduling of messages The TechWolf Skill Assistant sends messages to users on a regular basis. This scheduling of the messages can be customized to fit your company's needs. The following attributes can be customized: * How often suggestions are sent. The options are daily, weekly, monthly, quarterly (every 3 months), biannually (every 6 months), or yearly. By default, daily sends every weekday, weekly sends every Monday, and monthly, quarterly, biannually, and yearly send on the first Monday of the relevant month. * For weekly and longer frequencies, the day on which suggestions are sent can be customized in one of two ways: * By weekday: pick a specific weekday (Monday–Friday). For monthly, quarterly, biannually, and yearly frequencies, you also pick which occurrence of that weekday within the month (first, second, third, or fourth — for example, the third Wednesday). * By date: pick a fixed day of the month (1–28). If that date falls on a weekend, sending shifts to the next Monday. This option applies to monthly and longer frequencies. * For quarterly, biannually, and yearly frequencies, the starting month can be configured. For example, quarterly starting in February sends in February, May, August, and November. * The time when messages begin sending. This process may take some time. You can set it to a specific time of day, either on the hour or the half-hour. * The amount of time to wait before sending a reminder message to users with open suggestions. This can be set to a specific number of days. For example, if the reminder window is set to 3 days and the user has not validated the skill suggestions received on Monday, they will receive a reminder on Thursday. If the user validates the suggestions on Tuesday and chooses to validate more suggestions, but then leaves the new suggestions open, the reminder window is reset and a new reminder will be sent on Friday. Reminder messages are only sent on weekdays, so if the reminder window expires during the weekend, the reminder will be sent on Monday. Reminders can also follow the suggestion frequency; in that case, on each send day, employees who still have open suggestions from a previous send day receive a reminder, and employees without any open suggestions receive new suggestions if any are available. * Whether all messages are sent at the same time or based on each user's time zone. * A minimum number of Skills that must be available before suggestions are sent to an Employee. These customizations are configured by TechWolf. Let us know what you would like to change and we will make the necessary adjustments. # Send announcements Besides the regular skill suggestions, the TechWolf Skill Assistant can send a one-time announcement to your employees. You write the message yourself, so it can say whatever you need to tell them. A few ideas: * remind employees to rate their proficiency levels before the review season, * introduce a new Skill Assistant feature or a change in your skills programme, * nudge employees about an upcoming deadline. ## What employees see Each employee receives one message from the Skill Assistant in their Slack chat, in their own language. The message is text only, without buttons, and it does not change the skill suggestions they receive. ## What we need from you Announcements are sent by TechWolf on your behalf. To send one, let us know: * The text of the message in English, and in any other language you want to send it in. We can give you an Excel template with one row per language. Employees whose language is not provided receive the English text. Keep the message short. Every employee receives the same text, so it cannot include details such as the employee's name. * Who should receive it: all employees who have the Skill Assistant installed, or a specific list of employees. * The date and time it should be sent. # How It Looks Source: https://developers.techwolf.ai/integrations/skill-assistant/slack/how-it-looks # Suggestions ## Example: Flat list of Skills In this example, the card displays a flat list of Skill Suggestions without any grouping. The maximum number of suggested skills shown in the card is 10. ![Flat list of Skills](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slackflatlist.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=ab42febd7e94e85073f79fec4edc00f3) ## Example: Skills Grouped by Skill Cluster In this example, the card displays Skill Suggestions grouped by Skill Cluster. Each Skill Cluster appears as a separate section within the card, clearly labeled by its Skill Cluster name. Within each Skill Cluster, a maximum of 4 skills are shown. ![Skills Grouped by Skill Cluster](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slackgroupedbycluster.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=ce679c16c0b83c9f231663be74497f2c) ## Example: Skill Suggestions with sources In this example, the card includes the sources used to generate the Skill Suggestions. ![Skill Suggestions with sources](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slacksources.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=3504d46fd3cff03a07a3cf1469151111) ## Example: Skill Suggestions with skill descriptions In this example, the Skill Suggestions card includes a button to show the skill descriptions of the suggested skills. When the button is clicked, a message with the Skills and their descriptions is sent to the user. ![Skill Suggestions with skill description button](https://mintcdn.com/techwolf/qeHBS_Ncx3BNUtAy/integrations/skill-assistant/slack/images/slackskilldescriptionbutton.png?fit=max\&auto=format\&n=qeHBS_Ncx3BNUtAy\&q=85\&s=2ccbd37d745dbe672ffe5468c957baad) ### Skill descriptions ![Skills with their descriptions](https://mintcdn.com/techwolf/qeHBS_Ncx3BNUtAy/integrations/skill-assistant/slack/images/slackskilldescriptions.png?fit=max\&auto=format\&n=qeHBS_Ncx3BNUtAy\&q=85\&s=03d20f7ed3cddeb7f0aefa80ea0abd7a) ### Skill descriptions in Skill Cluster format If the skills are grouped by Skill Cluster, the skill descriptions message will be formatted accordingly. ![Skills with their descriptions in Skill Cluster format](https://mintcdn.com/techwolf/qeHBS_Ncx3BNUtAy/integrations/skill-assistant/slack/images/slackskilldescriptionsgroupedbycluster.png?fit=max\&auto=format\&n=qeHBS_Ncx3BNUtAy\&q=85\&s=04919d51619f735cfe9e0cd4b520fb27) # Validated Suggestions In this example, the card displays a list of validated Skill Suggestions. ![Validated Suggestions](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slackvalidatedsuggestions.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=53bb3c063248276f0db2a3436c17c12d) # Outdated Message When a new reminder or new skill suggestions are sent while previous suggestions are still unsubmitted, the previous message is replaced with the outdated message. There is no time-based trigger — this only happens when the next reminder or new skill suggestions are sent. ![Outdated message replacing the previous suggestions message](https://mintcdn.com/techwolf/UIKPqxg5WqnaxR3i/integrations/skill-assistant/slack/images/outdated-message.png?fit=max\&auto=format\&n=UIKPqxg5WqnaxR3i\&q=85\&s=d420f150130606d3d9f1decd1b811b60) # App Home The Skill Assistant provides an App Home that enables employees to manage their Skill Profile directly in Slack, similar to the Skill Management Tab in Microsoft Teams. ## Example: Default Skill Profile Management In this example, the Employee can manage their Skill Profile by simply adding or deleting Skills from the App Home. When Skill descriptions are enabled, each Skill has a **Show details** button that opens a window with the Skill's description, described [below](#example-skill-details). ![App Home Skill Profile Interface](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-app-home-default.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=fa6b06700a04cf284794d502942c614d) ## Example: Skill Profile Management including suggested and self-rated proficiency levels The functionality can be extended to let the user govern their proficiency level for each Skill. Each level has a descriptive label so that the Employee knows what each level means. When available, a suggested proficiency level for each Skill is shown. When Skill descriptions or proficiency level descriptions are enabled, each Skill also has a **Show details** button, described [below](#example-skill-details). ![App Home with proficiency levels](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-app-home-proficiency.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=a78fb0014a3f8528437e39e16de5d161) Self-Rated Skill proficiency levels can be updated by the Employee by selecting a different proficiency level and confirming it. The confirmation names the Skill and the level it changes to, plus the level it changes from when one was saved. ![Confirming a new proficiency level](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-proficiency-confirm.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=9a13731c3958908791c11b7808f437bd) ## Example: Skill details The **Show details** button opens a window about that Skill. It shows the Skill's description and, with proficiency levels enabled, what each level means for this Skill. The suggested level is marked **(Suggested)** and the Employee's current level **✓ Selected**. Which parts are shown follows which descriptions are enabled. Without proficiency levels, the window shows only the description. ![Skill details window for a validated Skill](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-skill-details.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=e1ccd32cc07bd8abd5b0bd9dca3491b5) With proficiency levels enabled, the Employee can rate the Skill from this window: **Select** another level, then **Save**. For a rejected Skill, the same window is read-only, so the Employee can still read what the Skill means before deciding to accept it again. ![Read-only Skill details window for a rejected Skill](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-skill-details-rejected.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=f2fa1ec7d64d1f5ed6d3693c01545265) ### Adding a Skill with its details When the **Show details** button is offered, picking a Skill from the search does not add it right away. Otherwise the Skill is added at once. ![Searching for a Skill in the App Home](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-app-home-search.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=8e6772ad9cb865d5bddc55a3fdf9acc0) It opens the details window first, so the Employee reads what the Skill means and, with proficiency levels enabled, can **Select** their level. The Skill is added to their Skill Profile when they click **Add skill**, at the selected level if they chose one. ![Skill details window when adding a Skill from the search](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-skill-details-add.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=9dae721cf4081b65916126d5648582e9) ## Example: Skill Profile Management including job-critical skills The functionality can be extended to show which Skills are critical to the Employee's current Job. Each Skill shows whether it is a **Job skill**, and the job-critical Skills are listed first, so the Employee knows which Skills matter most and which to rate first. Employees can still delete any Skill. ![App Home with job-critical skills](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-app-home-job-skills.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=d0f72545e14da2f5097040a0548f9cff) ## Example: Skill Profile Management for SAP customers For SAP customers, the App Home is updated to reflect the same wording that is used in the SAP Growth Portfolio. A custom message can be configured with a link to the Employee's SAP Growth Portfolio. Additionally, the Skills that are already part of the Skill Profile of the Employee through their Job are shown. The Employee has this Skill because their Job requires it. Employees cannot delete Job Skills from their Skill Profile. ![App Home for SAP customers](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-app-home-sap.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=52c781e415661965bddeae43746d9fc0) # How It Works Source: https://developers.techwolf.ai/integrations/skill-assistant/slack/how-it-works # Suggestions ![Suggestions](https://mintlify.s3.us-west-1.amazonaws.com/techwolf/snippets/skill-assistant/images/suggestions.png) 1. **Scheduled trigger**: We send out suggestions at specific time intervals. On such an interval cycle, we trigger the TechWolf Skill Assistant. The interval can be changed depending on your needs. 2. **Fetch suggestions**: To get those suggestions, we fetch them from our own API. More specifically, from the [Suggestions Skill Profile](/reference/latest/Employees/EmployeeSuggestions/post-employees-suggestions-skills) endpoint, for all employees. 3. **Format suggestions**: The Skill Assistant first determines which users should receive suggestions or reminders. The system determines this by checking when each user last received a suggestion and comparing it against the configured timing parameters for suggestions and reminders. The suggestions are then formatted based on the configurations for the message content. See how the message looks like in the `How It Looks` section. 4. **Send suggestions**: We send out the suggestions to the messaging platform. 5. **Users receive the message**: The messaging platform delivers the message to the correct user. ### How the Skill Engine API max skills setting affects suggestions The Skill Engine API uses the `max_skills` setting to return the top ranked Skills for an Employee based on their data. This setting does not directly mean that an Employee will only ever see that number of suggestions over time. The ranking is based on the Employee Skill Profile and includes Skills that were already accepted or rejected. The Skill Engine API then filters out already validated Skills before suggestions are shown in the Skill Assistant. #### What happens near the limit Rejected Skills can still influence the top `max_skills` ranking through an indirect effect. A rejection acts as feedback for the recommendation model and can change the confidence scores of related Skills. When an Employee is close to the limit, this recalculation can reorder the Employee Skill Profile and cause a different Skill to enter the top `max_skills`. 1. The Skill Engine API returns the top `max_skills` Skills from the Employee Skill Profile. 2. The Employee validates suggestions (for example, accepts 6 and rejects 4). 3. The recommendation scores are recalculated based on the new feedback, including the rejection signal, which can change nearby Skill rankings. 4. If this recalculation pulls another Skill into the top `max_skills`, that Skill can appear as a new suggestion. #### What happens when data changes When new Skill Events are added, probabilities can change and different Skills can enter the top `max_skills` ranking. This can create new suggestions for the Employee. ![Employee Skill Profile states after new Skill Events](https://mintlify.s3.us-west-1.amazonaws.com/techwolf/snippets/skill-assistant/images/max-skills-profiles-after-new-events.png) 1. New Skill Events are added for the Employee. 2. New inferred Skills are scored and compared against the current top `max_skills` ranking. 3. Only the new Skills that enter the top `max_skills` become visible suggestions. 4. Repeating this process over time can lead to more than `max_skills` validated Skills on an Employee profile. # Validations ![Validations](https://mintlify.s3.us-west-1.amazonaws.com/techwolf/snippets/skill-assistant/images/validations.png) 1. The user clicks submit on a card, which informs the messaging platform that it should send an update to the TechWolf Skill Assistant. 2. The message is received by the Skill Assistant, which receives a list of confirmed and rejected skills. 3. The TechWolf Skill Assistant stores this information, such as which skills, but also when and by whom. 4. The feedback is sent to the TechWolf API, using the [Employee Skill Profile feedback endpoint](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile) and can be tracked with the `source` field as `"tw-slack-bot"`. To access feedback provided by an employee through the Skill Assistant, use the [Employee List Skill Event endpoint](/reference/latest/Employees/SkillEvents/get-employees-employee-external-id-skill-events) with `skill_profile_feedback` as `event_type`. The resulting Skill Events with `source` field as `"tw-slack-bot"` are the feedback events given using the Skill Assistant. # App Home In addition to our Skill Assistant: We offer an App Home that enables employees to efficiently manage and track their skills. Within the App Home, employees can: * **View and Reevaluate Skills**: Access their validated and rejected skills for assessment and potential updates. * **Add Missing Skills**: Identify and add any skills that may be lacking. * **Self-rate Skill proficiency levels (optional)**: Update the proficiency level of a Skill. * **Read Skill details (optional)**: Open a Skill's description and what each proficiency level means for it, before rating or adding it. See [How It Looks](/integrations/skill-assistant/slack/how-it-looks#example-skill-details). ![App Home Skill Profile Interface](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/slack/images/slack-app-home-default.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=fa6b06700a04cf284794d502942c614d) # Linking users through Custom Properties An important step for the Skill Assistant to work is linking employee profiles in TechWolf to users in the messaging platform. This can be done by setting a Custom Property on the employee profile in TechWolf. The Skill Assistant will then use this Custom Property to link the employee profile to the user in the messaging platform. # Data flows ### General overview ![Data Flow Overview](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slack-overview-dataflow.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=fbd6beb567aa311560e37cb775f144f9) #### Components **Slack** The Slack environment used by the customer. **AWS infrastructure** TechWolf utilizes AWS infrastructure to facilitate communication between Slack and the Skill Assistant. This infrastructure comprises: * **CloudFront**: Processes and routes incoming requests at edge locations, minimizing latency by handling traffic close to its source. * **Lambda at Edge**: Processes incoming requests by extracting the Enterprise or Workspace ID and uses DynamoDB to determine the correct Skill Assistant deployment region (EU or US) for routing. * **Global DynamoDB**: Maintains a mapping between Enterprise/Workspace IDs and their corresponding deployment regions (EU or US). **Skill Assistant** TechWolf's backend system responsible for generating skill suggestions, processing feedback, and managing data for the App Home. **Skill Engine API** The main TechWolf product. Handles skill-related data processing and integration. #### Data processing **Types of data that is processed** * **Skill Suggestions**: Automatically inferred skills for an employee, retrieved from the Skill Engine API. * **Skill Feedback**: Employee feedback on their suggested skills. Either validating that they have the skills, or rejecting the skills. * **Skill Profile**: A list of validated and rejected skills maintained in the Skill Engine API. * **Slack User Data**: Employee details retrieved from Slack systems, including name. **Data Processing Overview** | | **Managed by** | **Suggestions** | **Feedback** | **Skill Profile** | **Slack User Data** | | - | - | - | - | - | - | | **Slack** | Customer | X | X | X | X | | **AWS: CloudFront** | TechWolf | | | | | | **AWS: Lambda at Edge** | TechWolf | | X | X | X | | **AWS: Global DynamoDB** | TechWolf | | | | | | **Skill Assistant** | TechWolf | X | X | X | X | #### Data storage **Overview of Data Storage Locations** | | **Managed by** | **Suggestions** | **Feedback** | **Skill Profile** | **Slack User Data** | | - | - | - | - | - | - | | **Slack** | Customer | X | X | | X | | **AWS** | TechWolf | | | | | | **Skill Assistant** | TechWolf | X | X | | X *(No personal identifiable information stored)* | #### **Communication Protocols** All data exchanges occur over REST APIs secured by **TLS 1.2** or higher. ### Suggesting Skills ![Suggesting Skills](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/suggesting-skills-dataflow-slack.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=892ee91f36bdd9eb3f6d2803877fb701) **Process** 1. **Fetch suggestions**: On a regular basis, the Skill Assistant will fetch suggestions generated by the API. 2. **Sending the suggestion**: The suggestion is sent by the Skill Assistant to the customer Slack tenant. **Data Involved** 1. Slack ID, Internal ID, Suggestion 2. Slack ID, Suggestion ### User Input User input entails button clicks, messages and App Home interactions. ![User Input](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/user-input-dataflow-slack.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=4d472dde5a265b6838adbc699ddb43c9) 1. **User input request**: When a user interacts with a suggestion or the App Home, it is sent to CloudFront in the TechWolf AWS instance. 2. **Routing to Skill Assistant**: The request is processed and routed by CloudFront to the Skill Assistant. Only necessary information is retained, and names and email addresses are dropped. 3. **Execution of request**: The Skill Assistant directs the request in proper format to the API, where the request is executed on the customer's data. 4. **Response to user**: A response, based on the request's proper execution, is sent back to the concerning Slack user. **Data Involved** 1. [Event Data](https://api.slack.com/events) or [Interactivity Data](https://api.slack.com/reference/interaction-payloads/block-actions), Feedback, Slack User Data (Contains the name of the user which cannot be dropped from the request.) 2. [Event Data](https://api.slack.com/events) or [Interactivity Data](https://api.slack.com/reference/interaction-payloads/block-actions), Feedback, Slack User Data (Contains the name of the user which cannot be dropped from the request.) 3. Internal ID, Slack ID, Depending on the event: Feedback, Request suggestions or Skill Profile 4. Slack ID, Custom response, Depending on the event: Suggestion or Skill Profile # Installation Source: https://developers.techwolf.ai/integrations/skill-assistant/slack/installation # Required Roles for Slack Installation The required roles for the Slack installation are: * **Slack (Enterprise Grid) Admin**: A user with administrative privileges who can manage app installations, approve app requests, and configure app settings across the Slack Enterprise Grid organization. This role is essential for overseeing the Skill Assistant integration and ensuring proper deployment. * **Customer Contact with TechWolf**: A designated representative who coordinates with TechWolf's team to facilitate the integration process, provide necessary information, and ensure successful implementation of the Skill Assistant in your Slack environment. # Required Slack App Permissions The required permissions for the Slack app are: | OAuth Scope | Description | Request Reason | | - | - | - | | chat:write | Send messages as Skill Assistant | The app needs to be able to send messages containing suggestions, reminders and other content to the users of the app. | | im:history | View messages and other content in direct messages that Skill Assistant has been added to | The app needs to be able to view messages users send to the app to be able to answer those messages. | | im:write | Start direct messages with people | The app needs to be able to start sending messages directly to users, to for example send them skill suggestions. | | users:read | View people in a workspace | The app needs to be able to get all the users from the workspace to be able to send suggestions to them. | # Installation steps The installation consists of several steps, which are described in detail below. TechWolf needs to configure the Skill Assistant to work with your Slack environment and you need to install the app in your Slack environment. Once installed, employees can receive Skill Suggestions in direct messages and manage their Skill Profile in the Skill Assistant's App Home. **1. Share your Enterprise or Workspace ID with TechWolf.** If you are using a Slack Enterprise Grid, you need to share your Enterprise ID with TechWolf. If you only have a single Slack Workspace, you need to share your Workspace ID with TechWolf. **2. Link Slack users to employee profiles in TechWolf** We need a method to link employee profiles in the TechWolf API to Slack Users. See [Linking users and employee profiles in TechWolf ](#linking-slack-users-and-employee-profiles-in-techwolf). **3. Install in Skill Assistant application in Slack** Install the Skill Assistant in your Slack environment by following [these steps](#install-the-skill-assistant-in-slack) **4. Enable the Skill Assistant for your workspaces** > [!WARNING] > > This step is only required if you are using a Slack Enterprise Grid. Enable the Skill Assistant for your workspaces by following [these steps](#enable-the-skill-assistant-for-your-workspaces) ### Linking Slack users and employee profiles in TechWolf In order for TechWolf's Skill Assistant to deliver personalized and timely skill suggestions via Slack, it is crucial that we can accurately link each employee in your organization to their corresponding Slack user. This can be accomplished by setting a [Custom Property]() on the employee profile in TechWolf. The Skill Assistant will then use this Custom Property to link the employee profile to the user in the messaging platform. The Slack ID should be stored in a Custom Property with the key `employee_slack_id`. * If you are using Enterprise Grid, use the Enterprise Slack ID * If you are using a single workspace, use the Workspace Slack ID > [!NOTE] > > For Slack, we require the **User ID** which has one of the following > formats: `U02ABCDEF34` or `W02ABCDEF34`. The mapping between the employee ID known in TechWolf's SkillEngine and their corresponding custom property should be sent to TechWolf via a datasource integration so that we can store it accordingly. ### Install the Skill Assistant in Slack To install the Skill Assistant in Slack, you need to install the app in your Slack environment. Follow the following steps: **Step 1** Install the app in the region where your data should be stored: the US region, the CA region, or otherwise the EU region. > **[Click here to install the Skill Assistant in the US region](https://slack.com/oauth/v2/authorize?client_id=1179833433430.8333872682304\&scope=chat:write,im:history,im:write,users:read\&user_scope=\&redirect_uri=https://teamsbot.us.skillengine.eu/api/slack/oauth)** > **[Click here to install the Skill Assistant in the CA region](https://slack.com/oauth/v2/authorize?client_id=1179833433430.8333872682304\&scope=chat:write,im:history,im:write,users:read\&user_scope=\&redirect_uri=https://teamsbot.ca.skillengine.eu/api/slack/oauth)** > **[Click here to install the Skill Assistant in the EU region](https://slack.com/oauth/v2/authorize?client_id=1179833433430.8333872682304\&scope=chat:write,im:history,im:write,users:read\&user_scope=)** **2. Select the organization** If you are using Enterprise Grid, you need to install the Skill Assistant app for your organization. > [!WARNING] > > Make sure to select your organization and not your workspace when using Enterprise Grid. Only when you are not using Enterprise Grid, you can install the app for a single workspace. ![Organization selection](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slackorganizationselection.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=84736d8aef670aee2e4d387fce3b656e) **3. Allow the app** Allow the app to access your Slack environment. > [!WARNING] > > The Skill Assistant app is currently not available in the Slack Marketplace. > Slack will display a warning that shows this. ![Allow the app](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slackinstallation.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=5bc5d0da66c812a0d9092a986cd925c5) **4. Succesful installation** If the installation is successful, you will see the following message. > **Using Enterprise Grid** > > ![Succesful installation](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slacksuccessenterpriseinstallation.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=c077dff9ce43e4c96ddcf898d795ecec) > **Using a single workspace** > > ![Succesful installation](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slacksuccessinstallation.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=a3b84f63b8be9fb3e190386deee646bb) ### Enable the Skill Assistant for your workspaces > [!WARNING] > > This step is only required if you are using a Slack Enterprise Grid. If you are using a Slack Enterprise Grid, you need to enable the Skill Assistant for your workspaces. Follow the following steps: **1. Add the app to your workspaces** If the installation was successful, you will see a button named "Add the app to your workspaces". This will bring you to the page where you can add the app to your workspaces. **2. Add the app to your workspaces** At the right top corner of the page, you will see a dropdown named "Manage". Click it and select "Add to more workspaces". ![Add the app to your workspaces](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/slack/images/slackaddtoworkspaces.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=542cfb97d798338718c25783b2ebd9c4) **3. Select the workspaces** Select the workspaces you want to add the app to and click on "Next". **4. Review the permissions** Review the permissions and click on "Next". **5. Add to the workspaces** Select the checkbox "I'm ready to add this app" and click the button "Add App". # Customizations Source: https://developers.techwolf.ai/integrations/skill-assistant/teams/customizations # Branding ## What can be customized? The TechWolf Skill Assistant can be customized in a number of ways to better fit your company's needs. The following is a list of customizations that can be made: * The name of the application * The short description of the application * The full description of the application * The icon of the application * The outline icon of the application * The accent color of the application Additionaly, the following is a list of customizations that can be made in the Skill Profile tab: * The labels of the self-rated Skill proficiency levels ![](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/teams/images/customizations.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=01ae40bfc54898132cf9dec6b34d2d3e) ## How to customize the application in Teams? You can customize the branding of the application in Teams by following [this Microsoft guide](https://learn.microsoft.com/en-us/microsoftteams/customize-apps#create-a-default-customization-for-an-app). # Customize the content of messages The content of the messages that are sent by the TechWolf Skill Assistant can be customized to better fit your company's needs. The following attributes can be customized: * The wording of the messages can be changed to better fit your company's culture. More information can be found in the [wording section](#customize-the-wording-of-messages). * The language of the messages. More information can be found in the [language section](#customize-the-language-of-messages). * The skill vocabulary used to display the skills. This can be TechWolf skills or Workday skills. * The amount of skills that are suggested per message. * The grouping of the skills in the suggestions. Skills can be grouped by Skill Cluster or have no grouping. For skills grouped by Skill Cluster, the maximum number of skills per cluster can be set. * The option to show the sources of the skills in the suggestions. This can be set to show the source of the skills or not. * The option to show the skill descriptions of the suggestions. This can only be used when using the TechWolf or Workday skill vocabulary. These customizations are configured by TechWolf. Let us know what you would like to change and we will make the necessary adjustments. ### Customize the language of messages The TechWolf Skill Assistant sends messages to users in the language that is set by the user in their app. This is only the case if the language is one of the allowed languages, otherwise English is used. You can customize in which languages your employees are allowed to use. If one of your employees uses a language we support, but that is not allowed, they will also default to English. The allowed languages of the messages can be set to a subset of the following languages: English, French, German and Dutch. The allowed languages of skills in TechWolf vocabulary are: English, French, German and Dutch. The allowed languages of skills in other vocabularies are: English. ### Customize the wording of messages Messages can also be changed from their default messaging. Those messages can contain: * A link that is not personalized. * Any text of course. The following lists all possible messages and their default text. We highly recommend customizing these messages to your company to greatly improve user experience * **Installation message**: The first message the user receives. > Hello! > > I'm the Skill Assistant, here to help you keep your skills profile accurate and > up to date. Here's how I can assist you: > >
    >
  • I'll send you skill suggestions that you can review and validate.
    • >
  • You can manage your skill profile in the **Skill Profile** tab.
    • >
> > If you have any questions or need assistance, contact us at \[[support@techwolf.ai](mailto:support@techwolf.ai)]\(mailto:[support@techwolf.ai](mailto:support@techwolf.ai)). * **Hello message**: The Skill Assistant's answer to a message containing `hello` or a similar word in other languages. > Hello! I'm the Skill Assistant, here to help you keep your skills profile > accurate and up to date. I'll send you skill suggestions that you can review > and validate to ensure your profile reflects your expertise. You can manage > your own skill profile in the Skill Profile tab. * **Help message**: The Skill Assistant's answer to a message containing `Help`. > Hello! I'm the Skill Assistant, here to help you keep your skills profile > accurate and up to date. I'll send you skill suggestions that you can review > and validate to ensure your profile reflects your expertise. You can manage > your own skill profile in the Skill Profile tab. * **Hello/Help message for unlinked users**: The Skill Assistant's answer to a message containing `hello` or `help` or a similar word in other languages when the user is not linked to an Employee in the TechWolf system. > Hello! I'm the Skill Assistant, here to help you keep your skills > profile accurate and up to date. > > You currently do not have access. Contact your HR department to get > access. * **Timed suggestion message**: The text above a suggestion message that is sent on the configured interval. There were no open suggestions before this one. > Hi, below you can find a number of suggested skills for you. Deselect skills > that you feel you do not have. * **Validate more message**: The text above new suggestions when the user requested more suggestions on the previous set. > Hi, below you can find a number of additional suggested skills for you. > Deselect skills that you feel you do not have. * **Reminder message**: The text above a suggestion message that is sent on the configured interval. There were open suggestions before this one. > Hi, this is a reminder. Below you can find a number of suggested skills for > you. Deselect skills that you feel you do not have. * **No more skills message**: When the user wants to validate more, but there are no more suggestions for now. > There are no more skills to validate at this time!Good work 🥳 * **Submitted message**: When the user submits their suggestions, the text on that card changes. > Your response has been successfully submitted. * **Outdated message**: Previous unsubmitted suggestions are closed, and new suggestions are sent. This is the text that is shown on the old suggestions. This only happens when the next reminder or new skill suggestions are sent — there is no time-based trigger that marks a message outdated on its own. > This request no longer exists. A more recent reminder has been sent with a > list of skills for you to validate. * **SAP Growth Profile link**: The message on top of the Skill Profile tab that contains the link to the Employee's SAP Growth Portfolio. By default, no message is displayed. # Customize the scheduling of messages The TechWolf Skill Assistant sends messages to users on a regular basis. This scheduling of the messages can be customized to fit your company's needs. The following attributes can be customized: * How often suggestions are sent. The options are daily, weekly, monthly, quarterly (every 3 months), biannually (every 6 months), or yearly. By default, daily sends every weekday, weekly sends every Monday, and monthly, quarterly, biannually, and yearly send on the first Monday of the relevant month. * For weekly and longer frequencies, the day on which suggestions are sent can be customized in one of two ways: * By weekday: pick a specific weekday (Monday–Friday). For monthly, quarterly, biannually, and yearly frequencies, you also pick which occurrence of that weekday within the month (first, second, third, or fourth — for example, the third Wednesday). * By date: pick a fixed day of the month (1–28). If that date falls on a weekend, sending shifts to the next Monday. This option applies to monthly and longer frequencies. * For quarterly, biannually, and yearly frequencies, the starting month can be configured. For example, quarterly starting in February sends in February, May, August, and November. * The time when messages begin sending. This process may take some time. You can set it to a specific time of day, either on the hour or the half-hour. * The amount of time to wait before sending a reminder message to users with open suggestions. This can be set to a specific number of days. For example, if the reminder window is set to 3 days and the user has not validated the skill suggestions received on Monday, they will receive a reminder on Thursday. If the user validates the suggestions on Tuesday and chooses to validate more suggestions, but then leaves the new suggestions open, the reminder window is reset and a new reminder will be sent on Friday. Reminder messages are only sent on weekdays, so if the reminder window expires during the weekend, the reminder will be sent on Monday. Reminders can also follow the suggestion frequency; in that case, on each send day, employees who still have open suggestions from a previous send day receive a reminder, and employees without any open suggestions receive new suggestions if any are available. * Whether all messages are sent at the same time or based on each user's country median time zone. * A minimum number of Skills that must be available before suggestions are sent to an Employee. These customizations are configured by TechWolf. Let us know what you would like to change and we will make the necessary adjustments. # Send announcements Besides the regular skill suggestions, the TechWolf Skill Assistant can send a one-time announcement to your employees. You write the message yourself, so it can say whatever you need to tell them. A few ideas: * remind employees to rate their proficiency levels before the review season, * introduce a new Skill Assistant feature or a change in your skills programme, * nudge employees about an upcoming deadline. ## What employees see Each employee receives one message from the Skill Assistant in their Teams chat, in their own language. The message is text only, without buttons, and it does not change the skill suggestions they receive. ## What we need from you Announcements are sent by TechWolf on your behalf. To send one, let us know: * The text of the message in English, and in any other language you want to send it in. We can give you an Excel template with one row per language. Employees whose language is not provided receive the English text. Keep the message short. Every employee receives the same text, so it cannot include details such as the employee's name. * Who should receive it: all employees who have the Skill Assistant installed, or a specific list of employees. * The date and time it should be sent. # How It Looks Source: https://developers.techwolf.ai/integrations/skill-assistant/teams/how-it-looks # Suggestions ## Example: Flat list of Skills In this example, the card displays a flat list of Skill Suggestions without any grouping. The maximum number of suggested skills shown in the card is 10. ![Flat list of Skills](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/flat-list.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=1d4a6999059caaf683550e688a7791d9) ## Example: Skills Grouped by Skill Cluster In this example, the card displays Skill Suggestions grouped by Skill Cluster. Each Skill Cluster appears as a separate section within the card, clearly labeled by its Skill Cluster name. Within each Skill Cluster, a maximum of 4 skills are shown. ![Skills Grouped by Skill Cluster](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/grouped-by-cluster.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=0f79cf233eaac0e55e714bcf3fe0caee) ## Example: Skill Suggestions with "View Sources" Button In this example, the card includes a "View Sources" button that allows users to view the underlying sources for the suggested skills. The button has been clicked, revealing the sources used to generate the Skill Suggestions. ![Skill Suggestions with "View Sources" Button](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/view-sources.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=6cdbc74a1ea7ebb7dc555ca00a6a650f) ## Example: Skill Suggestions with English Descriptions In this example, the card includes the English skill descriptions of the suggested skills. By default, skill descriptions are hidden. An info icon is displayed, which users can click to reveal the skill descriptions. ![Skill description icon](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/teams-skill-description-icon.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=eafd920937c3f8753170028b46729325) When the user clicks the info icon, the English skill descriptions are displayed. ![English skill descriptions](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/teams-skill-description-expanded.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=2dbee1818f8039c05c182a780e8afbaa) Skill descriptions can also be shown in combination with the sources. ![Skill descriptions with sources](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/teams-skill-description-with-sources.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=e2ebb49b364c88866b32b0d0c5484641) # Validated Suggestions In this example, the card displays a list of validated Skill Suggestions. ![Validated Suggestions](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/validated-suggestions.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=f87e4596ebe4a78fc764c09e297a591e) # Outdated Message When a new reminder or new skill suggestions are sent while previous suggestions are still unsubmitted, the previous message is replaced with the outdated message. There is no time-based trigger — this only happens when the next reminder or new skill suggestions are sent. ![Outdated message replacing the previous suggestions message](https://mintcdn.com/techwolf/UIKPqxg5WqnaxR3i/integrations/skill-assistant/teams/images/outdated-message.png?fit=max\&auto=format\&n=UIKPqxg5WqnaxR3i\&q=85\&s=14621b27ae6ceb00785904038e0908b3) # Skill Management Tab ## Example: Normal Skill Profile Management In this example, the Employee can manage their Skill Profile by simply adding or deleting Skills. ![Skill Management Tab Interface](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_default.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=1202f3aa46fc313aa2e46f9b7dd3d8c2) ## Example: Skill Profile Management including suggested and self-rated proficiency levels The functionality can be extended to let the user govern their proficiency level for each skill. Each level has a descriptive label so that the Employee knows what each level means. When available, a suggested proficiency level per skill is shown. When Skill descriptions or proficiency level descriptions are enabled, each Skill also has a **Show details** button, described [below](#example-skill-details). ![Skill Management Tab Interface](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_proficiency.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=aa72c6ab1e90567cef01a72ea8023efe) Self-Rated Skill proficiency levels can be updated by the Employee by clicking on a different proficiency level. ## Example: Skill details With proficiency levels and Skill descriptions or proficiency level descriptions enabled, the **Show details** button opens a dialog about that Skill. It shows the Skill's description and, for each proficiency level, what that level means for this Skill. The suggested level carries a **Suggested** tag and the Employee's current level is selected. Which parts are shown follows which descriptions are enabled. ![Skill details dialog for a validated Skill](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_skill_details.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=a1548304f8ace85ce83c0f0b0addf3ac) The Employee can rate the Skill from this dialog: pick another level, then **Save**. For a rejected Skill, the same dialog is read-only, so the Employee can still read what the Skill means before deciding to add it back. ![Read-only Skill details dialog for a rejected Skill](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_skill_details_rejected.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=70bd57a56f49624f286bd9ea13d1f573) ### Adding a Skill with its details When the **Show details** button is offered, clicking a Skill in the search results does not add it right away. Otherwise the Skill is added at once. ![Searching for a Skill in the Skill Management Tab](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_search.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=5a0416563d1e3a14b0fce0ebb584ac11) It opens the details dialog first, so the Employee reads what the Skill means and can pick their level. The Skill is added to their Skill Profile when they click **Add**, at the picked level if they chose one. ![Skill details dialog when adding a Skill from the search](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_skill_details_add.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=cefea643a80bb703cf015480ccded2e2) ## Example: Skill Profile Management including job-critical skills The functionality can be extended to show which Skills are critical to the Employee's current Job. A **Job Skill** column marks each Skill, and the job-critical Skills are listed first, so the Employee knows which Skills matter most and which to rate first. Employees can still delete any Skill. ![Skill Management Tab with job-critical skills](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_job_skills.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=b78f345cf711d0cf357da0692f86b484) ## Example: Skill Profile Management for SAP customers For SAP customers, the UI is updated to reflect the same wording that is used in the SAP Growth Portfolio. A custom message can be configured with a link to the Employee's SAP Growth Portfolio. Additionaly, the Skills that are already part of the Skill Profile of the Employee through their Job are shown. Employee has this Skill because their Job requires it. Employees cannot delete Job Skills from their Skill Profile. ![Skill Management Tab Interface](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_sap.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=50644c0500fba7fa2c4d9ab7f2596d79) # How It Works Source: https://developers.techwolf.ai/integrations/skill-assistant/teams/how-it-works # Suggestions ![Suggestions](https://mintlify.s3.us-west-1.amazonaws.com/techwolf/snippets/skill-assistant/images/suggestions.png) 1. **Scheduled trigger**: We send out suggestions at specific time intervals. On such an interval cycle, we trigger the TechWolf Skill Assistant. The interval can be changed depending on your needs. 2. **Fetch suggestions**: To get those suggestions, we fetch them from our own API. More specifically, from the [Suggestions Skill Profile](/reference/latest/Employees/EmployeeSuggestions/post-employees-suggestions-skills) endpoint, for all employees. 3. **Format suggestions**: The Skill Assistant first determines which users should receive suggestions or reminders. The system determines this by checking when each user last received a suggestion and comparing it against the configured timing parameters for suggestions and reminders. The suggestions are then formatted based on the configurations for the message content. See how the message looks like in the `How It Looks` section. 4. **Send suggestions**: We send out the suggestions to the messaging platform. 5. **Users receive the message**: The messaging platform delivers the message to the correct user. ### How the Skill Engine API max skills setting affects suggestions The Skill Engine API uses the `max_skills` setting to return the top ranked Skills for an Employee based on their data. This setting does not directly mean that an Employee will only ever see that number of suggestions over time. The ranking is based on the Employee Skill Profile and includes Skills that were already accepted or rejected. The Skill Engine API then filters out already validated Skills before suggestions are shown in the Skill Assistant. #### What happens near the limit Rejected Skills can still influence the top `max_skills` ranking through an indirect effect. A rejection acts as feedback for the recommendation model and can change the confidence scores of related Skills. When an Employee is close to the limit, this recalculation can reorder the Employee Skill Profile and cause a different Skill to enter the top `max_skills`. 1. The Skill Engine API returns the top `max_skills` Skills from the Employee Skill Profile. 2. The Employee validates suggestions (for example, accepts 6 and rejects 4). 3. The recommendation scores are recalculated based on the new feedback, including the rejection signal, which can change nearby Skill rankings. 4. If this recalculation pulls another Skill into the top `max_skills`, that Skill can appear as a new suggestion. #### What happens when data changes When new Skill Events are added, probabilities can change and different Skills can enter the top `max_skills` ranking. This can create new suggestions for the Employee. ![Employee Skill Profile states after new Skill Events](https://mintlify.s3.us-west-1.amazonaws.com/techwolf/snippets/skill-assistant/images/max-skills-profiles-after-new-events.png) 1. New Skill Events are added for the Employee. 2. New inferred Skills are scored and compared against the current top `max_skills` ranking. 3. Only the new Skills that enter the top `max_skills` become visible suggestions. 4. Repeating this process over time can lead to more than `max_skills` validated Skills on an Employee profile. # Validations ![Validations](https://mintlify.s3.us-west-1.amazonaws.com/techwolf/snippets/skill-assistant/images/validations.png) 1. The user clicks submit on a card, which informs the messaging platform that it should send an update to the TechWolf Skill Assistant. 2. The message is received by the Skill Assistant, which receives a list of confirmed and rejected skills. 3. The TechWolf Skill Assistant stores this information, such as which skills, but also when and by whom. 4. The feedback is sent to the TechWolf API, using the [Employee Skill Profile feedback endpoint](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile) and can be tracked with the `source` field as `"tw-teams-bot"`. To access feedback provided by an employee through the Skill Assistant, use the [Employee List Skill Event endpoint](/reference/latest/Employees/SkillEvents/get-employees-employee-external-id-skill-events) with `skill_profile_feedback` as `event_type`. The resulting Skill Events with `source` field as `"tw-teams-bot"` are the feedback events given using the Skill Assistant. # Employee Skill Management Tab In addition to our Skill Assistant: We offer an interactive tab that enables employees to efficiently manage and track their skills. Within this tab, employees can: * **View and Reevaluate Skills**: Access their validated and rejected skills for assessment and potential updates. * **Add Missing Skills**: Identify and add any skills that may be lacking. * **Self-rate Skill proficiency levels (optional)**: Update the proficiency level of a Skill. * **Read Skill details (optional)**: Open a Skill's description and what each proficiency level means for it, before rating or adding it. See [How It Looks](/integrations/skill-assistant/teams/how-it-looks#example-skill-details). ![Skill Management Tab Interface](https://mintcdn.com/techwolf/wduD7N2PiGvxnQNj/integrations/skill-assistant/teams/images/skillmanagement_default.png?fit=max\&auto=format\&n=wduD7N2PiGvxnQNj\&q=85\&s=1202f3aa46fc313aa2e46f9b7dd3d8c2) # Linking users ### Through Custom Properties An important step for the Skill Assistant to work is linking employee profiles in TechWolf to users in the messaging platform. This can be done by setting a Custom Property on the employee profile in TechWolf. The Skill Assistant will then use this Custom Property to link the employee profile to the user in the messaging platform. ### Through Microsoft Graph Another way to link employee profiles in TechWolf to users in the messaging platform is to use the Microsoft Graph API. This is the preferred method, as it is more secure and reliable. TechWolf reads a configurable user property from the Microsoft Graph API and matches its value to the employee ID known within TechWolf's SkillEngine API. By default this is the `Employee ID` (`employeeId`) property, but it can be set to any other Microsoft Graph user property during onboarding. See [Linking Microsoft Teams users and employee profiles in TechWolf](./installation/#linking-microsoft-teams-users-and-employee-profiles-in-techwolf) for the available options. For example, when the default `employeeId` property is used, TechWolf reads it through the following endpoint: ``` https://graph.microsoft.com/v1.0/users/?$select=employeeId ``` Notice the `$select` query parameter, which limits the response to the configured linking property of the given Teams user. # Data flows ### General overview ![Data Flow Overview](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/general-overview-dataflow.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=96525fe2161e0e0f4303224b30af9ed3) #### Components **Microsoft Teams** The Microsoft Teams environment used by the customer. **Azure infrastructure** TechWolf utilizes Azure infrastructure to facilitate communication between Microsoft Teams and the Skill Assistant. This infrastructure comprises: * **Bot Service**: Required by Microsoft Teams to create a bot. It acts as the intermediary between Teams and the Skill Assistant, handling message exchanges and event triggers from Teams users. * **Entra Application**: Handles authentication and authorization with Microsoft Teams and the Graph API. * **Front Door**: Routes incoming requests from the Bot Service or Skill Profile tab to the appropriate Skill Assistant deployment (EU/US). **Skill Assistant** TechWolf's backend system responsible for generating skill suggestions, processing feedback, and managing data for the Skill Profile tab. **Skill Engine API** The main TechWolf product. Handles skill-related data processing and integration. #### Data processing **Types of data that is processed** * **Skill Suggestions**: Automatically inferred skills for an employee, retrieved from the Skill Engine API. * **Skill Feedback**: Employee feedback on their suggested skills. Either validating that they have the skills, or rejecting the skills. * **Skill Profile**: A list of validated and rejected skills maintained in the Skill Engine API. * **Microsoft User Data**: Employee details retrieved from Microsoft systems, including name and email. **Data Processing Overview** | | **Managed by** | **Suggestions** | **Feedback** | **Skill Profile** | **Microsoft User Data** | | - | - | - | - | - | - | | **Microsoft Teams** | Customer | X | X | X | X | | **Azure: Entra Application** | TechWolf | | | | | | **Azure: Bot Service** | TechWolf | X | X | | X | | **Azure: Front Door** | TechWolf | X | X | X | X | | **Skill Assistant** | TechWolf | X | X | X | X | #### Data storage **Overview of Data Storage Locations** | | **Managed by** | **Suggestions** | **Feedback** | **Skill Profile** | **Microsoft User Data** | | - | - | - | - | - | - | | **Microsoft Teams** | Customer | X | X | | X | | **Azure** | TechWolf | | | | | | **Skill Assistant** | TechWolf | X | X | | X *(No personal identifiable information stored)* | #### **Communication Protocols** All data exchanges occur over REST APIs secured by **TLS 1.2** or higher. ### Suggesting Skills ![Suggesting Skills](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/suggesting-skills-dataflow.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=f9aed2abf5b8b27571272a1cf25daccd) **Process** 1. **Fetch suggestions**: On a regular basis, the Skill Assistant will fetch suggestions generated by the API. 2. **Routing the suggestion**: The suggestion is sent to the Azure Tenant, where it is routed to the concerning employee. 3. **Sending the suggestion**: The suggestion is sent through the 'adaptive card' format by the Bot Service to the customer Teams tenant. **Data Involved** 1. Teams ID, Internal ID, Suggestion 2. Teams ID, Suggestion 3. Teams ID, Suggestion ### User Input User input entails button clicks, messages and installation events. ![User Input](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/user-input-dataflow.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=6d8d564163c4218f3965ebbc014d501c) 1. **User input request**: When a user interacts with a suggestion, it is sent to the Bot service in the TechWolf Azure instance. 2. **Routing to Skill Assistant**: The request is processed and routed by the Bot Service to the Skill Assistant. Only necessary information is retained, and names and email addresses are dropped. 3. **Execution of request**: The Skill Assistant directs the request in proper format to the API, where the request is executed on the customer's data. 4. **Response to user**: A response, based on the request's proper execution, is sent back to the Bot Service to route it back to the concerning user. 5. **Sending the response**: The response is sent to the user by the Bot Service. **Data Involved** 1. [Event Data](https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0#activity-object), Feedback, MS User Data (Contains first name, last name and email address which cannot be dropped from the request. [ref](https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0#channelaccount-object)) 2. [Event Data](https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0#activity-object), Feedback, MS User Data (Contains first name, last name and email address which cannot be dropped from the request. [ref](https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0#channelaccount-object)) 3. Internal ID, Teams ID, Depending on the event: Feedback, Request suggestions or Skill Profile 4. Teams ID, Custom response, Depending on the event: Suggestion or Skill Profile 5. Teams ID, Custom response, Depending on the event: Suggestion or Skill Profile # Installation Source: https://developers.techwolf.ai/integrations/skill-assistant/teams/installation # Required Roles for Teams Installation The required roles for the Teams installation are: * **Azure Admin**: A user with administrative privileges who can grant permissions to the Skill Assistant app and run a script to force install the app for users. * **Teams Admin**: A user with administrative privileges who can install and manage apps in Teams. * **Azure Group Admin**: A user that can create and maintain an Azure group of users. * **Customer Contact with TechWolf**: A designated representative who coordinates with TechWolf's team to facilitate the integration process, provide necessary information, and ensure successful implementation of the Skill Assistant in your Teams environment. # Required Teams App Permissions The Skill Assistant application requires the following permissions: * `User.Read.All` application permission * `User.Read` delegated permission The `User.Read.All` application permission allows the app to read user profiles for all users in the organization. This is necessary for the Skill Assistant to fetch the linking property of a user (by default the Employee ID) using the Microsoft Graph API. More information about this can be found in the [Linking Microsoft Teams users and employee profiles in TechWolf ](#linking-microsoft-teams-users-and-employee-profiles-in-techwolf) section. The `User.Read.All` permission is also required for the Skill Assistant to fetch the user's country information, which is used to send suggestions according to the user's country timezone when the user-based scheduling setting is enabled. This country information is read from the **usageLocation** property in Microsoft Graph. > [!NOTE] > > For the Skill Assistant to use **user timezones** (when user-based > scheduling is enabled), the **usageLocation** property must be set for each > user in Microsoft 365 / Entra ID. The Skill Assistant uses usageLocation to > derive the user's timezone. If usageLocation is not set for a user, that > user will receive suggestions according to the tenant's default timezone > instead. You can set usageLocation in the [Microsoft 365 admin > center](https://admin.microsoft.com/) or via [Microsoft > Graph](https://learn.microsoft.com/en-us/graph/api/user-update). The Skill > Assistant also updates a user's timezone whenever it receives it from Teams > (e.g. from the message context); this only happens after the user has sent > their first message to the Skill Assistant. The `User.Read` delegated permission allows the app to read user profiles for the user who is currently logged in. This is necessary for the Skill Assistant to properly show the Skill Profile Tab. # Installation steps The installation consists of several steps, which are described in detail below. TechWolf needs to configure the Skill Assistant to work with your tenant, you need to give the app the right permissions, and you need to install the app in your Teams environment. **1. Share your Azure Tenant ID with TechWolf.** Share your **Azure Tenant ID** with TechWolf. TechWolf will configure the Skill Assistant to work with your production tenant. Follow the steps in [Get Azure Tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant) to find your Azure Tenant ID. **2. Link Microsoft users to employee profiles in TechWolf** We need a method to link employee profiles in the TechWolf API to Teams Users in Microsoft Teams. See [Linking Microsoft Teams users and employee profiles in TechWolf ](#linking-microsoft-teams-users-and-employee-profiles-in-techwolf). **3. Whitelist the Skill Profile Tab URL (if required)** If your organization restricts outbound internet traffic by default (i.e., blocks all URLs unless explicitly allowed), you will need to whitelist the following URL to ensure the Skill Profile tab functions correctly: `teams-tab-frontdoor.skillengine.eu`. This URL doesn't handle any personal or company data, it only loads the visual interface for the Skill Profile tab in Microsoft Teams. **4. Grant permissions to the Skill Assistant app** Grant the app the required permissions. Follow [these steps](#grant-permissions-to-the-skill-assistant-app). **5. Customize the branding of the Skill Assistant app** Customize the branding of the Skill Assistant app by following [these steps](./customizations/#branding). **6. Install the Skill Assistant for users** Install the Skill Assistant for users following [these steps](#installing-the-skill-assistant-for-users) ### Linking Microsoft Teams users and employee profiles in TechWolf In order for TechWolf's Skill Assistant to deliver personalized and timely skill suggestions via Microsoft Teams, it is crucial that we can accurately link each employee in your organization to their corresponding Teams user. There are two options to link the two IDs: 1. [Through Microsoft Graph (preferred)](#through-microsoft-graph-preferred) 2. [Through Custom Properties](#through-custom-properties) If this is set up correctly, the TechWolf Skill Assistant will be able to fetch all skill suggestions and send them to the right Teams user. #### Through Microsoft Graph (preferred) The preferred method is to use the Microsoft Graph API to read a user property whose value matches the employee ID known within TechWolf's SkillEngine API. By default this is the `Employee ID` (`employeeId`) property. This requires the `Employee ID` property to be set in Azure for each user, and for that value to *exactly match* the employee ID known within TechWolf's SkillEngine API. In that case we can automatically link the Teams user to the employee profile in TechWolf. Ideally, the Employee ID is filled in automatically using an integration with your organization's HR system. If this is not possible, you can manually populate the Employee ID property by following this guide: [Set Employee ID in Microsoft 365](https://o365info.com/set-employee-id-microsoft-365/) > [!NOTE] > > **Linking on a different Microsoft Graph property.** You are not limited to > the `Employee ID` property. If your organization stores the matching value > elsewhere, TechWolf can read it from any other Microsoft Graph user > property instead. Let TechWolf know during onboarding which property to use, > and we will configure it for your tenant. > > * **Top-level property:** any user property, for example > `onPremisesImmutableId`. > * **Nested property:** a property inside a complex type, addressed with dot > notation, for example > `onPremisesExtensionAttributes.extensionAttribute1`. > > We recommend pointing this at a stable, non-personal identifier (such as an > employee number or immutable ID). The configured value is stored on the > TechWolf side to perform the link, so avoid properties that contain personal > data, like `mail` or `userPrincipalName`. > > Whichever property is configured, its value must *exactly match* the > employee ID known within TechWolf's SkillEngine API. #### Through Custom Properties If the `Employee ID` property is not set in Azure, or if the Employee ID property in Azure is different from the employee ID stored in the TechWolf SkillEngine API, we can use a [Custom Property]() for each employee profile in the TechWolf SkillEngine API. The Azure ID should be stored in the Custom Property with the key `employee_azure_id`. The mapping between the employee ID known in TechWolf's SkillEngine and their corresponding custom property should be send to TechWolf via the datasource integration so that we can store it accordingly. > [!NOTE] > > The Azure ID we require (often referred to as the **Object ID**) has the > following format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (e.g. > `3f2a9c4e-7b6d-4e2b-9c9a-1a2b3c4d5e6f`). ### Grant permissions to the Skill Assistant app **1. Go to your Teams admin page** Go to your [Teams admin page](https://admin.teams.microsoft.com/). **2. Navigate to Manage apps** Go to **Teams apps** -> **Manage apps** ![Manage apps menu](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/teamsadminappmenu.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=75a18c4060e26df1060f8771f8291ed6) **3. Search TechWolf Skill Assistant** Type "TechWolf Skill Assistant" in the search bar. ![Search app](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/searchapp.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=ab7ff78cf730ff66854809071319a1e0) **4. Click on TechWolf Skill Assistant** Click on the name of the "TechWolf Skill Assistant" app. **5. Navigate to the Permissions tab** Navigate to the Permissions tab (1). **6. Grant permissions** Grant the app the required permissions. Do so by pressing **Grant admin consent** (2). This will open a pop up. More information about the required permissions can be found in the [Required permissions of the Skill Assistant application](#required-teams-app-permissions) section. ![Grant admin consent](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/grantpermissions.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=283feca31b6c01f922ecd78d38b95849) **7. Select account** Select your account and log in if necessary (1). **8. Accept permissions** Review the required permissions and grant them, by clicking **Accept** (2). ![Popup](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/popup.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=530d5169faaf7f5c4e4289b2e0e4e415) ### Installing the Skill Assistant for users Depending on your organisation's workflow to install apps for employees, you should now install the Skill Assistant for your employees. We recommend the following workflow: **1. Setup user groups** The easiest way to install the app for a subset of users is to create a group in Azure AD and assign the app to that group. This way, you can easily manage who has access to the app. To create a group, follow the [Microsoft guide on creating a group](https://learn.microsoft.com/en-us/entra/fundamentals/groups-view-azure-portal). **2. Setup installation** We recommend to use the app centric management functionality if possible. If you are using app centric functionality, then follow [these steps](#install-the-app-using-app-centric-management) to install the app. If you are not using app centric functionality, then follow [these steps](#install-the-app-without-app-centric-management) to install the app. **3. Force install using Graph API** If the app is not installed for all users, you can force the installation for the remaining users using the Microsoft Graph API by following [these steps](#force-installing-the-app-using-the-microsoft-graph-api). #### Install the app using App Centric Management If you are using app centric management for app availability, you can install the app for the group of users by following the following steps. **1. Make app available for users** Make the app available for the group of users by following [this guide from Microsoft](https://learn.microsoft.com/en-us/microsoftteams/app-centric-management#add-or-modify-app-availability-for-users). **2. Install the app for users** If you are using app centric management for installation, you can install the app for the group of users by following [this guide from Microsoft](https://learn.microsoft.com/en-us/microsoftteams/install-teams-apps#install-apps-using-app-centric-management). If you are not using app centric management for installation, you can use Setup Policies to install the app for the group of users. Follow [these steps](#install-the-app-using-setup-policies) to install the app using Setup Policies. > [!WARNING] > > This can take a significant amount of time. We advise to install the users at > least 1 week before the go-live date. > > Some users might need to restart their Teams to get the app installed. > > If there are still users that don't have the app after a week, the force > installation using the next step needs to be done. #### Install the app without App Centric Management > [!NOTE] > > We recommend to use app centric management for installation if possible. **1. Install the app using setup policies** You can install the app for a group of users using setup policies. Follow [these steps](#install-the-app-using-setup-policies) to install the app using Setup Policies. > [!WARNING] > > The setup policy is only applied after the permission policy is updated (see step 2). > [!WARNING] > > This can take a significant amount of time. We advise to install the users at > least 1 week before the go-live date. > > Some users might need to restart their Teams to get the app installed. > > If there are still users that don't have the app after a week, the force > installation using the next step needs to be done. **2. Update permission policy** We recommend to adjust the global permission policy to allow the TechWolf Skill Assistant app. If modifying the global policy is not desired, you can create a new permission policy by following [this guide](https://learn.microsoft.com/en-us/microsoftteams/teams-app-permission-policies#create-an-app-permission-policy) and assign it to the group by following [these steps](#assigning-the-permission-policy-to-a-group). #### Install the app using Setup Policies Follow [this guide from Microsoft](https://learn.microsoft.com/en-us/microsoftteams/teams-app-setup-policies#install-apps-to-teams-client-of-your-users) to install the app using Setup Policies. Make sure to apply the setup policy to the group of users by following [this section from the Microsoft guide](https://learn.microsoft.com/en-us/microsoftteams/teams-app-setup-policies#assign-a-custom-policy-in-app-setup-policy-to-users-and-groups). > [!WARNING] > > If a setup policy is already applied to a user, the new setup policy will > not be applied to that user! > > If you have different groups of users that require different app configurations, you'll need to create a unique setup policy for each group. #### Assigning the permission policy to a group This section describes how to assign the permission policy to a group of users. > [!NOTE] > > This section is only relevant when you do not have the app centric > management functionality and have created a new permission policy. Microsoft Teams does not support assigning app permission policies to groups. However, it does support [assigning policies to a batch of users](https://learn.microsoft.com/en-us/microsoftteams/assign-policies-users-and-groups#assign-a-policy-to-a-batch-of-users). > [!NOTE] > > These steps require a setup policy to be applied to the group first. > [!WARNING] > > The users linked to the permission policy will not be automatically updated > when users are added/deleted from the group. **1. Navigate to Manage Users** Go to **Users** -> **Manage users** **2. Click on the filter icon** Click on the filter icon in the top right corner. ![Filter icon](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/filter-users.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=d0595807b11258e351dee2af6ef0f8be) **3. Filter on setup policy** Select the setup policy as filter and the created setup policy as filter value. Click on **Apply** to apply the filter. ![Filter setup policy](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/teams/images/filter-setup-policy.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=3a2ede9c1baa68fc31a2243699179bf3) **4. Select all users** Click on the checkmark icon in the top left corner to select all users. ![Select all users](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/select-all-users.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=161d4801c75b54c0d8dfcce01edb1007) **5. Edit settings** Click on the **Edit settings** button in the top left corner. ![Edit settings](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/teams/images/edit-settings.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=e81cb8f4b3aa2ee05d8f860df69d8f01) **6. Assign the permission policy** Select the created permission policy from the dropdown menu. Click on **Apply** to assign the permission policy to the selected users. ![Assign permission policy](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/teams/images/assign-permission-policy.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=4e31c13a72de72a6fd14951f1c9ac6d2) #### Force installing the app using the Microsoft Graph API If the app is not installed for all users, you can force the installation for the remaining users using the [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/api/userteamwork-post-installedapps). **1. Create file with Azure IDs** Create a text file containing all Azure IDs (Object IDs) of the people for which the app needs to be installed. This file is structured as a list of the Azure IDs, separated by newlines. ```plaintext theme={null} 3f2a9c4e-7b6d-4e2b-9c9a-1a2b3c4d5e6f a1b2c3d4-e5f6-7890-abcd-ef1234567890 12345678-90ab-cdef-1234-567890abcdef ... ``` **2. Download the script** We created a template script that you can use to force install the app. > **[Download the script](https://26502993.fs1.hubspotusercontent-eu1.net/hubfs/26502993/Developer%20portal/script.ps1)** **3. Create a new service principal** Create a new service principal in Azure AD to run the script. Follow the [Microsoft guide on creating a service principal](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#register-an-application-with-microsoft-entra-id-and-create-a-service-principal). **4. Create a client secret** A client secret is needed to run the script. In the newly created service principal, select `Certificates & secrets`. Select `Client secrets`, and then select `New client secret` and click `Add`. You will need this secret later to run the script. ![Client secret](https://mintcdn.com/techwolf/hcu65nk-6HLQY3kl/integrations/skill-assistant/teams/images/clientsecret.png?fit=max\&auto=format\&n=hcu65nk-6HLQY3kl\&q=85\&s=483aa149852aa0a00b7d59bca4d3c478) **5. Add the permission** The script requires the `TeamsAppInstallation.ReadWriteForUser.All` and `User.Read.All` permissions. In the service principal, select `API permissions`. Click on `Add a permission` and select `Microsoft Graph`. Select `Application permissions` and search for `TeamsAppInstallation.ReadWriteForUser.All` and select it. Search `User.Read.All` and select it too. Click on `Add permissions` to add the permission. Select the added permissions and click `Grant admin consent`. ![Add permission](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/graphpermissions.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=6e1e5af1c722bbfab96bed98955d9115) **6. Fill in the variables** Fill in the variables in the script: * `$FilePath`: the path to the previously created file (from Step 1) containing the Azure IDs * `$ApplicationID`: The Application Client ID of the newly created service principal (from step 3) * `$ClientSecret`: The Application Client Secret of the newly created service principal (from step 4) * `$TenantID`: The tenant ID of your Teams instance **7. Run the script in Powershell** Run the script in Powershell. In [Azure Portal](https://portal.azure.com/), click in the top right on the `Cloud Shell` icon. ![Powershell logo](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/teams/images/powershelllogo.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=edc1195cff26c9ca5beb844e3100a16f) Click on `Manage files` and upload the file with Azure IDs and the filled in script. Run the script by typing `./script.ps1`. # Customizations Source: https://developers.techwolf.ai/integrations/skill-assistant/workday/customizations # Branding ## What can be customized? The name of the Skill Assistant can be customized. ## How to customize the application in Workday? To customize the name of the Workday Skill Assistant, it needs to be configured in both TechWolf and Workday. You can set the name of the Workday Skill Assistant during the creation of the custom task, as described in the deployment steps of the [installation guide](/integrations/skill-assistant/workday/installation). # Customize the content of messages The content of the messages that are sent by the TechWolf Skill Assistant can be customized to better fit your company's needs. The following attributes can be customized: * The wording of the messages can be changed to better fit your company's culture. More information can be found in the [wording section](#customize-the-wording-of-messages). * The language of the messages. More information can be found in the [language section](#customize-the-language-of-messages). * The amount of skills that are suggested per message. * The option to show the sources of the skills in the suggestions. This can be set to show the source of the skills or not. * The option to show the skill descriptions of the suggestions. This is only available when using the TechWolf or Workday skill vocabulary. * The labels of the self-rated Skill proficiency levels, shared by the validation flow and the Skill Profile tab. These customizations are configured by TechWolf. Let us know what you would like to change and we will make the necessary adjustments. ### Customize the language of messages The TechWolf Skill Assistant sends messages to users in the language that is set by the user in their app. This is only the case if the language is one of the allowed languages, otherwise English is used. You can customize in which languages your employees are allowed to use. If one of your employees uses a language we support, but that is not allowed, they will also default to English. The allowed languages of the messages can be set to a subset of the following languages: English, French, German and Dutch. ### Customize the wording of messages Messages can also be changed from their default messaging. Those messages can contain any text of course. The following lists all possible messages and their default text. We highly recommend customizing these messages to your company to greatly improve user experience #### Notification messages * **Timed suggestion notification**: The notification that is sent on the configured interval. > Hi, below you can find a number of suggested skills for you. Deselect skills > that you feel you do not have. * **Reminder notification**: The notification that is sent on the configured interval when there has been no interaction with the application. > Hi, this is a reminder. Below you can find a number of suggested skills for > you. Deselect skills that you feel you do not have. #### Home card messages The home card is the card shown on the Workday home page, see the [how it looks](/integrations/skill-assistant/workday/how-it-looks#home-card) page. Each of its texts can be customized: * **Home card header**: The title of the home card. > Skill Suggestions * **Home card subtitle**: The text shown under the home card header. > Update your worker skill profile * **Home card action required label**: The label shown on the home card when the user has open skill suggestions. > ACTION REQUIRED * **Home card no action required label**: The label shown on the home card when the user has no open skill suggestions. > NO ACTION REQUIRED * **Home card with suggestions message**: The message shown on the home card when the user has open skill suggestions. The placeholder `{{suggestion_amount}}` is replaced with the number of open suggestions and can be used in your customized message. > You have open skill suggestion for review. * **Home card without suggestions message**: The message shown on the home card when the user has no open skill suggestions. > Your worker skill profile is up-to-date. #### In-app messages * **Suggestions overview message**: The message shown on the home screen above the suggestions. > Based on the available data, the below suggestions might be important to > consider to further complete your Worker Profile. > > **Please review these suggestions by clicking on the > *"Review Skills"* button.** * **Review skills message**: The message shown when the user clicks on the "Review Skills" button. > The below skills might be relevant to add to your Worker Profile. These > skills have been inferred for you based on a combination of HR and Business > data. In the "Source" column, you can see from which actual source the skill > has been inferred. Please validate the suggestions and submit the ones you > approve. * **Self-rate Proficiency Levels message**: The message shown when the user lands on the (optional) self-rating proficiency levels page after validating Skill Suggestions. > For the following Skills you accepted, please rate your proficiency level. * **Approved skills message**: The message shown when the user approves skills. > The approved skills have been added to your Workday profile. * **Rejected skills message**: The message shown when the user rejects skills. > The rejected skills have been saved. * **No more skills message**: When the user wants to validate more, but there are no more suggestions for now. > There are no more skills to validate at this time!Good work 🥳 #### Skill Profile tab messages The Skill Profile tab is described on the [how it works](/integrations/skill-assistant/workday/how-it-works#employee-skill-profile-tab) page. Its texts are customizable too: * **Skill profile page description**: The message shown at the top of the Skill Profile tab. > This page shows the skills currently on your Workday worker profile. Add a > skill, set your self-rated proficiency, re-accept a skill you previously > rejected, or remove one that is no longer relevant. Each change is > confirmed before it is saved. * **Add a skill popup description**: The message shown in the popup that opens from the "Add a skill" button. > Search for a skill to add to your profile. * **Remove skill confirmation**: The question asked before a skill is removed. The placeholder `{{skill}}` is replaced with the skill name. > Are you sure you no longer have the skill ? * **Add skill back confirmation**: The question asked before a rejected skill is added back. The placeholder `{{skill}}` is replaced with the skill name. > Are you sure you want to add back to your profile? # Customize the scheduling of messages The TechWolf Skill Assistant sends messages to users on a regular basis. This scheduling of the messages can be customized to fit your company's needs. The following attributes can be customized: * How often suggestions are sent. The options are daily, weekly, monthly, quarterly (every 3 months), biannually (every 6 months), or yearly. By default, daily sends every weekday, weekly sends every Monday, and monthly, quarterly, biannually, and yearly send on the first Monday of the relevant month. * For weekly and longer frequencies, the day on which suggestions are sent can be customized in one of two ways: * By weekday: pick a specific weekday (Monday–Friday). For monthly, quarterly, biannually, and yearly frequencies, you also pick which occurrence of that weekday within the month (first, second, third, or fourth — for example, the third Wednesday). * By date: pick a fixed day of the month (1–28). If that date falls on a weekend, sending shifts to the next Monday. This option applies to monthly and longer frequencies. * For quarterly, biannually, and yearly frequencies, the starting month can be configured. For example, quarterly starting in February sends in February, May, August, and November. * The time when messages begin sending. This process may take some time. You can set it to a specific time of day, either on the hour or the half-hour. * The amount of time to wait before sending a reminder message to users with open suggestions. This can be set to a specific number of days. For example, if the reminder window is set to 3 days and the user has not validated the skill suggestions received on Monday, they will receive a reminder on Thursday. If the user validates the suggestions on Tuesday and chooses to validate more suggestions, but then leaves the new suggestions open, the reminder window is reset and a new reminder will be sent on Friday. Reminder messages are only sent on weekdays, so if the reminder window expires during the weekend, the reminder will be sent on Monday. Reminders can also follow the suggestion frequency; in that case, on each send day, employees who still have open suggestions from a previous send day receive a reminder, and employees without any open suggestions receive new suggestions if any are available. * Whether all messages are sent at the same time or based on each user's time zone. * A minimum number of Skills that must be available before suggestions are sent to an Employee. These customizations are configured by TechWolf. Let us know what you would like to change and we will make the necessary adjustments. # How It Looks Source: https://developers.techwolf.ai/integrations/skill-assistant/workday/how-it-looks # Notifications ![Notifications](https://mintcdn.com/techwolf/jRvVdauoGLPlUtTp/integrations/skill-assistant/workday/images/workday-notifications.png?fit=max\&auto=format\&n=jRvVdauoGLPlUtTp\&q=85\&s=38dbd6631a8208118b21601a63f41aeb) # Home card ![Home card](https://mintcdn.com/techwolf/jRvVdauoGLPlUtTp/integrations/skill-assistant/workday/images/workday-home-card.png?fit=max\&auto=format\&n=jRvVdauoGLPlUtTp\&q=85\&s=adc951c5aeac62839d39d7abba8195ae) # App Home Screen ![App home screen](https://mintcdn.com/techwolf/FJOgJd1B0f99cjKg/integrations/skill-assistant/workday/images/workday-main-page.png?fit=max\&auto=format\&n=FJOgJd1B0f99cjKg\&q=85\&s=bb52f3919d0bea5ca48b9c51ed0b6ec2) The **Description** and **Sources** columns are optional and can be shown or hidden per customer preference. # Validation flow ## Suggestions ![Suggestions](https://mintcdn.com/techwolf/FJOgJd1B0f99cjKg/integrations/skill-assistant/workday/images/workday-review-skills.png?fit=max\&auto=format\&n=FJOgJd1B0f99cjKg\&q=85\&s=c905a4fa540a01a0d4eee37603d4b604) As on the App Home Screen, the **Description** and **Sources** columns are optional and can be shown or hidden per customer preference. The optional **Required job skill** column marks which suggested skills are critical to the Employee's current Job. ## Self-rating Proficiency levels ![Self-rating Proficiency Levels](https://mintcdn.com/techwolf/FJOgJd1B0f99cjKg/integrations/skill-assistant/workday/images/workday-self-rate-proficiency-levels.png?fit=max\&auto=format\&n=FJOgJd1B0f99cjKg\&q=85\&s=65d7f8dd64548509aff516e87b163ca4) ## Skills summary without Self-rated Proficiency Levels ![Skills summary without Self-rated Proficiency Levels](https://mintcdn.com/techwolf/FJOgJd1B0f99cjKg/integrations/skill-assistant/workday/images/workday-skills-summary.png?fit=max\&auto=format\&n=FJOgJd1B0f99cjKg\&q=85\&s=aaa237029871a53b52e6b07c92ababb7) ## Skills summary with Self-rated Proficiency Levels ![Skills summary with Self-rated Proficiency Levels](https://mintcdn.com/techwolf/FJOgJd1B0f99cjKg/integrations/skill-assistant/workday/images/workday-skills-summary-with-self-rated-proficiency-levels.png?fit=max\&auto=format\&n=FJOgJd1B0f99cjKg\&q=85\&s=ad32d394e94417fbed39b6a0bc63092d) ## No more suggestions ![No more suggestions](https://mintcdn.com/techwolf/jRvVdauoGLPlUtTp/integrations/skill-assistant/workday/images/workday-no-suggestions.png?fit=max\&auto=format\&n=jRvVdauoGLPlUtTp\&q=85\&s=c15a2d99573575e76b16c6d9c26d6323) # Skill Profile tab The **Manage your skill profile** view lets employees manage their skill profile at any time, see the [how it works](/integrations/skill-assistant/workday/how-it-works#employee-skill-profile-tab) page. ## Example: Normal Skill Profile Management In this example, the Employee can manage their Skill Profile by adding or removing Skills, and by adding back a Skill they rejected earlier. The **Details** column is optional and can be shown or hidden per customer preference. ![Skill Profile tab](https://mintcdn.com/techwolf/0VWJd1tvfGL9QCBR/integrations/skill-assistant/workday/images/workday-skill-profile.png?fit=max\&auto=format\&n=0VWJd1tvfGL9QCBR\&q=85\&s=647d70ad0d757a8a14ef28e3d3f1adca) ## Example: Skill Profile Management including suggested and self-rated proficiency levels The functionality can be extended to let the user govern their proficiency level for each skill. Each level has a descriptive label so that the Employee knows what each level means. When available, a suggested proficiency level per skill is shown; a skill without one shows a dash. ![Skill Profile tab with proficiency levels](https://mintcdn.com/techwolf/0VWJd1tvfGL9QCBR/integrations/skill-assistant/workday/images/workday-skill-profile-proficiency.png?fit=max\&auto=format\&n=0VWJd1tvfGL9QCBR\&q=85\&s=6ff786518bb7a21743ba6f8e765246ca) Self-Rated Skill proficiency levels can be updated by the Employee by clicking on the current level and picking a different one. The same popup opens from the **Show details** button and also shows the skill description and the suggested level. ![Skill details and rating popup](https://mintcdn.com/techwolf/0VWJd1tvfGL9QCBR/integrations/skill-assistant/workday/images/workday-skill-profile-details.png?fit=max\&auto=format\&n=0VWJd1tvfGL9QCBR\&q=85\&s=4f8fee8ea7c66cc5085b1dc4da53339f) ## Example: Skill Profile Management including job-critical skills The functionality can be extended to show which Skills are critical to the Employee's current Job. A **Required job skill** column marks each Skill, and the job-critical Skills are listed first, so the Employee knows which Skills matter most and which to rate first. ![Skill Profile tab with job-critical skills](https://mintcdn.com/techwolf/0VWJd1tvfGL9QCBR/integrations/skill-assistant/workday/images/workday-skill-profile-job-skills.png?fit=max\&auto=format\&n=0VWJd1tvfGL9QCBR\&q=85\&s=cb661a29313419c5c1bf259c47a87143) ## Example: Removing a skill and adding one back Removing a skill asks for confirmation first. ![Remove skill confirmation](https://mintcdn.com/techwolf/0VWJd1tvfGL9QCBR/integrations/skill-assistant/workday/images/workday-skill-profile-remove.png?fit=max\&auto=format\&n=0VWJd1tvfGL9QCBR\&q=85\&s=29ecf59bf23bba68d9100cfc08a7e413) Adding back a skill that was rejected earlier also asks for confirmation, and shows the skill description. When proficiency levels are used, the Employee picks their level before adding the skill back. ![Add skill back confirmation](https://mintcdn.com/techwolf/0VWJd1tvfGL9QCBR/integrations/skill-assistant/workday/images/workday-skill-profile-add-back.png?fit=max\&auto=format\&n=0VWJd1tvfGL9QCBR\&q=85\&s=13298e21fbcb39550b201107dfc0ff62) ## Example: Adding a skill The **Add a skill** button opens a search over the skill vocabulary. Skills already on the profile are left out of the results. ![Add a skill popup](https://mintcdn.com/techwolf/0VWJd1tvfGL9QCBR/integrations/skill-assistant/workday/images/workday-skill-profile-add-skill.png?fit=max\&auto=format\&n=0VWJd1tvfGL9QCBR\&q=85\&s=d70141267eb110f4089338e2dbcd8ed2) After picking a result and pressing **Next**, the Employee sees the skill description and, when proficiency levels are used, picks their level. Pressing **Add** adds the skill to the profile. ![Add a skill details popup](https://mintcdn.com/techwolf/0VWJd1tvfGL9QCBR/integrations/skill-assistant/workday/images/workday-skill-profile-add-skill-details.png?fit=max\&auto=format\&n=0VWJd1tvfGL9QCBR\&q=85\&s=579651b8b8ec1b77ba411013f057c1af) # How It Works Source: https://developers.techwolf.ai/integrations/skill-assistant/workday/how-it-works # Suggestions ![Suggestions](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/workday/images/suggestions-workday.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=ff9ab3e7d2d38c05bf96b263cf97325c) 1. **Scheduled trigger**: We send out suggestions at specific time intervals. On such an interval cycle, we trigger the TechWolf Skill Assistant. The interval can be changed depending on your needs. 2. **Fetch employees**: To get employees that have suggestions, we fetch them from our own API. More specifically, from the [Suggestions Skill Profile](/reference/latest/Employees/EmployeeSuggestions/post-employees-suggestions-skills) endpoint. 3. **Send notifications**: We send out the notifications to Workday. 4. **Users receive the notification**: Workday delivers the notification to the correct user. ### How the Skill Engine API max skills setting affects suggestions The Skill Engine API uses the `max_skills` setting to return the top ranked Skills for an Employee based on their data. This setting does not directly mean that an Employee will only ever see that number of suggestions over time. The ranking is based on the Employee Skill Profile and includes Skills that were already accepted or rejected. The Skill Engine API then filters out already validated Skills before suggestions are shown in the Skill Assistant. #### What happens near the limit Rejected Skills can still influence the top `max_skills` ranking through an indirect effect. A rejection acts as feedback for the recommendation model and can change the confidence scores of related Skills. When an Employee is close to the limit, this recalculation can reorder the Employee Skill Profile and cause a different Skill to enter the top `max_skills`. 1. The Skill Engine API returns the top `max_skills` Skills from the Employee Skill Profile. 2. The Employee validates suggestions (for example, accepts 6 and rejects 4). 3. The recommendation scores are recalculated based on the new feedback, including the rejection signal, which can change nearby Skill rankings. 4. If this recalculation pulls another Skill into the top `max_skills`, that Skill can appear as a new suggestion. #### What happens when data changes When new Skill Events are added, probabilities can change and different Skills can enter the top `max_skills` ranking. This can create new suggestions for the Employee. ![Employee Skill Profile states after new Skill Events](https://mintcdn.com/techwolf/JdUJW5PN6MYJZDA8/snippets/skill-assistant/images/max-skills-profiles-after-new-events.png?fit=max\&auto=format\&n=JdUJW5PN6MYJZDA8\&q=85\&s=5f5c9f960f5630cdf02e45f60501179d) 1. New Skill Events are added for the Employee. 2. New inferred Skills are scored and compared against the current top `max_skills` ranking. 3. Only the new Skills that enter the top `max_skills` become visible suggestions. 4. Repeating this process over time can lead to more than `max_skills` validated Skills on an Employee profile. # Validations ![Validations](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/workday/images/validations-workday.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=0643a469d09b083b0b1ed05c189c145e) 1. a) The user clicks on "Approve" or "Reject" when validating suggestions, which informs Workday that it should send an update to the TechWolf Skill Assistant. b) (Optional) When proficiency levels for Skills are enabled, the user can choose a proficiency level for each accepted Skill Suggestion. 2. The validation is received by the Skill Assistant, which receives a list of approved or rejected skills. 3. The TechWolf Skill Assistant stores this information, such as which skills, but also when and by whom the skills were approved or rejected. 4. The feedback is sent to the TechWolf API, using the [Employee Skill Profile feedback endpoint](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile) and can be tracked with the `source` field as `"tw-workday-bot"`. To access feedback provided by an employee through the Skill Assistant, use the [Employee List Skill Event endpoint](/reference/latest/Employees/SkillEvents/get-employees-employee-external-id-skill-events) with `skill_profile_feedback` as `event_type`. The resulting Skill Events with `source` field as `"tw-workday-bot"` are the feedback events given using the Skill Assistant. # Employee Skill Profile Tab In addition to validating suggestions, the Worker Skill Assistant app offers a **Manage your skill profile** view that lets employees manage their skill profile at any time, without waiting for a suggestion. Within this view, employees can: * **View and Reevaluate Skills**: See the skills on their profile and the skills they rejected earlier, and add a rejected skill back. * **Add Missing Skills**: Search the skill vocabulary and add any skills that may be lacking. * **Remove Skills**: Remove a skill that is no longer relevant. * **Self-rate Skill proficiency levels (optional)**: Set or update the proficiency level of a Skill. Every change is confirmed by the employee and saved on its own: 1. The change is received by the Skill Assistant, which stores it together with when and by whom it was made. 2. The change is sent to the TechWolf API using the [Employee Skill Profile feedback endpoint](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile), with the `source` field set to `"tw-workday-bot-tab"` so that changes made in this view can be told apart from validated suggestions. 3. An added or removed skill is also added to or removed from the employee's Workday worker profile, so both profiles stay in step. # Linking Workday users and employee profiles in TechWolf There are two ways to link Workday users to employee profiles in TechWolf: 1. Use the Worker ID as the Employee ID in TechWolf. 2. Use the Employee ID from Workday as the Employee ID in TechWolf. **Note**: The chosen mapping method must be consistent across your organization and communicated to TechWolf during the initial setup phase. # Data flows ### General overview ![Data Flow Overview](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/workday/images/workday-overview-dataflow.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=207aaa3e3e7ca5c11d823857beec8e8d) #### Components **Workday** The Workday environment used by the customer. **AWS infrastructure** TechWolf utilizes AWS infrastructure to facilitate communication between Workday and the Skill Assistant. This infrastructure comprises: * **CloudFront**: Processes and routes incoming requests at edge locations, minimizing latency by handling traffic close to its source. * **Lambda at Edge**: Processes incoming requests by extracting the Tenant ID and uses DynamoDB to determine the correct Skill Assistant deployment region (EU or US) for routing. * **Global DynamoDB**: Maintains a mapping between Tenant IDs and their corresponding deployment regions (EU or US). **Skill Assistant** TechWolf's backend system responsible for generating skill suggestions and processing feedback. **Skill Engine API** The main TechWolf product. Handles skill-related data processing and integration. #### Data processing **Types of data that is processed** * **Skill Suggestions**: Automatically inferred skills for an employee, retrieved from the Skill Engine API. * **Skill Feedback**: Employee feedback on their suggested skills. Either validating that they have the skills, or rejecting the skills. * **Skill Profile**: A list of validated and rejected skills maintained in the Skill Engine API, managed by the employee in the Skill Profile tab. * **Workday User Data**: Employee details retrieved from Workday systems. No personal identifiable information. **Data Processing Overview** | | **Managed by** | **Suggestions** | **Feedback** | **Skill Profile** | **Workday User Data** | | - | - | - | - | - | - | | **Workday** | Customer | X | X | X | X | | **AWS: CloudFront** | TechWolf | | | | | | **AWS: Lambda at Edge** | TechWolf | | X | | | | **AWS: Global DynamoDB** | TechWolf | | | | | | **Skill Assistant** | TechWolf | X | X | X | X | #### Data storage **Overview of Data Storage Locations** | | **Managed by** | **Suggestions** | **Feedback** | **Skill Profile** | **Workday User Data** | | - | - | - | - | - | - | | **Workday** | Customer | | X | X | X | | **AWS** | TechWolf | | | | | | **Skill Assistant** | TechWolf | X | X | | X | #### **Communication Protocols** All data exchanges occur over REST and SOAP APIs secured by **TLS 1.2** or higher. ### Sending notifications ![Sending notifications](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/workday/images/sending-notifications-dataflow.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=651963b531fa33d32fae680079b6a975) **Process** 1. **Fetch employees**: On a regular basis, the Skill Assistant will fetch employees that have suggestions. 2. **Sending the notifications**: The notifications are sent by the Skill Assistant to Workday. **Data Involved** 1. Workday User ID, Internal ID, Suggestion 2. Workday User ID ### User interacts with the application ![User interacts with the application](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/skill-assistant/workday/images/user-interacts-application-dataflow.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=6bc554e40f510985ea282b8543abf944) **Process** 1. **User input request**: When a user interacts with the application, it is sent to CloudFront in the TechWolf AWS instance. 2. **Routing to Skill Assistant**: The request is processed and routed by CloudFront to the Skill Assistant. 3. **Execution of request**: The Skill Assistant directs the request in proper format to the API, where the request is executed on the customer's data. 4. **Response to user**: A response, based on the request's proper execution, is sent back to the concerning Workday user. **Data Involved** 1. Workday User ID 2. Workday User ID 3. Workday User ID, Internal ID, Depending on the event: Feedback or Request suggestions 4. Workday User ID, Internal ID, Suggestion # Installation Source: https://developers.techwolf.ai/integrations/skill-assistant/workday/installation # Installation steps **Step 1** Contact your TechWolf representative to get the Skill Assistant installed in your Workday environment. We will contact Workday to set up the application in your tenant. This can take up to 2 weeks. **Step 2** Once the Skill Assistant is installed in your Workday environment, use the [Deployment Guide](#deployment-guide) to configure the Skill Assistant. ## Deployment guide The deployment guide provides comprehensive step-by-step instructions for installing the Skill Assistant in your Workday environment. This guide covers all required roles, permissions, and configuration steps necessary for a successful installation. > **[Deployment guide](https://developers.techwolf.be/uploads/documents/TechWolf_Worker_Skill_Assistant_Deployment_Guide.pdf)** # Linking Workday users and employee profiles in TechWolf There are two ways to link Workday users to employee profiles in TechWolf: 1. Use the Worker ID as the Employee ID in TechWolf. 2. Use the Employee ID from Workday as the Employee ID in TechWolf. **Note**: The chosen mapping method must be consistent across your organization and communicated to TechWolf during the initial setup phase. # Event Types Source: https://developers.techwolf.ai/integrations/webhooks/event_types All webhook payloads follow the [CloudEvents 1.0](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md) specification. Each event has a **type** (e.g. `ai.techwolf.employee.skill_profile.updated.v1`) and a **data** object with tenant and resource identifiers. You only need to support the event types you consume; the **health check** event is required for all consumers. ## Event type reference Events are grouped by entity. Follow the links to the full specification and example payload for each type. **Employee** * [Skill Profile Updated](#employee-skill-profile-updated) - Employee Skills added/removed or attributes updated * [Suggested Skill Profile Updated](#employee-suggested-skill-profile-updated) - Employee suggested (inferred, not yet validated) Skills changed **Job** * [Skill Profile Updated](#job-skill-profile-updated) - Job Skills added/removed or attributes updated * [Suggested Skill Profile Updated](#job-suggested-skill-profile-updated) - Job suggested (inferred, not yet validated) Skills changed **Course** * [Skill Profile Updated](#course-skill-profile-updated) - Course Skills added/removed **Skill vocabulary** Per-Skill events. Each one is anchored on a **single Skill** in the vocabulary (a Vocabulary Skill or a Custom Skill); fetch that Skill via [GET /taxonomy/skills/\{skill\_id}](/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-skill-id). * [Skill Created](#skill-created) - New Skill in vocabulary or Custom Skill created * [Skill Updated](#skill-updated) - Skill or Custom Skill updated * [Skill Deleted](#skill-deleted) - Skill removed from vocabulary or Custom Skill deleted **Taxonomy** A tenant-level event. It is anchored on the **tenant's Taxonomy as a whole** (not a single Skill); consume it through the Taxonomy changes export ([POST /taxonomy/changes](/reference/latest/Export/TaxonomyExport/post-taxonomy-changes)), which reports both structural operations (Domains, Subdomains, Skill Clusters) and vocabulary operations. * [Taxonomy Updated](#taxonomy-updated) - The tenant Taxonomy or Vocabulary changes > [!NOTE] > > These two groups differ in granularity, not just naming. The three **Skill** > events fire for one Skill at a time and point you at that Skill's endpoint. > **Taxonomy Updated** fires for the tenant Taxonomy as a whole and points you > at the changes export, where each event corresponds to a single operation > (identified by `external_id`). **Health Check** (required for all endpoints) * [Health Check](#health-check) - Liveness check ## Event specifications Below are the full specifications for each event type, grouped by entity: when it is emitted, expected frequency, suggested consumer action, and payload format. The expected frequency is expressed per affected entity (e.g. per Employee, per Job); this is not the total number of webhooks per day. Note that this is only a high-level indication; actual frequency is dependent on the activity levels in the SkillEngine API or any linked system such as the TechWolf Skill Assistant, the TechWolf Console, external platforms with integrations, etc. As for when the events are emitted, we offer at-least-once delivery on at least the triggers specified per event. TechWolf may add new fields to existing webhook versions (e.g. extra fields in the `data` object). Your endpoint should tolerate unknown fields and not break when new ones are sent. *** ### Employee Skill Profile Updated | Detail | Specification | | - | - | | **Emitted when** | Inference completes for the Employee (including the initial inference after the Employee is created, which may produce an empty Skill Profile), Skills are validated or rejected, or the Skill attributes (e.g. proficiency) of existing validated Skills are updated. | | **Expected frequency** | Daily (per Employee) | | **Suggested action** | Retrieve the Employee Skill Profile from the SkillEngine API ([GET /employees/\{external\_id}/skill\_profile](/reference/latest/Employees/EmployeeProfile/get-employees-external-id-skill-profile)) and propagate changes. | > [!NOTE] > > An empty Skill Profile (`"skills": []`) is a valid state: it means inference > has run for the Employee but no Skills could be inferred (yet). Treat these > webhooks like any other — fetch the Skill Profile by `external_id` without > special-casing. As soon as Skills are inferred or validated, they will flow > through on a subsequent webhook. **v1 - latest version** **Event type:** `ai.techwolf.employee.skill_profile.updated.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `external_id` | Employee's external ID; use in the path when calling the API. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.employee.skill_profile.updated.v1", "source": "https://{tenant}.{region}.techwolf.ai/employees/{employee_external_id}/skill_profile", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "external_id": "{employee_external_id}" } } ``` *** ### Employee Suggested Skill Profile Updated | Detail | Specification | | - | - | | **Emitted when** | The set of suggested (inferred, not yet validated or rejected) Skills for the Employee changes. | | **Suggested action** | Retrieve the Employee Skill Profile from the SkillEngine API ([GET /employees/\{external\_id}/skill\_profile](/reference/latest/Employees/EmployeeProfile/get-employees-external-id-skill-profile)) and read the Skills with `validation_state` `suggested`. | > [!NOTE] > > This event covers **suggested** Skills only (inferred, not yet validated or > rejected). It is separate from [Employee Skill Profile > Updated](#employee-skill-profile-updated), which covers validated Skill > Profile changes. Subscribe to it on a webhook to be notified when the > suggested Skills change. **v1 - latest version** **Event type:** `ai.techwolf.employee.skill_profile.suggested_updated.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `external_id` | Employee's external ID; use in the path when calling the API. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.employee.skill_profile.suggested_updated.v1", "source": "https://{tenant}.{region}.techwolf.ai/employees/{employee_external_id}/skill_profile", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "external_id": "{employee_external_id}" } } ``` *** ### Job Skill Profile Updated | Detail | Specification | | - | - | | **Emitted when** | Inference completes for the Job (including the initial inference after the Job is created, which may produce an empty Skill Profile), Skills are validated or rejected, or the Skill attributes (e.g. proficiency, criticality) of existing validated Skills are updated. | | **Expected frequency** | Weekly-monthly (per Job) | | **Suggested action** | Retrieve the Job Skill Profile from the SkillEngine API ([GET /job\_architecture/jobs/\{job\_external\_id}/skill\_profile](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-skill-profile)) and propagate changes. | > [!NOTE] > > An empty Skill Profile (`"skills": []`) is a valid state: it means inference > has run for the Job but no Skills could be inferred (yet). Treat these > webhooks like any other — fetch the Skill Profile by `external_id` without > special-casing. As soon as Skills are inferred or validated, they will flow > through on a subsequent webhook. **v1 - latest version** **Event type:** `ai.techwolf.job_architecture.job.skill_profile.updated.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `external_id` | Job's external ID; use in the path when calling the API. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.job_architecture.job.skill_profile.updated.v1", "source": "https://{tenant}.{region}.techwolf.ai/job_architecture/jobs/{job_external_id}/skill_profile", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "external_id": "{job_external_id}" } } ``` *** ### Job Suggested Skill Profile Updated | Detail | Specification | | - | - | | **Emitted when** | The set of suggested (inferred, not yet validated or rejected) Skills for the Job changes. | | **Suggested action** | Retrieve the Job Skill Profile from the SkillEngine API ([GET /job\_architecture/jobs/\{job\_external\_id}/skill\_profile](/reference/latest/Jobs/JobProfile/get-job-architecture-jobs-job-external-id-skill-profile)) and read the Skills with `validation_state` `suggested`. | > [!NOTE] > > This event covers **suggested** Skills only (inferred, not yet validated or > rejected). It is separate from [Job Skill Profile > Updated](#job-skill-profile-updated), which covers validated Skill Profile > changes. Subscribe to it on a webhook to be notified when the suggested > Skills change. **v1 - latest version** **Event type:** `ai.techwolf.job_architecture.job.skill_profile.suggested_updated.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `external_id` | Job's external ID; use in the path when calling the API. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.job_architecture.job.skill_profile.suggested_updated.v1", "source": "https://{tenant}.{region}.techwolf.ai/job_architecture/jobs/{job_external_id}/skill_profile", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "external_id": "{job_external_id}" } } ``` *** ### Course Skill Profile Updated | Detail | Specification | | - | - | | **Emitted when** | Skills are added to or removed from the Course Skill Profile. | | **Expected frequency** | Monthly (per Course) | | **Suggested action** | Retrieve the Course Skill Profile from the SkillEngine API ([GET /courses/\{external\_id}/skill\_profile](/reference/latest/Courses/CourseProfile/get-courses-external-id-skill-profile)) and propagate changes. | **v1 - latest version** **Event type:** `ai.techwolf.course.skill_profile.updated.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `external_id` | Course's external ID; use in the path when calling the API. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.course.skill_profile.updated.v1", "source": "https://{tenant}.{region}.techwolf.ai/courses/{course_external_id}/skill_profile", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "external_id": "{course_external_id}" } } ``` *** ### Skill Created | Detail | Specification | | - | - | | **Scope** | A single Skill in the vocabulary (a Vocabulary Skill or a Custom Skill). | | **Emitted when** | New Skills are added to the TechWolf vocabulary, or Custom Skills are created. | | **Expected frequency** | Monthly-quarterly (per Skill) | | **Suggested action** | Retrieve the new Skill from the SkillEngine API ([GET /taxonomy/skills/\{skill\_id}](/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-skill-id)) and propagate changes. | **v1 - latest version** **Event type:** `ai.techwolf.taxonomy.skill.created.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `external_id` | Identifies the Skill. | | `external_vendor` | Indicates the Skill's vendor; pass as the vendor query parameter when fetching the Skill from the API. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.taxonomy.skill.created.v1", "source": "https://{tenant}.{region}.techwolf.ai/taxonomy/skills/{skill_external_id}", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "external_id": "{skill_external_id}", "external_vendor": "{skill_external_vendor}" } } ``` *** ### Skill Updated | Detail | Specification | | - | - | | **Scope** | A single Skill in the vocabulary (a Vocabulary Skill or a Custom Skill). | | **Emitted when** | Skills are updated in the TechWolf vocabulary, or Custom Skills are updated. | | **Expected frequency** | Monthly-quarterly (per Skill) | | **Suggested action** | Retrieve the updated Skill from the SkillEngine API ([GET /taxonomy/skills/\{skill\_id}](/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-skill-id)) and propagate changes. | **v1 - latest version** **Event type:** `ai.techwolf.taxonomy.skill.updated.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `external_id` | Identifies the Skill. | | `external_vendor` | Indicates the Skill's vendor; pass as the vendor query parameter when fetching the Skill from the API. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.taxonomy.skill.updated.v1", "source": "https://{tenant}.{region}.techwolf.ai/taxonomy/skills/{skill_external_id}", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "external_id": "{skill_external_id}", "external_vendor": "{skill_external_vendor}" } } ``` *** ### Skill Deleted | Detail | Specification | | - | - | | **Scope** | A single Skill in the vocabulary (a Vocabulary Skill or a Custom Skill). | | **Emitted when** | Skills are removed from the TechWolf vocabulary, or Custom Skills are deleted. | | **Expected frequency** | Monthly-quarterly (per Skill) | | **Suggested action** | The Skill will no longer be available from the SkillEngine API (404). To handle out-of-order events, you can verify with [GET /taxonomy/skills/\{skill\_id}](/reference/latest/Taxonomy/TaxonomySkills/get-taxonomy-skills-skill-id) and propagate the deletion. | **v1 - latest version** **Event type:** `ai.techwolf.taxonomy.skill.deleted.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `external_id` | Identifies the Skill. | | `external_vendor` | Indicates the Skill's vendor; use as the vendor query parameter when verifying via the API. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.taxonomy.skill.deleted.v1", "source": "https://{tenant}.{region}.techwolf.ai/taxonomy/skills/{skill_external_id}", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "external_id": "{skill_external_id}", "external_vendor": "{skill_external_vendor}" } } ``` *** ### Taxonomy Updated | Detail | Specification | | - | - | | **Scope** | The tenant's Taxonomy as a whole (structural and vocabulary operations), not a single Skill. Each event corresponds to one operation, identified by `external_id`. | | **Emitted when** | The tenant's Skills Taxonomy changes or when the vocabulary is updated. | | **Expected frequency** | Weekly (per tenant) | | **Suggested action** | Retrieve Taxonomy changes from the SkillEngine API ([POST /taxonomy/changes](/reference/latest/Export/TaxonomyExport/post-taxonomy-changes)). Filter by `operation_type` to get only the kind of change you need; use `external_id` from the event to request the specific change that triggered the webhook. | **v1 - latest version** **Event type:** `ai.techwolf.taxonomy.updated.v1` **Event data** | Field | Description | | - | - | | `tenant_name` | Identifies the tenant. | | `operation_type` | Type of change; use to filter when calling the taxonomy or vocabulary export API. See [POST /taxonomy/changes](/reference/latest/Export/TaxonomyExport/post-taxonomy-changes) for a full list of values. | | `external_id` | Identifies the specific change; pass when calling the taxonomy export API to fetch only that change. | ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.taxonomy.updated.v1", "source": "https://{tenant}.{region}.techwolf.ai/taxonomy/export", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": { "tenant_name": "{tenant}", "operation_type": "{operation_type}", "external_id": "{operation_external_id}" } } ``` *** ### Health Check | Detail | Specification | | - | - | | **Emitted when** | TechWolf checks that your webhook consumer is live. | | **Suggested action** | Respond with a 2XX status code. No business logic required. | **Payload format** ```json theme={null} { "specversion": "1.0", "type": "ai.techwolf.health_check", "source": "https://{tenant}.{region}.techwolf.ai/", "id": "{event_uuid}", "time": "2024-01-15T10:30:00Z", "data": {} } ``` # Overview Source: https://developers.techwolf.ai/integrations/webhooks/overview # TechWolf Webhooks Webhooks let you receive real-time change notifications from TechWolf. When something changes in your tenant, TechWolf sends a POST request to your endpoint over HTTPS. We use **thin events**: each payload only signals that something changed and provides identifiers (e.g. tenant, resource `external_id`), not the full details of the changed resource. Querying the SkillEngine API is required to get the authoritative state of the changed resource. This section describes: * [Supported webhook events](/integrations/webhooks/event_types) - event types, versions, when they are emitted, and how to react * [Protocol and delivery](/integrations/webhooks/protocol-delivery) - transport, payload format, headers, and delivery guarantees * [Security](/integrations/webhooks/security) - signature verification (Ed25519) and optional OAuth2 endpoint authentication Consumers only need to support the event types they care about. The **health check** event type is mandatory for every consumer so TechWolf can verify your endpoint is live and functioning. ## Consumer responsibilities * Expose an HTTPS endpoint and allowlist our [source IPs](/integrations/webhooks/protocol-delivery#source-ip-addresses). * Accept the **health check** event type on every webhook endpoint so TechWolf can verify the endpoint is live. * [Verify signatures](/integrations/webhooks/security) and validate timestamp freshness; return 2XX on successful receipt of a valid message, 401 on verification failure, 400 on invalid request. * Handle at-least-once delivery: deduplicate by event `id` and implement idempotent processing. * Fetch full state from the SkillEngine API; the payload only contains identifiers and metadata, not the resource itself. * **Recommended:** run a periodic reconciliation in addition to webhooks to correct any drift. > **[Event types](/integrations/webhooks/event_types)** > > Events with versioned payloads. > **[Protocol & delivery](/integrations/webhooks/protocol-delivery)** > > HTTPS POST, CloudEvents 1.0, at-least-once delivery, 15s timeout. > **[Security](/integrations/webhooks/security)** > > Ed25519 signature verification and optional OAuth2 for your endpoint. # Protocol and Delivery Source: https://developers.techwolf.ai/integrations/webhooks/protocol-delivery ## Transport | Aspect | Specification | | - | - | | **HTTP method** | POST | | **Protocol** | HTTPS only | | **Timeout** | Response expected within 15 seconds | | **Batching** | Not supported | | **Ordering** | Not guaranteed | | **Delivery semantics** | At-least-once | | **Success** | Consumer must respond with a 2XX status code | ## Retry behaviour By default, TechWolf retries delivery when your endpoint returns one of these status codes: **408**, **429**, **500**, **502**, **503**, **504**, or when a request fails due to **timeouts** or **other network errors**. * **Attempts:** up to three retries per delivery * **Backoff:** exponential between attempts * **Retry-After:** if your endpoint responds with a `Retry-After` header, TechWolf uses that value (delay-seconds or HTTP-date per RFC 7231) instead of the default backoff ## Source IP addresses All webhook requests are sent from a fixed, static set of IP addresses. Allowlist the IPs for your region so that your endpoint accepts delivery from TechWolf. See [IP Addresses ](/integrations/reference/ip-addresses) for the current list. ## Event format All webhook payloads follow the [CloudEvents 1.0](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md) specification. ### Base structure ```json theme={null} { "specversion": "1.0", "type": "", "source": "", "id": "", "time": "", "data": { ... } } ``` ### Field semantics | Field | Description | | - | - | | `specversion` | CloudEvents spec version (1.0). | | `type` | Event type and version; use to route the event and to know which API to call for the full state. | | `source` | URL of the resource that changed. | | `id` | Unique per event. Use to deduplicate, since delivery is at-least-once. | | `time` | When the change occurred (ISO 8601). Useful for ordering or idempotency. | | `data` | Identifiers and metadata to locate the change and call the API (e.g. tenant, `external_id`, `operation_type`, `external_vendor`). Use these to fetch the full state from the API; the payload does not contain the resource itself. | ## Request headers Unless you request or configure otherwise, each webhook request includes the following headers: | Header | Description | | - | - | | `Content-Type` | `application/json` | | `User-Agent` | `TechWolf-Webhooks/1.0` | | `X-Event-Id` | Same as the event `id` in the body; used when verifying the signature and for deduplication. | | `X-Tenant` | Tenant name; used when verifying the signature and when calling the API. | | `X-Signature-Timestamp` | Time the message was signed (seconds since Unix epoch). Used when verifying the signature and to reject stale requests (replay protection). | | `X-Signature-V1` | Hex-encoded signature(s). May contain multiple comma-separated values during key rotation; at least one must verify. | See [Security](/integrations/webhooks/security) for how to verify the signature. # Security Source: https://developers.techwolf.ai/integrations/webhooks/security ## Signature verification (Ed25519) Webhook authenticity and integrity are ensured using **Ed25519** asymmetric signatures. ### Key material from TechWolf For each webhook endpoint, TechWolf provides: * **Public key (Ed25519)** - used by you to verify webhook signatures Private keys are held only by TechWolf and securely managed. ### Signed message format The signature is computed over: ``` timestamp:tenant:event_id:request_body ``` The result is sent in the `X-Signature-V1` header: ``` X-Signature-V1: , ``` TechWolf supports non-breaking key rotation. During a rotation window, the same request may be signed with multiple active private keys, so `X-Signature-V1` can contain several signatures. **Validate the webhook by verifying that at least one signature matches** using any of the currently active public keys. This allows key updates without downtime. ### Security responsibilities You **must**: * Verify the Ed25519 signature using the provided public key * Validate timestamp freshness to prevent replay attacks (e.g. reject requests where the `X-Signature-Timestamp` is older than 5 minutes) * Reject invalid or stale requests with a **401** response *** ## Python example: signature verification ```python theme={null} from nacl.signing import VerifyKey from nacl.exceptions import BadSignatureError # Public key provided by TechWolf (hex-encoded) PUBLIC_KEY = "TECHWOLF_PUBLIC_KEY_HEX" verify_key = VerifyKey(bytes.fromhex(PUBLIC_KEY)) signatures = request.headers["X-Signature-V1"] timestamp = request.headers["X-Signature-Timestamp"] tenant = request.headers["X-Tenant"] event_id = request.headers["X-Event-Id"] body = request.data.decode("utf-8") # TechWolf signature payload format: # ::: message = f"{timestamp}:{tenant}:{event_id}:{body}".encode("utf-8") # X-Signature-V1 may contain multiple comma-separated signatures. # The request is valid if at least one signature matches. for signature in signatures.split(","): try: verify_key.verify( message, bytes.fromhex(signature.strip()), ) break except BadSignatureError: continue else: abort(401, "invalid request signature") ``` *** ## OAuth2 endpoint authentication (optional) In addition to signature verification, TechWolf can authenticate webhook requests to your endpoint using **OAuth2**. This protects against unauthorised callers reaching your endpoint. OAuth2 is **optional** and does **not** replace signature verification; authenticity and integrity are always guaranteed by Ed25519. ### Request format When OAuth2 is enabled, TechWolf sends an access token in the **Authorization** header: ``` Authorization: Bearer ``` ### Enabling OAuth2 To enable OAuth2 for webhook delivery, you must provide: | Item | Description | | - | - | | **OAuth2 Token URL** | Your token endpoint | | **Grant type** | `client_credentials` | | **Client credentials for TechWolf** | `client_id`, `client_secret` | | **Scope** | As required by your endpoint | | **Additional parameters** | Any other fields your token endpoint expects (e.g. `audience`, `resource`, or custom parameters). Provide name and value per parameter. | ### Client authentication method When TechWolf requests an access token from your token endpoint (client credentials grant), the `client_id` and `client_secret` can be sent in one of two ways: | Method | Description | | - | - | | **Form-encoded (POST)** | `client_id` and `client_secret` in the POST body (`application/x-www-form-urlencoded`). | | **HTTP Basic (POST)** | `client_id` and `client_secret` in the `Authorization` header (Basic auth). | ## Custom headers (optional) You can configure **custom headers** that TechWolf will send with every webhook request to your endpoint (e.g. for routing or internal auth). The standard headers (including signature headers) are always sent; custom headers are added on top. # How It Works Source: https://developers.techwolf.ai/integrations/workday-job-description-sync/how-it-works ## Data Flow * Publishing a Job's primary description in the TechWolf Console triggers a real-time push: TechWolf converts the description to Workday rich text and updates the matching Job Profile through Workday's `Submit_Job_Profile` web service ([Human\_Resources, v46.1 ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Human_Resources/v46.1/Human_Resources.html)). Only Job Profiles whose Job is known to TechWolf and carries a published TechWolf description are synchronized — TechWolf overwrites those descriptions in Workday with the published version on our side, and leaves every other Job Profile in your tenant as is. * A weekly reconciliation pass re-checks every job in scope and re-applies the published description wherever Workday has drifted. * Before every update, TechWolf reads the current Workday description [`Get_Job_Profiles` v46.1 ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Human_Resources/v46.1/Get_Job_Profiles.html) and only writes when it differs from the published version — an unchanged description produces no Workday write at all. ## What Is Written Each update submits only the `Job_Description` field of `Job_Profile_Basic_Data`. Skill qualifications and all other job-profile fields are separate elements of the Workday payload and are never included. The integration never creates job profiles (an update for a profile that no longer exists in Workday is skipped, not re-created) and never deletes anything — a job removed from TechWolf simply stops being updated. ## Business Process Behavior Every update is a *Manage Job Profile* business process event initiated by the Integration System User and completed automatically as an external load — each one is recorded in the profile's process history like any other change. * If a Manage Job Profile event started by one of your admins is still pending on a profile, the integration's update is deflected by Workday. TechWolf records it as skipped and retries on the next cycle — the sync for that profile simply pauses until your event completes or is canceled. TechWolf never cancels or overrides events in your tenant. * TechWolf confirms every update by re-reading the profile after the write; an update is only considered successful once the re-read shows the published description. ## Recoverability Every update is an effective-dated Manage Job Profile event, so Workday's change history retains the prior description of every profile — nothing is destroyed by an update. A Workday admin can rescind or correct any event to reverse it, and your TechWolf team can assist with broader restores on request. # Installation Source: https://developers.techwolf.ai/integrations/workday-job-description-sync/installation ## System Requirements The Job Description Sync makes use of existing Workday functionality. The customer will need a TechWolf contract with a live TechWolf tenant, populated with (a subset of) the Job entities in Workday, and job descriptions authored in the TechWolf Console. This integration authenticates with OAuth only. ## Workday Configuration A Workday integration user must be configured in the Workday tenant with an implementation security group. > [!NOTE] > > If you already have a Job Skill Sync integration configured, the same ISU, > security group, and API Client can be reused: steps 1–3 and 5–7 are already > in place, and the `Job Information` domain policy from that setup is already > sufficient for this integration's read access. The **only new step is the > business process permission in step 4** — after granting it, run `Activate > Pending Security Policy Changes` and continue to the Console Configuration > section. ### 1. Create Integration System User (ISU) * `Create Integration System User` business process. * Do not allow UI sessions as this user will only be used for automations. * Please securely store the username and password of this user. * **Set the ISU's language preferences:** The integration requires the ISU's locale and display language to be English (United States); this language preference can be set when proxying as the ISU. Note that ISUs do not show up in the `Start Proxy` task. Instead, starting the proxy can be done by running the `All Workday Accounts` report, filtering the "User Name" column on the ISU's username, and then, from the account's related actions, choosing "Security Profile" > "Start Proxy". ![Proxy as the ISU](https://mintcdn.com/techwolf/78HQBVn3Dl89YqaK/integrations/workday-skill-sync-integration/images/proxy-isu.png?fit=max\&auto=format\&n=78HQBVn3Dl89YqaK\&q=85\&s=b69d70f1611a02bbf3fbab4b59c0b0cd) While proxying as the ISU, run the `Change Preferences` task and set the fields from the table below: | Field | Value | | - | - | | Preferred Locale | English (United States) - en\_US | | Preferred Display Language | English | ![Set the language preferences for the ISU](https://mintcdn.com/techwolf/78HQBVn3Dl89YqaK/integrations/workday-skill-sync-integration/images/update-isu-language.png?fit=max\&auto=format\&n=78HQBVn3Dl89YqaK\&q=85\&s=c1f5f98efaaba4fc7362e778c9f72123) Remember to stop the proxy after setting the language preferences, using the `Stop Proxy` task. ### 2. Update password expiration rules for ISU * In the `Maintain Password Rules` business process under "System Users exempt from password expiration" add the newly created ISU to the list. * **Note:** This ensures the integrations will keep running without interruptions due to password expiration. ![Maintain Password Rules](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/maintain-password-rules.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=29aee6b3bcbb1b2540de35c103d3c578) ### 3. Set up security permissions for the ISU through security policies * Go to `Create Security Group`, choose "Integration System Security Group (Unconstrained)". * **Note on acceptance testing:** Consider using two different security groups, one Unconstrained and one Constrained. This way, the test-set is scoped while the correct permissions are applied for other Web Services. ![Create Security Group](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-security-group.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=1582d2fc302fd6b313c4ce6b21c86e3b) ![Create Security Group Detail](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-security-group-detail.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=75cff95ca512f394bd97836ce3da5df6) * The next screen presents you with an Edit form to add additional information. Add your ISU to the list. This can be changed later too. Do not check "Inactive". ![Edit Security Group](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/edit-int-sys-sec-group.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=3f8ce8d82ee37928b361712c58248a9e) ### 4. Set up the Security Group's permissions Job descriptions live on the Workday Job Profile, and Workday manages changes to job profiles through the **Manage Job Profile business process** — the same process that runs when an admin edits a job profile in the Workday UI. The integration therefore needs two kinds of permissions: domain access to *read* job profiles, and permission to *start* the business process that updates them. #### Domain security policies (read access) * Search for "View Security Group" and select your created security group. * Select the option menu next to the Security Group's name, go to "Security Group" and select "Maintain Domain Permissions for Security Group". * Under Integration Permissions add the following Domain Security Policy: | Domain Security Policy | Access | | - | :-: | | Job Information | Put | #### Business process permission (update access) * Search for "Edit Business Process Security Policy" and select the **Manage Job Profile** business process. ![Edit Business Process Security Policy for Manage Job Profile](https://mintcdn.com/techwolf/ZzEQMTncF4DIYNSg/integrations/workday-job-description-sync/images/edit-business-process-security-policy.png?fit=max\&auto=format\&n=ZzEQMTncF4DIYNSg\&q=85\&s=9ed1fa3cff6d623c9923d00f662c589c) * Under "Who Can Start the Business Process", find the Initiating Action **Submit Job Profile (Web Service)** and add your security group to its Security Groups. ![Add the security group to the Submit Job Profile (Web Service) initiating action](https://mintcdn.com/techwolf/ZzEQMTncF4DIYNSg/integrations/workday-job-description-sync/images/submit-job-profile-web-service.png?fit=max\&auto=format\&n=ZzEQMTncF4DIYNSg\&q=85\&s=9c1ec7e570e272d1d9438fec8087ac10) * Run the `Activate Pending Security Policy Changes` task to apply both changes. ![Activate Pending Security Policy Changes](https://mintcdn.com/techwolf/ZzEQMTncF4DIYNSg/integrations/workday-job-description-sync/images/activate_pending_security_policy_changes.png?fit=max\&auto=format\&n=ZzEQMTncF4DIYNSg\&q=85\&s=75e9e9c47d5647b5ae6bb7584fa1ffea) > [!NOTE] > > This business process permission is the entire update-side key: with it, the > integration's updates complete automatically and are recorded as regular, > auditable Manage Job Profile events in your tenant's history. The > integration only ever submits the job description field — skills and all > other profile fields are never part of its payload. If your security team > wants Workday itself to enforce description-only updates as well, an opt-in > server-side restriction is available — ask your TechWolf contact. ### 5. Find out the correct Workday API URL * Search for `Public Web Services` in the search bar at the top of the Workday home page. * In the list, click the three dots next to the `Human Resources (public)` entry. Select `View WSDL` under `Web Service`. ![View wsdl](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-wsdl-for-api-url.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=1a436b6f7aa163adb51205ba350c49ce) * The resulting page will take some time to load. Once it is loaded, look for "soapbind:address location" near the bottom of the page. You will see a section like this: ```xml theme={null} ``` * Copy the base tenant URL up to and including your tenant name. The service name and version should be excluded from the URL. * Note that the API URL can differ between implementation tenants and production tenants, so the steps described above need to be repeated for each tenant individually. > [!NOTE] > > If you are using **OAuth Authentication** (recommended), continue with the > OAuth setup steps below before connecting the integration. > > If you have arranged **Basic Authentication**, this is the final Workday > configuration step. Proceed to the > [TechWolf Configuration](#techwolf-configuration) section. ### 6. Create API Client for Integrations * Search for "Register API Client for Integrations" business process * Enable non-expiring refresh tokens to ensure continuity of service * Under "Scope (Functional Areas)", add exactly these scopes:
Scope (Functional Area) Needed for
![API Client Setup](/integrations/workday-skill-sync-integration/images/register-api-client-for-integrations.png) * Optionally, restrict the client to TechWolf's IP ranges by filling in the "Restricted to IP Ranges" field with the values from the [IP Addresses ](/integrations/reference/ip-addresses) page * Securely store the client ID and client secret ![API Client Credentials](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-api-client-for-integrations.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=0198dc19f26da04632cc0acb3512c9ca) ### 7. Generate Refresh Token * Search for "View API Clients" report * Click "API Clients for Integrations" tab * Note down the token endpoint. You will need to share this later. ![API Client Refresh Token](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-refresh-token.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=7778fec41090d9abd5733e888f636476) * Find your API client and select "Manage Refresh Tokens for Integrations" * Under "Workday Account", type in your ISU * Press OK * Check the box "Generate new refresh token" * Press OK * Securely store the refresh token. > [!WARNING] > > Keep your OAuth credentials secure and share them only with TechWolf through > secure channels. ## Console Configuration This integration is configured self-service in the TechWolf Console: 1. Enter the Workday API URL and the ISU's OAuth credentials (client ID, client secret, refresh token). Further explanation specified in section beneath [Linking Workday & TechWolf](#linking-workday--techwolf) 2. Run the connection validation. It verifies each layer separately: the credentials (token fetch), read access (profile fetch), and update access — a reversible test write that appends a marker to one job profile's description, confirms it, and restores the original. 3. Enable the integration. > [!NOTE] > > **Choosing the validation job profile.** The validation asks for the ID of a > job profile to test against, and remembers it for later validations. Pick a > low-traffic or seperate test profile — each validation shows up as a Manage > Job Profile event in that profile's history. ## Linking Workday & TechWolf Jobs are matched on the same identifier configuration as the [Job Skill Sync](/integrations/workday-skill-sync-integration/installation-jobs#linking-workday--techwolf---seamless-matching-of-job-ids): either Workday Job Codes (Job Profile IDs) or Workday IDs (WIDs), matching the Job `external_id` in TechWolf. If you run both integrations, they share this setting. ## Deployment Tasks & Responsibilities 1. **Customer**: Create the Integration System User and grant the permissions described above (for existing Job Skill Sync tenants: only the business process permission). 2. **Customer**: Enter the Workday API URL, OAuth credentials and ID of Job Profile we use during validation in the TechWolf Console and run the validation. 3. **TechWolf**: Potentially follow the first synchronization and confirm go-live with the customer. 4. **Customer**: Check end-user test scenarios — publish a job description in the Console and verify it appears on the Workday Job Profile. # Overview Source: https://developers.techwolf.ai/integrations/workday-job-description-sync/overview # Job Description Sync Integration with Workday This guide covers the deployment of the Workday - TechWolf Job Description Sync Integration: what the integration does, the Workday configuration it requires, and how it is enabled. The intended audience is the Integration Implementer. ## Functional Objective Job descriptions are authored, improved, and published in the TechWolf Console. Without this integration, getting the approved text back into Workday is a manual copy-paste step. The Job Description Sync closes that loop: when a job's primary description is published in TechWolf, the matching Workday Job Profile's description is updated automatically. **Key benefits:** * No manual re-entry: published descriptions land on the Workday Job Profile within minutes, with formatting preserved (converted to Workday rich text). * Self-healing: a scheduled weekly reconciliation re-checks every job in scope, so a missed update always converges back to the published version. * Safe by construction: the integration only ever writes the job description field — skills, titles, and every other profile field are untouched — and it never creates or deletes job profiles. * Fully auditable: every update is a regular Manage Job Profile business process event in your tenant's history, so Workday's change history and rescind tooling apply to every change. ## Scope * One-way: TechWolf → Workday. TechWolf is the source of truth for the primary job description. * Single primary description per job. Multilingual descriptions are not supported. * Jobs are matched 1:1 on your tenant's configured identifier (Job Profile ID, or Workday ID) — the same identifier mapping as the Job Skill Sync. ## Enablement Configuration is self-service in the TechWolf Console: enter the Integration System User credentials, run the connection validation (a reversible test write against a job profile you designate), and enable. See [Installation](/integrations/workday-job-description-sync/installation) for the required Workday permissions — for tenants already running the Job Skill Sync, setup is a single additional security grant. # How It Works Source: https://developers.techwolf.ai/integrations/workday-skill-sync-integration/how-it-works ## Data Flow * During the initial setup phase and when new skill vocabulary versions are released, TechWolf will push and update the external skill mapping in Workday. * Worker and Job Skills are synchronized in a bidirectional flow, where Worker and Job skill data updates in the SkillEngine API are synchronized in real-time to Workday using a push strategy. * Workday updates are synced at regular intervals to the SkillEngine API using a pull strategy. This means that all flows are all initiated by TechWolf. The frequency by which Workday skills are synchronized to TechWolf is every 2 hours. * Worker skills synced by the Workday Integration are tracked using the `source` field in the [Employee Skill Profile Feedback endpoint ](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile) payload, tagged as `"workday-integration"`. To retrieve these sources in an Employee's profile, use the query parameter `?include=sources` in the [Employee Skill Profile Feedback endpoint ](/reference/latest/Employees/EmployeeProfile/patch-employees-external-id-skill-profile), which returns the Skill's `source_event` with `"event_type": "skill_profile_feedback"` and `"source": "workday-integration"`. * Job skills synced by the Workday Integration are tracked using the `source` field in the [Job Skill Profile Feedback endpoint ](/reference/latest/Jobs/JobProfile/patch-job-architecture-jobs-job-external-id-skill-profile) payload, tagged as `"workday-integration"`. To retrieve these sources from a Job, use the [List Job Profile Data endpoint ](). Items with `"data_type": "skill_profile_feedback"` and `"source": "workday-integration"` indicate skills synced by the Workday Integration. In summary: For Workers, TechWolf will access Workday's *Talent and Staffing* Web services to retrieve and update skill data. For Jobs, TechWolf will access Workday's *Human Resources* Web services to retrieve and update skill data. TechWolf also synchronizes skill data from external sources and skills from external systems performing skill harmonization. ### Initial Load The initial load occurs after the Workday Integration System User credentials are shared and set up in TechWolf. The TechWolf team ensures the initial batch of data is loaded into both systems, starting a process on TechWolf's side. During the initial data load, customers can choose between two synchronization strategies: 1. **Merge Strategy**: Combines skills from both Workday and TechWolf systems. Skills present in Workday but not in TechWolf will be synced to TechWolf, and vice versa. This preserves existing skill data in both systems. TechWolf takes precedence over Workday in case of conflicting values. 2. **Overwrite Strategy**: Replaces all skills in Workday with the skill data from TechWolf. This strategy clears existing Workday skills before importing TechWolf data. These synchronization strategies are automatically applied to any new Jobs or Employees that exist in both Workday and TechWolf systems. Below is an example demonstrating the merge strategy in action: Worker profile of Grayson Rogers before the initial load: ![Workday Profile Before](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/workday-profile-before.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=e66b0147b8bf6043541d389b5f25c82b) Assuming a lot of skills have been validated already, we get his profile after the initial sync: ![Workday Profile Initial Sync](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/workday-profile-initial-sync.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=837463dd5e0a2ad6b0ffc7ebd8d4dba2) In TechWolf, we see the same profile as before, with the addition of the skills that were in Grayson's original Workday profile; these are now validated in TechWolf. ### Important Limitation: Workday-First Precedence Some customers may require a variation where **Workday takes precedence** over TechWolf for overlapping skills. This use case is **not natively supported** by the current synchronization strategies. **Workaround:** * Request a **snapshot export from Workday** containing all skills, criticality, and proficiency values. * Import this snapshot as feedback into TechWolf to align TechWolf’s profiles with Workday. * After alignment, use either the **Merge** or **Overwrite** strategy for the initial sync. The result will effectively preserve Workday’s precedence while still enabling bidirectional synchronization. ### Skill Validation in TechWolf Grayson Rogers validates the skill "Acoustic Modelling" in TechWolf. This validation is pushed to Workday immediately: ![Workday Profile TechWolf to Workday](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/workday-profile-tw2wd.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=9c22b1e6629604fb3569c5739b1a1a14) ### Skill Validation in Workday When an employee provides feedback in Workday, for example, adds "Facilities Operations" and removes "Performance Management", the changes are reflected in TechWolf accordingly. The changes are synchronized **every 2 hours**, so not immediately in this direction. ### Custom Skills Next to Workday Skills Cloud skills, the integration also supports **customer-specific custom skills** (Workday *Maintained Skills*). When this optional feature is enabled, custom skills managed in TechWolf are synchronized to Workday's skill catalog (created, renamed, and inactivated automatically) and flow through the Worker and Job profile synchronization like any other skill. TechWolf is the source of truth for custom skills: a custom skill removed in TechWolf is inactivated in Workday and removed from the profiles it was on. Because TechWolf manages these custom skills, the Workday tenant must exclude Maintained Skills from its automated skill management process, so that Workday does not replace them with Skills Cloud Skills; see [Synonym Management](/integrations/reference/workday-skills#automated-skill-management-synonym-management) for the required configuration. # Installation Source: https://developers.techwolf.ai/integrations/workday-skill-sync-integration/installation-employees ## System Requirements The TechWolf Skill Sync integration will make use of existing Workday functionality. The customer will need a TechWolf contract with a live TechWolf tenant. This TechWolf tenant must be populated with (a subset of) the worker's entities in Workday. Additionally, Workday's Synonym Management must be enabled in the Workday tenant, with the correct configuration. For Skills Cloud Skills, the sync only supports canonical Skills, not their synonyms; Synonym Management resolves synonyms to their canonical Skill so profiles remain fully syncable. See [Automated Skill Management (Synonym Management)](/integrations/reference/workday-skills#automated-skill-management-synonym-management) for the required configuration, also as it relates to the optional synchronization of custom skills managed in TechWolf to Workday as Maintained Skills. ## Workday Configuration A Workday integration user must be configured in the Workday tenant with an implementation security group. > [!NOTE] > > If you already have a Job Skill Sync integration configured, you can either > set up a new, separate configuration or reuse parts of the existing one. > When reusing the existing setup, the same ISU can be kept, with only the > Permissions needing to be updated in step 4. Additionally, when using OAuth, > the API Client scopes also need to be updated in step 6. ## Authentication The integration supports both OAuth and Basic Authentication. For enhanced security, we recommend using OAuth authentication. Basic Authentication can be used on request. If you already have Basic Authentication configured, or prefer to continue using it, we will continue to support this method as well. To set up the integration using **OAuth Authentication**, complete steps 1 through 7. To set up the integration using **Basic Authentication**, complete steps 1 through 5. **What you'll share with TechWolf:** If you choose OAuth Authentication: * Workday API URL * Token URL * Client ID * Client secret * Refresh token If you choose Basic Authentication: * Workday API URL * Username * Password ### 1. Create Integration System User (ISU) * `Create Integration System User` business process. * Do not allow UI sessions as this user will only be used for automations. * Please securely store the username and password of this user. * **Set the ISU's language preferences:** The integration requires the ISU's locale and display language to be English (United States); this language preference can be set when proxying as the ISU. Note that ISUs do not show up in the `Start Proxy` task. Instead, starting the proxy can be done by running the `All Workday Accounts` report, filtering the "User Name" column on the ISU's username, and then, from the account's related actions, choosing "Security Profile" > "Start Proxy". ![Proxy as the ISU](https://mintcdn.com/techwolf/78HQBVn3Dl89YqaK/integrations/workday-skill-sync-integration/images/proxy-isu.png?fit=max\&auto=format\&n=78HQBVn3Dl89YqaK\&q=85\&s=b69d70f1611a02bbf3fbab4b59c0b0cd) While proxying as the ISU, run the `Change Preferences` task and set the fields from the table below: | Field | Value | | - | - | | Preferred Locale | English (United States) - en\_US | | Preferred Display Language | English | ![Set the language preferences for the ISU](https://mintcdn.com/techwolf/78HQBVn3Dl89YqaK/integrations/workday-skill-sync-integration/images/update-isu-language.png?fit=max\&auto=format\&n=78HQBVn3Dl89YqaK\&q=85\&s=c1f5f98efaaba4fc7362e778c9f72123) Remember to stop the proxy after setting the language preferences, using the `Stop Proxy` task. ### 2. Update password expiration rules for ISU * In the `Maintain Password Rules` business process under "System Users exempt from password expiration" add the newly created ISU to the list. * **Note:** This ensures the integrations will keep running without interruptions due to password expiration. ![Maintain Password Rules](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/maintain-password-rules.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=29aee6b3bcbb1b2540de35c103d3c578) ### 3. Set up security permissions for the ISU through security policies * Go to `Create Security Group`, choose "Integration System Security Group (Unconstrained)". * **Note on acceptance testing:** Consider using two different security groups, one Unconstrained and one Constrained. This way, the test-set is scoped while the correct permissions are applied for other Web Services. ![Create Security Group](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-security-group.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=1582d2fc302fd6b313c4ce6b21c86e3b) ![Create Security Group Detail](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-security-group-detail.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=75cff95ca512f394bd97836ce3da5df6) * The next screen presents you with an Edit form to add additional information. Add your ISU to the list. This can be changed later too. Do not check "Inactive". ![Edit Security Group](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/edit-int-sys-sec-group.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=3f8ce8d82ee37928b361712c58248a9e) ### 4. Edit the Security Group's domain security policies * Search for "View Security Group" and select your created security group. ![View Security Group](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-security-group.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=d268ce61b141a5973c8f66d2cac22eab) * Select the option menu next to the Security Group's name, go to "Security Group" and select "Maintain Domain Permissions for Security Group". ![View Security Group Action](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-security-group-action.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=52e883c48f17c9bd30bf61c176c94db4) * Under Integration Permissions add the following Domain Security Policies, and run the `Activate Pending Security Policy Changes` task to apply the changes. | Domain Security Policy | Access | | - | :-: | | Manage: External Skills | Put | | Person Data: Skills | Put | | Set up: Skills and Experience | Put | ### 5. Find out the correct Workday API URL * Search for `Public Web Services` in the search bar at the top of the Workday home page. * In the list, click the three dots next to the `Human Resources (public)` entry. Select `View WSDL` under `Web Service`. ![View wsdl](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-wsdl-for-api-url.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=1a436b6f7aa163adb51205ba350c49ce) * The resulting page will take some time to load. Once it is loaded, look for "soapbind:address location" near the bottom of the page. You will see a section like this: ```xml theme={null} ``` * Copy the base tenant URL up to and including your tenant name. The service name and version should be excluded from the URL. * Note that the API URL can differ between implementation tenants and production tenants, so the steps described above need to be repeated for each tenant individually. > [!NOTE] > > If you are using **OAuth Authentication** (recommended), continue with the > OAuth setup steps below before connecting the integration. > > If you have arranged **Basic Authentication**, this is the final Workday > configuration step. Proceed to the > [TechWolf Configuration](#techwolf-configuration) section. ### 6. Create API Client for Integrations * Search for "Register API Client for Integrations" business process * Enable non-expiring refresh tokens to ensure continuity of service * Under "Scope (Functional Areas)", add exactly these scopes:
Scope (Functional Area) Needed for
![API Client Setup](/integrations/workday-skill-sync-integration/images/register-api-client-for-integrations.png) * Optionally, restrict the client to TechWolf's IP ranges by filling in the "Restricted to IP Ranges" field with the values from the [IP Addresses ](/integrations/reference/ip-addresses) page * Securely store the client ID and client secret ![API Client Credentials](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-api-client-for-integrations.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=0198dc19f26da04632cc0acb3512c9ca) ### 7. Generate Refresh Token * Search for "View API Clients" report * Click "API Clients for Integrations" tab * Note down the token endpoint. You will need to share this later. ![API Client Refresh Token](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-refresh-token.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=7778fec41090d9abd5733e888f636476) * Find your API client and select "Manage Refresh Tokens for Integrations" * Under "Workday Account", type in your ISU * Press OK * Check the box "Generate new refresh token" * Press OK * Securely store the refresh token. > [!WARNING] > > Keep your OAuth credentials secure and share them only with TechWolf through > secure channels. When the authentication credentials and Workday API URL are shared, the setup is complete on the customer's Workday tenant. TechWolf will validate that the ISU has the required permissions and that the API URL is correct. ## TechWolf Configuration The TechWolf tenant will be configured by TechWolf itself. 1. In the integration service on the TechWolf side, TechWolf adds the credentials of the customer-created ISU. For this, the customer will need to share the following values with TechWolf: * The Workday API URL (see Step 5 of the Workday Configuration section) * Authentication credentials: * OAuth Authentication (recommended): client ID, client secret, and refresh token (see Steps 6–7 of the Workday Configuration section) * Basic Authentication (on request): ISU username and password (see Step 1 of the Workday Configuration section) 2. TechWolf adds TechWolf API credentials with correct scopes to have access to the TechWolf API and links that TechWolf tenant to the Workday tenant. 3. TechWolf validates that the ISU has the required permissions and that the Workday API URL is correct. 4. TechWolf runs an initial sync of worker profiles with the TechWolf API and sets up the tenant configuration to start the bidirectional sync process. ## Routing Through an API Gateway If your organisation fronts the Workday APIs with an API gateway, the integration can call the gateway instead of the vendor host directly. Two settings are available, both configured by TechWolf together with the credentials: * **Custom URL**: instead of the vendor API URL, share the gateway URL that proxies it. The integration keeps appending the same vendor API paths to it, so the gateway must forward requests to Workday unchanged. * **Custom headers**: any number of extra HTTP headers (for example an API key or a correlation ID required by the gateway) that are sent on every request the integration makes. > [!NOTE] > > Both settings are pass-through only. TechWolf sends the values as configured > and does not perform any gateway-specific authentication, signing, or token > refresh; the gateway is expected to forward the integration's own > credentials to Workday. Reserved headers (e.g. `Authorization`, > `Content-Type`) are managed by the integration and cannot be set as custom > headers. ## Linking Workday & TechWolf This section is only required if the customer is **NOT** using the Workday ID as the API ID in TechWolf. ### Seamless Matching of Employee IDs A critical aspect of this process is the seamless coupling of Employee IDs across both platforms. There are two options for direct ID matching: 1. **Using Employee IDs**: If you want to use Workday Employee IDs as the identifier field in Workday, then this same ID must also be used as the Employee `external_id` in TechWolf. 2. **Using Workday IDs (WIDs)**: If you want to use Workday IDs as the identifier field in Workday, then this same ID must also be used as the Employee `external_id` in TechWolf. If neither of these direct matching approaches is possible, then the IDs must be linked through custom properties. ### Creating Custom Properties * For each Employee in the TechWolf system, introduce a new custom property such as `employee_workday_id`. This property will store the corresponding Workday ID of the Employee. * Detailed instructions for creating new custom property definitions can be found [here ](). ### Setting Custom Property Values * Once the custom property is defined, assign the Workday ID to each Employee's TechWolf profile. * Steps for setting these values are outlined [here ](). During a pilot phase, it is possible to manually establish a link between TechWolf IDs and Workday IDs for each Employee. While this approach is feasible for a limited scope, it lacks scalability for broader deployment. ## Deployment Methodology The following tasks and responsibilities assume that: 1. The customer has the appropriate TechWolf API license(s). 2. The TechWolf API contains all Employee information corresponding to Workday workers and data from other external systems. 3. A Skill Profile validation tool (e.g., MS Teams bot) is set up and configured (see separate deployment guide). ### Deployment Tasks & Responsibilities 1. **TechWolf**: Setup Skill Sync environment and tenant requirements 2. **Customer**: Verify the Synonym Management configuration (see [System Requirements](#system-requirements)). 3. **Customer**: Create Integration System User (ISU) based on workflow described above. 4. **Customer**: Share authentication credentials with TechWolf: * OAuth Authentication (recommended): client ID, client secret, and refresh token * Basic Authentication (on request): ISU username and password 5. **Customer**: Share Workday API URL with TechWolf. 6. **TechWolf**: Run initial sync of worker profiles with TechWolf API. 7. **TechWolf**: Setup tenant configuration and start bidirectional sync process. 8. **Customer**: Check end-user test scenarios. # Installation Source: https://developers.techwolf.ai/integrations/workday-skill-sync-integration/installation-jobs ## System Requirements The TechWolf Skills integration will make use of existing Workday functionality. The customer will need a TechWolf contract with a live TechWolf tenant. This TechWolf tenant must be populated with (a subset of) the Job's entities in Workday. Additionally, Workday's Synonym Management must be enabled in the Workday tenant, with the correct configuration. For Skills Cloud Skills, the sync only supports canonical Skills, not their synonyms; Synonym Management resolves synonyms to their canonical Skill so profiles remain fully syncable. See [Automated Skill Management (Synonym Management)](/integrations/reference/workday-skills#automated-skill-management-synonym-management) for the required configuration, also as it relates to the optional synchronization of custom skills managed in TechWolf to Workday as Maintained Skills. ## Workday Configuration A Workday integration user must be configured in the Workday tenant with an implementation security group. > [!NOTE] > > If you already have an Employee Skill Sync integration configured, you can > either set up a new, separate configuration or reuse parts of the existing > one. When reusing the existing setup, the same ISU can be kept, with only > the Permissions needing to be updated in step 4. Additionally, when using > OAuth, the API Client scopes also need to be updated in step 6. ## Authentication The integration supports both OAuth and Basic Authentication. For enhanced security, we recommend using OAuth authentication. Basic Authentication can be used on request. If you already have Basic Authentication configured, or prefer to continue using it, we will continue to support this method as well. To set up the integration using **OAuth Authentication**, complete steps 1 through 7. To set up the integration using **Basic Authentication**, complete steps 1 through 5. **What you'll share with TechWolf:** If you choose OAuth Authentication: * Workday API URL * Token URL * Client ID * Client secret * Refresh token If you choose Basic Authentication: * Workday API URL * Username * Password ### 1. Create Integration System User (ISU) * `Create Integration System User` business process. * Do not allow UI sessions as this user will only be used for automations. * Please securely store the username and password of this user. * **Set the ISU's language preferences:** The integration requires the ISU's locale and display language to be English (United States); this language preference can be set when proxying as the ISU. Note that ISUs do not show up in the `Start Proxy` task. Instead, starting the proxy can be done by running the `All Workday Accounts` report, filtering the "User Name" column on the ISU's username, and then, from the account's related actions, choosing "Security Profile" > "Start Proxy". ![Proxy as the ISU](https://mintcdn.com/techwolf/78HQBVn3Dl89YqaK/integrations/workday-skill-sync-integration/images/proxy-isu.png?fit=max\&auto=format\&n=78HQBVn3Dl89YqaK\&q=85\&s=b69d70f1611a02bbf3fbab4b59c0b0cd) While proxying as the ISU, run the `Change Preferences` task and set the fields from the table below: | Field | Value | | - | - | | Preferred Locale | English (United States) - en\_US | | Preferred Display Language | English | ![Set the language preferences for the ISU](https://mintcdn.com/techwolf/78HQBVn3Dl89YqaK/integrations/workday-skill-sync-integration/images/update-isu-language.png?fit=max\&auto=format\&n=78HQBVn3Dl89YqaK\&q=85\&s=c1f5f98efaaba4fc7362e778c9f72123) Remember to stop the proxy after setting the language preferences, using the `Stop Proxy` task. ### 2. Update password expiration rules for ISU * In the `Maintain Password Rules` business process under "System Users exempt from password expiration" add the newly created ISU to the list. * **Note:** This ensures the integrations will keep running without interruptions due to password expiration. ![Maintain Password Rules](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/maintain-password-rules.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=29aee6b3bcbb1b2540de35c103d3c578) ### 3. Set up security permissions for the ISU through security policies * Go to `Create Security Group`, choose "Integration System Security Group (Unconstrained)". * **Note on acceptance testing:** Consider using two different security groups, one Unconstrained and one Constrained. This way, the test-set is scoped while the correct permissions are applied for other Web Services. ![Create Security Group](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-security-group.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=1582d2fc302fd6b313c4ce6b21c86e3b) ![Create Security Group Detail](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-security-group-detail.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=75cff95ca512f394bd97836ce3da5df6) * The next screen presents you with an Edit form to add additional information. Add your ISU to the list. This can be changed later too. Do not check "Inactive". ![Edit Security Group](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/edit-int-sys-sec-group.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=3f8ce8d82ee37928b361712c58248a9e) ### 4. Edit the Security Group's domain security policies * Search for "View Security Group" and select your created security group. ![View Security Group](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-security-group.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=d268ce61b141a5973c8f66d2cac22eab) * Select the option menu next to the Security Group's name, go to "Security Group" and select "Maintain Domain Permissions for Security Group". ![View Security Group Action](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-security-group-action.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=52e883c48f17c9bd30bf61c176c94db4) * Under Integration Permissions add the following Domain Security Policies, and run the `Activate Pending Security Policy Changes` task to apply the changes. | Domain Security Policy | Access | | - | :-: | | Job Information | Put | | Manage: External Skills | Put | | Set up: Skills and Experience | Put | ![Integration Permissions](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-job-integration-permissions.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=01c64e40ea8ef0eca7643d4c0f9b257d) ### 5. Find out the correct Workday API URL * Search for `Public Web Services` in the search bar at the top of the Workday home page. * In the list, click the three dots next to the `Human Resources (public)` entry. Select `View WSDL` under `Web Service`. ![View wsdl](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-wsdl-for-api-url.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=1a436b6f7aa163adb51205ba350c49ce) * The resulting page will take some time to load. Once it is loaded, look for "soapbind:address location" near the bottom of the page. You will see a section like this: ```xml theme={null} ``` * Copy the base tenant URL up to and including your tenant name. The service name and version should be excluded from the URL. * Note that the API URL can differ between implementation tenants and production tenants, so the steps described above need to be repeated for each tenant individually. > [!NOTE] > > If you are using **OAuth Authentication** (recommended), continue with the > OAuth setup steps below before connecting the integration. > > If you have arranged **Basic Authentication**, this is the final Workday > configuration step. Proceed to the > [TechWolf Configuration](#techwolf-configuration) section. ### 6. Create API Client for Integrations * Search for "Register API Client for Integrations" business process * Enable non-expiring refresh tokens to ensure continuity of service * Under "Scope (Functional Areas)", add exactly these scopes:
Scope (Functional Area) Needed for
![API Client Setup](/integrations/workday-skill-sync-integration/images/register-api-client-jobs.png) * Optionally, restrict the client to TechWolf's IP ranges by filling in the "Restricted to IP Ranges" field with the values from the [IP Addresses ](/integrations/reference/ip-addresses) page * Securely store the client ID and client secret ![API Client Credentials](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/view-api-client-for-integrations.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=0198dc19f26da04632cc0acb3512c9ca) ### 7. Generate Refresh Token * Search for "View API Clients" report * Click "API Clients for Integrations" tab * Note down the token endpoint. You will need to share this later. ![API Client Refresh Token](https://mintcdn.com/techwolf/0Ad82QpBivsiQKdJ/integrations/workday-skill-sync-integration/images/create-refresh-token.png?fit=max\&auto=format\&n=0Ad82QpBivsiQKdJ\&q=85\&s=7778fec41090d9abd5733e888f636476) * Find your API client and select "Manage Refresh Tokens for Integrations" * Under "Workday Account", type in your ISU * Press OK * Check the box "Generate new refresh token" * Press OK * Securely store the refresh token. > [!WARNING] > > Keep your OAuth credentials secure and share them only with TechWolf through > secure channels. When the authentication credentials and Workday API URL are shared, the setup is complete on the customer's Workday tenant. TechWolf will validate that the ISU has the required permissions and that the API URL is correct. ## TechWolf Configuration The TechWolf tenant will be configured by TechWolf itself. 1. In the integration service on the TechWolf side, TechWolf adds the credentials of the customer-created ISU. For this, the customer will need to share the following values with TechWolf: * The Workday API URL (see Step 5 of the Workday Configuration section) * Authentication credentials: * OAuth Authentication (recommended): client ID, client secret, and refresh token (see Steps 6–7 of the Workday Configuration section) * Basic Authentication (on request): ISU username and password (see Steps 1–2 of the Workday Configuration section) 2. TechWolf adds TechWolf API credentials with correct scopes to have access to the TechWolf API and links that TechWolf tenant to the Workday tenant. 3. TechWolf validates that the ISU has the required permissions and that the Workday API URL is correct. 4. TechWolf runs an initial sync of Job profiles with the TechWolf API and sets up the tenant configuration to start the bidirectional sync process. ## Routing Through an API Gateway If your organisation fronts the Workday APIs with an API gateway, the integration can call the gateway instead of the vendor host directly. Two settings are available, both configured by TechWolf together with the credentials: * **Custom URL**: instead of the vendor API URL, share the gateway URL that proxies it. The integration keeps appending the same vendor API paths to it, so the gateway must forward requests to Workday unchanged. * **Custom headers**: any number of extra HTTP headers (for example an API key or a correlation ID required by the gateway) that are sent on every request the integration makes. > [!NOTE] > > Both settings are pass-through only. TechWolf sends the values as configured > and does not perform any gateway-specific authentication, signing, or token > refresh; the gateway is expected to forward the integration's own > credentials to Workday. Reserved headers (e.g. `Authorization`, > `Content-Type`) are managed by the integration and cannot be set as custom > headers. ## Linking Workday & TechWolf - Seamless Matching of Job IDs A critical aspect of this process is the seamless coupling of Job IDs across both platforms. There are two options for direct ID matching: 1. **Using Job Codes**: If you want to use Workday Job Codes (also known as Job Profile IDs) as the identifier field in Workday, then this same ID must also be used as the Job `external_id` in TechWolf. 2. **Using Workday IDs (WIDs)**: If you want to use Workday IDs as the identifier field in Workday, then this same ID must also be used as the Job `external_id` in TechWolf. This option is only available if you have a generator configured in Workday for Job Codes. For details on how to set this up, please refer to the Workday documentation, e.g. [Create ID Definitions and Sequence Generators](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/tenant-setup/id-definitions-and-sequence-generators/dan1370796358261.html?lang=en-us). ## Deployment Methodology The following tasks and responsibilities assume that: 1. The customer has the appropriate TechWolf API license(s). 2. The TechWolf API contains all Job information corresponding to Workday Jobs and data from other external systems. ### Deployment Tasks & Responsibilities 1. **TechWolf**: Setup Skill Sync environment and tenant requirements 2. **Customer**: Verify the Synonym Management configuration (see [System Requirements](#system-requirements)). 3. **Customer**: Create Integration System User (ISU) based on workflow described above. 4. **Customer**: Share authentication credentials with TechWolf: * OAuth Authentication (recommended): `client_id`, `client_secret`, and refresh token * Basic Authentication (on request): ISU `username` and `password` 5. **Customer**: Share Workday API URL with TechWolf. 6. **TechWolf**: Run initial sync of Job profiles with TechWolf API. 7. **TechWolf**: Setup tenant configuration and start bidirectional sync process. 8. **Customer**: Check end-user test scenarios. # Overview Source: https://developers.techwolf.ai/integrations/workday-skill-sync-integration/overview-employees # Employee Skill Sync Integration with Workday This Deployment Guide provides instructions that will assist in the process of deploying the Workday - TechWolf Employee Skill Sync Integration, including detail on the configuration and deployment of the integration in the customer's Workday tenant. The intended audience for this document is the Integration Implementer. ## Integration The Integration has been designed, developed, tested, documented, and deployed by TechWolf with Workday's guidance and oversight. The integration facilitates the flow of data required between Workday and TechWolf Skills or specific use case(s) and is not intended to address all use cases customers may be interested in. The customer benefits by receiving pre-built, pre-tested, documented, partner-maintained integrations that minimize implementer's effort as compared to custom integrations for the specific use case(s) addressed. ## Functional Objective TechWolf and Workday are partnering to enhance skill management within organizations. TechWolf leverages data from various sources, including business systems, to infer skills. These inferred skills are seamlessly integrated into Workday skill profiles, providing a comprehensive and real-time view of employees' skills. The integration also enables profile synchronization between TechWolf and Workday, ensuring that both platforms' updates are consistently reflected. This can be further facilitated with the use of the [TechWolf Skill Assistant ](/integrations/skill-assistant/overview), where employees can either be notified of or validate newly suggested skills. This integration does not depend on the Skill Assistant; any other skill validation approach can be used. The integration is agnostic to the skill validation. **Key benefits:** * TechWolf synchronizes employee skill profiles across all relevant systems, harmonizing skills across all systems. * The accurate and up-to-date skill data in Workday can be used for downstream purposes within Workday, e.g. Talent Marketplace and Learning. * As TechWolf does not rely on manual assessments, we increase employee adoption to your talent marketplace with automated skill profiles. * Custom skill support: customer-specific custom skills (Workday Maintained Skills) are synchronized alongside the Skills Cloud vocabulary (optional; see [How It Works](./how-it-works#custom-skills)). ## Important Information ### Software Partner API Versioning To minimize the impact on Customers, Software Partners, and Workday, Workday Software Alliances only requires Software Partners to update API versions in their integrations when not doing so will result in meaningful impact on a current or future Customer. Given that Workday's approach to API updates expects that updates are backward compatible (with few exceptions), API version updates are rarely required for a previously badged integration. However, Workday reserves the right to require a partner to update an integration to the latest API version if the current version is negatively impacting a joint customer or is resulting in unnecessary support and/or maintenance effort. We also strongly encourage partners to take the opportunity when making other updates to their integration to also move to the latest version of any API's leveraged. ## Reference Material Reference materials and documentation can be found at: * TechWolf developer documentation: [https://developers.techwolf.ai/ ](https://developers.techwolf.ai/) * TechWolf Skill Sync source IP addresses: [IP Addresses ](/integrations/reference/ip-addresses) * Workday x TechWolf field mapping matrix (on request). * Used Workday Web Service operations: * `Put_Skill` ([Workday API ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Talent/v43.2/Put_Skill.html)) * `Get_Skills` ([Workday API ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Talent/v43.2/Get_Skills.html)) * Only used when custom skill support is enabled (see [How It Works](./how-it-works#custom-skills)). * `Manage_Skills` ([Workday API ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Talent/v43.2/Manage_Skills.html)) * `Get_Manage_Skills` ([Workday API ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Talent/v43.2/Get_Manage_Skills.html)) ## Glossary of Terms * **Certified Integration**: An integration system developed by TechWolf that enables the data flow between Workday and TechWolf. Certification is achieved after meeting all requirements from Workday. - **Configurable Security Policy**: The Configurable Security Policy describes the access required for each Integration System User and permissions needed for the integration to function. - **Integration Implementer(s)**: The individual or group of individuals responsible for deploying the integration. Workday generally recommends that the customer engage the appropriate Workday Certified Consultants when deploying any integration. - **SkillEngine API**: The TechWolf API. This is the TechWolf system where skill data is stored, calculated, and used for related skills functionality. Interaction works through the REST API. - **Skill Profile**: The set of skills of an Employee. - **Customer Skill Sources**: Implies all customer platforms, integrations, and data that can serve as a source of skill information. Think of learning platforms, and Workday itself. # Overview Source: https://developers.techwolf.ai/integrations/workday-skill-sync-integration/overview-jobs # Job Skill Sync Integration with Workday This Deployment Guide provides instructions that will assist in the process of deploying the Workday - TechWolf Job Skill Sync Integration, including detail on the configuration and deployment of the integration in the customer's Workday tenant. The intended audience for this document is the Integration Implementer. ## Integration The Integration facilitates the flow of data required between Workday and TechWolf Skills or specific use case(s) and is not intended to address all use cases customers may be interested in. The customer benefits by receiving pre-built, pre-tested, documented, partner-maintained integrations that minimize implementer's effort as compared to custom integrations for the specific use case(s) addressed. ## Functional Objective TechWolf wants to enhance skill management within organizations. TechWolf leverages data from various sources, including business systems, to infer skills. These inferred skills are seamlessly integrated into Workday skill profiles, providing a comprehensive and real-time view of jobs' skills. The integration also enables profile synchronization between TechWolf and Workday, ensuring that both platforms' updates are consistently reflected. Besides skill presence or absence, the integration also synchronizes the needed skill proficiency and the skill criticality (whether the skill is marked as `required` for the job in Workday) of the jobs' skills. **Key benefits:** * Effortless skill identification: Our solution streamlines skill identification for job profiles by automatically extracting data from various sources (incl. Workday) and leveraging our labor market data to infer and structure skills into profiles, eliminating manual efforts. * Governance & maintenance made simple: Easily oversee and control your job skill profiles within your job catalog through an intuitive interface. This setup supports collaborative efforts among multiple owners simultaneously, while providing tailored access to various user groups, ensuring a strong and effective governance framework. * Skill synchronization & harmonization: TechWolf synchronizes job skill profiles across all relevant systems, harmonizing skills across all systems. * Enriched downstream use cases: The accurate and up-to-date skill data in Workday can be used for downstream purposes within Workday, e.g. Talent Marketplace. * Custom skill support: customer-specific custom skills (Workday Maintained Skills) are synchronized alongside the Skills Cloud vocabulary (optional; see [How It Works](./how-it-works#custom-skills)). ## Important Information ### Software Partner API Versioning To minimize the impact on Customers, Software Partners, and Workday, Workday Software Alliances only requires Software Partners to update API versions in their integrations when not doing so will result in meaningful impact on a current or future Customer. Given that Workday's approach to API updates expects that updates are backward compatible (with few exceptions), API version updates are rarely required for a previously badged integration. However, Workday reserves the right to require a partner to update an integration to the latest API version if the current version is negatively impacting a joint customer or is resulting in unnecessary support and/or maintenance effort. We also strongly encourage partners to take the opportunity when making other updates to their integration to also move to the latest version of any API's leveraged. ## Reference Material Reference materials and documentation can be found at: * TechWolf developer documentation: [https://developers.techwolf.ai/ ](https://developers.techwolf.ai/) * TechWolf Skill Sync source IP addresses: [IP Addresses ](/integrations/reference/ip-addresses) * Workday x TechWolf field mapping matrix (on request). * Used Workday Web Service operations: * `Put_Skill` ([Workday API ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Talent/v43.2/Put_Skill.html)) * `Get_Skills` ([Workday API ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Talent/v43.2/Get_Skills.html)) * Only used when custom skill support is enabled (see [How It Works](./how-it-works#custom-skills)). * `Get_Job_Profiles` ([Workday API ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Human_Resources/v42.2/Get_Job_Profiles.html)) * `Put_Job_Profile` ([Workday API ](https://community.workday.com/sites/default/files/file-hosting/productionapi/Human_Resources/v42.2/Put_Job_Profile.html)) ## Glossary of Terms * **Configurable Security Policy**: The Configurable Security Policy describes the access required for each Integration System User and permissions needed for the integration to function. * **Integration Implementer(s)**: The individual or group of individuals responsible for deploying the integration. Workday generally recommends that the customer engage the appropriate Workday Certified Consultants when deploying any integration. * **SkillEngine API**: The TechWolf API. This is the TechWolf system where skill data is stored, calculated, and used for related skills functionality. Interaction works through the REST API. * **Skill Profile**: The set of skills of an Employee. * **Customer Skill Sources**: Implies all customer platforms, integrations, and data that can serve as a source of skill information. Think of learning platforms, and Workday itself. # Explanation: Skill Harmonization Source: https://developers.techwolf.ai/integrations/workday-skill-sync-integration/skill-harmonization TechWolf is set on playing nice in the Skills ecosystem. This means we must be able to speak everyone's language. Languages have dictionaries to translate between them; for skills we have mappings. > **Mapping** > > Comparing two ontologies and creating the most optimal translation between > skills themselves generates a **mapping**. Additionally, when we translate full sentences between languages (French and Mandarin Chinese), we don't translate each word individually, context is important. This is also the case for translating skill profiles for entities. Simply translating each skill without context does not drive optimal value and insights. > **Harmonization** > > Skill **harmonization** is the process of using the **mapping** to display > the correct set of skills for an entity, in different ontologies. The difference is best explained using an example. See the [mapping](#example-mapping) and [harmonization](#example-harmonization) sections. Lastly, just like French and Mandarin Chinese translation has its own peculiarities compared to Hindi to Italian, mapping and harmonizing skills between TechWolf and different vendors can have its own peculiarities. We strive to reduce the amount of such differences. ## Example: Mapping Consider the following mapping from Vendor 1 to Vendor 2. | Skill Vendor 1 | Skill Vendor 2 | | - | - | | Python 3.12 (Programming) | Python | | Python 3.13 (Programming) | Python | | Power BI | Microsoft Power BI | | JavaScript (Web Development) | JavaScript | | Data Analytics | Data Analysis | | AI & Machine Learning | Machine Learning | | SQL Database Querying | SQL | | UX Design | User Experience Design | While Vendor 1 has two representations for the skill `python`, Vendor 2 only has one. As we want both Vendor 1 skills to be correctly mapped, they both map to the same skill for Vendor 2. It is clear what should be done when we map from `Python 3.12 (Programming)` to `Python`. The other way around is more complex, as a decision has to be made: 1. add `Python 3.12 (Programming)` 2. add `Python 3.13 (Programming)` 3. add both TechWolf leverages complex algorithms to figure out the most optimal skill, and selects only one as "primary" mapping (for example, `2.` in the scenario above). > [!TIP] > > Each skill in both TechWolf and vendors can have multiple mappings in > TechWolf, with an order of precedence for each mapping item. The primary > mapping is the highest ranked mapping and is most often the closest (an > exact match is ideal). ## Example: Harmonization Now that we know the mapping, we can translate profiles. This is where **harmonization** is used. Consider Lisa, a junior software engineer: | Skill Vendor 1 Skill | | - | | Python 3.12 (Programming) | | Power BI | | JavaScript (Web Development) | | Data Analytics | | AI & Machine Learning | | SQL Database Querying | | UX Design | If we want to harmonize Lisa's profile, we must map her `Python 3.12 (Programming)` skill to `Python` in Vendor 2. But now Lisa's profile is not following the most optimal mapping anymore! (that would be to change her original profile to contain `Python 3.13 (Programming)`, but that would change Lisa's original input). Instead, when we harmonize, we keep track of all existing skills, and will opt for using non-primary mappings when it drives consistency in profiles. > [!TIP] > > TechWolf considers existing profiles when harmonizing profiles between > ontologies, and will keep the non-primary skills in user input to drive > consistency and trust. # File Organization Source: https://developers.techwolf.ai/integrations/reference/file-structure This document outlines the standard file structure used by TechWolf for file organization. This structure is designed to facilitate automation and ensure compliance with data handling requirements. > [!NOTE] > > This documentation is provided for reference purposes only. As a customer, you > will be helped by our team to set up the correct structure for your files. > > We recommend following this structure as it provides several benefits: > > * Organized grouping of integration files > * Standardized import and export locations > * Simplified automation and compliance management, improving the onboarding > and security. # S3 File Structure ## Tenant Structure The top-level folders in a customer's S3 bucket correspond to different environment types. These are one of the following: * `production` * `staging` * `testing` ## Folder Organization Each environment folder follows a standardized structure to maintain clear separation between input and output files. The `external` folder contains all files that customers have access to. The rest of the path will be of the following format: > **S3 File tree structure** > > * `input/`: Path with write access, for input files and integrations > > * `integrations/`: Integration-specific input files > > * `sap_skill_sync/`: SAP skill synchronization data. Only used when > the SAP skill sync is enabled. > * `file_based/`: File-based integrations input files. > > > [!NOTE] > > > > The following items are examples, not rules. The main point is > > that files are separated per integration for easier navigation. > > * `sap_datasource/` > * `LinkedInLearning_learnings/` > * `jobs/` > * `workday/` > * `workday_employee/` > * `WorkdayEmployee_WorkingHistory/` > * ... (additional integration-specific folders) > * `output/`: Files available for viewing and download > * `exports/`: Standard export files > * `[export type]/`: Exports grouped by type Some examples: * `testing/external/input/integrations/file_based/sap_datasource/` * `production/external/output/exports/data-maturity-scan/dms_employees/quality_matrix_report.xlsx` # SFTP File Structure ## Folder Organization SFTP servers are not always owned by TechWolf, so it is possible that following an exact structure is not possible. To help set up a structure, here are our guidelines which improve onboarding, observability, and security. | | What | Why | | | - | - | - | - | | 1 | Any prefixing directories you need to organize your files on the server. Communicate this to TechWolf, this is where TechWolf will start looking for files. | To allow flexible organization and clear communication of file locations. | COULD | | 2 | Create a clear separation between environments if the same SFTP server is used for multiple environments. Call the environments `production`, `staging`, or `testing`. These should be readable/understandable by all parties involved. | To avoid confusion and ensure all people involved can easily identify which environment files belong to. | MUST | | 3 | Create a clear separation between input and output files (`input/` and `output/`). | To prevent accidental overwrites and to clarify the direction of data flow. | MUST | | 4 | Add a subdirectory indicating what the files are about; their purpose (`integrations/`, `integrations/file_based/`, `discovery/`, `manual_file_sharing_for_customer_request/`, etc.) | To make it clear what each set of files is for, improving navigation and management. | COULD | | 5 | Create a subdirectory for each integration type. | To improve organization, safety, and traceability of files related to different integrations. | SHOULD | All of this improves clarity, observability, and security, and is a sustainable setup that will prevent people from "forgetting" what files are, and where they are. > [!NOTE] > > Please communicate path decisions, and especially any deviations from this > structure to TechWolf. > **SFTP Example File tree structure** > > * `path/to/your/files`: Any prefixing directories you need to organize your files on the server. > * `staging/`: Environment-specific files > * `production/`: Environment-specific files > * `input/`: For input files and integrations > * `integrations/`: Integration-specific input files > > [!NOTE] > > > > The following items are examples, not rules. The main point > > is that files are separated per integration for easier > > navigation. > * `LinkedInLearning_learnings/` > * `jobs/` > * `workday/` > * `workday_employees/` > * `WorkdayEmployee_WorkingHistory/` > * ... (additional integration-specific folders) > * `output/`: Files available for viewing and download > * `exports/`: Standard export files > * `[export type]/`: Exports grouped by type # IP Addresses Source: https://developers.techwolf.ai/integrations/reference/ip-addresses Several TechWolf services connect to your systems from a fixed, static set of IP addresses. If your infrastructure needs inbound or outbound traffic restrictions, allowlist the relevant IP addresses for your region so that TechWolf can reach your systems. IP addresses indicated with `*` as their service apply to all services. It is always safe to add all IP addresses from a region, as they are all owned by TechWolf. > [!NOTE] > > IP addresses are listed per region. Make sure to allowlist the addresses for > the region your integration is hosted in. ## EU | IP Address | Services | | - | - | | 15.237.20.171 | \* | | 52.47.56.198 | \* | | 13.37.160.251 | [webhooks](/integrations/webhooks/protocol-delivery) | | 13.36.99.139 | [webhooks](/integrations/webhooks/protocol-delivery) | | 52.47.130.99 | [webhooks](/integrations/webhooks/protocol-delivery) | ## US | IP Address | Services | | - | - | | 34.226.223.38 | \* | | 52.23.123.55 | [webhooks](/integrations/webhooks/protocol-delivery) | | 18.214.28.250 | [webhooks](/integrations/webhooks/protocol-delivery) | | 34.205.219.76 | [webhooks](/integrations/webhooks/protocol-delivery) | ## Canada | IP Address | Services | | - | - | | 35.182.88.145 | \* | | 15.157.53.19 | \* | # Self-service SFTP setup Source: https://developers.techwolf.ai/integrations/reference/sftp/self-service-setup This guide walks through configuring a customer-hosted SFTP server as an input integration from the Console. It applies to customers, implementation partners, and TechWolf Professional Services. For the trust model and the role of each key, see [How SFTP works](/integrations/reference/sftp/how-sftp-works) and [Security](/integrations/reference/sftp/security). # Prerequisites * A customer-hosted SFTP server that is reachable from TechWolf's egress IP addresses. > [!NOTE] > > TechWolf's egress IP addresses are available on request from your > TechWolf contact. * Admin access to install an SSH public key on the SFTP server (or, for legacy servers, a service-account password). * The remote folder path(s) that TechWolf should pull files from. # Steps **1. Open the SFTP Configuration page** In the Console, go to **Integrations → SFTP Configuration** (`/integrations/sftp-config`). ![Empty state of the SFTP Configuration page](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/01-empty-state.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=6763f75b39fc0b577f4964b1c147d5e2) **2. Start a new connection** Click **Connect a server**. A drawer opens on the **Setup** tab. ![Empty connection drawer on the Setup tab](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/02-drawer-create-empty.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=bff287f68184c69d75ad636bb8cf15bb) **3. Fill in identity and connection** Provide a **Name**, an optional **Description**, the **Host** and **Port** (default `22`), and the SFTP **Username** that TechWolf will log in as. ![Setup tab with identity and connection fields filled in](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/03-drawer-setup-filled.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=82d9d127174ba8482cc2c6034fee853c) **4. Choose authentication** Select **SSH key** (strongly recommended). TechWolf generates the keypair on the **Keys** tab. The private key never leaves TechWolf. See [How SFTP works: keys](/integrations/reference/sftp/how-sftp-works#keys-who-holds-what) for the keypair model. > [!WARNING] > > Password authentication is significantly less secure than SSH-key > authentication. The password is transmitted on every connection, > must be rotated frequently, and offers no protection against > credential reuse or leaks. Choose **Password** only if the SFTP > server cannot accept public keys. See > [Security: SSH key preferred over password](/integrations/reference/sftp/security#ssh-key-preferred-over-password). **5. Create the connection** Click **Create connection**. The drawer flips to the **Keys** tab. ![Empty Keys tab right after creating a connection](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/04-keys-tab-empty.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=9a8166598ce3563fd5d85be299c12ce0) **6. Generate a keypair and install the public key** Click **Generate keypair**. The public key is revealed once: copy it or click **Download**. Install it in the `authorized_keys` file of the configured user on the SFTP server. Multiple active keys per server are supported, which enables [key rotation without downtime](/integrations/reference/sftp/security#key-rotation-without-downtime). For background on what is actually being exchanged on each connection, see [How SFTP works: keys](/integrations/reference/sftp/how-sftp-works#keys-who-holds-what). ![Keys tab showing the revealed public key](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/05-keys-public-revealed.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=f7f9da3887f6e82aab4231f63347fd82) **7. Verify and pin the host key** Return to the **Setup** tab and click **Test connection**. On success, the server's SHA256 host-key fingerprint is captured and locked automatically. Every later connection must match it. ![Test connection succeeded with the host-key fingerprint locked](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/11-test-connection-success.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=be6a810ff5fd0f9b1519df3de6233a9d) **8. Configure folder mappings** Open the **Mappings** tab and click **Add mapping**. * **Remote folder on server**: the absolute path on the SFTP server, for example `/outbox/hr-feed`. * **TechWolf destination**: the subpath under TechWolf's file-based ingest prefix. File-based input integrations read from here. Each mapping can be toggled on or off independently. ![Adding a new mapping in the Mappings tab](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/06-mappings-add-draft.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=ffeaa982156e43d196a494e98dbb2409) ![Mappings tab with a saved mapping](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/07-mappings-saved.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=4f967855bf5169f7362b248921b059ab) **9. Browse the server (optional)** The **Browse** tab opens a live, read-only view of the SFTP server using the configured credentials. Useful for verifying a remote path before adding a mapping. Browsing never marks files as pulled. ![Browse tab showing files inside /outbox/hr-feed](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/13-browse-populated.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=08fccbe7faf577a48199857e4e7f479b) **10. Confirm on the overview** Close the drawer. The card on the overview shows the last pull time, the watched-paths count, and a health tag (Healthy, Idle, No keys, or Disabled). ![Overview with a connected SFTP server card](https://mintcdn.com/techwolf/1OOzBwAfiuFGjToG/images/sftp-config/10-overview-with-card.png?fit=max\&auto=format\&n=1OOzBwAfiuFGjToG\&q=85\&s=7bfa4622616f8abd4836632ef8b59f4f) # Single Sign-On for the TechWolf Console Source: https://developers.techwolf.ai/integrations/reference/sso This page describes SSO for the **TechWolf Console**. It does not apply to API authentication. For API access, see [Authentication](/tutorials/getting-started/authentication) in the Tutorials. With Single Sign-On (SSO), your employees can log in to the TechWolf Console using your company's existing identity provider (IdP) instead of separate credentials. This simplifies access management and aligns with your existing security policies. Use this page as your reference while setting up and reviewing the connection. It lists the supported providers, the exact values your IdP admin needs (ACS URL, entity ID, application URL, attributes), and the answers to the questions that usually come up during setup and security review, so you can configure SSO and clear your security review without contacting us. ## Supported SSO Providers TechWolf supports the following SSO providers for the TechWolf console: | Provider | | - | | Generic OIDC | | Generic SAML | | Okta Workforce Identity (using OIDC) | | Entra ID | | Google Workspace (using OIDC) | | Keycloak | | Microsoft Active Directory Federation Services (ADFS) | | PingFederate | ## Where each value goes SSO connects two sides, and each side needs values from the other: | Where you enter it | What you enter | Where you find it | | - | - | - | | The SSO setup flow in the Console | Values about **your IdP**: its sign in URL (PingFederate calls it the server URL), metadata URL or signing certificate | Your IdP | | Your IdP | Values about **TechWolf**: ACS URL, SP entity ID, application URL, relay state, `email` attribute | The tables on this page | ## How your values are built Every TechWolf value is built from three things: your **tenant name**, your **region**, and the **environment** (production or staging). Your tenant name is the first part of your Console URL. If your Console is at `https://yourcompany.console.techwolf.ai`, your tenant name is `yourcompany`. The table below shows the parts that depend on your region. The next section puts them into each field. | Region | Auth0 tenant | Auth domain | | - | - | - | | EU | `techwolf` | `eu3.auth.techwolf.ai` | | US | `techwolf-us` | `us3.auth.techwolf.ai` | | CA | `techwolf-ca` | `ca1.auth.techwolf.ai` | ## Setting up the connection (for your IdP / IT admin) | Field | Template | EU, production | US, production | CA, production | EU, staging | | - | - | - | - | - | - | | Protocol | SAML 2.0 | SAML 2.0 | SAML 2.0 | SAML 2.0 | SAML 2.0 | | ACS / callback URL (also recipient, destination) | `https:///login/callback` | `https://eu3.auth.techwolf.ai/login/callback` | `https://us3.auth.techwolf.ai/login/callback` | `https://ca1.auth.techwolf.ai/login/callback` | `https://eu3.auth.techwolf.ai/login/callback` | | SP entity ID | `urn:auth0::-sso` | `urn:auth0:techwolf:-sso` | `urn:auth0:techwolf-us:-sso` | `urn:auth0:techwolf-ca:-sso` | `urn:auth0:techwolf:-staging-sso` | | Application URL (also sign-in URL) | your Console URL | `https://.console.techwolf.ai` | `https://.console.techwolf.ai` | `https://.console.techwolf.ai` | `https://-staging.console.techwolf.ai` | | Relay state | `/` | `/` | `/` | `/` | `/` | | IdP metadata URL | enter your IdP's metadata URL in the setup flow | *(from your IdP)* | *(from your IdP)* | *(from your IdP)* | *(from your IdP)* | > [!WARNING] > > Replace `` with your own tenant name in every value. Do not copy the > values with `` still in them. If your Console is at > `https://yourcompany.console.techwolf.ai`, the US production SP entity ID is > `urn:auth0:techwolf-us:yourcompany-sso`. > The **application URL** is the URL of your Console. Some IdPs label this field > "sign-in URL"; it is the same value. ### Required attributes | Attribute | Expected format | Example | | - | - | - | | `email` | A valid email address. SAML `NameFormat`: `unspecified` (any format accepted). | `jane.doe@acme.com` | We use `email` to link the SSO user to their Console account, so it must be present. `username` is optional and can be any format. ### Additional SAML settings * **Login type:** SP-initiated only (IdP-initiated is not supported). See [Login must start from the Console](#login-must-start-from-the-console). * **Request signing:** supported. Algorithm RSA-SHA256, digest SHA256, binding HTTP-POST. * **Signing certificate:** X.509 (`.pem` or `.cer`). * **Assertion encryption:** optional. Supported as a per-connection configuration and enabled when your organisation requires it; off by default. * **Logout:** SP-initiated logout ends the user's Console session and returns them to the Console. SAML Single Logout (SLO) is not supported. ### Login must start from the Console We only support SP-initiated login. Your users open the Console URL, click the SSO button and are sent to your IdP. Login that starts from your IdP (IdP-initiated), such as clicking an app tile in the Microsoft or Okta portal, does not work. Check this when you fill in the sign in URL of your IdP in the setup flow. It must be the URL that accepts a login request from TechWolf, not a URL that starts a login on its own. For PingFederate: | URL ends with | Login type | Use it? | | - | - | - | | `/idp/SSO.saml2` | SP-initiated | Yes | | `/idp/startSSO.ping` | IdP-initiated | No, login will fail | `/idp/` in the URL is fine. It only means the URL points to your IdP server. ## Security and architecture review | Question | Answer | | - | - | | Identity management system | OAuth 2.0 (Auth0) | | Authentication protocol | OIDC with federated SAML 2.0 for enterprise SSO | | Authorization method | Role-based access control (RBAC) | | Supported identity providers | Generic OIDC, Generic SAML, Okta Workforce Identity, Entra ID, Google Workspace, Keycloak, Microsoft ADFS, PingFederate | | Hosting regions | EU, US, CA | ## User provisioning and access | Question | Answer | | - | - | | How are accounts created? | Manually today (CSV upload). SCIM auto-provisioning is on the roadmap. | | How is access granted? | Add users to a group in your IdP that has access to the connection. | | Separate test and production SSO? | Yes, a separate connection per environment. | ## Next Steps To set up SSO for your organisation, follow the steps on the user management page of the Console or contact your TechWolf account manager or [support@techwolf.ai](mailto:support@techwolf.ai). You can only set up one SSO connection per Console. # Skills in Workday Source: https://developers.techwolf.ai/integrations/reference/workday-skills The Workday Skill vocabularies (Skills Cloud and Maintained Skills), how the Skills Cloud evolves through quarterly updates and Synonym Management, and what TechWolf integrations expect from your Workday tenant ## Skill Vocabularies In the scope of TechWolf, Workday's Skill features draw on two distinct vocabularies: * The **Workday Skills Cloud**: the vocabulary of Skills that Workday itself maintains, shared across tenants and continuously improved by Workday. It contains: * **Canonical Skills**: the redundancy-free core of the vocabulary. TechWolf integrations exchange canonical Skills only. * **Synonyms**: alternative names for canonical Skills, such as historical names, spelling variants, or genuine synonyms. Unless disabled or excluded, Workday resolves these to their linked canonical Skill through [Synonym Management](#automated-skill-management-synonym-management). * **Maintained Skills**: customer-specific Skills maintained in your own tenant, separate from the Skills Cloud. Unless disabled or excluded, where possible, Workday resolves these to their canonical Skills Cloud Skill equivalent through [Synonym Management](#automated-skill-management-synonym-management). TechWolf allows customers to choose Workday as their preferred Skills language. Workday Skills are then shown in all downstream applications, such as the Skill Assistant, the Console, or any other application built on top of the SkillEngine API. By default, only the canonical Skills from the Skills Cloud vocabulary are supported. However, TechWolf provides methods to create custom skills within the TechWolf platform, which can optionally be synchronized to Workday as Maintained Skills when using the [Skill Sync integrations](/integrations/workday-skill-sync-integration/how-it-works#custom-skills). For broader questions about Skills Cloud itself, Workday maintains a [Workday Skills Cloud FAQ](https://community-content.workday.com/content/workday-community/en-us/faq/products/talent-management/the-next-level/workday-skills-cloud-faq.html?lang=en-us) on Workday Community, with more documentation in the Community space itself too. ## Vocabulary Updates Four times a year, on the *first Wednesday of February, May, August, and November*, Workday runs a background process for Skills Cloud ontology updates. As a result of the ontology update procedure, impacted Skills in your tenant are automatically replaced by their latest Skills Cloud version. A Skill can be affected in three ways: * **Canonical Added**: a new canonical Skill is introduced. * **Skill Deprecated**: an outdated Skill is retired. * **Synonym Added**: a Skill is merged into a canonical Skill as a synonym, and references to it are moved to the canonical Skill. This cadence is part of how Workday keeps Skill data accurate and up to date; see the [Workday Skills Cloud Ontology: Insights and Cadence](https://doc.workday.com/release-notes/en-us/doc/9220027.html?lang=en-us) release note and future related release notes for the full details. ### Updates in Workday Workday announces each update through the **Skills Cloud Updates report**. The report is made available on the first Wednesday of the update month (February, May, August, or November) and remains available in Production tenants for 28 days, until the update takes effect. Users with access receive a Workday notification when the report is ready. To view the report: 1. Make sure you have the required permissions. The report is secured to the **Skills Cloud Updates** domain; typically the **HR Administrator**, **Integration Administrator**, and **Talent Administrator** security groups have access. You can verify the configuration in your tenant with the *View Security for Securable Item* task, searching for "Skills Cloud Updates". 2. Open the **Skills Cloud Updates** report by typing its name in the Workday search bar. The report shows two key dates: * **Task Last Updated Date**: when Workday last refreshed the report's contents. * **Effective Date of Skills Cloud Update**: when Workday migrates the listed Skills in your tenant, 28 days after the Task Last Updated Date. For each impacted Skill, the report lists the Skill in your tenant, the Skills Cloud Skill that replaces it, the change type, and usage counts showing where the Skill is referenced (Employees, Job Profiles, Job Postings, and so on), so you can assess the impact before the changes take effect. Skills that are not referenced in your tenant, but updated, are not in the report. ### How TechWolf handles these updates When Workday is used as the preferred Skills language in your TechWolf environment, TechWolf applies the same vocabulary changes as Workday to that environment, timed around Workday's rollout, so that the Skills you see through TechWolf stay consistent with the Skills in your Workday tenant. However, this process happens gradually, in the following manner: * **28 days before the roll-out**, Workday makes the **Skills Cloud Updates** report available. * At the same time, the TechWolf Console informs Console users about the upcoming changes, including a report of the exact changes that will be applied. The list of Skills lets you understand which Skills are affected. * The notification also indicates the **time window** in which you may see inconsistencies between Workday and what is visible in the Console. * TechWolf applies the vocabulary update **right before Workday's update**: the TechWolf update is executed at a fixed time shortly before the earliest Workday rollout (1am UTC+13), and the transition is complete once Workday's own rollout has fully finished. * Workday's rollout itself can start somewhat later than 1am local Workday tenant time, and can take multiple hours to complete. Your tenant's local time depends on the [Workday data center region](https://community-content.workday.com/en-us/reference/get-help/support/workday-data-centers/workday-data-center-locations-and-tenant-mapping.html?lang=en-us#accordion-fb3b7063f1-item-092a1db9e6) your tenant is hosted in. The exact combined process is as follows: 1. On the first Wednesday of February, May, August and November, Workday generates the impact report at 1am local datacenter timezone. 2. Workday's failure resilience retries up to 5 times to generate it, the report itself taking \~45 seconds. 3. Right after the report is finished becoming available, the timestamp is marked. That timestamp is now between `1am + 45 seconds` local time and `1am + 5 retries * 5 minutes + 45 seconds` (`= 01:25:45am`) local time. 4. Exactly 28 days later, Workday starts rolling out the Skills Cloud update. If your tenant got the report at `01:10:45am`, it is likely close to that same time. 5. Some time before that, at `1am UTC+13`, TechWolf rolls out the vocabulary update already. This means that customers in the east get the update right before their Workday tenant updates, while customers more west will have more time between the TechWolf update and the Workday update in their timezone. 6. Workday is rolling out the change, which can take up to 1 hour. The process is resilient, so will pick up failed changes at each next hour as long as there are failures. 7. The Workday update is done, the TechWolf update has passed, meaning that at this point, everything is consistent again. The inconsistencies are limited to a timespan of \< 24 hours. To mitigate inconsistencies even more, the TechWolf Console also presents an overview of which Skills changed; not only the Skills already in use, but all changing Skills. This can help you work more safely, knowing what will change. ### Considerations for users While the update is rolling out, you should prevent performing governance exercises that require exact Skills to be kept during the exercises. Even 28 days before it might already be interesting to you to be aware that Skills will be changing in the Workday Skills Cloud *and* correspondingly, in TechWolf. Additionally, because these improvements, much like TechWolf's own vocabulary updates, are intended to improve the quality and consistency of your Skill data, it is important to understand that this is a required part of the process. Workday and TechWolf are ever-evolving systems, and with the right level of reporting on what exactly is changing, you should be comfortable with the changes made during these updates. ## Automated Skill Management (Synonym Management) Synonyms can appear in your tenant over time, for example through the above-mentioned [Vocabulary Updates](#vocabulary-updates) that merge an existing Skill into a canonical Skill as a synonym. Workday's **Synonym Management** background process resolves these: it runs continuously and replaces synonymous Skills in your tenant with their canonical Skills Cloud Skill. For details on this Workday functionality, see [Concept: Automated Skill Management](https://doc.workday.com/admin-guide/en-us/human-capital-management/skills-and-skills-cloud/skills-cloud/bkh1675290302153.html) in the Workday documentation. TechWolf integrations only support canonical Skills Cloud Skills, not their synonyms. The [Skill Sync integrations](/integrations/workday-skill-sync-integration/how-it-works) rely on Synonym Management to resolve synonyms to their canonical Skill, so that full profiles can be synchronized and both systems stay consistent. However, when using custom TechWolf skills in Workday as Maintained Skills, these Maintained Skills should not be resolved to their canonical Skills Cloud Skill equivalents, but rather remain as Maintained Skills. The custom Skill synchronization is a unidirectional process, from TechWolf to Workday, and if a custom Skill in TechWolf were to be found to have no Maintained Skill equivalent in Workday (because it was resolved to a Skills Cloud Skill and deleted), a new Maintained Skill would automatically be re-created in Workday, only for this Skill to be deleted again, and so on. This results in the following required configuration: * **Keep Synonym Management enabled**, and do not exclude individual Skills Cloud Skills from it. Workday offers an *Exclude from Synonym Management* option per Skill, including directly from the Skills Cloud Updates report; excluded Skills stay synonyms and can therefore not be synchronized to TechWolf. * **When the Custom Skill Sync is live, enable the *Exclude Maintained Skills from Synonym Management* setting.** Custom skills are managed in TechWolf and synchronized to Workday as Maintained Skills; Workday must not replace them with Skills Cloud Skills. TechWolf already ensures that no custom skills are created that duplicate a Skills Cloud Skill. > [!NOTE] > > Workday excludes Maintained Skills from Synonym Management by default when > Skills Cloud is first enabled in a tenant. Verify that the configuration > matches your integration setup rather than assuming the defaults. ## References * [Workday Skills Cloud Ontology: Insights and Cadence](https://doc.workday.com/release-notes/en-us/doc/9220027.html?lang=en-us): release note describing the update cadence and the Skills Cloud Updates report. * [Concept: Automated Skill Management](https://doc.workday.com/admin-guide/en-us/human-capital-management/skills-and-skills-cloud/skills-cloud/bkh1675290302153.html): admin guide page describing Synonym Management and its exclusion options. * [Workday Skills Cloud FAQ](https://community-content.workday.com/content/workday-community/en-us/faq/products/talent-management/the-next-level/workday-skills-cloud-faq.html?lang=en-us): frequently asked questions about Skills Cloud on Workday Community. * [Workday Data Center Locations and Tenant Mapping](https://community-content.workday.com/en-us/reference/get-help/support/workday-data-centers/workday-data-center-locations-and-tenant-mapping.html?lang=en-us#accordion-fb3b7063f1-item-092a1db9e6): find your tenant's data center region to determine the local time of the rollout. # Open Source AI Models, Datasets & Tools Source: https://developers.techwolf.ai/open-source/index Explore TechWolf's open source contributions to the AI community At TechWolf, we're committed to advancing the field of AI and Natural Language Processing by open-sourcing our models and datasets. Our contributions focus on skill extraction, career path analysis, and job market understanding. ## Models ## Datasets ## Tools ## Research Impact Our open source contributions have made a significant impact in the field of AI-powered skill extraction and career path analysis: * **Total Model Downloads:** * **Total Dataset Downloads:** * **Combined Likes:** * **Dataset Size:** 140,000+ labeled examples * **Industry Coverage:** 24+ different sectors These resources are actively used by researchers and practitioners in the field of HR Tech and AI-powered career development. ## License and Usage Most of our datasets are released under the [CC BY 4.0 License](https://creativecommons.org/licenses/by/4.0/), allowing for both academic and commercial use with proper attribution. Our models are generally available for commercial use and are compatible with the Hugging Face Endpoints API for easy deployment. For implementation details and usage examples, visit our repositories on [Hugging Face](https://huggingface.co/TechWolf).