tasks

« Previous section Next section »

UCloud Developer Guide / Core / Communication / Tasks

Tasks

Tasks give services a way to communicate progress to end-users.

Rationale

A task in UCloud displays the progress of any long-running process. Both services and providers use this functionality. Each task is uniquely identified by a key. Each task belongs to a specific end-user. Services/providers communicate progress updates regularly. If the end-user is online when an update occurs, then the end-user is notified.

Providers use this functionality through one of the Control interfaces. They do not invoke the interface directly.

Table of Contents

1. Examples

2. Remote Procedure Calls

3. Data Models

Example: Counting to 3 (Produced by the service)

Frequency of useCommon

Actors

  • The UCloud/Core service user (ucloud)

Communication Flow: Kotlin
Tasks.create.call(
    CreateRequest(
        initialStatus = null, 
        owner = "User#1234", 
        title = "We are counting to 3", 
    ),
    ucloud
).orThrow()

/*
Task(
    complete = false, 
    jobId = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
    modifiedAt = 0, 
    owner = "User#1234", 
    processor = "_ucloud", 
    startedAt = 0, 
    status = null, 
    title = "We are counting to 3", 
)
*/
Tasks.postStatus.call(
    PostStatusRequest(
        update = TaskUpdate(
            complete = false, 
            jobId = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
            messageToAppend = "Count is now 1", 
            newStatus = null, 
            newTitle = null, 
            progress = null, 
            speeds = emptyList(), 
        ), 
    ),
    ucloud
).orThrow()

/*
Unit
*/
Tasks.postStatus.call(
    PostStatusRequest(
        update = TaskUpdate(
            complete = false, 
            jobId = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
            messageToAppend = "Count is now 2", 
            newStatus = null, 
            newTitle = null, 
            progress = null, 
            speeds = emptyList(), 
        ), 
    ),
    ucloud
).orThrow()

/*
Unit
*/
Tasks.postStatus.call(
    PostStatusRequest(
        update = TaskUpdate(
            complete = false, 
            jobId = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
            messageToAppend = "Count is now 3", 
            newStatus = null, 
            newTitle = null, 
            progress = null, 
            speeds = emptyList(), 
        ), 
    ),
    ucloud
).orThrow()

/*
Unit
*/
Tasks.markAsComplete.call(
    FindByStringId(
        id = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
    ),
    ucloud
).orThrow()

/*
Unit
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as ucloud
curl -XPUT -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/tasks" -d '{
    "title": "We are counting to 3",
    "owner": "User#1234",
    "initialStatus": null
}'


# {
#     "jobId": "b06f51d2-88af-487c-bb4c-4cc156cf24fd",
#     "owner": "User#1234",
#     "processor": "_ucloud",
#     "title": "We are counting to 3",
#     "status": null,
#     "complete": false,
#     "startedAt": 0,
#     "modifiedAt": 0
# }

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/tasks/postStatus" -d '{
    "update": {
        "jobId": "b06f51d2-88af-487c-bb4c-4cc156cf24fd",
        "newTitle": null,
        "speeds": [
        ],
        "progress": null,
        "complete": false,
        "messageToAppend": "Count is now 1",
        "newStatus": null
    }
}'


# {
# }

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/tasks/postStatus" -d '{
    "update": {
        "jobId": "b06f51d2-88af-487c-bb4c-4cc156cf24fd",
        "newTitle": null,
        "speeds": [
        ],
        "progress": null,
        "complete": false,
        "messageToAppend": "Count is now 2",
        "newStatus": null
    }
}'


# {
# }

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/tasks/postStatus" -d '{
    "update": {
        "jobId": "b06f51d2-88af-487c-bb4c-4cc156cf24fd",
        "newTitle": null,
        "speeds": [
        ],
        "progress": null,
        "complete": false,
        "messageToAppend": "Count is now 3",
        "newStatus": null
    }
}'


# {
# }

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/tasks/markAsComplete" -d '{
    "id": "b06f51d2-88af-487c-bb4c-4cc156cf24fd"
}'


# {
# }
Communication Flow: Visual

Example: Counting to 3 (Received by end-user)

Frequency of useCommon

Actors

  • An authenticated user (user)

Communication Flow: Kotlin
Tasks.listen.subscribe(
    Unit,
    user,
    handler = { /* will receive messages listed below */ }
)

/*
TaskUpdate(
    complete = false, 
    jobId = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
    messageToAppend = "Count is now 1", 
    newStatus = null, 
    newTitle = null, 
    progress = null, 
    speeds = emptyList(), 
)
*/

/*
TaskUpdate(
    complete = false, 
    jobId = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
    messageToAppend = "Count is now 2", 
    newStatus = null, 
    newTitle = null, 
    progress = null, 
    speeds = emptyList(), 
)
*/

/*
TaskUpdate(
    complete = false, 
    jobId = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
    messageToAppend = "Count is now 3", 
    newStatus = null, 
    newTitle = null, 
    progress = null, 
    speeds = emptyList(), 
)
*/

/*
TaskUpdate(
    complete = true, 
    jobId = "b06f51d2-88af-487c-bb4c-4cc156cf24fd", 
    messageToAppend = null, 
    newStatus = null, 
    newTitle = null, 
    progress = null, 
    speeds = emptyList(), 
)
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------
Communication Flow: Visual

Remote Procedure Calls

list

RequestResponseError

ListRequest

Page<Task>

CommonErrorMessage

listen

RequestResponseError

Unit

TaskUpdate

CommonErrorMessage

view

RequestResponseError

FindByStringId

Task

CommonErrorMessage

create

RequestResponseError

CreateRequest

Task

CommonErrorMessage

markAsComplete

RequestResponseError

FindByStringId

Unit

CommonErrorMessage

postStatus

RequestResponseError

PostStatusRequest

Unit

CommonErrorMessage

Data Models

Progress

data class Progress(
    val title: String,
    val current: Int,
    val maximum: Int,
)
Properties

Speed

data class Speed(
    val title: String,
    val speed: Double,
    val unit: String,
    val asText: String,
)
Properties

Task

data class Task(
    val jobId: String,
    val owner: String,
    val processor: String,
    val title: String?,
    val status: String?,
    val complete: Boolean,
    val startedAt: Long,
    val modifiedAt: Long,
)
Properties

TaskUpdate

data class TaskUpdate(
    val jobId: String,
    val newTitle: String?,
    val speeds: List<Speed>?,
    val progress: Progress?,
    val complete: Boolean?,
    val messageToAppend: String?,
    val newStatus: String?,
)
Properties

CreateRequest

data class CreateRequest(
    val title: String,
    val owner: String,
    val initialStatus: String?,
)
Properties

ListRequest

data class ListRequest(
    val itemsPerPage: Int?,
    val page: Int?,
)
Properties

PostStatusRequest

data class PostStatusRequest(
    val update: TaskUpdate,
)
Properties

PrevioussupportNextmonitoring

Last updated