schedule

This module provides functionality to search and retrieve schedules from the Smart1 SDK API.

Overview

The schedule module allows you to:

Search schedules with pagination
Filter schedules by multiple criteria (order, dock, state, job type, dates, etc.)
Sort schedule results by various properties
Retrieve specific schedule fields to optimize API calls
Work with schedule timing information (dates, hours, events)
Manage capacity information for schedules

Main Components

GetAndSearchScheduleByPage

Main use case for retrieving schedules from the API with advanced filtering and pagination.

Models

Schedule

Represents a schedule entity with complete information.

Properties:

id: Int - Unique schedule identifier
orderId: Int - Related order ID
dockId: Int - Related dock ID
sequence: Int - Sequence number (related to order)
stateName: String - Current state name
job: JobType - Job type (DELIVERY, PICKUP, EMPTY)
dateInit: String - Initial date
dateEnd: String - End date
hourInit: String - Initial hour
hourEnd: String - End hour
capacityInfo: List<CapacityInfo> - Capacity information
arrivalQueueDate: String - Arrival queue date
arrivalQueueHour: String - Arrival queue hour
dateEventInit: String - Event initial date
hourEventInit: String - Event initial hour
dateEventEnd: String - Event end date
hourEventEnd: String - Event end hour
companyId: Int - Company ID
addedOnDate: String - Creation date
updateOnDate: String - Last update date

ScheduleFilters

Comprehensive filters for schedule search.

Properties: 19 different filter options including IDs, dates, times, states, and more.

ScheduleOrderSort

Sorting configuration with 20 sortable properties.

Types

ScheduleProperty

Enum with 20 properties for field selection.

Values:

ID, ORDER_ID, DOCK_ID, SEQUENCE, STATE_NAME, JOB
DATE_INIT, DATE_END, HOUR_INIT, HOUR_END, CAPACITY
ARRIVAL_QUEUE_DATE, ARRIVAL_QUEUE_HOUR
DATE_EVENT_INIT, HOUR_EVENT_INIT, DATE_EVENT_END, HOUR_EVENT_END
COMPANY_ID, ADDED_ON_DATE, UPDATE_ON_DATE

JobType

Enum representing job types.

Values:

DELIVERY - Delivery job
PICKUP - Pickup job
EMPTY - Empty job
UNKNOWN - Unknown job type

ScheduleState

Enum for schedule states.

Values:

ASSIGNED - Schedule assigned
IN_QUEUE - In queue
DOCK_ACTIVITY - Dock activity in progress
COMPLETED - Schedule completed
UNKNOWN - Unknown state

Usage Examples

Basic Search - Get All Schedules

import com.servinformacion.smart1sdk.android.schedule.GetAndSearchScheduleByPage
import com.servinformacion.smart1sdk.android.core.ResultS1SDK

class ScheduleViewModel : ViewModel() {
    
    private val getSchedules = GetAndSearchScheduleByPage()
    
    fun loadSchedules() {
        viewModelScope.launch {
            val result = getSchedules(
                page = 1,
                pageQuantity = 20
            )
            
            when (result) {
                is ResultS1SDK.Success -> {
                    val schedules = result.data.data
                    val totalPages = result.data.paginationInfo.totalPages
                    // Handle success
                }
                is ResultS1SDK.Error -> {
                    // Handle error
                }
            }
        }
    }
}

Filter by Order ID

import com.servinformacion.smart1sdk.android.schedule.model.ScheduleFilters

suspend fun getSchedulesByOrder(orderId: Int) {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        filters = ScheduleFilters(
            orderIds = listOf(orderId)
        ),
        page = 1
    )
    
    // Handle result
}

Filter by Job Type

import com.servinformacion.smart1sdk.android.schedule.types.JobType

suspend fun getDeliverySchedules() {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        filters = ScheduleFilters(
            jobs = listOf(JobType.DELIVERY)
        ),
        page = 1
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val deliveries = result.data.data
            println("Found ${deliveries.size} delivery schedules")
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}

Filter by State Name

suspend fun getSchedulesByState(stateName: String) {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        filters = ScheduleFilters(
            stateNames = listOf(stateName)
        ),
        page = 1
    )
    
    // Handle result
}

Filter by Date Range

import com.servinformacion.smart1sdk.android.core.types.ApiSearchType

suspend fun getSchedulesByDateRange(startDate: String, endDate: String) {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        filters = ScheduleFilters(
            dateInit = listOf(startDate, endDate)
        ),
        searchType = ApiSearchType.CONTAINS,
        page = 1
    )
    
    // Handle result
}

Sort Schedules by Sequence

import com.servinformacion.smart1sdk.android.schedule.model.ScheduleOrderSort
import com.servinformacion.smart1sdk.android.core.types.ApiSortType

suspend fun getSchedulesSortedBySequence() {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        orderSort = ScheduleOrderSort(
            sequence = ApiSortType.ASC,
            dateInit = ApiSortType.ASC
        ),
        page = 1
    )
    
    // Handle result
}

Optimized Field Selection

import com.servinformacion.smart1sdk.android.schedule.types.ScheduleProperty

suspend fun getScheduleBasicInfo() {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        fields = listOf(
            ScheduleProperty.ID,
            ScheduleProperty.ORDER_ID,
            ScheduleProperty.DOCK_ID,
            ScheduleProperty.SEQUENCE,
            ScheduleProperty.STATE_NAME,
            ScheduleProperty.JOB,
            ScheduleProperty.DATE_INIT,
            ScheduleProperty.HOUR_INIT
        ),
        page = 1,
        pageQuantity = 50
    )
    
    // Handle result
}

Advanced Search with Multiple Filters

suspend fun advancedScheduleSearch(orderId: Int, dockId: Int) {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        filters = ScheduleFilters(
            orderIds = listOf(orderId),
            dockIds = listOf(dockId),
            jobs = listOf(JobType.DELIVERY, JobType.PICKUP),
            companyIds = listOf(1)
        ),
        logicalOperator = ApiLogicalOperator.AND,
        orderSort = ScheduleOrderSort(
            sequence = ApiSortType.ASC,
            dateInit = ApiSortType.ASC
        ),
        searchType = ApiSearchType.EXACT,
        page = 1,
        pageQuantity = 20
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val dataSet = result.data
            println("Total schedules: ${dataSet.paginationInfo.totalRecords}")
            
            dataSet.data.forEach { schedule ->
                println("Schedule ${schedule.id} - Sequence: ${schedule.sequence}")
                println("  Job: ${schedule.job.apiName}")
                println("  State: ${schedule.stateName}")
                println("  Date: ${schedule.dateInit} ${schedule.hourInit}")
            }
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}

Get Schedules with Capacity Information

suspend fun getSchedulesWithCapacity(orderId: Int) {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        filters = ScheduleFilters(orderIds = listOf(orderId)),
        fields = listOf(
            ScheduleProperty.ID,
            ScheduleProperty.SEQUENCE,
            ScheduleProperty.CAPACITY
        )
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            result.data.data.forEach { schedule ->
                println("Schedule ${schedule.id}:")
                schedule.capacityInfo.forEach { capacity ->
                    println("  - ${capacity.name}: ${capacity.value} ${capacity.unit}")
                }
            }
        }
        is ResultS1SDK.Error -> {
            // Handle error
        }
    }
}

Filter by Dock and Job Type

suspend fun getDockSchedulesByJob(dockId: Int, jobType: JobType) {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        filters = ScheduleFilters(
            dockIds = listOf(dockId),
            jobs = listOf(jobType)
        ),
        orderSort = ScheduleOrderSort(
            dateInit = ApiSortType.ASC,
            hourInit = ApiSortType.ASC
        ),
        page = 1
    )
    
    // Handle result
}

Get Schedules with Event Times

suspend fun getSchedulesWithEvents(orderId: Int) {
    val getSchedules = GetAndSearchScheduleByPage()
    
    val result = getSchedules(
        filters = ScheduleFilters(orderIds = listOf(orderId)),
        fields = listOf(
            ScheduleProperty.ID,
            ScheduleProperty.SEQUENCE,
            ScheduleProperty.DATE_EVENT_INIT,
            ScheduleProperty.HOUR_EVENT_INIT,
            ScheduleProperty.DATE_EVENT_END,
            ScheduleProperty.HOUR_EVENT_END
        )
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            result.data.data.forEach { schedule ->
                println("Schedule ${schedule.id}:")
                println("  Event Start: ${schedule.dateEventInit} ${schedule.hourEventInit}")
                println("  Event End: ${schedule.dateEventEnd} ${schedule.hourEventEnd}")
            }
        }
        is ResultS1SDK.Error -> {
            // Handle error
        }
    }
}

Pagination Example

class ScheduleListViewModel : ViewModel() {
    private val getSchedules = GetAndSearchScheduleByPage()
    private var currentPage = 1
    private val pageSize = 20
    
    suspend fun loadNextPage(orderId: Int) {
        val result = getSchedules(
            filters = ScheduleFilters(orderIds = listOf(orderId)),
            page = currentPage,
            pageQuantity = pageSize,
            orderSort = ScheduleOrderSort(sequence = ApiSortType.ASC)
        )
        
        when (result) {
            is ResultS1SDK.Success -> {
                val dataSet = result.data
                val schedules = dataSet.data
                val hasMorePages = currentPage < dataSet.paginationInfo.totalPages
                
                // Update UI with schedules
                updateScheduleList(schedules)
                
                if (hasMorePages) {
                    currentPage++
                }
            }
            is ResultS1SDK.Error -> {
                // Handle error
            }
        }
    }
}

Important Notes

Required Field: Always include ScheduleProperty.ID in the fields list.
Field Selection: Request only needed fields for better performance.
Pagination: Results are paginated. Use DataSet.paginationInfo to navigate.
Job Types:

DELIVERY: Delivery operation
PICKUP: Pickup operation
EMPTY: Empty operation (no load)

Schedule States: States can be dynamic. Use stateName string property for filtering.
Sequence: Indicates the order of schedules within an order.
Time Fields:

dateInit/dateEnd: Scheduled time window
arrivalQueueDate/Hour: Queue arrival time
dateEventInit/End: Actual event times

Capacity Info: Contains dynamic capacity data (weight, volume, etc.).
Search Types:

EXACT: Exact match
CONTAINS: Partial match (useful for text/date searches)

Response Structure

data class DataSet<T>(
    val data: List<T>,                   // List of schedules
    val paginationInfo: PaginationInfo,  // Pagination metadata
    val capacityInfo: CapacityInfo       // API capacity information
)

Error Handling

Common errors:

CommonError.InvalidInputData - Invalid parameters (empty fields, invalid page)
ApiError.ExpiredToken - Session token expired (handled automatically)
ApiError.Unauthorized - Invalid or missing authentication
ApiError.NotFound - No schedules found

Best Practices

Optimize Queries: Request only necessary fields
Use Filters: Narrow down results with appropriate filters
Pagination: Load data in pages for better performance
Sequence Order: Sort by sequence to maintain logical order
Error Handling: Always handle potential errors
Time Windows: Use date/hour fields to manage schedule timing
Capacity Tracking: Monitor capacity info for load management

Use Cases

Schedule Management: View and manage delivery/pickup schedules
Dock Operations: Track schedules by dock
Order Tracking: View all schedules for an order
Capacity Planning: Monitor capacity usage across schedules
Time Management: Track scheduled vs actual event times
Queue Management: Monitor arrival queue times

Packages

com.servinformacion.smart1sdk.android.schedule

androidJvm

com.servinformacion.smart1sdk.android.schedule.model

androidJvm

com.servinformacion.smart1sdk.android.schedule.types

androidJvm