Tasks

API: Internal/Beta

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 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: TypeScript
// Authenticated as ucloud
await callAPI(TaskApi.create(
    {
        "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
}
*/
await callAPI(TaskApi.postStatus(
    {
        "update": {
            "jobId": "b06f51d2-88af-487c-bb4c-4cc156cf24fd",
            "newTitle": null,
            "speeds": [
            ],
            "progress": null,
            "complete": false,
            "messageToAppend": "Count is now 1",
            "newStatus": null
        }
    }
);

/*
{
}
*/
await callAPI(TaskApi.postStatus(
    {
        "update": {
            "jobId": "b06f51d2-88af-487c-bb4c-4cc156cf24fd",
            "newTitle": null,
            "speeds": [
            ],
            "progress": null,
            "complete": false,
            "messageToAppend": "Count is now 2",
            "newStatus": null
        }
    }
);

/*
{
}
*/
await callAPI(TaskApi.postStatus(
    {
        "update": {
            "jobId": "b06f51d2-88af-487c-bb4c-4cc156cf24fd",
            "newTitle": null,
            "speeds": [
            ],
            "progress": null,
            "complete": false,
            "messageToAppend": "Count is now 3",
            "newStatus": null
        }
    }
);

/*
{
}
*/
await callAPI(TaskApi.markAsComplete(
    {
        "id": "b06f51d2-88af-487c-bb4c-4cc156cf24fd"
    }
);

/*
{
}
*/
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: TypeScript

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

API: Internal/Beta Auth: Users

Request Response Error
ListRequest Page<Task> CommonErrorMessage

listen

API: Internal/Beta Auth: Users

Request Response Error
Unit TaskUpdate CommonErrorMessage

view

API: Internal/Beta Auth: Users

Request Response Error
FindByStringId Task CommonErrorMessage

create

API: Internal/Beta Auth: Services

Request Response Error
CreateRequest Task CommonErrorMessage

markAsComplete

API: Internal/Beta Auth: Services

Request Response Error
FindByStringId Unit CommonErrorMessage

postStatus

API: Internal/Beta Auth: Services

Request Response Error
PostStatusRequest Unit CommonErrorMessage

Data Models

Progress

API: Internal/Beta

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

Speed

API: Internal/Beta

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

API: Internal/Beta

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

API: Internal/Beta

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

API: Internal/Beta

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

ListRequest

API: Internal/Beta

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

PostStatusRequest

API: Internal/Beta

data class PostStatusRequest(
    val update: TaskUpdate,
)
Properties
update: TaskUpdate