Xperiflow Jobs
Info: You can think of Xperiflow Jobs in a similar light to OneStream Data Management Jobs.
**Note:** You will see the terms *Job* and *Xperiflow Job* used interchangeably throughout this article.
Overview
Jobs represent the "what" and "when" of work in Xperiflow. When you need to perform a complex operation—like training a model, processing data, or running an analysis—you execute a Job that describes:
- What operation to perform (the job type)
- What parameters to use (communication metadata)
- When to execute it (immediately or scheduled)
- Where it belongs (which project, if applicable)
- How important it is (priority level)
Jobs in Xperiflow serve as the primary mechanism for executing asynchronous, long-running operations. Each job:
- Maps to a specific Task type that defines the actual execution logic
- Contains communication metadata (comm_metadata) that provides parameters to the task
- Tracks execution progress through various activity statuses
- Can be scheduled for future execution or run immediately
- Supports checkpoints for resuming from failures
- Can be associated with SensibleAI Forecast projects for data science workflows
Core Concepts
Jobs vs Tasks
Understanding the relationship between Jobs and Tasks is fundamental:
- Jobs: High-level work units that are inserted into the job queue. They represent the "what" and "when" of execution.
- Tasks: The actual execution units that perform the work. Tasks are organized in trees and can have subtasks that run sequentially or in parallel.
Think of it like a restaurant order:
- The Job is your complete order (e.g., "dinner for two")
- The Tasks are the individual steps (appetizer, main course, dessert) that must be completed
When you submit a Job, the system automatically creates and manages the underlying Tasks needed to complete it.
Job Types
Job Types represent different categories of work that can be performed in Xperiflow. Each job type corresponds to a specific operation or workflow, such as running a data pipeline, executing a routine, deploying a model, or processing data.
Data Operations
Jobs that handle data loading, validation, and processing:
- TargetDataLoad: Loads target data into a project
- FeatureDataLoad: Loads feature data
- DataSourceUpdate: Updates data sources
Pipeline Execution
Jobs that run automated workflows:
- Pipeline: Runs the complete automated pipeline (feature engineering and modeling)
- Prediction: Generates predictions from models
Model Management
Jobs for building, rebuilding, and deploying models:
- ModelRebuild: Rebuilds a model. This is the combination of TargetDataLoad, FeatureDataLoad, Pipeline, and Deploy jobs
- Deploy: Deploys models for production use
Routine Execution
Jobs for executing custom routines:
- RoutineExecution: Executes a user-defined routine
Data Uploads
Jobs for importing data:
- EventUpload: Uploads event data
- LocationUpload: Uploads location data
Exports
Jobs for exporting results:
- ModelForecastExport: Exports model forecasts
- FeatureImpactExport: Exports feature impact analysis
System Operations
Jobs for system maintenance and management:
- ProjectCreation: Creates a new project
- ProjectCopy: Copies an existing project
**Note:** This is not an exhuastive list of all available jobs. Please see the Api Documentation for the complete list of available Jobs and their associated Parameters.
Communication Metadata (Job Input Parameters)
Each Job carries comm_metadata_json, a JSON string containing parameters validated against a Job Type specific JSON schema. This ensures type safety and validation before job execution begins.
How Job Types Work
When you submit a job, you specify:
- Job Type: What operation to perform (e.g., "Pipeline", "RoutineExecution")
- Parameters: The specific inputs needed for that operation (passed via communication metadata)
- Context: Project association, priority, scheduling, etc.
The system uses the job type to:
- Validate that you have permission to run that type of operation
- Determine what parameters are required
- Route the job to the appropriate execution engine
- Track progress and status appropriately
Example: Understanding Job Types in Practice
If you want to run a complete data science pipeline, you would submit a Pipeline job type with parameters indicating which project and build to process. The system knows that a Pipeline job:
- Requires a project context
- Needs a buildinfo_id parameter
- May take significant time to complete
- Can be checkpointed at various stages
- Should track progress through multiple phases
In contrast, a RoutineExecution job type:
- Can run at the framework level (no project required)
- Needs routine_instance_id and routine_run_id parameters
- Executes user-defined custom logic
- Has different validation rules
Discovering Available Job Types
The available job types in your Xperiflow installation depend on:
- The version of Xperiflow you're running
- Any custom job types that have been registered
- The specific application context (some job types are application-specific)
Job Lifecycle
Jobs progress through a well-defined lifecycle with the following states:
Lifecycle States
A Job can be in one of several states:
Initial States:
- INITIALIZED: The Job has been created but not yet submitted
- QUEUED: The Job is waiting in the queue to be picked up for execution
- CHECKING: The system is verifying permissions and prerequisites
Active States:
- RUNNING: The Job is currently executing
- RUNNINGSUBTASKS: The Job's subtasks are executing (the Job itself is coordinating)
Paused States:
- PAUSED: Execution has been temporarily paused
- PENDING_PAUSED: A pause request is being processed
Completion States:
- COMPLETED: The Job finished successfully
- USERCANCELLED: The Job was cancelled by a user
- SYSCANCELLED: The Job was cancelled by the system (e.g., due to timeout)
- SYSERROR: The Job failed due to an error
- SYSERROR_RERUNNABLE: The Job failed but can be safely rerun
Time Tracking
Jobs track several important timestamps:
- Creation Time: When the Job was first created
- Queued Time: When the Job entered the queue (may be in the future for scheduled Jobs)
- Start Time: When execution actually began
- End Time: When execution completed
- Last Activity Time: The most recent update to the Job
These timestamps help you understand how long Jobs take and how they are progressing along.
Job Submission Process
When you submit a Job, the system performs several steps:
- Validation: Checks that all required information is present and valid
- Permission Check: Verifies you have permission to run this type of Job
- Resource Check: Ensures sufficient CPU, memory, and other resources are available
- Prerequisite Check: Confirms any required prior Jobs or states are complete
- Queue Insertion: Adds the Job to the execution queue
If any check fails, the Job is rejected with a clear error message explaining why.
Immediate vs Scheduled Jobs
Jobs can be executed in two ways:
Immediate Jobs:
- Enter the queue immediately
- Execute as soon as resources are available
- Used for operations you want to start right away
Scheduled Jobs:
- Enter the queue but wait until a specified time
- Execute automatically when the scheduled time arrives
- Useful for batch processing, maintenance tasks, or time-sensitive operations
Job Priority
Jobs have a priority level (1-10, where 1 is highest priority). The system executes higher-priority Jobs before lower-priority ones when multiple Jobs are waiting.
- Priority 1-3: Critical, time-sensitive operations
- Priority 4-7: Normal operations
- Priority 8-10: Background tasks and maintenance
Monitoring and Status
Progress Tracking
Jobs provide real-time progress information:
- Percent Complete: A value from 0% to 100% indicating how much work is done
- Total Tasks: The number of subtasks that need to complete (may be unknown initially)
- Completed Tasks: How many subtasks have finished
Status Queries
You can query Jobs to see:
- Current status and progress
- Execution history and timestamps
- Associated project and user information
- Error details (if the Job failed)
Waiting for Completion
The system can wait for a Job to complete, periodically checking its status and reporting progress. This is useful when you need to know when an operation finishes before proceeding.
Checkpoints
Checkpoints are save points that allow Jobs to resume from a known good state after a failure.
How Checkpoints Work
Think of checkpoints like save points in a video game:
- The Job reaches a milestone (e.g., "data loaded successfully")
- A checkpoint is created, capturing the current state
- If the Job fails later, you can resume from the checkpoint instead of starting over
Common Checkpoint Points
In SensibleAI Forecast, checkpoints are typically created at:
- Post DataLoad: After data has been successfully loaded
- Pre Pipeline: Before pipeline execution begins
- Post Feature Engineering: After feature engineering completes
- Post Modeling: After model training completes
- Post Pipeline: After the complete pipeline finishes
- Post Deploy: After deployment completes
Resuming from Checkpoints
If a Job fails, you can create a new Job that resumes from a checkpoint. This saves time and resources by avoiding re-execution of work that already completed successfully.
Job Properties
Project Association
Jobs can be associated with projects or run at the framework level:
- Project Jobs: Tied to a specific project, have access to project data and resources
- Framework Jobs: Not tied to a project, operate at the system level
Most SensibleAI Forecast are project Jobs, while system maintenance and routine execution might be framework Jobs.
Deletability
Some Jobs can be deleted after completion, while others are protected:
- Deletable Jobs: Can be removed to clean up history
- Protected Jobs: Cannot be deleted (e.g., Jobs tied to important state information)
Error Logging
When Jobs fail, they generate error logs that contain:
- What went wrong
- Where in the execution it failed
- Stack traces and diagnostic information
These logs help diagnose and fix issues. The job id will be included in the error log entries.