id: servicenow_iam
name: ServiceNow IAM
version: 1.0.0
description: "ServiceNow identity lifecycle (sys_user table) — look up, create and update employee accounts, enable/disable accounts (with lock-out clearing), and discover the available user fields for mapping. Basic or OAuth 2.0 (password grant) authentication."
changelog: "1.0.0 — Initial release: get/create/update user, enable/disable user, user field discovery via sys_dictionary."
category: identity

# Per-instance configuration. The base URL is the instance root, e.g.
# https://company.service-now.com (scripts append /api/now).
config_schema:
  properties:
    url:
      type: string
      description: "ServiceNow instance URL, e.g. https://company.service-now.com"
    auth_type:
      type: string
      description: "Authentication method: basic (username + password) or oauth (OAuth 2.0 password grant via /oauth_token.do — also requires client_id/client_secret)"
      default: basic
    username:
      type: string
      description: "ServiceNow username (needs read/write ACLs on the sys_user table)"
    password:
      type: string
      description: "ServiceNow password"
      x-soar-sensitive: true
    client_id:
      type: string
      description: "OAuth client ID (oauth auth_type only — from an Application Registry entry)"
    client_secret:
      type: string
      description: "OAuth client secret (oauth auth_type only)"
      x-soar-sensitive: true
    api_version:
      type: string
      description: "Optional REST API version segment (e.g. v2). Leave empty to use the unversioned endpoints."
  required:
    - url
    - username
    - password

# Documented for reference; the bundled scripts build the headers themselves.
# Basic:  Authorization: Basic base64(username:password)
# OAuth:  POST /oauth_token.do (grant_type=password) then Authorization: Bearer <access_token>
auth:
  - id: basic
    type: basic
    username_field: username
    password_field: password

# User resolution: every account command accepts user_id (sys_id), user_name or
# email — the first one provided wins, in that order.
commands:
  - id: get_user
    name: servicenow-iam-get-user
    description: "Look up a user account by sys_id, username or email."
    risk: read
    inputs_schema:
      properties:
        user_id: { type: string, description: "User sys_id" }
        user_name: { type: string, description: "Username (user_name field)" }
        email: { type: string, description: "Email address" }
        fields: { type: string, description: "Comma-separated fields to return (sys_id always included)" }
      required: []
    outputs_schema: { properties: {} }
  - id: create_user
    name: servicenow-iam-create-user
    description: "Create a user account. Common fields have named inputs; anything else goes through fields/custom_fields."
    inputs_schema:
      properties:
        user_name: { type: string, description: "Username (user_name field)" }
        email: { type: string, description: "Email address" }
        first_name: { type: string, description: "First name" }
        last_name: { type: string, description: "Last name" }
        title: { type: string, description: "Job title" }
        department: { type: string, description: "Department (sys_id or exact name)" }
        manager: { type: string, description: "Manager (sys_id or exact user name)" }
        phone: { type: string, description: "Business phone" }
        mobile_phone: { type: string, description: "Mobile phone" }
        active: { type: boolean, description: "Account active state (default true)" }
        fields: { type: string, description: "Additional sys_user fields as name=value;name2=value2" }
        custom_fields: { type: string, description: "Custom fields as name=value;name2=value2 (u_ prefix added when missing)" }
      required: [user_name]
    outputs_schema: { properties: {} }
  - id: update_user
    name: servicenow-iam-update-user
    description: "Update a user account resolved by sys_id, username or email."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User sys_id" }
        user_name: { type: string, description: "Username used to resolve the account when user_id is empty" }
        email: { type: string, description: "Email used to resolve the account when user_id and user_name are empty" }
        first_name: { type: string, description: "First name" }
        last_name: { type: string, description: "Last name" }
        title: { type: string, description: "Job title" }
        department: { type: string, description: "Department (sys_id or exact name)" }
        manager: { type: string, description: "Manager (sys_id or exact user name)" }
        phone: { type: string, description: "Business phone" }
        mobile_phone: { type: string, description: "Mobile phone" }
        fields: { type: string, description: "Additional sys_user fields as name=value;name2=value2" }
        custom_fields: { type: string, description: "Custom fields as name=value;name2=value2 (u_ prefix added when missing)" }
      required: []
    outputs_schema: { properties: {} }
  - id: enable_user
    name: servicenow-iam-enable-user
    description: "Enable a user account (sets active=true and clears locked_out), resolved by sys_id, username or email."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User sys_id" }
        user_name: { type: string, description: "Username used to resolve the account when user_id is empty" }
        email: { type: string, description: "Email used to resolve the account when user_id and user_name are empty" }
      required: []
    outputs_schema: { properties: {} }
  - id: disable_user
    name: servicenow-iam-disable-user
    description: "Disable a user account (sets active=false), resolved by sys_id, username or email."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User sys_id" }
        user_name: { type: string, description: "Username used to resolve the account when user_id is empty" }
        email: { type: string, description: "Email used to resolve the account when user_id and user_name are empty" }
      required: []
    outputs_schema: { properties: {} }
  - id: list_user_fields
    name: servicenow-iam-list-user-fields
    description: "List the sys_user table fields (name and label) from the sys_dictionary — useful to build field mappings."
    risk: read
    inputs_schema:
      properties:
        limit: { type: number, description: "Maximum dictionary entries (default 500)" }
      required: []
    outputs_schema: { properties: {} }

  - id: test_connection
    name: servicenow-iam-test-connection
    description: "Verify connectivity and credentials (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }