# Manage Insights User Skill

Automates the creation of Insights users with artist-level permissions via the Altafonte user creation step function. Supports both single and bulk user creation.

## Quick Start

### Single User
```bash
/manage-insights-user \
  --users '[{"first_name": "Dylan", "last_name": "Bourne", "email": "dylan@bournecreatives.com"}]' \
  --artist_urls "https://insights.sonymusic.com/artist/f804f611-da3c-4b60-aa6e-ddfe39e6aeba/"
```

### Multiple Users
```bash
/manage-insights-user \
  --users '[{"first_name": "Andy", "last_name": "Varley", "email": "av@insanity.com"}, {"first_name": "Alice", "last_name": "Beal", "email": "ab@insanity.com"}]' \
  --artist_urls "f804f611-da3c-4b60-aa6e-ddfe39e6aeba,a1b2c3d4-e5f6-7890-1234-567890abcdef" \
  --output_name "Insights-Insanity-Records-2026-04-16"
```

## Prerequisites

1. **AWS Wrapper Script**: The `aws-with-awsume` wrapper script must be installed at `~/.local/bin/aws-with-awsume`. This wrapper automatically sources awsume credentials for AWS CLI commands.

   The wrapper script is created during skill setup and handles:
   - Sourcing awsume credentials
   - Suppressing terminal escape sequences
   - Running AWS CLI commands with proper credentials

2. **AWS Credentials**: You must have `awsume` configured with a `prod` profile. The first time you run the skill, you may need to authenticate:
   ```bash
   awsume prod
   # Enter MFA code when prompted
   ```

3. **MCP Servers**: The following MCP servers must be configured:
   - `neo4j-prod` - For querying Neo4j production (required)
   - `github` - For GitHub operations (optional)

## Files

- `skill.json` - Skill manifest with parameter definitions
- `skill.md` - Detailed implementation guide
- `handler.py` - Python handler (reference implementation)
- `README.md` - This file

## How It Works

The skill follows these steps:

1. Parse users JSON and extract GlobalParticipant IDs from artist URLs
2. Query Neo4j prod for all LabelParticipant UUIDs (once per artist)
3. Generate two CSV files with all users:
   - No-email version: One row per user per LabelParticipant
   - Send-email version: One row per user
4. Upload no-email CSV to S3 → triggers step function
5. Monitor step function execution
6. Upload send-email CSV to S3 → sends email invites
7. Monitor second step function execution
8. Query Neo4j for Identity IDs for all users
9. Generate Harness segment CSV with all Identity IDs

## Output Files

All files are saved to `~/Downloads/`:

- `<output_name>.csv` - Full user permissions (no email)
- `<output_name>-Send-Email.csv` - Email invite triggers
- `<output_name>-Harness.csv` - Identity IDs for Harness segment

## Parameters

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `users` | Yes | JSON | Array of user objects with `first_name`, `last_name`, `email` |
| `artist_urls` | Yes | String | Comma-separated artist URLs or GlobalParticipant IDs |
| `output_name` | No | String | Base name for output files (auto-generated if omitted) |
| `skip_email` | No | Boolean | Skip sending email invites (default: false) |

## Troubleshooting

### AWS Credentials Expired
```bash
awsume prod
# Enter MFA code when prompted
```

### AWS Wrapper Script Not Found
Verify the wrapper script exists and is executable:
```bash
ls -l ~/.local/bin/aws-with-awsume
chmod +x ~/.local/bin/aws-with-awsume
```

### No LabelParticipants Found
Verify the GlobalParticipant ID is correct by checking the Insights URL.

### Step Function Failed
Check the AWS console for detailed logs:
```
https://us-east-1.console.aws.amazon.com/states/home?region=us-east-1#/statemachines
```

### Neo4j Query Failed
Verify the `neo4j-prod` MCP server is configured and accessible.

## Known Limitations

1. **Harness Upload**: The Harness segment CSV must be uploaded manually via the Harness UI. The skill generates the CSV and provides the direct link to the segment definition page for upload.

   **Why manual?** The Harness MCP API does not currently support safe programmatic segment updates. Re-tested 2026-06-09: `list` on `fme_rule_based_segment_definition` still returns `[]`, `get` is not supported for this resource type, and workspace-level `list` on `fme_rule_based_segment` also returns `[]`. The `update` operation exists and theoretically supports adding individual users via a `rules` whitelist, but it **replaces the entire definition** — there is no PATCH/append. Since the current state cannot be read, any write would wipe all existing segment members. The `change_request` execute action has the same limitation (requires passing the full segment object).

   **Upload location:** [Sony_Users_Bulk_Import segment](https://app.harness.io/ng/account/cej_iP27SSSgxFiM6TOjAw/all/fme/orgs/TheOrchardFME/projects/Default/org/5b4b5c30-21c9-11ea-a4e7-0a9b522eabbd/ws/5b5212f0-21c9-11ea-a4e7-0a9b522eabbd/segments/a4bc5637-86ee-11ef-bacb-627fbfefd41c/env/5b53e7b0-21c9-11ea-a4e7-0a9b522eabbd/definition)

   This segment is used by the `show_sme_data` feature flag to control access to Insights SME features.

2. **Production Only**: This skill only creates users in production. QA user creation is not supported (and typically not needed).

## Recent Improvements

### v1.1.0 (2026-05-06)
- **Improved documentation**: Enhanced Harness upload instructions with direct segment URL
- **API investigation**: Researched Harness MCP API capabilities and documented limitations
- **Cleaner codebase**: Removed unused handler.py reference implementation

### v1.0.0 (2026-04-16)
- **Initial release** with full automation from Neo4j query to Harness CSV generation
- **AWS wrapper script**: Created `aws-with-awsume` to handle credential sourcing automatically
- **Bulk user support**: Process multiple users in a single invocation
- **Step function monitoring**: Automated monitoring of both user creation and email sending workflows

### Known Issues Fixed
- **Terminal escape sequences**: Updated wrapper script to suppress terminal control sequences that cluttered output
- **Monitoring reliability**: Improved status checking to properly detect SUCCEEDED/FAILED states

### Future Enhancements
- **Harness API integration**: If Harness improves their API to support safe segment retrieval and updates, or provides a CSV upload API endpoint, this manual step could be automated
- **Notifications**: Add Slack/email notifications when user provisioning completes
- **Audit logging**: Track all user creation requests in a central location

## Related Documentation

- [Altafonte User Creation](https://www.notion.so/Altafonte-User-Creation-19a97177520f80beabbbc89eab7b7263)
- [Neo4j Participant Debugger Workflow](/.claude-workflows/neo4j-participant-debugger.md)