Allocation Process

API: Stable

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:

  1. User submits application to relevant project using Grants.submitApplication

  2. All grant approvers must review the application

    • User and reviewer can comment on the application via GrantComments.createComment

    • User and reviewer can perform edits to the application via Grants.editApplication

  3. Reviewer either performs Grants.updateApplicationState to approve or reject

  4. If the GrantApplication was approved then resources are granted to the GrantApplication.recipient

Table of Contents

1. Remote Procedure Calls
Name Description
browseAffiliationsByResource No description
browseApplications List active [`GrantApplication`](/docs/reference/dk.sdu.cloud.grant.api.GrantApplication.md)s
browseProducts No description
browseProjects Endpoint for users to browse projects which they can send a [`GrantApplication`](/docs/reference/dk.sdu.cloud.grant.api.GrantApplication.md) to
retrieveAffiliations No description
viewApplication Retrieves an active [`GrantApplication`](/docs/reference/dk.sdu.cloud.grant.api.GrantApplication.md)
closeApplication Closes an existing [`GrantApplication`](/docs/reference/dk.sdu.cloud.grant.api.GrantApplication.md)
editApplication Performs an edit to an existing [`GrantApplication`](/docs/reference/dk.sdu.cloud.grant.api.GrantApplication.md)
submitApplication Submits a [`GrantApplication`](/docs/reference/dk.sdu.cloud.grant.api.GrantApplication.md) to a project
transferApplication Transfers allocation request to other root project
updateApplicationState Approves or rejects an existing [`GrantApplication`](/docs/reference/dk.sdu.cloud.grant.api.GrantApplication..md) If accepted by all grant givers this will trigger granting of resources to the `GrantApplication.Document.recipient`.
2. Data Models
Name 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`
CreateApplication No description
GrantApplication No description
GrantApplication.Comment No description
GrantApplication.Document No description
GrantApplication.Form 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
ProjectWithTitle No description
UpdateApplicationState No description
BrowseApplicationsRequest The base type for requesting paginated content.
BrowseProjectsRequest The base type for requesting paginated content.
CloseApplicationRequest No description
EditApplicationRequest No description
GrantApplication.AllocationRequest No description
GrantsBrowseAffiliationsByResourceRequest The base type for requesting paginated content.
GrantsBrowseAffiliationsRequest The base type for requesting paginated content.
GrantsBrowseProductsRequest No description
RetrieveApplicationRequest No description
TransferApplicationRequest No description
GrantsBrowseProductsResponse No description

Remote Procedure Calls

browseAffiliationsByResource

API: Stable Auth: Users

Request Response Error
GrantsBrowseAffiliationsByResourceRequest PageV2<ProjectWithTitle> CommonErrorMessage

browseApplications

API: Stable Auth: Users

List active GrantApplications

Request Response Error
BrowseApplicationsRequest PageV2<GrantApplication> CommonErrorMessage

Lists active GrantApplications which are relevant to a project. By using BrowseApplicationFlags it is possible to filter on ingoing and/or outgoing.

browseProducts

API: Stable Auth: Users

Request Response Error
GrantsBrowseProductsRequest GrantsBrowseProductsResponse CommonErrorMessage

browseProjects

API: Stable Auth: Users

Endpoint for users to browse projects which they can send a GrantApplication to

Request Response Error
BrowseProjectsRequest PageV2<ProjectWithTitle> CommonErrorMessage

Concretely, this will return a list for which the user matches the criteria listed in ProjectApplicationSettings.allowRequestsFrom.

retrieveAffiliations

API: Stable Auth: Users

Request Response Error
GrantsBrowseAffiliationsRequest PageV2<ProjectWithTitle> CommonErrorMessage

viewApplication

API: Stable Auth: Users

Retrieves an active GrantApplication

Request Response Error
RetrieveApplicationRequest GrantApplication CommonErrorMessage

Only the creator and grant reviewers are allowed to view any given GrantApplication

closeApplication

API: Stable Auth: Users

Closes an existing GrantApplication

Request Response Error
BulkRequest<CloseApplicationRequest> Unit CommonErrorMessage

This action is identical to rejecting the GrantApplication using updateApplicationState except it can be performed by the GrantApplication creator.

editApplication

API: Stable Auth: Users

Performs an edit to an existing GrantApplication

Request Response Error
BulkRequest<EditApplicationRequest> Unit CommonErrorMessage

Both the creator and any of the grant reviewers are allowed to edit the application.

submitApplication

API: Stable Auth: Users

Submits a GrantApplication to a project

Request Response Error
BulkRequest<CreateApplication> BulkResponse<FindByLongId> CommonErrorMessage

In order for the user to submit an application they must match any criteria in ProjectApplicationSettings.allowRequestsFrom. If they are not the request will fail.

transferApplication

API: Stable Auth: Authenticated

Transfers allocation request to other root project

Request Response Error
BulkRequest<TransferApplicationRequest> Unit CommonErrorMessage

updateApplicationState

API: Stable Auth: Users

Approves or rejects an existing GrantApplication If accepted by all grant givers this will trigger granting of resources to the GrantApplication.Document.recipient.

Request Response Error
BulkRequest<UpdateApplicationState> Unit CommonErrorMessage

Only the grant reviewer can perform this action.

Data Models

UserCriteria

API: Stable

Describes some criteria which match a user

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

This is used in conjunction with actions that require authorization.


UserCriteria.Anyone

API: Stable

Matches any user

data class Anyone(
    val type: String /* "anyone" */,
)
Properties
type: String /* "anyone" */ The type discriminator

UserCriteria.EmailDomain

API: Stable

Matches any user with an email domain equal to domain

data class EmailDomain(
    val domain: String,
    val type: String /* "email" */,
)
Properties
domain: String
type: String /* "email" */ The type discriminator

UserCriteria.WayfOrganization

API: Stable

Matches any user with an organization matching org

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

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

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

CreateApplication

API: Stable

data class CreateApplication(
    val document: GrantApplication.Document,
)
Properties
document: GrantApplication.Document

GrantApplication

API: Stable

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 entireity

GrantApplication.Comment

API: Stable

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

API: Stable

data class Document(
    val recipient: GrantApplication.Recipient,
    val allocationRequests: List<GrantApplication.AllocationRequest>,
    val form: GrantApplication.Form,
    val referenceId: 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

referenceId: String? A reference used for out-of-band book-keeping

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

API: Stable

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

    class PlainText : Form()
}
Properties
type: String /* "form" */ The type discriminator

GrantApplication.Form.PlainText

API: Stable

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

GrantApplication.GrantGiverApprovalState

API: Stable

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

API: Stable

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

API: Stable

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

API: Stable

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

GrantApplication.Recipient.NewProject

API: Stable

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

GrantApplication.Recipient.PersonalWorkspace

API: Stable

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

GrantApplication.Revision

API: Stable

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

API: Stable

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

GrantApplication.Status

API: Stable

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

API: Stable

enum class GrantApplicationFilter {
    SHOW_ALL,
    ACTIVE,
    INACTIVE,
}
Properties
SHOW_ALL
ACTIVE
INACTIVE

ProjectWithTitle

API: Stable

data class ProjectWithTitle(
    val projectId: String,
    val title: String,
)
Properties
projectId: String
title: String

UpdateApplicationState

API: Stable

data class UpdateApplicationState(
    val applicationId: Long,
    val newState: GrantApplication.State,
    val notify: Boolean?,
)
Properties
applicationId: Long
newState: GrantApplication.State
notify: Boolean?

BrowseApplicationsRequest

API: Stable

The base type for requesting paginated content.

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

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
filter: GrantApplicationFilter?
includeIngoingApplications: Boolean?
includeOutgoingApplications: Boolean?
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

BrowseProjectsRequest

API: Stable

The base type for requesting paginated content.

data class BrowseProjectsRequest(
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
)

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

CloseApplicationRequest

API: Stable

data class CloseApplicationRequest(
    val applicationId: String,
)
Properties
applicationId: String

EditApplicationRequest

API: Stable

data class EditApplicationRequest(
    val applicationId: Long,
    val document: GrantApplication.Document,
)
Properties
applicationId: Long
document: GrantApplication.Document

GrantApplication.AllocationRequest

API: Stable

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

GrantsBrowseAffiliationsByResourceRequest

API: Stable

The base type for requesting paginated content.

data class GrantsBrowseAffiliationsByResourceRequest(
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
    val applicationId: String,
)

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
applicationId: String

GrantsBrowseAffiliationsRequest

API: Stable

The base type for requesting paginated content.

data class GrantsBrowseAffiliationsRequest(
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
)

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

GrantsBrowseProductsRequest

API: Stable

data class GrantsBrowseProductsRequest(
    val projectId: String,
    val recipientType: String,
    val recipientId: String,
    val showHidden: Boolean?,
)
Properties
projectId: String
recipientType: String
recipientId: String
showHidden: Boolean?

RetrieveApplicationRequest

API: Stable

data class RetrieveApplicationRequest(
    val id: Long,
)
Properties
id: Long

TransferApplicationRequest

API: Stable

data class TransferApplicationRequest(
    val applicationId: Long,
    val transferToProjectId: String,
    val revisionComment: String,
)
Properties
applicationId: Long
transferToProjectId: String
revisionComment: String

GrantsBrowseProductsResponse

API: Stable

data class GrantsBrowseProductsResponse(
    val availableProducts: List<Product>,
)
Properties
availableProducts: List<Product>