JetBrains Space Help

Work with Space

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 recipient = MessageRecipient.Channel(ChatChannel.FromName("CI-channel")) val content = ChatMessage.Text("Build failed") api.space().chats.messages.sendMessage(recipient, content) } } } }

The space() API is a Space HTTP API client that works by sending HTTP requests to Space.

How the API client authorizes in 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).

To change permissions of the Automation service account

  1. Open the required project, then Settings.

  2. In the Access tab, find the Automation Service role and change the permissions.

How to make the work with the API client easier

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

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:

Example. Creating an issue

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 must grant the Create Issues permission.

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 ) } } } }
Last modified: 27 September 2021