Allocation Process¶

Grants provide a way for users of UCloud to apply for resources.

Rationale¶

In order for any user to use UCloud they must have credits. Credits are required for use of any compute or storage. There are only two ways of receiving any credits, either through an admin directly granting you the credits or by receiving them from a project.

Grants acts as a more user-friendly gateway to receiving resources from a project. Every GrantApplication goes through the following steps:

User submits application to relevant project
All grant givers must review the application
- User and reviewer can comment on the application
- User and reviewer can perform edits to the application
Reviewer either approve or reject
If the GrantApplication was approved then resources are granted to the recipient

Table of Contents¶

1. Remote Procedure Calls

Name	Description
`browse`	No description
`retrieve`	No description
`retrieveLogo`	No description
`retrieveRequestSettings`	No description
`deleteComment`	No description
`postComment`	No description
`retrieveGrantGivers`	No description
`submitRevision`	No description
`transfer`	No description
`updateRequestSettings`	No description
`updateState`	No description
`uploadLogo`	No description

2. Data Models

Name	Description
`GrantApplication`	No description
`GrantApplication.Comment`	No description
`GrantApplication.Document`	No description
`GrantApplication.Form`	No description
`GrantApplication.Form.GrantGiverInitiated`	No description
`GrantApplication.Form.PlainText`	No description
`GrantApplication.GrantGiverApprovalState`	No description
`GrantApplication.Period`	No description
`GrantApplication.Recipient`	No description
`GrantApplication.Recipient.ExistingProject`	No description
`GrantApplication.Recipient.NewProject`	No description
`GrantApplication.Recipient.PersonalWorkspace`	No description
`GrantApplication.Revision`	Contains information about a specific revision of the application.
`GrantApplication.State`	No description
`GrantApplication.Status`	No description
`GrantApplicationFilter`	No description
`GrantGiver`	No description
`Templates`	No description
`Templates.PlainText`	No description
`UserCriteria`	Describes some criteria which match a user
`UserCriteria.Anyone`	Matches any user
`UserCriteria.EmailDomain`	Matches any user with an email domain equal to `domain`
`UserCriteria.WayfOrganization`	Matches any user with an organization matching `org`
`GrantApplication.AllocationRequest`	No description
`GrantRequestSettings`	No description
`GrantsV2.Browse.Request`	The base type for requesting paginated content.
`GrantsV2.DeleteComment.Request`	No description
`GrantsV2.PostComment.Request`	No description
`GrantsV2.RetrieveGrantGivers.Request`	No description
`GrantsV2.RetrieveGrantGivers.Request.ExistingApplication`	No description
`GrantsV2.RetrieveGrantGivers.Request.ExistingProject`	No description
`GrantsV2.RetrieveGrantGivers.Request.NewProject`	No description
`GrantsV2.RetrieveGrantGivers.Request.PersonalWorkspace`	No description
`GrantsV2.RetrieveLogo.Request`	No description
`GrantsV2.SubmitRevision.Request`	No description
`GrantsV2.Transfer.Request`	No description
`GrantsV2.UpdateState.Request`	No description
`GrantsV2.RetrieveGrantGivers.Response`	No description

Remote Procedure Calls¶

`browse`¶

Request	Response	Error
`GrantsV2.Browse.Request`	`PageV2<GrantApplication>`	`CommonErrorMessage`

`retrieve`¶

Request	Response	Error
`FindByStringId`	`GrantApplication`	`CommonErrorMessage`

`retrieveLogo`¶

Request	Response	Error
`GrantsV2.RetrieveLogo.Request`	`Unit`	`CommonErrorMessage`

`retrieveRequestSettings`¶

Request	Response	Error
`Unit`	`GrantRequestSettings`	`CommonErrorMessage`

`deleteComment`¶

Request	Response	Error
`GrantsV2.DeleteComment.Request`	`Unit`	`CommonErrorMessage`

`postComment`¶

Request	Response	Error
`GrantsV2.PostComment.Request`	`FindByStringId`	`CommonErrorMessage`

`retrieveGrantGivers`¶

Request	Response	Error
`GrantsV2.RetrieveGrantGivers.Request`	`GrantsV2.RetrieveGrantGivers.Response`	`CommonErrorMessage`

`submitRevision`¶

Request	Response	Error
`GrantsV2.SubmitRevision.Request`	`FindByStringId`	`CommonErrorMessage`

`transfer`¶

Request	Response	Error
`GrantsV2.Transfer.Request`	`Unit`	`CommonErrorMessage`

`updateRequestSettings`¶

Request	Response	Error
`GrantRequestSettings`	`Unit`	`CommonErrorMessage`

`updateState`¶

Request	Response	Error
`GrantsV2.UpdateState.Request`	`Unit`	`CommonErrorMessage`

`uploadLogo`¶

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

Data Models¶

`GrantApplication`¶

data class GrantApplication(
    val id: String,
    val createdBy: String,
    val createdAt: Long,
    val updatedAt: Long,
    val currentRevision: GrantApplication.Revision,
    val status: GrantApplication.Status,
)

Properties

id: String A unique identifier representing a GrantApplication

The ID is used for all requests which manipulate the application. The ID is issued by UCloud/Core when the initial revision is submitted. The ID is never re-used by the system, even if a previous version has been closed.

createdBy: String Username of the user who originially submitted the application

createdAt: Long Timestamp representing when the application was originially submitted

updatedAt: Long Timestamp representing when the application was last updated

currentRevision: GrantApplication.Revision Information about the current revision

status: GrantApplication.Status Status information about the application in its entirety

`GrantApplication.Comment`¶

data class Comment(
    val id: String,
    val username: String,
    val createdAt: Long,
    val comment: String,
    val type: String /* "comment" */,
)

Properties

id: String

username: String

createdAt: Long

comment: String

type: String /* "comment" */ The type discriminator

`GrantApplication.Document`¶

data class Document(
    val recipient: GrantApplication.Recipient,
    val allocationRequests: List<GrantApplication.AllocationRequest>,
    val form: GrantApplication.Form,
    val referenceIds: List<String>?,
    val revisionComment: String?,
    val parentProjectId: String?,
    val type: String /* "document" */,
)

Properties

recipient: GrantApplication.Recipient Describes the recipient of resources, should the application be accepted

Updateable by: Original creator (createdBy of application) Immutable after creation: Yes

allocationRequests: List<GrantApplication.AllocationRequest> Describes the allocations for resources which are requested by this application

Updateable by: Original creator and grant givers Immutable after creation: No

form: GrantApplication.Form A form describing why these resources are being requested

Updateable by: Original creator Immutable after creation: No

referenceIds: List<String>? A reference used for out-of-band bookkeeping

Updateable by: Grant givers Immutable after creation: No

revisionComment: String? A comment describing why this change was made

Update by: Original creator and grant givers Immutable after creation: No. First revision must always be null.

parentProjectId: String? When creating a new project the user should choose one of the affiliations to be its parent.

type: String /* "document" */ The type discriminator

`GrantApplication.Form`¶

sealed class Form {
    abstract val type: String /* "form" */

    class GrantGiverInitiated : Form()
    class PlainText : Form()
}

Properties

type: String /* "form" */ The type discriminator

`GrantApplication.Form.GrantGiverInitiated`¶

data class GrantGiverInitiated(
    val text: String,
    val subAllocator: Boolean?,
    val type: String /* "grant_giver_initiated" */,
)

Properties

text: String

subAllocator: Boolean?

type: String /* "grant_giver_initiated" */ The type discriminator

`GrantApplication.Form.PlainText`¶

data class PlainText(
    val text: String,
    val type: String /* "plain_text" */,
)

Properties

text: String

type: String /* "plain_text" */ The type discriminator

`GrantApplication.GrantGiverApprovalState`¶

data class GrantGiverApprovalState(
    val projectId: String,
    val projectTitle: String,
    val state: GrantApplication.State,
    val type: String /* "grant_giver_approval_state" */,
)

Properties

projectId: String

projectTitle: String

state: GrantApplication.State

type: String /* "grant_giver_approval_state" */ The type discriminator

`GrantApplication.Period`¶

data class Period(
    val start: Long?,
    val end: Long?,
    val type: String /* "period" */,
)

Properties

start: Long?

end: Long?

type: String /* "period" */ The type discriminator

`GrantApplication.Recipient`¶

sealed class Recipient {
    abstract val type: String /* "recipient" */

    class ExistingProject : Recipient()
    class NewProject : Recipient()
    class PersonalWorkspace : Recipient()
}

Properties

type: String /* "recipient" */ The type discriminator

`GrantApplication.Recipient.ExistingProject`¶

data class ExistingProject(
    val id: String,
    val type: String /* "existingProject" */,
)

Properties

id: String

type: String /* "existingProject" */ The type discriminator

`GrantApplication.Recipient.NewProject`¶

data class NewProject(
    val title: String,
    val type: String /* "newProject" */,
)

Properties

title: String

type: String /* "newProject" */ The type discriminator

`GrantApplication.Recipient.PersonalWorkspace`¶

data class PersonalWorkspace(
    val username: String,
    val type: String /* "personalWorkspace" */,
)

Properties

username: String

type: String /* "personalWorkspace" */ The type discriminator

`GrantApplication.Revision`¶

Contains information about a specific revision of the application.

data class Revision(
    val createdAt: Long,
    val updatedBy: String,
    val revisionNumber: Int,
    val document: GrantApplication.Document,
    val type: String /* "revision" */,
)

The primary contents of the revision is stored in the document. The document describes the contents of the application, including which resource allocations are requested and by whom. Every time a change is made to the application, a new revision is created. Each revision contains the full document. Changes between versions can be computed by comparing with the previous revision.

Properties

createdAt: Long Timestamp indicating when this revision was made

updatedBy: String Username of the user who created this revision

revisionNumber: Int A number indicating which revision this is

Revision numbers are guaranteed to be unique and always increasing. The first revision number must be 0. The backend does not guarantee that revision numbers are issued without gaps. Thus it is allowed for the first revision to be 0 and the second revision to be 10.

document: GrantApplication.Document Contains the application form from the end-user

type: String /* "revision" */ The type discriminator

`GrantApplication.State`¶

enum class State {
    APPROVED,
    REJECTED,
    CLOSED,
    IN_PROGRESS,
}

Properties

APPROVED

REJECTED

CLOSED

IN_PROGRESS

`GrantApplication.Status`¶

data class Status(
    val overallState: GrantApplication.State,
    val stateBreakdown: List<GrantApplication.GrantGiverApprovalState>,
    val comments: List<GrantApplication.Comment>,
    val revisions: List<GrantApplication.Revision>,
    val projectTitle: String?,
    val projectPI: String,
    val type: String /* "status" */,
)

Properties

overallState: GrantApplication.State

stateBreakdown: List<GrantApplication.GrantGiverApprovalState>

comments: List<GrantApplication.Comment>

revisions: List<GrantApplication.Revision>

projectTitle: String?

projectPI: String

type: String /* "status" */ The type discriminator

`GrantApplicationFilter`¶

enum class GrantApplicationFilter {
    SHOW_ALL,
    ACTIVE,
    INACTIVE,
}

Properties

SHOW_ALL

ACTIVE

INACTIVE

`GrantGiver`¶

data class GrantGiver(
    val id: String,
    val title: String,
    val description: String,
    val templates: Templates,
    val categories: List<ProductCategory>,
)

Properties

id: String

title: String

description: String

templates: Templates

categories: List<ProductCategory>

`Templates`¶

sealed class Templates {
    class PlainText : Templates()
}

`Templates.PlainText`¶

data class PlainText(
    val personalProject: String,
    val newProject: String,
    val existingProject: String,
    val type: String /* "plain_text" */,
)

Properties

personalProject: String The template provided for new grant applications when the grant requester is a personal project

newProject: String The template provided for new grant applications when the grant requester is a new project

existingProject: String The template provided for new grant applications when the grant requester is an existing project

type: String /* "plain_text" */ The type discriminator

`UserCriteria`¶

Describes some criteria which match a user

sealed class UserCriteria {
    abstract val id: String?
    abstract val type: String

    class Anyone : UserCriteria()
    class EmailDomain : UserCriteria()
    class WayfOrganization : UserCriteria()
}

This is used in conjunction with actions that require authorization.

Properties

id: String?

type: String

`UserCriteria.Anyone`¶

Matches any user

data class Anyone(
    val id: String?,
    val type: String,
    val type: String /* "anyone" */,
)

Properties

id: String?

type: String

type: String /* "anyone" */ The type discriminator

`UserCriteria.EmailDomain`¶

Matches any user with an email domain equal to domain

data class EmailDomain(
    val domain: String,
    val id: String?,
    val type: String,
    val type: String /* "email" */,
)

Properties

domain: String

id: String?

type: String

type: String /* "email" */ The type discriminator

`UserCriteria.WayfOrganization`¶

Matches any user with an organization matching org

data class WayfOrganization(
    val org: String,
    val id: String?,
    val type: String,
    val type: String /* "wayf" */,
)

The organization is currently derived from the information we receive from WAYF.

Properties

org: String

id: String?

type: String

type: String /* "wayf" */ The type discriminator

`GrantApplication.AllocationRequest`¶

data class AllocationRequest(
    val category: String,
    val provider: String,
    val grantGiver: String,
    val balanceRequested: Long?,
    val period: GrantApplication.Period,
    val type: String /* "allocation_request" */,
)

Properties

category: String

provider: String

grantGiver: String

balanceRequested: Long?

period: GrantApplication.Period

type: String /* "allocation_request" */ The type discriminator

`GrantRequestSettings`¶

data class GrantRequestSettings(
    val enabled: Boolean,
    val description: String,
    val allowRequestsFrom: List<UserCriteria>,
    val excludeRequestsFrom: List<UserCriteria>,
    val templates: Templates,
)

Properties

enabled: Boolean

description: String

allowRequestsFrom: List<UserCriteria>

excludeRequestsFrom: List<UserCriteria>

templates: Templates

`GrantsV2.Browse.Request`¶

The base type for requesting paginated content.

data class Request(
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
    val filter: GrantApplicationFilter?,
    val includeIngoingApplications: Boolean?,
    val includeOutgoingApplications: Boolean?,
)

Paginated content can be requested with one of the following consistency guarantees, this greatly changes the semantics of the call:

Consistency	Description
`PREFER`	Consistency is preferred but not required. An inconsistent snapshot might be returned.
`REQUIRE`	Consistency is required. A request will fail if consistency is no longer guaranteed.

The consistency refers to if collecting all the results via the pagination API are consistent. We consider the results to be consistent if it contains a complete view at some point in time. In practice this means that the results must contain all the items, in the correct order and without duplicates.

If you use the PREFER consistency then you may receive in-complete results that might appear out-of-order and can contain duplicate items. UCloud will still attempt to serve a snapshot which appears mostly consistent. This is helpful for user-interfaces which do not strictly depend on consistency but would still prefer something which is mostly consistent.

The results might become inconsistent if the client either takes too long, or a service instance goes down while fetching the results. UCloud attempts to keep each next token alive for at least one minute before invalidating it. This does not mean that a client must collect all results within a minute but rather that they must fetch the next page within a minute of the last page. If this is not feasible and consistency is not required then PREFER should be used.

📝 NOTE: Services are allowed to ignore extra criteria of the request if the next token is supplied. This is needed in order to provide a consistent view of the results. Clients should provide the same criterion as they paginate through the results.

Properties

itemsPerPage: Int? Requested number of items per page. Supported values: 10, 25, 50, 100, 250.

next: String? A token requesting the next page of items

consistency: PaginationRequestV2Consistency? Controls the consistency guarantees provided by the backend

itemsToSkip: Long? Items to skip ahead

filter: GrantApplicationFilter?

includeIngoingApplications: Boolean?

includeOutgoingApplications: Boolean?

`GrantsV2.DeleteComment.Request`¶

data class Request(
    val applicationId: String,
    val commentId: String,
)

Properties

applicationId: String

commentId: String

`GrantsV2.PostComment.Request`¶

data class Request(
    val applicationId: String,
    val comment: String,
)

Properties

applicationId: String

comment: String

`GrantsV2.RetrieveGrantGivers.Request`¶

sealed class Request {
    class ExistingApplication : Request()
    class ExistingProject : Request()
    class NewProject : Request()
    class PersonalWorkspace : Request()
}

`GrantsV2.RetrieveGrantGivers.Request.ExistingApplication`¶

data class ExistingApplication(
    val id: String,
    val type: String /* "ExistingApplication" */,
)

Properties

id: String

type: String /* "ExistingApplication" */ The type discriminator

`GrantsV2.RetrieveGrantGivers.Request.ExistingProject`¶

data class ExistingProject(
    val id: String,
    val type: String /* "ExistingProject" */,
)

Properties

id: String

type: String /* "ExistingProject" */ The type discriminator

`GrantsV2.RetrieveGrantGivers.Request.NewProject`¶

data class NewProject(
    val title: String,
    val type: String /* "NewProject" */,
)

Properties

title: String

type: String /* "NewProject" */ The type discriminator

`GrantsV2.RetrieveGrantGivers.Request.PersonalWorkspace`¶

data class PersonalWorkspace(
    val type: String /* "PersonalWorkspace" */,
)

Properties

type: String /* "PersonalWorkspace" */ The type discriminator

`GrantsV2.RetrieveLogo.Request`¶

data class Request(
    val projectId: String,
)

Properties

projectId: String

`GrantsV2.SubmitRevision.Request`¶

data class Request(
    val revision: GrantApplication.Document,
    val comment: String,
    val applicationId: String?,
)

Properties

revision: GrantApplication.Document

comment: String

applicationId: String?

`GrantsV2.Transfer.Request`¶

data class Request(
    val applicationId: String,
    val target: String,
    val comment: String,
)

Properties

applicationId: String

target: String

comment: String

`GrantsV2.UpdateState.Request`¶

data class Request(
    val applicationId: String,
    val newState: GrantApplication.State,
)

Properties

applicationId: String

newState: GrantApplication.State

`GrantsV2.RetrieveGrantGivers.Response`¶

data class Response(
    val grantGivers: List<GrantGiver>,
)

Properties

grantGivers: List<GrantGiver>

Allocation Process¶

Rationale¶

Table of Contents¶

Remote Procedure Calls¶

browse¶

retrieve¶

retrieveLogo¶

retrieveRequestSettings¶

deleteComment¶

postComment¶

retrieveGrantGivers¶

submitRevision¶

transfer¶

updateRequestSettings¶

updateState¶

uploadLogo¶

Data Models¶

GrantApplication¶

GrantApplication.Comment¶

GrantApplication.Document¶

GrantApplication.Form¶

GrantApplication.Form.GrantGiverInitiated¶

GrantApplication.Form.PlainText¶

GrantApplication.GrantGiverApprovalState¶

GrantApplication.Period¶

GrantApplication.Recipient¶

GrantApplication.Recipient.ExistingProject¶

GrantApplication.Recipient.NewProject¶

GrantApplication.Recipient.PersonalWorkspace¶

GrantApplication.Revision¶

GrantApplication.State¶

GrantApplication.Status¶

GrantApplicationFilter¶

GrantGiver¶

Templates¶

Templates.PlainText¶

UserCriteria¶

UserCriteria.Anyone¶

UserCriteria.EmailDomain¶

UserCriteria.WayfOrganization¶

GrantApplication.AllocationRequest¶

GrantRequestSettings¶

GrantsV2.Browse.Request¶

GrantsV2.DeleteComment.Request¶

GrantsV2.PostComment.Request¶

GrantsV2.RetrieveGrantGivers.Request¶

GrantsV2.RetrieveGrantGivers.Request.ExistingApplication¶

GrantsV2.RetrieveGrantGivers.Request.ExistingProject¶

GrantsV2.RetrieveGrantGivers.Request.NewProject¶

GrantsV2.RetrieveGrantGivers.Request.PersonalWorkspace¶

GrantsV2.RetrieveLogo.Request¶

GrantsV2.SubmitRevision.Request¶

GrantsV2.Transfer.Request¶

GrantsV2.UpdateState.Request¶

GrantsV2.RetrieveGrantGivers.Response¶

`browse`¶

`retrieve`¶

`retrieveLogo`¶

`retrieveRequestSettings`¶

`deleteComment`¶

`postComment`¶

`retrieveGrantGivers`¶

`submitRevision`¶

`transfer`¶

`updateRequestSettings`¶

`updateState`¶

`uploadLogo`¶

`GrantApplication`¶

`GrantApplication.Comment`¶

`GrantApplication.Document`¶

`GrantApplication.Form`¶

`GrantApplication.Form.GrantGiverInitiated`¶

`GrantApplication.Form.PlainText`¶

`GrantApplication.GrantGiverApprovalState`¶

`GrantApplication.Period`¶

`GrantApplication.Recipient`¶

`GrantApplication.Recipient.ExistingProject`¶

`GrantApplication.Recipient.NewProject`¶

`GrantApplication.Recipient.PersonalWorkspace`¶

`GrantApplication.Revision`¶

`GrantApplication.State`¶

`GrantApplication.Status`¶

`GrantApplicationFilter`¶

`GrantGiver`¶

`Templates`¶

`Templates.PlainText`¶

`UserCriteria`¶

`UserCriteria.Anyone`¶

`UserCriteria.EmailDomain`¶

`UserCriteria.WayfOrganization`¶

`GrantApplication.AllocationRequest`¶

`GrantRequestSettings`¶

`GrantsV2.Browse.Request`¶

`GrantsV2.DeleteComment.Request`¶

`GrantsV2.PostComment.Request`¶

`GrantsV2.RetrieveGrantGivers.Request`¶

`GrantsV2.RetrieveGrantGivers.Request.ExistingApplication`¶

`GrantsV2.RetrieveGrantGivers.Request.ExistingProject`¶

`GrantsV2.RetrieveGrantGivers.Request.NewProject`¶

`GrantsV2.RetrieveGrantGivers.Request.PersonalWorkspace`¶

`GrantsV2.RetrieveLogo.Request`¶

`GrantsV2.SubmitRevision.Request`¶

`GrantsV2.Transfer.Request`¶

`GrantsV2.UpdateState.Request`¶

`GrantsV2.RetrieveGrantGivers.Response`¶