Skip to navigation
Concepts

Connected services

Use the services your organization works with, through the same key.
View as Markdown

A connected service is a system outside Basement that your organization uses: a service desk, an issue tracker, a knowledge base. A person connects an account of the service in Connections. After that, agents and programs can use the tools of that service through the Gateway.

Services you can connect

ServiceWhat a key can do
Jira (and Confluence)Search and read issues and pages, create and change them. Sign in with Atlassian, or use an email and an API token.
GLPISearch and read tickets, the knowledge base and users. Create tickets, add follow-ups and solutions, change and assign tickets.
MultiDadosSearch and read tickets with their history and attachments. Create tickets, reply, change status, and schedule a reply or a change for later.
Any MCP serverConnect a server with a token, custom headers or OAuth. Its tools become available through the Gateway.

An admin sets a service up one time for the organization. Then each member connects their own account, and their agents act as them.

Whose account a key uses

A connection is private to the person who made it, or shared with the organization. A key uses the connections that the person who connected the key can use. A key never reaches another person’s private connection.

For a service desk, this means an agent sees the tickets that its person sees, and writes as that person.

Read and write

Each tool of a service is a read tool or a write tool. An access level gives a key read, or read and write, for each service:

  • With read, the key lists the service’s tools and calls the read tools. A write tool answers 403.
  • With read and write, the key calls every tool.

How to call a service

Three tools give access to every connected service:

1

List the services

list_connected_services answers the services the key can use, and each connection with its connectionId.

2

List the tools of a service

list_service_tools answers the tools of one service. Each tool has a toolSlug (for example jira__getJiraIssue), a description, the schema of its arguments, whether it reads or writes, and whether this key can call it.

3

Run a tool

execute_service_tool runs a tool. Give the toolSlug and the tool’s arguments.

const { tools } = await basement.services.listTools({ toolkitSlug: "jira" });
const result = await basement.services.execute({
  toolSlug: "jira__getJiraIssue",
  arguments: { issueIdOrKey: "OPS-12" },
});

The answer is what the service answered. When the service fails or refuses the call, the HTTP API answers 502 with the service’s message.