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

Description
Counting to 3 (Produced by the service)
Counting to 3 (Received by end-user)

2. Remote Procedure Calls

Name	Description
`list`	No description
`listen`	No description
`view`	No description
`create`	No description
`markAsComplete`	No description
`postStatus`	No description

3. Data Models

Name	Description
`Progress`	No description
`Speed`	No description
`Task`	No description
`TaskUpdate`	No description
`CreateRequest`	No description
`ListRequest`	No description
`PostStatusRequest`	No description

Example: Counting to 3 (Produced by the service)¶

Frequency of use	Common
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 use	Common
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`¶

Request	Response	Error
`ListRequest`	`Page<Task>`	`CommonErrorMessage`

`listen`¶

Request	Response	Error
`Unit`	`TaskUpdate`	`CommonErrorMessage`

`view`¶

Request	Response	Error
`FindByStringId`	`Task`	`CommonErrorMessage`

`create`¶

Request	Response	Error
`CreateRequest`	`Task`	`CommonErrorMessage`

`markAsComplete`¶

Request	Response	Error
`FindByStringId`	`Unit`	`CommonErrorMessage`

`postStatus`¶

Request	Response	Error
`PostStatusRequest`	`Unit`	`CommonErrorMessage`

Data Models¶

`Progress`¶

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

Properties

title: String

current: Int

maximum: Int

`Speed`¶

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

Properties

title: String

speed: Double

unit: String

asText: String

`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

jobId: String

owner: String

processor: String

title: String?

status: String?

complete: Boolean

startedAt: Long

modifiedAt: Long

`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

jobId: String

newTitle: String?

speeds: List<Speed>?

progress: Progress?

complete: Boolean?

messageToAppend: String?

newStatus: String?

`CreateRequest`¶

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

Properties

title: String

owner: String

initialStatus: String?

`ListRequest`¶

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

Properties

itemsPerPage: Int?

page: Int?

`PostStatusRequest`¶

data class PostStatusRequest(
    val update: TaskUpdate,
)

Properties

update: TaskUpdate

Tasks¶

Rationale¶

Table of Contents¶

Example: Counting to 3 (Produced by the service)¶

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

Remote Procedure Calls¶

list¶

listen¶

view¶

create¶

markAsComplete¶

postStatus¶

Data Models¶

Progress¶

Speed¶

Task¶

TaskUpdate¶

CreateRequest¶

ListRequest¶

PostStatusRequest¶

`list`¶

`listen`¶

`view`¶

`create`¶

`markAsComplete`¶

`postStatus`¶

`Progress`¶

`Speed`¶

`Task`¶

`TaskUpdate`¶

`CreateRequest`¶

`ListRequest`¶

`PostStatusRequest`¶