Interact with other Space Modules
The kotlinScript
block provides the space()
API that lets you work with other Space modules like Chats, Issues, Documents, and so on.
For example, this is how you can send a message to a channel from a job:
job("Build and publish") {
container(displayName = "Build and notify", image = "gradle:7.1-jre11") {
kotlinScript { api ->
try {
api.gradle("build")
} catch (ex: Exception) {
val channel = ChannelIdentifier.Channel(ChatChannel.FromName("CI-channel"))
val content = ChatMessage.Text("Build failed")
api.space().chats.messages.sendMessage(channel = channel, content = content)
}
}
}
}
The space()
API is a Space HTTP API client that works by sending HTTP requests to Space.
To authorize in Space, the space()
API client uses an Automation service account. When you create a project, Space creates this account based on the Automation Service role.
The service account exists only in the project scope and doesn't have any global permissions. This means that the space()
client can work only with Space modules within the current project (for example, Issues, Documents, Checklists, and so on) or with Space modules that don't check permissions (for example, Chats).
Open the required project, then Settings.
In the Access tab, find the Automation Service role and change the permissions.
As the space()
API client uses the Space HTTP API, the best place to look for particular code snippets is the Space API Playground. Here you can find the required API request, check the required permissions, and get a Kotlin code snippet (switch the code snippet panel to Kotlin SDK):
![API Playground API Playground](https://resources.jetbrains.com/help/img/space/automation_api_playground.png)
One more way to ease working with the client is to edit your .space.kts
file in IntelliJ IDEA with the installed Space plugin (starting IntelliJ IDEA 2021.1, the plugin is bundled with the IDE). The plugin provides code completion for the Automation DSL and for the space()
client APIs:
The following job builds a Gradle project and if the build fails, creates an issue. In order for this job to work, the Automation Service role in your project must have the Create Issues permission, which you can enable for this role in Project Settings → Access.
job("Build") {
container(displayName = "Create issue on build fail", image = "gradle") {
kotlinScript { api ->
try {
api.gradle("build")
} catch (ex: Exception) {
// get project Id
val id = api.projectId()
// get current build run number
val runNumber = api.executionNumber()
//get all issue statuses
val statuses = api.space().projects.planning.issues.statuses.
getAllIssueStatuses(project = ProjectIdentifier.Id(id))
//get id of 'Open' issue status
val openStatusId = statuses.find { it.name == "Open" }?.id
?: throw kotlin.Exception("The 'Open' state doesn't exist in the project")
// create issue with 'Open' status
api.space().projects.planning.issues.createIssue(
project = ProjectIdentifier.Id(id),
// generate name based on build run number
title = "Job 'Build and publish' #$runNumber failed",
description = "${ex.message}",
status = openStatusId
)
}
}
}
}
Thanks for your feedback!