# Create 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
/create-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
/create-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"
```

## Installation

### Step 1: Copy Skill Files

Copy this entire directory to your Copilot skills directory:

```bash
cp -r . ~/.copilot/skills/create-insights-user/
```

### Step 2: Install AWS Wrapper Script

The skill requires the `aws-with-awsume` wrapper script to handle AWS credentials:

```bash
mkdir -p ~/.local/bin
cp aws-with-awsume ~/.local/bin/
chmod +x ~/.local/bin/aws-with-awsume
```

Make sure `~/.local/bin` is in your PATH. Add this to your `~/.zshrc` or `~/.bashrc` if needed:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

## Prerequisites

1. **AWS Wrapper Script**: Must be installed at `~/.local/bin/aws-with-awsume` (see Installation Step 2 above)

   The wrapper script handles:
   - Sourcing awsume credentials automatically
   - 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 in your Copilot settings:
   - `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 for Claude
- `aws-with-awsume` - AWS CLI wrapper script
- `CHANGELOG.md` - Version history
- `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. While update operations exist, retrieving the current segment structure to safely merge new Identity IDs is not supported through available API endpoints.

   **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

## Detailed Documentation

For comprehensive documentation including the manual process and step-by-step instructions, see:

**[Creating Insights Users](https://www.notion.so/Technical-documentation-and-architecture-0e8ad5c7ce734594955fd675d144b704)** (Notion)

## Related Documentation

- [Altafonte User Creation](https://www.notion.so/Altafonte-User-Creation-19a97177520f80beabbbc89eab7b7263)