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 using
Grants.submitApplication
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
Reviewer either performs
Grants.updateApplicationState
to approve or rejectIf the
GrantApplication
was approved then resources are granted to theGrantApplication.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
Remote Procedure Calls¶
browseAffiliationsByResource
¶
Request | Response | Error |
---|---|---|
GrantsBrowseAffiliationsByResourceRequest |
PageV2<ProjectWithTitle> |
CommonErrorMessage |
browseApplications
¶
List active GrantApplication
s
Request | Response | Error |
---|---|---|
BrowseApplicationsRequest |
PageV2<GrantApplication> |
CommonErrorMessage |
Lists active GrantApplication
s which are relevant to a project. By using
BrowseApplicationFlags
it is possible to filter on ingoing and/or outgoing.
browseProducts
¶
Request | Response | Error |
---|---|---|
GrantsBrowseProductsRequest |
GrantsBrowseProductsResponse |
CommonErrorMessage |
browseProjects
¶
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
¶
Request | Response | Error |
---|---|---|
GrantsBrowseAffiliationsRequest |
PageV2<ProjectWithTitle> |
CommonErrorMessage |
viewApplication
¶
Retrieves an active GrantApplication
Request | Response | Error |
---|---|---|
RetrieveApplicationRequest |
GrantApplication |
CommonErrorMessage |
Only the creator and grant reviewers are allowed to view any given GrantApplication
closeApplication
¶
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
¶
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
¶
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
¶
Transfers allocation request to other root project
Request | Response | Error |
---|---|---|
BulkRequest<TransferApplicationRequest> |
Unit |
CommonErrorMessage |
updateApplicationState
¶
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
¶
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
¶
Matches any user
data class Anyone(
val type: String /* "anyone" */,
)
Properties
type
: String /* "anyone" */
The type discriminator
String /* "anyone" */
UserCriteria.EmailDomain
¶
Matches any user with an email domain equal to domain
data class EmailDomain(
val domain: String,
val type: String /* "email" */,
)
UserCriteria.WayfOrganization
¶
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.
CreateApplication
¶
data class CreateApplication(
val document: GrantApplication.Document,
)
Properties
document
: GrantApplication.Document
GrantApplication.Document
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
String
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
String
createdAt
: Long
Timestamp representing when the application was originially submitted
Long
updatedAt
: Long
Timestamp representing when the application was last updated
Long
currentRevision
: GrantApplication.Revision
Information about the current revision
GrantApplication.Revision
status
: GrantApplication.Status
Status information about the application in its entireity
GrantApplication.Status
GrantApplication.Comment
¶
data class Comment(
val id: String,
val username: String,
val createdAt: Long,
val comment: String,
val type: String /* "comment" */,
)
GrantApplication.Document
¶
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
GrantApplication.Recipient
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
List<GrantApplication.AllocationRequest>
Updateable by: Original creator and grant givers Immutable after creation: No
form
: GrantApplication.Form
A form describing why these resources are being requested
GrantApplication.Form
Updateable by: Original creator Immutable after creation: No
referenceId
: String?
A reference used for out-of-band book-keeping
String?
Updateable by: Grant givers Immutable after creation: No
revisionComment
: String?
A comment describing why this change was made
String?
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.
String?
type
: String /* "document" */
The type discriminator
String /* "document" */
GrantApplication.Form
¶
sealed class Form {
abstract val type: String /* "form" */
class PlainText : Form()
}
Properties
type
: String /* "form" */
The type discriminator
String /* "form" */
GrantApplication.Form.PlainText
¶
data class PlainText(
val text: String,
val type: String /* "plain_text" */,
)
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
String
projectTitle
: String
String
state
: GrantApplication.State
GrantApplication.State
type
: String /* "grant_giver_approval_state" */
The type discriminator
String /* "grant_giver_approval_state" */
GrantApplication.Period
¶
data class Period(
val start: Long?,
val end: Long?,
val type: String /* "period" */,
)
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
String /* "recipient" */
GrantApplication.Recipient.ExistingProject
¶
data class ExistingProject(
val id: String,
val type: String /* "existingProject" */,
)
GrantApplication.Recipient.NewProject
¶
data class NewProject(
val title: String,
val type: String /* "newProject" */,
)
GrantApplication.Recipient.PersonalWorkspace
¶
data class PersonalWorkspace(
val username: String,
val type: String /* "personalWorkspace" */,
)
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
Long
updatedBy
: String
Username of the user who created this revision
String
revisionNumber
: Int
A number indicating which revision this is
Int
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
GrantApplication.Document
type
: String /* "revision" */
The type discriminator
String /* "revision" */
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
GrantApplication.State
stateBreakdown
: List<GrantApplication.GrantGiverApprovalState>
List<GrantApplication.GrantGiverApprovalState>
comments
: List<GrantApplication.Comment>
List<GrantApplication.Comment>
revisions
: List<GrantApplication.Revision>
List<GrantApplication.Revision>
projectTitle
: String?
String?
projectPI
: String
String
type
: String /* "status" */
The type discriminator
String /* "status" */
GrantApplicationFilter
¶
enum class GrantApplicationFilter {
SHOW_ALL,
ACTIVE,
INACTIVE,
}
Properties
SHOW_ALL
ACTIVE
INACTIVE
ProjectWithTitle
¶
data class ProjectWithTitle(
val projectId: String,
val title: String,
)
UpdateApplicationState
¶
data class UpdateApplicationState(
val applicationId: Long,
val newState: GrantApplication.State,
val notify: Boolean?,
)
BrowseApplicationsRequest
¶
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?
GrantApplicationFilter?
includeIngoingApplications
: Boolean?
Boolean?
includeOutgoingApplications
: Boolean?
Boolean?
itemsPerPage
: Int?
Requested number of items per page. Supported values: 10, 25, 50, 100, 250.
Int?
next
: String?
A token requesting the next page of items
String?
consistency
: PaginationRequestV2Consistency?
Controls the consistency guarantees provided by the backend
PaginationRequestV2Consistency?
itemsToSkip
: Long?
Items to skip ahead
Long?
BrowseProjectsRequest
¶
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.
Int?
next
: String?
A token requesting the next page of items
String?
consistency
: PaginationRequestV2Consistency?
Controls the consistency guarantees provided by the backend
PaginationRequestV2Consistency?
itemsToSkip
: Long?
Items to skip ahead
Long?
CloseApplicationRequest
¶
data class CloseApplicationRequest(
val applicationId: String,
)
Properties
applicationId
: String
String
EditApplicationRequest
¶
data class EditApplicationRequest(
val applicationId: Long,
val document: GrantApplication.Document,
)
GrantApplication.AllocationRequest
¶
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" */,
)
GrantsBrowseAffiliationsByResourceRequest
¶
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.
Int?
next
: String?
A token requesting the next page of items
String?
consistency
: PaginationRequestV2Consistency?
Controls the consistency guarantees provided by the backend
PaginationRequestV2Consistency?
itemsToSkip
: Long?
Items to skip ahead
Long?
applicationId
: String
String
GrantsBrowseAffiliationsRequest
¶
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.
Int?
next
: String?
A token requesting the next page of items
String?
consistency
: PaginationRequestV2Consistency?
Controls the consistency guarantees provided by the backend
PaginationRequestV2Consistency?
itemsToSkip
: Long?
Items to skip ahead
Long?
GrantsBrowseProductsRequest
¶
data class GrantsBrowseProductsRequest(
val projectId: String,
val recipientType: String,
val recipientId: String,
val showHidden: Boolean?,
)
RetrieveApplicationRequest
¶
data class RetrieveApplicationRequest(
val id: Long,
)
Properties
id
: Long
Long
TransferApplicationRequest
¶
data class TransferApplicationRequest(
val applicationId: Long,
val transferToProjectId: String,
val revisionComment: String,
)
GrantsBrowseProductsResponse
¶
data class GrantsBrowseProductsResponse(
val availableProducts: List<Product>,
)