IT Ops Onboarding

# IT Ops — New-hire onboarding
# Triggered on a "Create User" form submission. Provisions the new hire's identity
# and access, then branches on whether they are a manager to finish their Slack setup,
# and records the whole run to an audit log.

parameter("fullName",      type=string) # New hire's full name
parameter("email",         type=string) # New hire's work email / sign-in address
parameter("department",    type=string) # Department to place the user in (e.g. "Revenue", "Engineering")
parameter("jobTitle",      type=string) # Job title for the directory profile
parameter("isManager",     type=bool)   # Whether the new hire is a people manager
parameter("teamChannelId", type=string) # Slack channel managers are invited to

require mcp Microsoft_Entra_ID
require mcp Jira
require mcp Slack
require mcp Gmail
require collection postgres

# ── 1. Provision the identity in Microsoft Entra ID ──────────────────────────
session("provision_identity") {
    use mcp Microsoft_Entra_ID

    + Create a Microsoft Entra ID account for {{ .params.fullName }} ({{ .params.email }}).
      Set the job title to "{{ .params.jobTitle }}" and add the user to the standard
      access groups for the {{ .params.department }} department.

    - Report the identity exactly as returned by Entra ID.
    schema {
        userPrincipalName: string   # the created UPN / sign-in address
        objectId:          string   # Entra object ID of the new account
        assignedGroups:    string[] # security / access groups the user was added to
        status:            string   # created | already_existed | error
    }
}

# ── 2. Open the access & equipment tickets in Jira ───────────────────────────
session("provision_access", after="provision_identity") {
    use mcp Jira
    context "New identity:\n{{ json .context.provision_identity }}"

    + Create the standard onboarding Jira issues for a new {{ .params.department }} hire:
      one for laptop / equipment provisioning and one for department tool access.
      Reference the Entra UPN from the identity above in each issue description.

    - Report every Jira issue that was created.
    schema {
        tickets: {
            key:     string # Jira issue key, e.g. IT-1423
            summary: string # issue summary
            url:     string # link to the issue
        }[]
    }
}

# ── 3a. Manager branch — add them to the team channel ────────────────────────
# Runs only when the new hire is a manager.
session("manager_setup",
        after="provision_access",
        expect="params.isManager") {
    use mcp Slack

    + Invite {{ .params.email }} to the Slack channel {{ .params.teamChannelId }}
      and post a short message introducing them as a new manager in {{ .params.department }}.

    - Report the channel actions taken.
    schema {
        channelId:    string # channel the manager was added to
        invited:      bool   # whether the invite succeeded
        announcement: string # the welcome message that was posted
    }
}

# ── 3b. Individual-contributor branch — update their profile ─────────────────
# Runs only when the new hire is NOT a manager.
session("contributor_setup",
        after="provision_access",
        expect="!params.isManager") {
    use mcp Slack

    + Update {{ .params.email }}'s Slack profile: set their title to
      "{{ .params.jobTitle }}" and their department field to "{{ .params.department }}".

    - Report the profile fields that were updated.
    schema {
        profileUpdated: bool     # whether the profile update succeeded
        fields:         string[] # profile fields that were set
    }
}

# ── 4. Record the onboarding run to the audit log ────────────────────────────
# after both branches: whichever branch was skipped resolves to null, and this
# session reads whichever one actually ran.
session("onboarding_record",
        after="manager_setup",
        after="contributor_setup") {
    use collection postgres
    context true

    + Insert one row into the onboarding_log table capturing this run: the UPN,
      department, whether the hire is a manager, the Jira issue keys, and the Slack
      action taken. Confirm the row was written.

    - Summarize the onboarding outcome in two sentences for the IT Ops record.
    schema {
        upn:       string # provisioned user principal name
        path:      string # "manager" | "contributor" — which branch ran
        summary:   string # 2-sentence human-readable outcome
        persisted: bool   # whether the audit row was written
    }
}

# ── 5. Send the tailored welcome email via Gmail ─────────────────────────────
# The capstone: `context true` pulls every prior session's output — identity,
# tickets, Slack setup, and the audit summary — plus params/vars, so the email
# is generated from the real run, not a static template.
session("welcome_email", after="onboarding_record") {
    use mcp Gmail
    context true

    + Using everything provisioned above — the Entra identity, the Jira tickets,
      the Slack setup, and the onboarding summary — write a warm, concrete welcome
      email for {{ .params.fullName }} and send it to {{ .params.email }}. Include:
        - their sign-in address (the Entra userPrincipalName),
        - the equipment and access tickets to expect, referenced by their Jira keys,
        - the Slack channel they were added to, or a nudge to finish their profile,
        - first-day next steps tailored to a {{ .params.jobTitle }} in {{ .params.department }}.

    - Report the email that was sent.
    schema {
        to:           string   # recipient address
        subject:      string   # subject line used
        body:         string   # full body of the email that was sent
        instructions: string[] # the onboarding steps included, one per item
        sent:         bool     # whether Gmail confirmed the send
    }
}