> ## Documentation Index > Fetch the complete documentation index at: https://hoopdev-docs-improve-idp-sso-pages.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Runbook Exec > Start a execution using a Runbook as input. If the connection has a JIRA issue template configured, it will create a JIRA issue. ## OpenAPI ````yaml https://use.hoop.dev/api/openapiv3.json post /plugins/runbooks/connections/{name}/exec openapi: 3.0.3 info: contact: email: help@hoop.dev name: Help url: https://help.hoop.dev description: >- Hoop.dev is an access gateway for databases and servers with an API for packet manipulation license: name: MIT url: https://opensource.org/license/mit termsOfService: https://hoop.dev/docs/legal/tos title: Hoop Api version: 1.49.10 servers: - url: https://use.hoop.dev/api security: [] tags: - description: > Hoop implements Oauth2 and OIDC protocol to authenticate users in the system. To obtain a valid access token users need to authenticate in their own identity provider which is generated as a JSON response to the endpoint `http(s)://use.hoop.dev/api/login`. The identity provider them redirects the user to the callback endpoint containing the access token. The recommended approach of obtaining an access token is by visiting the Webapp main's page or using the **Hoop command line**. Example: ```sh hoop config create --api-url https://use.hoop.dev # save the token after authenticating at $HOME/.hoop/config.toml hoop login # show token information hoop config view --raw ``` With an access token you could use any HTTP client to interact with the documented endpoints. The token must be sent through the `Authorization` header. Example: ```sh # obtain the current configuration of the server curl https://use.hoop.dev/api/serverinfo -H "Authorization: Bearer $ACCESS_TOKEN" ``` name: Authentication - description: > Users are active and assigned to the default organization when they signup. A user could be set to an inactive state preventing it from accessing the platform, however it’s recommended to manage the state of users in the identity provider. - The `sub` claim is used as the main identifier of the user in the platform. - The profile of the user is derived from the id_token claims `email` and `name`. When a user authenticates for the first time, it performs an automatic signup that persist the profile claims along with it’s unique identifier. ​ ### Groups Groups allows defining who may access or interact with certain resources. - For connection resources it’s possible to define which groups has access to a specific connection, this is enforced when the Access Control feature is enabled. - For review resources, it’s possible to define which groups are allowed to approve an execution, this is enforced when the Review feature is enabled. > This resource could be managed manually via Webapp or propagated by the identity provider via ID Token. In this mode, groups are sync when a user performs a login. ### Roles - The `admin` group is a special role that grants full access to all resources This role should be granted to users that are responsible for managing the Gateway. All other users are regular, meaning that they can access their own resources and interact with connections. name: User Management - description: Routes used to manage and obtain information about the runtime server. name: Server Management - description: Features available in the gateway. See also **Plugin** resources. name: Features - description: >- Proxy manager endpoints controls how clients connect via gRPC in the gateway. These endpoints are meant to be used when a client is initialized via `hoop proxy-manager`. name: Proxy Manager - name: Connections - name: Agents - name: Runbooks - name: Guard Rails - name: Reviews - name: Sessions - name: Organization Management - name: Reports paths: /plugins/runbooks/connections/{name}/exec: post: tags: - Runbooks summary: Runbook Exec description: >- Start a execution using a Runbook as input. If the connection has a JIRA issue template configured, it will create a JIRA issue. parameters: - description: The name of the connection in: path name: name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/openapi.RunbookRequest' description: The request body resource required: true x-originalParamName: request responses: '200': content: application/json: schema: $ref: '#/components/schemas/openapi.ExecResponse' description: The execution has finished '202': content: application/json: schema: $ref: '#/components/schemas/openapi.ExecResponse' description: The execution is still in progress '400': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Bad Request '404': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Not Found '422': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Internal Server Error components: schemas: openapi.RunbookRequest: properties: client_args: description: Additional arguments to pass down to the connection example: - '--verbose' items: type: string type: array env_vars: additionalProperties: type: string description: >- Environment Variables that will be included in the runtime * { envvar:[env-key]: [base64-val] } - Expose the value as environment variable * { filesystem:[env-key]: [base64-val] } - Expose the value as a temporary file path creating the value in the filesystem example: envvar: PASSWORD:MTIz filesystem: SECRET_FILE:bXlzZWNyZXQ= type: object file_name: description: The relative path name of the runbook file from the git source example: myrunbooks/run-backup.runbook.sql type: string jira_fields: additionalProperties: type: string description: Jira fields to create a Jira issue type: object metadata: additionalProperties: {} description: Metadata attributes to add in the session type: object parameters: additionalProperties: type: string description: >- The parameters of the runbook. It must match with the declared attributes example: amount: '10' wallet_id: '6736' type: object ref_hash: description: The commit sha reference to obtain the file example: 20320ebbf9fc612256b67dc9e899bbd6e4745c77 type: string required: - file_name type: object openapi.ExecResponse: properties: execution_time: description: The amount of time the execution took in miliseconds example: 5903 type: integer exit_code: description: >- The shell exit code, any non zero code means an error * 0 - Linux success exit code * -2 - internal gateway code that means it was unable to obtain a valid exit code number from the agent outcome packet * 254 - internal agent code that means it was unable to obtain a valid exit code number from the process example: 1 type: integer has_review: description: Inform if the connection has review enabled example: false type: boolean output: description: >- Output contains an utf-8 output containing the outcome of the ad-hoc execution type: string output_status: description: >- Status reports if the outcome of the execution * success - The execution was executed with success * failed - In case of internal error or when the agent returns an exit code greater than 0 or different than -2 * running - The execution may still be running. enum: - success - failed - running example: failed type: string session_id: description: Each execution creates a unique session id example: 5701046A-7B7A-4A78-ABB0-A24C95E6FE54 format: uuid type: string truncated: description: If the `output`` field is truncated or not example: false type: boolean type: object openapi.HTTPError: properties: message: example: the error description type: string type: object ````