Job Management

Overview

The Job Management API provides endpoints for managing asynchronous batch processing and report generation jobs. Control long-running tasks such as user imports, bulk updates, and report generation.

Endpoint List

Method	Endpoint	Description
GET	/api/admin/jobs	List jobs
GET	/api/admin/jobs/:id	Get job details
POST	/api/admin/jobs/:id/cancel	Cancel job
POST	/api/admin/jobs/users/import	Start user import
POST	/api/admin/jobs/users/export	Start user export
POST	/api/admin/jobs/users/bulk-update	Start bulk user update
POST	/api/admin/jobs/reports/generate	Start report generation
GET	/api/admin/jobs/:id/download	Download job result

---

List Jobs

Retrieve a list of jobs.

Endpoint

GET /api/admin/jobs

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 20, max: 100)
cursor	string	-	Pagination cursor
type	string	-	Filter by job type
status	string	-	Filter by status

Job Status

Status	Description
pending	Pending
running	Running
completed	Completed
failed	Failed
cancelled	Cancelled

Request Example

curl -X GET "https://{tenant-domain}/api/admin/jobs?status=running" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "job_abc123",
      "type": "user_import",
      "status": "running",
      "progress": 45,
      "total_items": 1000,
      "processed_items": 450,
      "created_at": 1706140800,
      "started_at": 1706140805
    },
    {
      "id": "job_def456",
      "type": "report_generation",
      "status": "completed",
      "progress": 100,
      "created_at": 1706054400,
      "started_at": 1706054405,
      "completed_at": 1706054800
    }
  ],
  "total": 15,
  "cursor": "eyJpZCI6ImpvYl9kZWY0NTYifQ=="
}

---

Get Job Details

Retrieve detailed information for a specified job.

Endpoint

GET /api/admin/jobs/:id

Path Parameters

Parameter	Type	Required	Description
id	string	✓	Job ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/jobs/job_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "job_abc123",
  "type": "user_import",
  "status": "running",
  "progress": 45,
  "total_items": 1000,
  "processed_items": 450,
  "success_count": 440,
  "error_count": 10,
  "errors": [
    {
      "row": 15,
      "field": "email",
      "error": "invalid_email",
      "message": "Invalid email format",
      "value": "invalid-email"
    },
    {
      "row": 23,
      "field": "email",
      "error": "email_already_exists",
      "message": "This email address is already in use",
      "value": "[email protected]"
    }
  ],
  "parameters": {
    "filename": "users_2024.csv",
    "update_existing": false,
    "send_welcome_email": true
  },
  "created_by": "usr_admin001",
  "created_at": 1706140800,
  "started_at": 1706140805,
  "estimated_completion": 1706141200
}

---

Cancel Job

Cancel a running job.

Endpoint

POST /api/admin/jobs/:id/cancel

Path Parameters

Parameter	Type	Required	Description
id	string	✓	Job ID

Request Example

curl -X POST "https://{tenant-domain}/api/admin/jobs/job_abc123/cancel" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "job_abc123",
  "status": "cancelled",
  "cancelled_at": 1706141000,
  "processed_items": 450
}

---

Start User Import

Bulk import users from a CSV file.

Endpoint

POST /api/admin/jobs/users/import

Request Body

Field	Type	Required	Description
file_url	string	✓	Import file URL
file_format	string	-	File format (csv, json, default: csv)
update_existing	boolean	-	Whether to update existing users
send_welcome_email	boolean	-	Whether to send welcome email
field_mapping	object	-	Field mapping

Request Example

curl -X POST "https://{tenant-domain}/api/admin/jobs/users/import" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://storage.example.com/imports/users_2024.csv",
    "file_format": "csv",
    "update_existing": false,
    "send_welcome_email": true,
    "field_mapping": {
      "Email Address": "email",
      "Full Name": "name",
      "Department": "metadata.department"
    }
  }'

Response Example

{
  "job_id": "job_import_xyz789",
  "status": "pending",
  "created_at": 1706140800
}

CSV Format Example

email,name,phone,department
[email protected],John Doe,090-1234-5678,Engineering
[email protected],Jane Smith,090-8765-4321,Sales

---

Start User Export

Export user data.

Endpoint

POST /api/admin/jobs/users/export

Request Body

Field	Type	Required	Description
format	string	✓	Output format (csv, json)
fields	string[]	-	Fields to export
filters	object	-	Filter conditions
include_pii	boolean	-	Whether to include PII (default: false)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/jobs/users/export" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "fields": ["id", "email", "name", "created_at", "last_login_at"],
    "filters": {
      "status": "active",
      "created_after": "2024-01-01"
    },
    "include_pii": true
  }'

Response Example

{
  "job_id": "job_export_abc123",
  "status": "pending",
  "created_at": 1706140800
}

---

Start Bulk User Update

Bulk update multiple users.

Endpoint

POST /api/admin/jobs/users/bulk-update

Request Body

Field	Type	Required	Description
filter	object	✓	Filter conditions for target users
updates	object	✓	Update content

Request Example

curl -X POST "https://{tenant-domain}/api/admin/jobs/users/bulk-update" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "metadata.department": "Engineering"
    },
    "updates": {
      "metadata.building": "Tower A"
    }
  }'

Response Example

{
  "job_id": "job_bulk_update_def456",
  "status": "pending",
  "estimated_affected_users": 150,
  "created_at": 1706140800
}

---

Start Report Generation

Generate various reports.

Endpoint

POST /api/admin/jobs/reports/generate

Request Body

Field	Type	Required	Description
report_type	string	✓	Report type
format	string	-	Output format (pdf, csv, xlsx)
date_range	object	-	Date range
options	object	-	Report options

Report Types

Type	Description
user_activity	User activity report
authentication_summary	Authentication summary report
security_audit	Security audit report
compliance_status	Compliance status report

Request Example

curl -X POST "https://{tenant-domain}/api/admin/jobs/reports/generate" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "authentication_summary",
    "format": "pdf",
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "options": {
      "include_charts": true,
      "group_by": "day"
    }
  }'

Response Example

{
  "job_id": "job_report_ghi789",
  "status": "pending",
  "created_at": 1706140800
}

---

Download Job Result

Download the result file of a completed job.

Endpoint

GET /api/admin/jobs/:id/download

Path Parameters

Parameter	Type	Required	Description
id	string	✓	Job ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/jobs/job_export_abc123/download" \
  -H "Authorization: Bearer {token}" \
  -o export.csv

Response

Returns file binary data or a signed download URL.

{
  "download_url": "https://storage.authrim.com/exports/xxx?signature=yyy",
  "expires_at": 1706144400,
  "filename": "users_export_2024-01-22.csv",
  "size_bytes": 524288
}

---

Job Error Codes

Error Code	Description
JOB_NOT_FOUND	Job not found
JOB_ALREADY_COMPLETED	Job is already completed
JOB_ALREADY_CANCELLED	Job is already cancelled
IMPORT_INVALID_FORMAT	Invalid import file format
IMPORT_VALIDATION_ERROR	Import data validation error
EXPORT_TOO_LARGE	Export data is too large
REPORT_GENERATION_FAILED	Report generation failed