Policy

Overview

A policy is a document that defines the for a group of workers. Given a worker’s properties and their , it describes what accounts and access they should have. Klef compares that to the current state of your systems and generates a of changes to make reality match the policy. A policy is written in Klef Policy Language (KPL).

Anatomy of a Policy

Policies describe who they apply to and how their target’s objects should look.

policy "Employee lifecycle" {            # name of the policy
  category = "Company-wide"
  applies  = everyone                    # which workers it applies to

  stage active {                         # the lifecyle stage at which it is applied
    target microsoft_entra.user {        # the target object's desired state
      displayName = worker.display_name
    }

    notify email "welcome" {               # notifications sent to interested parties
      send    = once
      subject = "Welcome"
      body    = "Your first sign-in: {{ microsoft_entra.sign_in_url }}"
      to      = [worker.personal_email]
    }
  }
}

KPL Reference

`applies`

Either everyone or a . Segments are a group of workers with something in common. They can be re-used across policies.

policy "Employee lifecycle" {
  category = "Company-wide"
  applies  = everyone        # <-- Applies to everyone
}

`stage`

A block for one . A worker is in exactly one stage at a time, and the block for that stage decides what applies to them.

policy "Employee lifecycle" {
  category = "Company-wide"
  applies  = everyone

  stage active {             # <-- Applies while the worker is active
  }

  stage leave {
  }

  stage terminated {
  }
}

Klef determines the worker’s stage from its HRIS’ status and assignment dates. Their lifecycle is defined as:

Stage	Written	A worker is here when
Pre-start	`pre_start`	They are hired and but haven’t hit their start date yet.
Active	`active`	They are hired and have met their start date.
Leave	`leave`	On a planned absence, such as parental or medical leave, and are expected back.
Suspended	`suspended`	On an involuntary hold.
Departing	`departing`	Their last work day is set but has not passed yet. They are still employed.
Terminated	`terminated`	Their last work day has passed, or the HRIS in some other way marks them terminated.

Omitting a Stage

If a policy has no block for a stage, it says nothing about that stage, and the worker’s accounts keep whatever they already have.

policy "Slack access" {
  category = "Company-wide"
  applies  = everyone

  stage active {
    target slack.user {
      userName = worker.business_email
      active   = true
    }
  }

  # <-- No leave block

  stage terminated {
    target slack.user {
      userName = worker.business_email
      active   = false
    }
  }
}

As an example, say your policy has an active block and a terminated block - both modifying a Slack account:

The worker goes on parental leave on May 1st, and moves to the leave stage.
Since the policy has no leave block, Klef makes no changes and their Slack account stays active.
The worker returns on August 1st, and moves back to the active stage. The active block applies again.
If the worker is instead terminated, the terminated block applies and their Slack account is deactivated.

`stage released`

This block, unlike terminated, applies when the policy stops covering an account. This can occur if a worker leaves the segment, a target is removed from the policy, or the policy is deleted. It’s not a worker lifecycle. Without it, Klef will apply a reasonable default, such as deactivating the account.

policy "Employee lifecycle" {
  category = "Company-wide"
  applies  = everyone

  stage released {           # <-- Applies once the policy stops covering the account
    target slack.user {
      userName = worker.business_email
      active   = true
    }
  }
}

`target`

A block naming one object in one , with the fields that object should have.

stage active {
  target microsoft_entra.user {      # <-- The Entra user each worker should have
    userPrincipalName = worker.business_email
    mailNickname      = worker.employee_id
    displayName       = "{{ worker.legal_name.given }} {{ worker.legal_name.family }}"
    accountEnabled    = true
  }
}

You do not have to indicate whether it’s a create or update. Klef compares the fields you wrote against the live object and does whichever one is needed. Each connector page lists the objects it accepts and the fields on each.

Mappings

A line inside a target that sets one field.

target microsoft_entra.user {
  userPrincipalName = worker.business_email     # <-- Sets userPrincipalName from the worker
  displayName       = "{{ worker.legal_name.given }} {{ worker.legal_name.family }}"
  accountEnabled    = true
  licenses          = ["SPE_E3"]
  jobTitle          = null
  mobilePhone       = unmanaged
}

Written	The value
`worker.business_email`	A worker field, copied as it is.
`"{{ ... }}"`	A Liquid template with worker fields filled in, so this one arrives as `Ada Lovelace`.
`true`	A fixed value, the same for every worker.
`["SPE_E3"]`	Picked from what the connector offers, such as licenses or groups. Klef adds and removes to match.
`null`	Klef owns the field and clears it.
`unmanaged`	Klef does not touch the field.

A value can also come from a script or a lookup table, which is what resources are for.

Field Types

Type	Written as
`string`	Text in quotes, supporting Liquid template
`bool`	`true` or `false`.
`int`	A number.
`date`	A date from the worker, such as `worker.end_date`.
`enum`	One of the values the connector page lists for the field.
`reference`	Something that already exists in the target, by its id, name, or address.
`link`	Another user in the same target, set from the worker’s manager.
`grant`	A list of what to grant, such as `["All Employees"]`. Klef adds and removes to match.
`array`	A list of rows, each written in `{ }`.
`map`	Entries in `{ }` whose names you choose, such as tags.
`object`	Fields in `{ }`, as the connector page lists them.

Templates

Text in quotes is a Liquid template, so it can read worker fields with {{ }} and use Liquid’s filters and tags. Text that runs to several lines is written as a heredoc, opened with <<TAG and closed by a line holding only the tag.

target microsoft_entra.user {
  displayName = "{{ worker.legal_name.given }} {{ worker.legal_name.family | upcase }}"   # <-- Ada LOVELACE
  jobTitle    = <<TITLE                                                                   # <-- Engineer, Platform
    {{ worker.job.name }}
    {%- if worker.department.name %}, {{ worker.department.name }}{% endif %}
  TITLE
}

`each`

A mapping value that writes one row for every record in a worker collection, such as worker.assignments. It fills an array field.

target oracle_fusion.worker {
  workRelationships = [
    {
      legalEmployerName = "Acme Logistics LLC"
      hireDate          = worker.hire_date

      assignments = each worker.assignments
            as assignment where assignment.status == "Active" {  # <-- One row for each active assignment
        assignmentNumber = assignment.source_id
        assignmentName   = assignment.job.name
        businessUnitName = assignment.business_unit.name
        primaryFlag      = assignment.is_primary
      }
    },
  ]
}

where is an optional filter. Join clauses with and to require all of them, or with or to require any of them.

Operator	Matches	Example
`==`, `!=`	Equals, or does not equal, the value.	`assignment.worker_type == "Contractor"`
`>`, `<`, `>=`, `<=`	Compares above or below the value.	`assignment.start_date >= "2026-01-01"`
`in`, `not in`	Is, or is not, one of a list.	`assignment.status in ["Active", "Leave"]`
`contains`	Contains the value.	`assignment.job.name contains "Engineer"`
`starts with`, `ends with`	Starts or ends with the value.	`assignment.job.code starts with "ENG"`

`unmanaged`

A mapping value that tells Klef to leave a field untouched. This is particularly useful on a grant such as groups, licenses, or channels. It tells Klef to retain what it had given in an earlier lifecycle stage.

stage active {
  target microsoft_entra.user {
    userPrincipalName = worker.business_email
    mailNickname      = worker.employee_id
    displayName       = "{{ worker.legal_name.given }} {{ worker.legal_name.family }}"
    accountEnabled    = true
    groups            = ["All Employees", "Engineering"]
  }
}

stage leave {
  target microsoft_entra.user {
    userPrincipalName = worker.business_email
    mailNickname      = worker.employee_id
    displayName       = "{{ worker.legal_name.given }} {{ worker.legal_name.family }}"
    accountEnabled    = false
    groups            = unmanaged      # <-- Keeps "All Employees" and "Engineering"
  }
}

`notify`

A block that sends a message when its stage’s changes apply, by email, Slack, Teams, or an HTTP request. Its name, in quotes after the channel, is unique across your policies. Klef records what it has sent under that name, so renaming a notification makes it a new one.

stage active {
  notify email "accounts_ready" {  # <-- Emails each worker's manager once they are set up
    send        = once
    title       = "Accounts ready"
    aggregation = per_worker
    subject     = "{{ worker.display_name }} is set up"
    body        = "They can sign in from their first day."
    to          = [manager(1)]
  }
}

Every channel takes these settings:

Setting	Required	Description
`send`	Yes	`once` sends once per worker, the first time they reach the stage, until they are terminated. `always` sends every time they enter the stage.
`title`		A name for the message. Teams shows it as a heading.
`aggregation`		`per_worker` sends one message for each worker, and is the default. `per_run` sends one message for the whole sync, and its text loops over `workers`.

Email

Setting	Required	Description
`subject`	Yes	The subject line.
`body`	Yes	The message.
`to`	Yes	Who receives it, as a list of recipients.
`cc`		Who is copied, as a list of recipients.
`bcc`		Who is copied without the others seeing, as a list of recipients.

An email can go to at most 50 addresses across to, cc, and bcc.

Each recipient is one of these:

Recipient	Who it is
`worker.business_email`
`manager(1)`	The worker’s direct manager. `manager(2)` is their manager’s manager, and so on up to `manager(10)`.
`"it@example.com"`	A fixed address.

to  = [worker.personal_email, manager(1)]
cc  = ["it@example.com"]
bcc = [member("0197c3f2-5b1a-7c3e-9d4f-2a6b8e1c0d3f")]

Slack

notify slack "new_starters" {
  send        = once
  title       = "New starters"
  aggregation = per_run
  text        = <<TEXT
    {% for worker in workers %}
    {{ worker.display_name }} starts as {{ worker.job.name }}.
    {% endfor %}
  TEXT
  webhook     = secret.people_channel
}

Setting	Required	Description
`text`	Yes	The message.
`webhook`, `webhooks`		The channel(s) incoming webhook URL.

Teams

notify teams "leaver" {
  send        = once
  title       = "Leaver"
  aggregation = per_worker
  text        = "{{ worker.display_name }} leaves on {{ worker.end_date }}."
  webhook     = secret.it_channel
}

Setting	Required	Description
`text`	Yes	The message.
`webhook`, `webhooks`		The channel(s) incoming webhook URL.

HTTP

notify http "joiner" {
  send        = once
  title       = "Joiner"
  aggregation = per_worker
  method      = post
  uri         = "https://hooks.example.com/joiner"
  body        = <<JSON
    { "email": "{{ worker.business_email }}", "start": "{{ worker.start_date }}" }
  JSON

  header "Authorization" = secret.hooks_token
}

Setting	Required	Description
`uri`	Yes	Where the request goes. Must be an absolute URL.
`method`		`get`, `post`, `put`, `patch`, or `delete`. Defaults to `post`.
`body`		What the request sends.
`header "<name>"`		A request header.

Passwords

If a target requires a password, Klef will set its first password. A notification can carry the link to that password as {{ <system>.sign_in_url }}. The password is only shown once and must be changed after first sign-in.

stage pre_start {
  target microsoft_entra.user {
    userPrincipalName = worker.business_email
    displayName       = worker.display_name
    accountEnabled    = true
  }

  notify email welcome {
    send    = once
    subject = "Your Microsoft account"
    body    = "Get your first sign-in here: {{ microsoft_entra.sign_in_url }}"  # <-- Links to the password
    to      = [worker.personal_email, manager(1)]
  }
}

Resources

Scripts, lookup tables, and secrets are global and can be shared between policies.

target microsoft_entra.user {
  mailNickname  = script.mail_alias # <-- Computed by a script
  usageLocation = lookup(table.usage_locations, worker.location.country)  # <-- Translated by a lookup table
}

notify slack "access_granted" {
  send        = once
  title       = "Access granted"
  aggregation = per_worker
  text        = <<TEXT
    {{ worker.display_name }} is set up.
    Their Microsoft and Slack accounts are ready to sign in to.
    First Microsoft sign-in: {{ microsoft_entra.sign_in_url }}
  TEXT

  webhooks = [secret.engineering_channel] # <-- Read from a secret
}

Resource	Written	What it does
Script	`script.<name>`	Computes a field’s value in JavaScript.
Lookup table	`lookup(table.<name>, <value>)`	Maps from one value to another another.
Secret	`secret.<name>`	Stores a credential.

An Example

policy "Employee lifecycle" {
  category = "Company-wide"
  applies  = everyone

  stage pre_start {
    target microsoft_entra.user {
      userPrincipalName = worker.business_email
      mailNickname      = worker.employee_id
      displayName       = "{{ worker.legal_name.given }} {{ worker.legal_name.family }}"
      givenName         = worker.legal_name.given
      surname           = worker.legal_name.family
      employeeId        = worker.employee_id
      jobTitle          = worker.job.name
      department        = worker.department.name
      usageLocation     = lookup(table.usage_locations, worker.location.country)
      manager           = worker.manager
      accountEnabled    = false
    }

    target oracle_fusion.worker {
      personNumber    = worker.employee_id
      firstName       = worker.legal_name.given
      lastName        = worker.legal_name.family
      legislationCode = "US"
      active          = false

      emails = [
        { emailType = "W1", emailAddress = worker.business_email, primaryFlag = true },
      ]

      workRelationships = [
        {
          legalEmployerName = "Acme Logistics LLC"
          workerType        = "E"
          hireDate          = worker.hire_date

          assignments = each worker.assignments
              as assignment where assignment.status in ["Pending", "Active"] {
            assignmentNumber = assignment.source_id
            assignmentName   = assignment.job.name
            actionCode       = "HIRE"
            businessUnitName = assignment.business_unit.name
            jobCode          = assignment.job.code
            locationCode     = assignment.location.code
            primaryFlag      = assignment.is_primary
            effectiveFrom    = assignment.start_date
          }
        },
      ]
    }

    notify email "new_starter" {
      send        = once
      title       = "New starter"
      aggregation = per_worker
      subject     = "{{ worker.display_name }} starts on {{ worker.start_date }}"
      body        = <<BODY
        {{ worker.display_name }} joins as {{ worker.job.name }}.
        Their Microsoft account is ready and switches on their first day.
        Hand them their first sign-in: {{ microsoft_entra.sign_in_url }}
      BODY
      to          = [manager(1)]
    }
  }

  stage active {
    target microsoft_entra.user {
      userPrincipalName = worker.business_email
      mailNickname      = worker.employee_id
      displayName       = "{{ worker.legal_name.given }} {{ worker.legal_name.family }}"
      givenName         = worker.legal_name.given
      surname           = worker.legal_name.family
      employeeId        = worker.employee_id
      jobTitle          = worker.job.name
      department        = worker.department.name
      usageLocation     = lookup(table.usage_locations, worker.location.country)
      manager           = worker.manager
      accountEnabled    = true
      licenses          = ["SPE_E3"]
      groups            = ["All Employees"]
    }

    target slack.user {
      userName    = worker.business_email
      displayName = worker.display_name
      title       = worker.job.name
      active      = true
      channels    = ["general", "announcements"]
    }

    target oracle_fusion.worker {
      personNumber    = worker.employee_id
      firstName       = worker.legal_name.given
      lastName        = worker.legal_name.family
      legislationCode = "US"
      active          = true

      emails = [
        { emailType = "W1", emailAddress = microsoft_entra.mail, primaryFlag = true },
      ]

      workRelationships = [
        {
          legalEmployerName = "Acme Logistics LLC"
          workerType        = "E"
          hireDate          = worker.hire_date

          assignments = each worker.assignments
              as assignment where assignment.status == "Active" {
            assignmentNumber = assignment.source_id
            assignmentName   = assignment.job.name
            businessUnitName = assignment.business_unit.name
            jobCode          = assignment.job.code
            locationCode     = assignment.location.code
            primaryFlag      = assignment.is_primary
            effectiveFrom    = assignment.start_date
          }
        },
      ]

      roles = ["Employee"]
    }

    notify slack "new_starters" {
      send        = once
      title       = "New starters"
      aggregation = per_run
      text        = <<TEXT
        {% for worker in workers %}
        Welcome {{ worker.display_name }}, who joins as {{ worker.job.name }}.
        {% endfor %}
      TEXT
      webhook     = secret.announcements_channel
    }
  }

  stage departing {
    notify email "leaver_handover" {
      send        = once
      title       = "Leaver"
      aggregation = per_worker
      subject     = "{{ worker.display_name }} leaves on {{ worker.end_date }}"
      body        = "Their access closes at the end of their last day. Please plan the handover."
      to          = [manager(1)]
      cc          = ["it@example.com"]
    }
  }

  stage terminated {
    target microsoft_entra.user {
      userPrincipalName = worker.business_email
      mailNickname      = worker.employee_id
      displayName       = "{{ worker.legal_name.given }} {{ worker.legal_name.family }}"
      accountEnabled    = false
      licenses          = []
      groups            = []
    }

    target slack.user {
      userName = worker.business_email
      active   = false
    }

    target oracle_fusion.worker {
      personNumber    = worker.employee_id
      firstName       = worker.legal_name.given
      lastName        = worker.legal_name.family
      legislationCode = "US"
      active          = false
      roles           = []
    }

    notify http "leaver" {
      send        = once
      title       = "Leaver"
      aggregation = per_worker
      method      = post
      uri         = "https://hooks.example.com/leavers"
      body        = <<JSON
        { "employeeId": "{{ worker.employee_id }}", "lastDay": "{{ worker.end_date }}" }
      JSON

      header "Authorization" = secret.hooks_token
    }
  }
}

Basics

Connectors

Administration

Overview

Anatomy of a Policy

KPL Reference

`applies`

`stage`

Omitting a Stage

`stage released`

`target`

Mappings

Field Types

Templates

`each`

`unmanaged`

`notify`

Email

Slack

Teams

HTTP

Passwords

Resources

An Example

​Overview

​Anatomy of a Policy

​KPL Reference

​applies

​stage

​Omitting a Stage

​stage released

​target

​Mappings

​Field Types

​Templates

​each

​unmanaged

​notify

​Email

​Slack

​Teams

​HTTP

​Passwords

​Resources

​An Example

Overview

Anatomy of a Policy

KPL Reference

`applies`

`stage`

Omitting a Stage

`stage released`

`target`

Mappings

Field Types

Templates

`each`

`unmanaged`

`notify`

Email

Slack

Teams

HTTP

Passwords

Resources

An Example