omni-user-manager 0.1.2

Omni User Manager - Sync users and groups with Omni

Omni User Manager

A tool for synchronizing users, groups, and user attributes with Omni.

Installation

pip install omni-user-manager

Configuration

Create a .env file with your Omni API credentials:

OMNI_BASE_URL=your_omni_base_url
OMNI_API_KEY=your_omni_api_key

Usage

You can use either omni-um or omni-user-manager as the CLI command. All examples below use omni-um for brevity, but both commands are fully supported and interchangeable.

The package uses a subcommand-based CLI structure for all major operations. Example usage:

Common Commands

Command	Description	Example
sync	Synchronize users, groups, and attributes	omni-um sync --source csv --users data/users.csv --groups data/groups.csv
get-user-by-id [USER_ID]	Get a user by ID (or all users if no ID)	omni-um get-user-by-id
search-users --query QUERY	Search users by email address (userName attribute, must be full email address)	omni-um search-users --query "[e-mail]"
get-user-attributes USER_ID	Get a user's custom attributes by user ID	omni-um get-user-attributes 123
get-group-by-id [GROUP_ID]	Get a group by ID (or all groups if no ID)	omni-um get-group-by-id
search-groups --query QUERY	Search groups by displayName (must be full group name, exact match)	omni-um search-groups --query "Admins"
get-group-members GROUP_ID	Get all members of a group by group ID	omni-um get-group-members 456
bulk-create-users USERS_FILE	Create multiple users from a file (skips users that already exist)	omni-um bulk-create-users data/users.json
bulk-update-users USERS_FILE	Update multiple users from a file	omni-um bulk-update-users data/users.json
delete-user USER_ID [--yes]	Delete a user by ID (with confirmation prompt unless --yes is provided)	omni-um delete-user fb46d9ee-95e7-4256-abf0-832af6c27f6b
bulk-delete-users USERS_FILE [--yes]	Delete multiple users by IDs from a file (CSV or JSON, with confirmation prompt unless --yes is provided)	omni-um bulk-delete-users all_users.csv
export-users-json	Export all users as JSON	omni-um export-users-json
export-users-csv OUTPUT_FILE	Export all users as CSV (id, userName, displayName, active, email)	omni-um export-users-csv all_users.csv
export-groups-json OUTPUT_FILE	Export all groups as JSON	omni-um export-groups-json all_groups.json

Migration Note: The CLI previously used top-level arguments (e.g., --get-user-by-id, --source, etc.). Now, you must specify a subcommand as the first argument. See the table below for how to update your usage:

Old Command Example	New Command Example
omni-user-manager --get-user-by-id	omni-user-manager get-user-by-id
omni-user-manager --get-user-by-id USER_ID	omni-user-manager get-user-by-id USER_ID
omni-user-manager --source json --users file.json	omni-user-manager sync --source json --users file.json
omni-user-manager --source csv ...	omni-user-manager sync --source csv ...

All other operations (search, export, bulk, etc.) are now subcommands as well. Run omni-user-manager --help for a full list.

Sync Modes

The tool supports three sync modes:

1. Full Sync (default): Syncs both group memberships and user attributes
2. Groups-only: Only syncs group memberships
3. Attributes-only: Only syncs user attributes

Using JSON Source

Use this when your user and group data is in a single JSON file following the SCIM 2.0 format:

# Full sync (groups and attributes)
omni-um sync --source json --users data/users.json

# Groups-only sync
omni-um sync --source json --users data/users.json --mode groups

# Attributes-only sync
omni-um sync --source json --users data/users.json --mode attributes

Example JSON format (users.json):

{
  "Resources": [
    {
      "active": true,
      "displayName": "User Name",
      "emails": [
        {
          "primary": true,
          "value": "[e-mail]"
        }
      ],
      "groups": [
        {
          "display": "group-name",
          "value": "group-id"
        }
      ],
      "id": "user-id",
      "userName": "[e-mail]",
      "urn:omni:params:1.0:UserAttribute": {
        "gcp_project": ["project1", "project2"],
        "axel_user": "true",
        "omni_user_timezone": "America/New_York"
      }
    }
  ]
}

Using CSV Source

Use this when your user data and group memberships are in separate CSV files:

# Full sync (groups and attributes)
omni-um sync --source csv --users data/users.csv --groups data/groups.csv

# Groups-only sync
omni-um sync --source csv --users data/users.csv --groups data/groups.csv --mode groups

# Attributes-only sync
omni-um sync --source csv --users data/users.csv --groups data/groups.csv --mode attributes

Example CSV formats:

users.csv:

id,userName,displayName,active,emails,userAttributes
user-id,[e-mail],User Name,true,{"primary": true, "value": "[e-mail]"},{"gcp_project": ["project1", "project2"], "axel_user": "true", "omni_user_timezone": "America/New_York"}

groups.csv:

id,name,members
group-id,group-name,["user-id-1", "user-id-2"]

Features

• Synchronize users, their group memberships, and attributes with Omni
• Support for both JSON and CSV data sources
• Three sync modes: full, groups-only, and attributes-only
• Detailed progress and error reporting
• Only updates when changes are needed
• Handles both adding and removing users from groups
• Updates user attributes using SCIM PUT operations
• Handles null values in user attributes appropriately
• Supports both single-value and multi-value attributes

Development

To install in development mode:

git clone [e-mail]:Hawkfry-Group/omni-user-manager.git
cd omni-user-manager
pip install -e .

Notes

• User attributes are updated using SCIM PUT operations
• Null values in user attributes are handled by removing the attribute
• Multi-value attributes should be provided as arrays
• Single-value attributes should be provided as strings
• The tool will only update attributes that have changed from their current values in Omni

Important: Omni assigns its own unique user IDs when users are created. Any update or delete operation (such as bulk-update-users) must use the Omni-assigned IDs, not placeholder or pre-specified IDs from your input files. To obtain the correct IDs, use the search-users or export-users-json command after creation and use those IDs for subsequent operations.

Note: DELETE operations return 204 No Content on success. The CLI now handles this correctly and does not treat it as an error.

Note: The search-users command requires the full email address (userName) for an exact match. Partial matches are not supported by the Omni API.

Note: The get-user-attributes command returns the user's custom attributes (if any) as a JSON object. If the user has no custom attributes, an empty object is returned.

Note: The get-group-by-id command returns a group by ID, or all groups if no ID is provided.

Note: The search-groups command searches by group displayName and requires the full group name for an exact match.

Note: The get-group-members command returns all members of a group by group ID as a JSON array.

Note: The bulk-create-users command skips users that already exist (HTTP 409), reporting them in a 'skipped' list. The summary at the end shows succeeded, failed, and skipped counts.

Note: The delete-user and bulk-delete-users commands require confirmation before deleting users, unless the --yes flag is provided. This is to prevent accidental deletion. The CLI will prompt you to type 'yes' to confirm the operation.

Note: The export-groups-json command exports all groups as a JSON array of group objects, each with fields such as id, displayName, and members.

Note: User and group history (audit) is not available via this CLI. To view audit history, please refer to the Omni platform's audit logs or logging dashboard.