Appearance

Job Roles ​

Job roles classify the positions within your organization. They standardize role titles across teams, enable reporting by function, and link vacancies to the type of hire needed.

Why Job Roles Matter ​

Without a consistent set of role definitions, the same position might be called "Software Engineer" in one team and "Developer" in another. Job roles provide a single taxonomy that the entire organization uses, which enables:

  • Reporting by role -- see how many Software Engineers, Engineering Managers, or Product Designers you have across all teams
  • Salary benchmarking -- compare compensation for the same role across geographies or departments
  • Vacancy planning -- when a team opens a vacancy, they select from a defined list of roles rather than entering free text
  • Skills gap analysis -- identify which roles are understaffed relative to your targets

Configuring Job Roles ​

  1. Navigate to Settings > Job Roles
  2. Click Add Job Role
  3. Enter the role name and an optional description
  4. Click Save

Repeat for each distinct role in your organization.

TIP

Align your Flowstate job roles with the role taxonomy in your HR system (Workday, BambooHR, etc.). This makes it easier to reconcile headcount data when importing from external sources.

Data Model ​

FieldTypeDescription
namestringRole title (e.g., "Software Engineer", "Engineering Manager")
descriptionstringOptional description of the role's responsibilities
isActivebooleanWhether the role is available for assignment (default: true)
sortOrderintegerControls display ordering in lists and dropdowns (default: 0)
externalIdstringYour external system's identifier for this role. Used by integrations to upsert the role without needing Flowstate's internal ID. Optional; see below.

Unique constraints:

  • [organizationId, name] -- no duplicate role names within an organization.
  • [organizationId, externalId] -- at most one role per external system ID (when set).

Sync from External Systems ​

Integrations (Custom Integration hooks and the REST API) can address job roles by your own externalId without pre-provisioning them. When an employee or vacancy payload includes a jobRole object, Flowstate:

  1. Tries to match an existing role by externalId first.
  2. Falls back to matching by title (the role's name). If the matched row has no externalId yet and you supplied one, Flowstate patches it so subsequent lookups deduplicate correctly.
  3. Auto-creates a new role using the title if nothing matches. Auto-create requires title — supplying only externalId with no match returns 404 NOT_FOUND.

Payload shape (identical on both surfaces):

json
{
  "jobRole": {
    "title": "Senior Engineer",
    "externalId": "ROLE-042"
  }
}

Precedence: when a caller sets both jobRoleId (raw Flowstate CUID) and jobRole on the same request, jobRoleId wins.

How Job Roles Are Used ​

Job roles are assigned to two entity types:

  • Employees (LiveEmployee.jobRoleId) -- the role the employee currently holds
  • Vacancies (LiveVacancy.jobRoleId) -- the role the vacancy is hiring for

Reporting and Grouping ​

Once roles are assigned, you can group and filter views across the platform by job role. For example:

  • View the team page grouped by role to see the functional composition of each team
  • Filter the headcount forecast to show only "Engineering Manager" positions
  • Compare vacancy counts by role to identify which functions have the most open positions

Vacancies and Hiring Plans ​

When creating a vacancy, the selected job role communicates what type of hire is needed. This is particularly valuable in scenario planning: you can model the impact of hiring three additional "Senior Backend Engineers" versus two "DevOps Engineers" and compare the cost and capacity implications.

WARNING

Do not confuse job roles with work types. Job roles describe what someone does (e.g., Software Engineer, Product Designer). Work types describe how they are employed (e.g., Full-time, Part-time, Fixed-term contract). Both are assigned independently. See Configuration: Work Types for details.

Best Practices ​

  • Keep the list manageable -- aim for 10 to 30 roles. Too many roles fragment your data; too few lose useful granularity
  • Use clear, standardized titles -- prefer "Software Engineer" over abbreviations like "SWE" or team-specific jargon
  • Include a description -- a brief sentence helps people choose the right role, especially in large organizations
  • Deactivate retired roles -- set isActive to false rather than deleting roles that are no longer in use, to preserve historical assignment data

Required Permissions ​

Managing job roles requires the settings_entity_config_* permission set.

Flowstate Documentation

Copyright 2026 Flowstate.