dock

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

Overview

The dock module allows you to:

Search docks with pagination
Filter docks by multiple criteria (status, fleet, load type, etc.)
Sort dock results by various properties
Retrieve specific dock fields to optimize API calls
Filter by dynamic additional information fields

Main Components

GetAndSearchDocksByPage

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

Models

Dock

Represents a dock entity with comprehensive information.

Properties:

id: Int - Unique dock identifier
name: String - Dock name
pickupTime: String - Pickup time (HH:MM:SS format)
deliveryTime: String - Delivery time (HH:MM:SS format)
objectId: Int - Related object ID for additional information
portId: Int - Related port ID
liftTruck: Int - Number of lift trucks
additionalInfo: JsonObject - Dynamic additional information
skillIds: List<Int> - Assigned skill IDs
status: PlaceStatusType - Dock status
fleet: FleetType - Fleet type
loadType: LoadType - Load type
companyId: Int - Related company ID
addedOnDate: String - Creation date (YYYY-MM-DD'T'HH:MM:SS)
updateOnDate: String - Last update date (YYYY-MM-DD'T'HH:MM:SS)

DockFilters

Filters to apply when searching docks.

Properties:

ids: List<Int>? - Filter by dock IDs
names: List<String>? - Filter by dock names
pickupTimes: List<String>? - Filter by pickup times
deliveryTimes: List<String>? - Filter by delivery times
objectIds: List<Int>? - Filter by object IDs
portIds: List<Int>? - Filter by port IDs
liftTrucks: List<Int>? - Filter by lift truck count
additionalInfo: List<JsonObject>? - Filter by additional info (dynamic structure)
skillIds: List<Int>? - Filter by skill IDs
status: List<PlaceStatusType>? - Filter by status
fleet: List<FleetType>? - Filter by fleet type
loadType: List<LoadType>? - Filter by load type
companyIds: List<Int>? - Filter by company IDs
addedOnDates: List<String>? - Filter by creation dates
updateOnDates: List<String>? - Filter by update dates

DockOrderSort

Sorting configuration for dock results.

Properties: All dock properties can be sorted (ASC/DESC). Set to null to skip sorting by that property.

Types

DockProperty

Enum representing available dock properties for field selection.

Values:

ID, NAME, PICKUP_TIME, DELIVERY_TIME, OBJECT_ID, PORT_ID, LIFT_TRUCK
ADDITIONAL_INFO, SKILL_IDS, STATUS, FLEET, LOAD_TYPE, COMPANY_ID
ADDED_ON_DATE, UPDATE_ON_DATE

Usage Examples

Basic Search - Get All Docks

import com.servinformacion.smart1sdk.android.dock.GetAndSearchDocksByPage
import com.servinformacion.smart1sdk.android.core.ResultS1SDK

class DockViewModel : ViewModel() {
    
    private val getDocks = GetAndSearchDocksByPage()
    
    fun loadDocks() {
        viewModelScope.launch {
            val result = getDocks(
                page = 1,
                pageQuantity = 20
            )
            
            when (result) {
                is ResultS1SDK.Success -> {
                    val docks = result.data.data
                    val totalPages = result.data.paginationInfo.totalPages
                    // Handle success
                }
                is ResultS1SDK.Error -> {
                    // Handle error
                }
            }
        }
    }
}

Search with Status Filter

import com.servinformacion.smart1sdk.android.dock.model.DockFilters
import com.servinformacion.smart1sdk.android.core.types.PlaceStatusType

suspend fun getActiveDocks() {
    val getDocks = GetAndSearchDocksByPage()
    
    val result = getDocks(
        filters = DockFilters(
            status = listOf(PlaceStatusType.ACTIVE)
        ),
        page = 1
    )
    
    // Handle result
}

Search by Fleet and Load Type

import com.servinformacion.smart1sdk.android.core.types.FleetType
import com.servinformacion.smart1sdk.android.core.types.LoadType
import com.servinformacion.smart1sdk.android.core.types.ApiLogicalOperator

suspend fun getDocksByFleetAndLoad() {
    val getDocks = GetAndSearchDocksByPage()
    
    val result = getDocks(
        filters = DockFilters(
            fleet = listOf(FleetType.INTERNAL),
            loadType = listOf(LoadType.FULL, LoadType.PARTIAL)
        ),
        logicalOperator = ApiLogicalOperator.AND,
        page = 1
    )
    
    // Handle result
}

Search with Sorting

import com.servinformacion.smart1sdk.android.dock.model.DockOrderSort
import com.servinformacion.smart1sdk.android.core.types.ApiSortType

suspend fun getDocksSortedByName() {
    val getDocks = GetAndSearchDocksByPage()
    
    val result = getDocks(
        orderSort = DockOrderSort(
            name = ApiSortType.ASC,
            addedOnDate = ApiSortType.DESC
        ),
        page = 1
    )
    
    // Handle result
}

Optimized Field Selection

Request only the fields you need:

import com.servinformacion.smart1sdk.android.dock.types.DockProperty

suspend fun getDockBasicInfo() {
    val getDocks = GetAndSearchDocksByPage()
    
    val result = getDocks(
        fields = listOf(
            DockProperty.ID,
            DockProperty.NAME,
            DockProperty.STATUS,
            DockProperty.PORT_ID
        ),
        page = 1,
        pageQuantity = 50
    )
    
    // Handle result
}

Search by Company

suspend fun getDocksByCompany(companyId: Int) {
    val getDocks = GetAndSearchDocksByPage()
    
    val result = getDocks(
        filters = DockFilters(
            companyIds = listOf(companyId)
        ),
        page = 1
    )
    
    // Handle result
}

Advanced Search with Multiple Filters

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

suspend fun advancedDockSearch() {
    val getDocks = GetAndSearchDocksByPage()
    
    val result = getDocks(
        fields = listOf(
            DockProperty.ID,
            DockProperty.NAME,
            DockProperty.STATUS,
            DockProperty.FLEET,
            DockProperty.LOAD_TYPE
        ),
        filters = DockFilters(
            names = listOf("Dock A", "Dock B"),
            status = listOf(PlaceStatusType.ACTIVE),
            fleet = listOf(FleetType.INTERNAL),
            companyIds = listOf(1, 2, 3)
        ),
        logicalOperator = ApiLogicalOperator.AND,
        orderSort = DockOrderSort(
            name = ApiSortType.ASC
        ),
        searchType = ApiSearchType.CONTAINS,
        page = 1,
        pageQuantity = 20
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val dataSet = result.data
            println("Total docks: ${dataSet.paginationInfo.totalRecords}")
            
            dataSet.data.forEach { dock ->
                println("Dock: ${dock.name} - Status: ${dock.status}")
            }
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}

Filter by Additional Info (Dynamic Fields)

The additionalInfo property supports dynamic filtering based on custom object configuration:

import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
import kotlinx.serialization.json.putJsonArray

suspend fun filterByAdditionalInfo() {
    val getDocks = GetAndSearchDocksByPage()
    
    // Single value filtering
    val singleValueFilter = buildJsonObject {
        put("custom_field_name", "value")
        put("custom_boolean_field", true)
        put("custom_number_field", 42)
    }
    
    // Multiple values filtering
    val multiValueFilter = buildJsonObject {
        putJsonArray("custom_field_name") {
            add("value1")
            add("value2")
        }
    }
    
    val result = getDocks(
        filters = DockFilters(
            additionalInfo = listOf(singleValueFilter)
        ),
        page = 1
    )
    
    // Handle result
}

Important Notes

Required Field: Always include DockProperty.ID in the fields list. The API requires this field.
Field Selection: Request only the fields you need for better performance and reduced bandwidth.
Pagination: Results are paginated. Use DataSet.paginationInfo to navigate pages.
Logical Operators:

ApiLogicalOperator.AND - All filters must match
ApiLogicalOperator.OR - Any filter can match

Search Types:

ApiSearchType.EXACT - Exact match
ApiSearchType.CONTAINS - Partial match (useful for search bars)

Additional Info: The additionalInfo field has a dynamic structure that depends on object configuration. It cannot be mapped to fixed models.
Status Types: Use PlaceStatusType enum for filtering by dock status (ACTIVE, INACTIVE, etc.)
Fleet Types: Use FleetType enum for filtering by fleet (INTERNAL, EXTERNAL, etc.)
Load Types: Use LoadType enum for filtering by load type (FULL, PARTIAL, EMPTY, etc.)

Response Structure

The response is wrapped in a DataSet<Dock>:

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

Error Handling

Common errors:

CommonError.InvalidInputData - Invalid parameters (empty fields, page <= 0, missing ID field)
ApiError.ExpiredToken - Session token expired (handled automatically)
ApiError.Unauthorized - Invalid or missing authentication
ApiError.NotFound - No docks found matching criteria

Packages

com.servinformacion.smart1sdk.android.dock

androidJvm

com.servinformacion.smart1sdk.android.dock.model

androidJvm

com.servinformacion.smart1sdk.android.dock.types

androidJvm