metaserver-web-python/README.md

# Meta File Server Query Application

A Python Flask web application that replicates the Make.com workflow for querying the Oliver metafile server to retrieve job information based on deliverable numbers.

## Features

- **Two-stage workflow**: First fetches XML to extract client information, then retrieves JSON data
- **Secure authentication**: Uses MD5 checksum authentication matching the original blueprint
- **Clean web interface**: Simple HTML form with responsive design
- **Error handling**: Comprehensive error handling for network issues, SSL problems, and parsing errors
- **Portable**: Self-contained with virtual environment for easy deployment

## Quick Start

### Option 1: Use the startup script
```bash
./start.sh
```

### Option 2: Manual setup
```bash
# Create and activate virtual environment
python3 -m venv meta-server-venv
source meta-server-venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python run.py
```

Then open your browser to: `http://localhost:5000`

## Usage

1. Enter a job/deliverable number in the web form
2. Click "Query Job Information"
3. The application will:
   - Fetch the XML file from the metafile server
   - Extract the client name from the jobpath
   - Retrieve the corresponding JSON data using the client information
   - Display the results in a formatted view

## API Endpoints

- `GET /` - Main web interface
- `GET /api/job/<job_number>` - Retrieve job information as JSON
- `GET /api/health` - Health check endpoint

## Example API Response

```json
{
  "success": true,
  "job_number": "6046034",
  "client": "ADIDAS",
  "data": {
    "JobSpecification": {
      // ... job data ...
    }
  }
}
```

## Configuration

The application uses these default settings:

- **Metafile Server**: `https://metafile.oliver.solutions/getFile`
- **API Key**: `$14W0TF~8FL` (from original blueprint)
- **Port**: 5000
- **SSL Verification**: Disabled (due to certificate issues)

## Project Structure

```
META-FILE-SERVER-QUERY/
├── app.py                  # Main Flask application
├── run.py                  # Application runner
├── start.sh               # Startup script
├── requirements.txt       # Python dependencies
├── templates/
│   └── index.html        # Web interface
├── static/               # Static assets (empty)
└── meta-server-venv/     # Python virtual environment
```

## Technical Details

### Workflow Process

1. **XML Retrieval**: 
   - Constructs URL: `{base_url}?root=XML&path={job_number}.xml&keyid=1&cs={checksum}`
   - Checksum: `MD5(api_key + "XML/" + filename)`

2. **Client Extraction**:
   - Parses XML for `Set-Property` with `Property="jobpath"`
   - Extracts client name using regex: `([A-Z][A-Z0-9_]*?)(?=/CAMPAIGNS/)`

3. **JSON Retrieval**:
   - Constructs URL: `{base_url}?root=JSON_STORE&sub={client}&path={job_number}.json&keyid=1&cs={checksum}`
   - Checksum: `MD5(api_key + "JSON_STORE/" + client + "/" + filename)`

### Error Handling

- SSL certificate verification disabled for metafile.oliver.solutions
- Network timeout protection (30 seconds)
- XML parsing error handling
- JSON parsing error handling
- HTTP status code validation

## Moving to Production

To deploy this application:

1. **Copy the entire directory** to your target server
2. **Install Python 3.7+** on the target system
3. **Run the startup script**: `./start.sh`
4. **For production**: Consider using a WSGI server like Gunicorn:
   ```bash
   pip install gunicorn
   gunicorn -w 4 -b 0.0.0.0:5000 app:app
   ```

## Troubleshooting

### SSL Certificate Issues
The application automatically handles SSL certificate verification issues by disabling verification. This is necessary because the metafile server has certificate problems.

### Connection Timeouts
The application has a 30-second timeout for requests. If you experience frequent timeouts, check your network connection to the metafile server.

### Missing Job Data
If a job number returns an error, verify:
1. The job number exists in the XML system
2. The corresponding JSON file exists in the JSON_STORE
3. The client name extraction is working correctly

## Development

To modify or extend the application:

1. Activate the virtual environment: `source meta-server-venv/bin/activate`
2. Make your changes to `app.py` or `templates/index.html`
3. Test your changes: `python run.py`
4. The server will automatically reload in debug mode

---

*Converted from Make.com blueprint: "AI COMPANION Metafile Server Grabber"*