{ "openapi": "3.0.0", "info": { "description": "## Runbook Automation – API Documentation\n\nRunbook Automation is responsible for the management of runbooks, runbook instances, actions, action instances, and\ntriggers.\n\n**Runbooks** are structured operational procedures which can be created, changed, and executed. They may include\nseveral types of actions. As runbooks may contain any mix of manual and automated steps, they can be run in\ndifferent way: Manual, semi-automated, or fully-automated.\n\n**Runbook instances** are the execution records of runbooks. They contain the status and details of one specific\nexecution and can be changed to step through an execution and finish it.\n\n**Actions** are re-usable automated actions that can be run independently or as part of a runbook. Runbook\nAutomation supports three different types of actions: HTTP actions, script actions, and Ansible actions.\n\n**Action instances** are the execution records of actions. Similarly to runbook instances for runbooks. They contain\nthe status and details of one specific execution of an action.\n\ncreate a link between incoming events and the proper response by executing the linked runbook with the data from the\nevent.\n\nAdditionally other administrative functions are presented in the API, including configuration and user management.\nSome of the additional functions may be inapplicable depending on the deployment option chosen for Runbook Automation.\n\n---\n\n**IMPORTANT:** Some APIs in this list are deprecated and replaced by v2 APIs. To find the new APIs, see the Cloud Pak for AIOps v2 API topic.\n\n---\n", "version": "0.0.0", "title": "Runbook Automation" }, "tags": [ { "name": "Runbook", "description": "Managing runbook objects" }, { "name": "Runbook instance", "description": "Managing instances of runbooks" }, { "name": "Action", "description": "Managing action objects" }, { "name": "Action instance", "description": "Managing instances of actions" }, { "name": "User", "description": "Operations about users" }, { "name": "Configuration", "description": "Managing configuration" }, { "name": "Tag", "description": "Retrieving runbook tags" }, { "name": "Statistics", "description": "Retrieving usage statistics" }, { "name": "Status", "description": "Get status of Runbook Automation" } ], "paths": { "/runbooks": { "get": { "summary": "Get all runbooks", "operationId": "getRunbookAll", "description": "# Get multiple Runbooks\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the v2 API endpoint `/aiops/api/v2/configuration/runbooks`. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nUse this API endpoint to retrieve several runbooks at once. This call\nsupports multiple query parameters to filter the output to the desired\nrunbooks. The output in JSON format will always be an array.\n\n\n## Query parameters\n\nBy default the latest versions of all runbooks are returned. Use the\nfollowing query parameters to limit the number of runbooks displayed and\nshape the output the way you need it.\n\n\n* **version**: Optional. Define which version or which versions of the runbooks\nshould be returned.\n * **draft** – return only the drafts of the runbooks. Drafts always have the version '0'. Every runbook always has a draft version. In case no changes have been applied after publishing/approving the content of the draft will be equal to the one of the latest version.\n * **approved** – return only the latest approved/published version. A runbook draft without an approved/published version will not show up in the result of this call.\n * **latest** – this is the default setting. Return only the latest version of a runbook. If a runbook has no approved/published version, the draft will be included in the result.\n * **all** – return all versions. This option will return all versions from each runbook.\n* **exportFormat**: Optional. Allows you to create data that can later be imported. The specifics of this\noperation are explained in the extra section below.\n * **true** – Standard export\n * **keepId** – ID preserving export\n * **false** – Does not convert output to export format (default)\n* **fields**: Optional. Restrict the output to the fields specified in this query parameter. You can define any\nnumber of fields in a comma separated list. All fields not present in this call will be stripped away. Using\nthis option reduces the amount of transferred data and may yield increased performance.\n* **filterByTag**: Optional. Restrict the returned runbooks to those that have the\nspecified tag. Runbooks without that tag will not be retrieved.\n* **filterById**: Optional. Comma-separated list of runbook IDs. Restrict the returned runbooks to those\ncontained in this list. Each runbook ID may also define a version using the notation\n`@`. Note however that *filterById* and *version* query parameters are used in\nconjunction. That means a specific runbook will only be returned, if the specific runbook is both included via\nthe *version* filter and included via the *filterById* filter. In order to only use *filterById* for arbitrarily\nselecting runbook versions set *version* to *all*.\n* **context**: Optional. Generate a set of statistics for each runbook. The context statistics are named *contextStats* which only\nconsider runbook executions within the given context. Setting the *context* query parameter will not have any\neffect if *exportFormat* is enabled or *fields* is set, but does not contain *contextStats*.\n\n## Access Rights\n\nAccess to runbooks is limited for users with the user role. Users with roles of author, approver, or manager can always access all\nrunbooks and all versions of a runbook. The following list provides details, how restrictions for the user role apply.\n\n * **Drafts**: The User Role cannot access any draft.\n * **Groups**: If the group feature is enabled, the User Role can only access runbooks, if the user and the runbook belong at least to one common group.\n * **Visibility**: Runbooks and runbooks versions which cannot be accessed will be filtered out automatically.\n\n## Additional Rules\n\nNot every combination of input conforming to the schema is allowed as there are additional restrictions how runbooks can be created.\nThe following rules are also enforced for this operation.\n\n* The combination of the *fields* filter together with any *exportFormat* is not allowed.\n* Setting *exportFormat* to *keepId* is not allowed, if the retrieved versions are set to *all*.\n\n## Export Mode\n\nEnabling the export mode by setting exportFormat to either _true_ or _keepId_ converts the output. This is done\nin a way so that the existing output can be imported again, by using the import API endpoint.\n\nThe first main objective of this data processing is to remove all read only data, which is not part of the data\nnecessary to create new runbooks. This means runbooks exported and imported will not retain, among other\nproperties, their version numbers, original creation or modification times.\n\nThe second main objective is to include referenced objects of the runbooks into the output data, so that the\nrelationships between runbooks and their automations or referenced runbooks can be preserved. Referenced\nautomations will be placed alongside the data and on import will be created so that runbooks remain intact. The\nsame is true for referenced runbooks using the nested runbooks feature. Referenced runbooks will be included\ndifferently depending on the export mode chosen. If _true_ is the export mode, all runbooks will be exported in\n\"flat\" mode. That means all references to other runbooks are resolved and the runbook is exported as if it does\nnot have any references. If _keepId_ is the export mode, all runbooks will retain their structure as nested\nrunbooks. Runbooks referenced by a fixed version number will be exported as new runbooks and will be assigned a\nnew runbookId upon import. Runbooks referenced by latest version will be exported retaining their runbookId.\n\nNote that sensitive data will be encrypted on export. Sensitive data includes fixed value parameter mappings\nfor parameters that are flagged as passwords and authentication headers for HTTP automation actions. The export\ncall will return the encryption token that was used for encrypting this data in a header named\n*x-rba-encryption-token*. This encryption token should be stored in a safe place separated from the exported\nrunbooks. It will be needed when importing the runbooks and restoring the encrypted sensitive data.\n\nLearn more about this feature on page \"Export and import runbooks\".\n\n## Response\n\nThe response will always be in application/json format.\n\n* **200**: The call was successful. See the output for the requested data.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "tags": [ "Runbook" ], "parameters": [ { "name": "version", "in": "query", "description": "Select the versions to retrieve", "required": false, "schema": { "type": "string", "enum": [ "draft", "approved", "latest", "all" ] } }, { "name": "exportFormat", "in": "query", "description": "Return result as importable JSON", "required": false, "allowEmptyValue": false, "schema": { "type": "string", "enum": [ "true", "keepId", "false" ] } }, { "name": "fields", "in": "query", "description": "Limit the content of the runbooks to the following fields", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "filterByTag", "in": "query", "description": "Filter the runbooks by tag", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "filterById", "in": "query", "description": "Filter the runbooks by IDs (comma-separated list)", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "context", "in": "query", "description": "Include statistics for specific context", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseRunbooksGet" }, "example": [ { "_id": "9b82f71d273674926a5af82503dbc48b", "_rev": "1-12c66db025c3c39ebe1213916e9c4fab", "parameters": [ { "name": "appName", "type": "string", "minLength": 1 }, { "name": "port", "type": "integer", "minimum": 1025, "maximum": 65535 }, { "name": "uuid", "type": "string", "minLength": 32, "maxLength": 36 } ], "steps": [ { "number": 1, "title": "Log in", "type": "manual", "description": "Log on to the system using SSH" }, { "number": 2, "title": "Resolve issue", "type": "manual", "description": "Perform the necessary steps to resolve the issue" } ], "name": "Generic runbook example", "description": "A generic example for a runbook.", "tags": [ "generic", "example" ], "readOnly": { "_createdAt": "2016-10-23T16:30:28.386Z", "_modifiedAt": "2016-10-25T12:10:87.997Z", "_createdBy": "johndoe@ibm.com", "_modifiedBy": "janedoe@ibm.com", "_runbookId": "7ef63332-5a3e-40f7-a923-af3ffb6795d3", "_type": "runbook", "_dataModel": 3, "_version": 1, "_tenantId": "82162ab32902edef239abved2354edb1", "_state": "approved", "_canBeAutomated": false, "_isLatest": true } } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "post": { "summary": "Create a new runbook", "description": "# Create a new runbook\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the v2 API endpoint `/aiops/api/v2/configuration/runbooks`. The **Publish** parameter is replaced by **draft**. Setting draft to false in v2 is equivalent to setting publish to true in v1. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nUse this API endpoint to create a new runbook. You need to define the contents of the new runbook in the body of this request as a JSON document.\n\n\n## JSON body\n\nSpecify the input JSON to define a new runbook. The following properties can be set:\n\n* **name**: The name of the runbook. This parameter is *mandatory*. Runbook names may contain up to 200 characters.\n* **exampleName**: If this property is set, the runbook will be treated as an example. This means it will be deleted if you reload the examples.\n* **description**: The description of the runbook. Define what the runbook is about and additional information to identify or execute the runbook.\n* **tags**: Tags are defined as an array of strings. Each tag may contain up to 30 characters. You can define any number of tags. Defining tags makes it easier to find the correct runbook.\n* **steps**: The content of the runbook. This parameter is *mandatory*.\nSteps are organized in an array of objects. Steps can be of the following types: manual, runbook, automation. Each type has a different set of properties and mandatory settings. Refer to the schema to see the differences. Leaving out a type will create a manual step.\n * **number**: The number will define in which order the steps are presented to operators. Step numbers need to start at '1' and be consecutive without any gaps.\n * **title**: Optional. A title to headline what this step is about.\n * **type**: Optional. The type of the step. See a description below for the different step types. Deprecated: Omitting the step type allows to define automations inside the step *description* for backward compatibility. It is recommended to use steps of type *automation* instead.\n * **description**: Manual steps only. The description will define the content of the step. In order to create special runbook elements (commands, parameters, goto, collapsible sections) refer to the documentation about \"Create a runbook\".\n * **runbookId**: Runbook steps only. The ID of the runbook to be used in this step.\n * **runbookVersion**: Optional. Runbook steps only. The version of the runbook to be used. Will be *latest* version, if omitted.\n * **automationId**: Automation steps only. The ID of the automation to be used in this step.\n * **goto**: Deprecated. Use 'branching' instead.\n * **branching**: Optional. Automation steps only. *branching* is an array of conditional branching definitions. After the automation completes the conditional branching definitions will be evaluated in the specified order until one condition matches and defines the next step.\n * **condition**: String defining the condition statement for this conditional branching definition. The syntax for condition strings is a subset of JSONata. Condition strings can check for automation status (e.g. 'status = \"successful\"'), return codes including http status codes (e.g. 'returnCode >= 400'), output (e.g. 'output = \"Ok\"') or execution time in seconds (e.g. 'executionTime < 5'). Supported operators are '=' and '!=' for string variables (status and output) and '=', '!=', '<', '>', '<=' and '>=' for number variables (returnCode and executionTime).\n * **target**: Step number to proceed with in case the condition string evaluations to true. Must be the number of a future step, or '-1' for the end of the runbook.\n * **mappings**: Runbook and automation steps only. Runbook and automation steps need to map all parameters of the referenced asset. *mappings* is an array of mapping objects. Create one mapping for each parameter in the referenced asset.\n * **automationParameterName** or **nestedRunbookParameterName**: Define the name of the automation/runbook parameter which should receive an input value.\n * **parameterMappingType**: Defines how the input will be mapped. The following options are available: 'parameter' uses the content of a runbook parameter, 'fixed' defines a constant value, 'useDefaultFromAutomation' uses the default value from the automation, 'useDefaultFromNestedRunbook' uses the default value from the runbook, 'automationOutput' uses the output from an automation running in an earlier step, 'userName' uses the name of the currently logged in user, when the runbook is executed.\n * **parameterValue**: Defines the content of the parameter depending on the mapping type. This property might define the name of the runbook parameter, the fixed value, or the step from which to pick the automation output from.\n* **approval**: Initiate the approval process by defining this element.\nYou may only specify this, if you enabled the approval process for your\nsubscription.\n * **action**: For runbook creation only \"submit\" is allowed. This will put the runbook into the status *pending*.\n * **comment**: Comments are only relevant for approve or reject actions. This property will be ignored on runbook creation.\n * **email**: Specify the email address of the approver. This must be a valid email address of an user with the approver role in your subscription.\n* **parameters**: Define any parameters you want to use in the runbook. All properties except 'name' are optional.\n * **name**: The name of the parameter. A parameter name is mandatory.\n * **description**: Textual description for what the parameter is used in this runbook.\n * **defaultValue**: Deprecated. Use 'default' instead.\n * **default**: If no other value is specified, the default will be used. The Runbook Automation UI will prefill input fields with the value specified here.\n * **isNotReqOnStart**: Deprecated. Use 'minLength' set to '0' or 'minItems' set to '0' instead.\n * **type**: Define the type of the parameter. The following types are supported: 'string' (default), 'integer', 'boolean', 'array'.\n * **enum**: Restrict the allowed entry to any values specified in this array. Only supported for parameters of type 'string' or 'integer'.\n * **enumLabels**: Define an additional set of descriptive texts for your 'enum' values. If no 'enum' is defined, this value is ignored and stripped away.\n * **minLength**: Set the minimum number of characters for a parameter of type 'string'.\n * **maxLength**: Set the maximum number of characters for a parameter of type 'string'.\n * **minimum**: Set the minimum value for a parameter of type 'integer'.\n * **maximum**: Set the maximum value for a parameter of type 'integer'.\n * **minItems**: Set the minimum number of items a parameter of type 'array' must contain.\n * **maxItems**: Set the maximum number of items a parameter of type 'array' may contain.\n * **items**: Define the allowed items inside a parameter of type 'array'.\n * **type**: May be either 'string', 'integer', or 'boolean'. Defines one type for all array entries.\n * **enum**: Restrict the allowed entry to any values specified in this array. Only supported for parameters of type 'string' or 'integer'.\n * **enumLabels**: Define an additional set of descriptive texts for your 'enum' values. If no 'enum' is defined, this value is ignored and stripped away.\n * **format**: Provide an additional format for the parameter to further describe the parameter. Supported values are:\n * password: The content is sensitive.\n * multiline: The content is expected to contain line breaking characters.\n* **automationMappings**: **Deprecated**. The usage of *automationMappings* is deprecated. It is recommended to define automation mappings directly inside the step. If automations are specified, define how they\nmap the runbook parameters to automation parameters with the automationMappings object. For each automation create one mapping entry in this array.\n * **mappingId**: Use this ID to identify which automation in your step description will be mapped in this object.\n * **parameterMappings**: This array contains one object for every parameter mapped.\n * **automationParameterName**: Define the name of the automation parameter which should receive an input value.\n * **parameterMappingType**: Defines how the input will be mapped. The following options are available: 'parameter' uses the content of a runbook parameter, 'fixed' defines a constant value, 'useDefaultFromAutomation' uses the default value from the automation, 'automationOutput' uses the output from an automation running in an earlier step, 'userName' uses the name of the currently logged in user, when the runbook is executed.\n * **parameterValue**: Defines the content of the parameter depending on the mapping type. This property might define the name of the runbook parameter, the fixed value, or the step from which to pick the automation output from.\n* **automations**: Previously exported runbooks may contain their\ncomplete automation definitions inline here.\n* **_runbookId**: Previously exported runbooks may try to set their runbook id here.\nIf the specified id does already exist the create call will fail.\n\nExcept for *name* and *steps* all properties of the runbook are optional\nand can be omitted. If the input is invalid a proper error message\ntogether with HTTP response code 400 will be returned, explaining the\nerror in the input.\n\n\n## Step Types\n\nRunbook Automation supports three different types of steps: Manual steps, runbook steps, and automation steps.\n\n* A *manual* step contains a description, which will be displayed to the users when the runbook is executed. The\n description usually contains a set of instructions the user should follow to accomplish the task at hand. It may\n contain references to parameters of the runbook as well as collapsible sections, commands, and goto elements.\n* An *automation* step is a reference to an existing automation definition of any type. The step defines which\n automation definition is to be used and how the parameters of the automation definition should be mapped.\n* A *runbook* step is a reference to another runbook to be used inside this runbook. This is also known as \"nested\n runbook\". The step defines which runbook should be inserted here and how the parameters of that runbook should\n be mapped.\n\n\n## Parameter Format Definitions Examples\n\nFollowing are several examples on how to define formats for parameters. The supported formats are a subset of the OpenAPI v3 which can be found on the [OpenAPI GitHub repository](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md).\n\n* *Mandatory Parameter of type string*\n ```\n { \"name\" : \"data\", \"type\" : \"string\", \"minLength\" : 1 }\n ```\n* *Optional Parameter of type string*\n ```\n { \"name\" : \"comment\", \"type\" : \"string\" }\n ```\n* *Numerical parameter representing a port with a value between 1025 and 65535 *\n ```\n { \"name\" : \"port\", \"type\" : \"integer\", \"minimum\" : 1025, \"maximum\" : 65535 }\n ```\n* *Array of strings with at least three entries and default values [ \"high\", \"medium\", \"low\" ]*\n ```\n {\n \"name\" : \"prio\",\n \"defaultValue\" : [ \"high\", \"medium\", \"low\" ],\n \"type\" : \"array\",\n \"items\" : {\n \"type\" : string\n },\n \"minItems\" : 3\n }\n ```\n\n\n## Additional Input Rules\n\nNot every combination of input conforming to the schema is allowed as there are additional restrictions how runbooks can be created.\nThe following rules are also enforced for this operation.\n\n* If the approval feature is disabled, the input may not define the \"approval\" property.\n* If the query parameter \"publish\" is set to true, the approval feature must be disabled.\n* If the query parameter \"publish\" is set to true, the user doing the request must have the permission to publish a runbook.\n* If approval.action is \"submit\", approval.email must also be set and the email address must be one matching a member of the subscription with approval rights.\n* User submitting a runbook for approval may not define themselves as the approver.\n* If an approval section is present, the action must be set and must be \"submit\".\n* For every automation step, all required input parameters must have mappings.\n* The automationId defined in an Automation step must match an existing automation definition.\n* If a step defines \"type\", the legacy format of defining automations within the description is not allowed.\n* Automation parameter mappings as a whole may either be defined in Automation Steps or via the top level deprecated \"automationMappings\". A combination of both methods is not possible.\n* Step numbers must start at 1 *and* must be consecutive *and* must be unique.\n* Legacy steps without a type with automations defined in their description, may not define more than one automation within each step.\n* A parameter may not define the flag *isNotReqOnStart* together with a *format* definition.\n* If a parameter defines a *format* definition and a *defaultValue*, the defaultValue must conform to the format definition.\n\n## Query parameters\n\nBy default a new runbook is created as a draft. If the approval feature\nis disabled, you may set the query parameter **publish** to `true`. If\ndone so, the runbook will be published directly.\n\n\n## Response\n\nThe response will always be in application/json format.\n\n* **201**: This indicates a successful runbook creation. The output will\ncontain the runbookId, which you might need for further API operations.\nUse this ID to identify the runbook.\n* **400**: The input was invalid. Read the error message and adjust your\ninput before trying again.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "createRunbook", "tags": [ "Runbook" ], "parameters": [ { "name": "publish", "in": "query", "description": "Define to publish new runbook directly", "required": false, "allowEmptyValue": false, "schema": { "type": "boolean" } } ], "responses": { "201": { "description": "Runbook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseRunbookCreated" }, "example": { "_id": "9b82f71d273674926a5af82503dbc48b", "_rev": "1-12c66db025c3c39ebe1213916e9c4fab", "parameters": [], "steps": [ { "number": 1, "title": "Log in", "type": "manual", "description": "Log on to the system using SSH" }, { "number": 2, "title": "Resolve issue", "type": "manual", "description": "Perform the necessary steps to resolve the issue" } ], "name": "Generic runbook example", "description": "A generic example for a runbook.", "tags": [ "generic", "example" ], "readOnly": { "_createdAt": "2016-10-23T16:30:28.386Z", "_modifiedAt": "2016-10-25T12:10:87.997Z", "_createdBy": "johndoe@ibm.com", "_modifiedBy": "janedoe@ibm.com", "_runbookId": "7ef63332-5a3e-40f7-a923-af3ffb6795d3", "_type": "runbook", "_dataModel": 3, "_version": 1, "_tenantId": "82162ab32902edef239abved2354edb1", "_state": "approved", "_canBeAutomated": false, "_isLatest": true } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestRunbookCreate" }, "example": { "name": "Perform DB2 database rollback", "description": "Perform a database rollback on an IBM DB2 database. This runbook guides you through the steps to correctly shut down the database, perform the rollback, and make it available again. Only perform when DBA has deemed it necessary.", "tags": [ "db2", "database", "data" ], "steps": [ { "number": 1, "title": "Log in", "type": "manual", "description": "Log in to the target system with db instance owner credentials" }, { "number": 2, "title": "Cleanup connections", "type": "manual", "description": "Disconnect all applications accessing the database" }, { "number": 3, "title": "Perform database rollback", "type": "automation", "automationId": "abcdef1234567890abcdef1234567890" }, { "number": 4, "title": "Restart DB2", "type": "manual", "description": "Start database manager and check whether the test application can connect" } ], "parameters": [ { "name": "instance", "defaultValue": "db2inst1" }, { "name": "user", "type": "string", "minLength": 1, "maxLength": 8 }, { "name": "password", "type": "string", "format": "password", "minLength": 8 }, { "name": "hostname", "type": "string" } ] } } }, "description": "Definition and content of the new runbook", "required": true } } }, "/runbooks/{runbookId}": { "get": { "summary": "Retrieve a single runbook", "description": "# Get runbook\n\n**IMPORTANT**: This endpoint is deprecated and replaced the following v2 API endpoints:\n\n*`/aiops/api/v2/configuration/runbooks/{id}`\n\n*`/aiops/api/v2/configuration/runbooks/{id}/stats`\n\n*`/aiops/api/v2/configuration/runbooks/{id}/references`\n\n*`/aiops/api/v2/configuration/runbooks/{id}/versions`\n\n*`/aiops/api/v2/configuration/runbooks/{id}/version/{version}`\n\n Additionally, the **exportFormat** parameter is replaced by **structure**. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nRetrieve one or more versions of a runbook identified by the runbookId.\nSearches the runbook repository for a single runbook with the supplied\nrunbookId. If found, the data is returned.\n\n\n**Note**: The runbook ID necessary for this call is the field with the\nname \"_runbookID\" from any operation retrieving runbooks. You cannot use\nthe document id (typically labeled as \"_id\") as identifier.\n\n\n## Parameters\n\n* **runbookId**: The ID to identify the runbook. Use the field labeled\nas \"_runbookId\".\n* **version**: Optional. This parameter identifies the version to be\nretrieved. It allows either an integer to retrieve a specific version or\nthe keyword \"all\" to get all versions of the runbook. If not specified\nthe latest version is returned by default. To retrieve the draft specify\nversion as \"0\".\n* **fields**: Optional. Control the output of the command by restricting\nthe displayed fields to the ones of this comma-separated list. This\noption may not be combined with \"stats\", \"context\" or \"exportFormat\".\n* **stats**: Optional. If set to \"true\" the output will also contain the\nstatistical information of this runbook, including sucess rate, number\nof executions and ratings. Enabling this will cause more data to be\ncollected and generally increases the response time. This option may not\nbe combined with \"fields\" or \"exportFormat\".\n* **context**: Optional. Generate a set of statistics for each runbook\nnamed **contextStats** which only considers runbook executions within\nthe given context. This option may not be combined with \"fields\" or\n\"exportFormat\".\n* **references**: Optional. Collect information about runbooks directly referencing this runbook. Will only\ndisplay data of the latest approved versions of runbooks and only of runbooks referencing the requested runbook\ndirectly. This option searches the whole runbook library and may increase the response time of this operation.\n* **exportFormat**: **Deprecated**. Use *structure* instead.\nOptional. If set to _true_ or _keepId_ converts the output into a JSON\nobject that can be used to create runbooks with the import route. It also retrieves\nautomations defined in the runbook and adds them to the runbook inline (except the automation was harvested, such as from Ansible). As this processing strips away many important runbook properties and\ntakes considerable more computing resources, it is advised to only\nenable it when necessary. Learn more about this feature on page \"Export and import runbooks\".\nThis option may not be combined with \"fields\", \"stats\" or \"context\".\n * **true** - The conversion removes all values that are read only (for example the\nrunbook ID, the version number, creator)\n * **keepId** - Like _true_, but does not remove the runbook ID. Thus when importing again, the import call will try to use the same ID again.\n This exportFormat mode is intended for migrating runbook from an old deployment to a new deployment. This exportFormat\n mode cannot be combined with _version=all_\n * **false** - Does not convert output to export format (default)\n* **structure**: Optional. Defines how the structure of the runbook should be displayed.\n * *original* - Default. This displays the runbook without additional modifications. Use this for editing runbooks.\n * *flat* - Dereference all runbook references inside the steps and and resolve parameter mappings for referenced\n runbooks. Use this for running runbooks. Cannot be combined with a fields option that excludes the steps part of the runbook.\n * *export* - Converts the output into a JSON object that can be used to create runbooks with the import route.\n It also retrieves automations defined in the runbook and adds them to the runbook inline (except the automation was harvested, such as from Ansible). As this processing strips away many important runbook properties and takes considerable\n more computing resources, it is advised to only use export structure when necessary. Learn more about this feature on page \"Export and import runbooks\".\n This option may not be combined with \"fields\", \"stats\" or \"context\".\n * exportKeepId* - Same as *export*, but also keeps the runbook ID. Thus when importing again, the import call\n will try to use the same ID again. The exportKeepId structure is intended for migrating runbooks from an old\n deployment to a new deployment. The exportKeepId structure cannot be combined with _version=all_.\n\n\n## Response\n\n* **200**: The call was successful. The requested data is returned to\nthe caller.\n* **400**: The input was invalid. Read the error message and adjust your\ninput before trying again.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **403**: The user is lacking the appropriate rights to conduct this\noperation.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "getRunbook", "tags": [ "Runbook" ], "parameters": [ { "name": "runbookId", "in": "path", "description": "ID of the runbook to get", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Specify the version to get", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Limit the content of the runbooks to the following fields", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "stats", "in": "query", "description": "Include runbook statistics", "required": false, "allowEmptyValue": false, "schema": { "type": "boolean", "default": false } }, { "name": "context", "in": "query", "description": "Include statistics for specific context", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "references", "in": "query", "description": "Include information of runbooks referencing this runbook", "required": false, "allowEmptyValue": false, "schema": { "type": "boolean" } }, { "name": "exportFormat", "in": "query", "description": "Return result as importable JSON", "required": false, "allowEmptyValue": false, "schema": { "type": "string", "enum": [ "true", "keepId", "false" ] } }, { "name": "structure", "in": "query", "description": "Define how the runbook should be displayed.", "required": false, "allowEmptyValue": false, "schema": { "type": "string", "enum": [ "original", "flat", "export", "exportKeepId" ] } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseRunbookGet" }, "example": [ { "_id": "9b82f71d273674926a5af82503dbc48b", "_rev": "1-12c66db025c3c39ebe1213916e9c4fab", "parameters": [ { "name": "appName", "type": "string", "minLength": 1 }, { "name": "port", "type": "integer", "minimum": 1025, "maximum": 65535 }, { "name": "uuid", "type": "string", "minLength": 32, "maxLength": 36 } ], "steps": [ { "number": 1, "title": "Log in", "type": "manual", "description": "Log on to the system using SSH" }, { "number": 2, "title": "Resolve issue", "type": "manual", "description": "Perform the necessary steps to resolve the issue" }, { "number": 3, "title": "Run automated script", "type": "automation", "automationId": "1094d17ef4da4ace993ab152e5a2851c" } ], "name": "Generic runbook example", "description": "A generic example for a runbook.", "tags": [ "generic", "example" ], "references": [ { "runbookId": "ee4dc9a1-13a6-40df-a38b-1e286099111c", "runbookVersion": 3, "stepNumber": 2 } ], "readOnly": { "_createdAt": "2016-10-23T16:30:28.386Z", "_modifiedAt": "2016-10-25T12:10:87.997Z", "_createdBy": "johndoe@ibm.com", "_modifiedBy": "janedoe@ibm.com", "_runbookId": "7ef63332-5a3e-40f7-a923-af3ffb6795d3", "_type": "runbook", "_dataModel": 3, "_version": 2, "_tenantId": "82162ab32902edef239abved2354edb1", "_state": "approved", "_canBeAutomated": false, "_isLatest": true } } ] } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "patch": { "summary": "Change an existing runbook", "description": "# Change a runbook\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the v2 API endpoint `/aiops/api/v2/configuration/runbooks/{id}`. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nChange the content or state of a single runbook identified by the\nrunbookId. Use this call for all changes to existing runbooks. These\npossible changes include: Changing the meta data of a runbook, set up or\nmodify the approval state of a runbook, creating a new version, and\nchanging the content of the runbook. It cannot be used to create a new\nrunbook. Depending on the state of the runbook certain changes might not\nbe possible at the moment, which means the same input might be accepted\nor rejected based on the state of the runbook. Until published or\napproved, all changes will affect only the draft version of the runbook.\n\n\nThis operations accepts JSON input and only the specified input will\nlead to changes in the runbook. Unspecified properties of the runbook\nwill remain unchanged.\n\n\n**Note**: The runbook ID necessary for this call is the field with the\nname \"_runbookID\" from any operation retrieving runbooks. You cannot use\nthe document id (typically labeled as \"_id\") as identifier.\n\n\n## Parameters\n\n* **publish**: Optional. Set to *true* in order to directly publish the runbook. May not be set, if the approval feature is enabled.\n* **runbookId**: The ID to identify the runbook. Use the field labeled as \"_runbookId\".\n* **runbook**: Optional. JSON object with the changes to the runbook. If this is empty, the only possible change is to publish the runbook. All other changes to the runbook are effected through input into this field. All possible properties are optional by default, although some input combinations may require other properties to be set as well.\n * **name**: Set this to change the name of the runbook.\n * **description**: Set this to change the description of the runbook.\n * **steps**: The content of the runbook.\n Steps are organized in an array of objects. Steps do have the following properties:\n * **number**: The number will define in which order the steps are presented to operators. Step numbers need to start at '1' and be consecutive without any gaps.\n * **title**: Optional. A title to headline what this step is about.\n * **type**: Optional. The type of the step. See a description below for the different step types. Deprecated: Omitting the step type allows to define automations inside the step *description* for backward compatibility. It is recommended to use steps of type *automation* instead.\n * **description**: Manual steps only. The description will define the content of the step. In order to create special runbook elements (commands, parameters, goto, collapsible sections) refer to the documentation about \"Create a runbook\".\n * **runbookId**: Runbook steps only. The ID of the runbook to be used in this step.\n * **runbookVersion**: Optional. Runbook steps only. The version of the runbook to be used. Will be *latest* version, if omitted.\n * **automationId**: Automation steps only. The ID of the automation to be used in this step.\n * **mappings**: Runbook and automation steps only. Runbook and automation steps need to map all parameters of the referenced asset. *mappings* is an array of mapping objects. Create one mapping for each parameter in the referenced asset.\n * **automationParameterName** or **nestedRunbookParameterName**: Define the name of the automation/runbook parameter which should receive an input value.\n * **parameterMappingType**: Defines how the input will be mapped. The following options are available: 'parameter' uses the content of a runbook parameter, 'fixed' defines a constant value, 'useDefaultFromAutomation' uses the default value from the automation, 'useDefaultFromNestedRunbook' uses the default value from the runbook, 'automationOutput' uses the output from an automation running in an earlier step, 'userName' uses the name of the currently logged in user, when the runbook is executed.\n * **parameterValue**: Defines the content of the parameter depending on the mapping type. This property might define the name of the runbook parameter, the fixed value, or the step from which to pick the automation output from.\n * **parameters**: Define any parameters you want to use in the runbook. All properties except 'name' are optional.\nsteps or for automation mappings.\n * **name**: The name of the parameter. A parameter name is mandatory.\n * **description**: Textual description for what the parameter is used in this runbook.\n * **defaultValue**: Deprecated. Use 'default' instead.\n * **default**: If no other value is specified, the default will be used. The Runbook Automation UI will prefill input fields with the value specified here.\n * **isNotReqOnStart**: Deprecated. Use 'minLength' set to '0' or 'minItems' set to '0' instead.\n * **type**: Define the type of the parameter. The following types are supported: 'string' (default), 'integer', 'boolean', 'array'.\n * **enum**: Restrict the allowed entry to any values specified in this array. Only supported for parameters of type 'string' or 'integer'.\n * **enumLabels**: Define an additional set of descriptive texts for your 'enum' values. If no 'enum' is defined, this value is ignored and stripped away.\n * **minLength**: Set the minimum number of characters for a parameter of type 'string'.\n * **maxLength**: Set the maximum number of characters for a parameter of type 'string'.\n * **minimum**: Set the minimum value for a parameter of type 'integer'.\n * **maximum**: Set the maximum value for a parameter of type 'integer'.\n * **minItems**: Set the minimum number of items a parameter of type 'array' must contain.\n * **maxItems**: Set the maximum number of items a parameter of type 'array' may contain.\n * **items**: Define the allowed items inside a parameter of type 'array'.\n * **type**: May be either 'string', 'integer', or 'boolean'. Defines one type for all array entries.\n * **enum**: Restrict the allowed entry to any values specified in this array. Only supported for parameters of type 'string' or 'integer'.\n * **enumLabels**: Define an additional set of descriptive texts for your 'enum' values. If no 'enum' is defined, this value is ignored and stripped away.\n * **format**: Provide an additional format for the parameter to further describe the parameter. Supported values are:\n * password: The content is sensitive.\n * multiline: The content is expected to contain line breaking characters.\n* **approval**: In order to define an action in the approval process define this element. You may only specify this, if you enabled the approval process for your subscription.\n * **action**: Define \"submit\" to initiate the approval. This will put the runbook into the status *pending*. Define \"accept\" or \"reject\" to respond to an ongoing approval process. Define \"cancel\" to abort an ongoing approval process.\n * **comment**: Comments are only relevant for approve or reject actions. This property will be ignored otherwise.\n * **email**: Specify the email address of the approver. This must be a valid email address of an user with the approver role in your subscription. It is mandatory if the action is \"submit\" and ignored in other cases.\n * **tags**: Replaces the existing set of tags with the one specified here.\n * **automationMappings**: **Deprecated**. The usage of *automationMappings* is deprecated. It is recommended to define automation mappings directly inside the step. Replaces the existing automationMappings with the ones defined here. If you added new automations in the steps, definition of suitable mappings may be required. For each automation create one mapping entry in this array.\n * **mappingId**: Use this ID to identify which automation in your step description will be mapped in this object.\n * **parameterMappings**: This array contains one object for every parameter mapped.\n * **automationParameterName**: Define the name of the automation parameter which should receive an input value.\n * **parameterMappingType**: Defines how the input will be mapped. The following options are available: 'parameter' uses the content of a runbook parameter, 'fixed' defines a constant value, 'useDefaultFromAutomation' uses the default value from the automation, 'automationOutput' uses the output from an automation running in an earlier step, 'userName' uses the name of the currently logged in user, when the runbook is executed.\n * **parameterValue**: Defines the content of the parameter depending on the mapping type. This property might define the name of the runbook parameter, the fixed value, or the step from which to pick the automation output from.\n * **automations**: Previously exported runbooks may contain their complete automation definitions inline here.\n\n## Step Types\n\nRunbook Automation supports three different types of steps: Manual steps, Runbook steps and Automation steps.\n\n* A *manual* step contains a description, which will be displayed to the users when the runbook is executed. The\n description usually contains a set of instructions the user should follow to accomplish the task at hand. It may\n contain references to parameters of the runbook as well as collapsible sections, commands, and goto elements.\n* An *automation* step is a reference to an existing automation definition of any type. The step defines which\n automation definition is to be used and how the parameters of the automation definition should be mapped.\n* A *runbook* step is a reference to another runbook to be used inside this runbook. This is also known as \"nested\n runbook\". The step defines which runbook should be inserted here and how the parameters of that runbook should\n be mapped.\n\n\n## Examples\n\n* Change the description of a runbook, but keep all other properties of\n the runbook unchanged:\n ```\n {\n \"description\" : \"This runbook handles the incident with the error ID E234ABC.\"\n }\n ```\n* Delete the existing set of tags and submit the runbook for approval:\n ```\n {\n \"tags\" : [],\n \"approval\" : {\n \"action\" : \"submit\",\n \"email\" : \"max.mustermann@de.ibm.com\"\n }\n }\n ```\n* Reject a pending runbook approval with a comment:\n ```\n {\n \"approval\" : {\n \"action\" : \"reject\",\n \"comment\" : \"Runbook is missing proper tags. It would be too hard to find the runbook.\"\n }\n }\n ```\n* Snippets to define an automation with matching parameter mapping and\n runbook parameters (Note: This is not a complete input, omissions are\n marked):\n ```\n {\n \"steps\" : [\n (…)\n {\n \"number\" : 3,\n \"title\" : \"Automation: Apply security fix 'AlphaBetaGamma'\",\n \"automationId\" : \"e28e9fe0e77111eaad96a77a139849d2\",\n \"mappings\" : [\n {\n \"automationParameterName\" : \"user\",\n \"parameterMappingType\" : \"userName\"\n },\n {\n \"automationParameterName\" : \"target\",\n \"parameterMappingType\" : \"parameter\",\n \"parameterValue\" : \"hostname\"\n }\n ]\n }\n ],\n \"parameters\" : [\n (…)\n {\n \"name\" : \"hostname\",\n \"description\" : \"The hostname of the system, where the automations should be executed on\"\n },\n {\n \"name\" : \"user\",\n \"description\" : \"The user under whose authority the automation should be executed\"\n }\n ]\n }\n ```\n\n## Additional Input Rules\n\nNot every combination of input conforming to the schema is allowed as there are additional restrictions how runbooks can be created.\nThe following rules are also enforced for this operation.\n\n* If the approval feature is disabled, the input may not define the \"approval\" property.\n* If the query parameter \"publish\" is set to true, the approval feature must be disabled.\n* If the query parameter \"publish\" is set to true, the user doing the request must have the permission to publish a runbook.\n* If approval.action is \"submit\", approval.email must also be set and the email address must be one matching a member of the subscription with approval rights.\n* User submitting a runbook for approval may not define themselves as the approver.\n* If an approval section is present, the action must be set and must be \"submit\".\n* If the approval action is reject or approve, the user must be the assignee of the approval.\n* If the approval action is cancel, reject, or approve there may not be another property in the req.body object, except for approval.\n* If the state of the runbook is not pending, the only allowed value for approval.action is \"submit\".\n* If the state of the runbook is pending, approval.action may not be \"submit\".\n* For every automation step, all required input parameters must have mappings.\n* The automationId defined in an Automation step must match an existing automation definition.\n* If a step defines \"type\", the legacy format of defining automations within the description is not allowed.\n* Automation parameter mappings as a whole may either be defined in Automation Steps or via the top level deprecated \"automationMappings\". A combination of both methods is not possible.\n* Step numbers must start at 1 *and* must be consecutive *and* must be unique.\n* Legacy steps without a type with automations defined in their description, may not define more than one automation within each step.\n* A parameter may not define the flag *isNotReqOnStart* together with a *format* definition.\n* If a parameter defines a *format* definition and a *defaultValue*, the defaultValue must conform to the format definition.\n\n\n## Response\n\n* **200**: The call was successful. The runbook has been changed.\n* **201**: The call was successful. A new version of a runbook has been\ncreated.\n* **400**: The input was invalid. Read the error message and adjust your\ninput before trying again.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **403**: The user is lacking the appropriate rights to conduct this\noperation.\n* **404**: A runbook with the supplied runbookId cannot be found.\n* **409**: The runbook is currently locked by another user.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "patchRunbook", "tags": [ "Runbook" ], "parameters": [ { "name": "publish", "in": "query", "description": "Define to publish new runbook directly", "required": false, "allowEmptyValue": false, "schema": { "type": "boolean" } }, { "name": "runbookId", "in": "path", "description": "ID of the runbook to patch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseRunbookPatch" }, "example": { "runbookId": "7ef63332-5a3e-40f7-a923-af3ffb6795d3", "runbookUrl": "https://rba.mybluemix.net/api/v1/rba/runbooks/7ef63332-5a3e-40f7-a923-af3ffb6795d3?version=0", "_createdAt": "2016-10-23T16:30:28.386Z", "_createdBy": "johndoe@ibm.com", "_modifiedAt": "2016-10-25T12:10:87.997Z", "_modifiedBy": "janedoe@ibm.com" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "Document Locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestRunbookPatch" } } }, "description": "Values to change in a runbook", "required": true } }, "delete": { "summary": "Delete a runbook", "description": "# Delete runbook\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the v2 API endpoint `/aiops/api/v2/configuration/runbooks/{id}`. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nCompletey delete a runbook. This call deletes all versions of the\nrunbook including the draft. Also deletes all runbook instances of this\nrunbook and all statistics associated with it. This action is not\nreversible.\n\nIn case this runbook is referenced by other runbooks, this call will fail with an 412 error code. The error\nmessage will contain information as to which runbooks are referencing this runbook. Either remove all references\nbefore trying this call again or use the \"force\" option. Using \"force\" will leave all runbooks referencing this\nrunbook in an erroneous state, in which they cannot be run.\n\n**Note**: The runbook ID necessary for this call is the field with the\nname \"_runbookID\" from any operation retrieving runbooks. You cannot use\nthe document id (typically labeled as \"_id\") as identifier.\n\n\n## Response\n\n* **204**: The call was successful. The runbook and its associated data\nhave been deleted.\n* **400**: The input was invalid. Read the error message and adjust your\ninput before trying again.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **412**: The runbook is referenced in at least one other runbook. Either change the referencing runbook or use\nthe force option.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "deleteRunbook", "tags": [ "Runbook" ], "parameters": [ { "in": "path", "name": "runbookId", "required": true, "description": "ID of the runbook to be deleted", "schema": { "type": "string" } }, { "in": "query", "name": "force", "required": false, "description": "Force a deletion, even if the runbook is referenced somewhere else", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "Runbook deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "Document Locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "412": { "description": "Precondition failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/runbooks/{runbookId}/execute": { "post": { "summary": "Execute a fully automated runbook", "description": "# Execute a fully automated runbook\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the v2 API endpoint `/aiops/api/v2/configuration/runbooks/{id}/run`. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nExecute a fully automated runbook. This API endpoint can only be used\nfor executing fully automated runbooks. In case of a valid input, the\nsuccessful creation of the execution record is immediately returned to\nthe user, while the runbook is still in execution. You can use the\nrunbookInstanceId information to retrieve the current state of the\nexecution from thereon. The runbook instance will automatically update\nits status, when results from the included automations become available.\nThis endpoint cannot be used to execute runbooks, which are not fully\nautomatable. To be fully automatable, a runbook must have exactly one\nautomation in every one of its step.\n\n\n**Note**: The runbook ID necessary for this call is the field with the\nname \"_runbookID\" from any operation retrieving runbooks. You cannot use\nthe document id (typically labeled as \"_id\") as identifier.\n\n\n## Parameters\n\n* **runbookId**: The ID to identify the runbook. Use the field labeled\nas \"_runbookId\".\n* **version**: Optional. Specify the version number to execute. Leaving\nthis option empty or specifying the keyword \"latest\", will execute the\nlatest published/approved version of this runbook.\n* **parameters**: Define the values of the parameters for this runbook execution. Depending on the format\ndefinition of the parameters, each parameter might enforce a specific format and may or may not be mandatory to\nspecify. For every parameter of the runbook not send in this request, the default value will be sent instead, if\nthe parameter has one. If no default value is defined an empty string will be sent instead. Definition of\nparameters and their values is done as an array of objects.\n * **name**: The name of the runbook parameter.\n * **value**: The value of the runbook parameter for this runbook execution.\n* **context**: Optional. Execute this runbook in a specific context.\nThis context can later be used for more fine-grained analysis of\nrunbook execution and tie it to specific other elements like Alerts or Stories in AIManager.\nCalculating statistics for a specific runbook and context is also possible.\n\n## Response\n\n* **201**: The call was successful. A runbook execution record has been\ncreated. Use the returned runbookInstanceId to check the status of the\nexecution.\n* **400**: The input was invalid. Read the error message and adjust your\ninput before trying again.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **402**: The monthly limit of runbook executions in your public cloud\nsubscription is exceeded.\n* **403**: The user is lacking the appropriate rights to conduct this\noperation.\n* **404**: A runbook with the supplied runbookId cannot be found.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "executeFarb", "tags": [ "Runbook" ], "parameters": [ { "name": "runbookId", "in": "path", "description": "ID of a fully automated runbook to execute", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Specify the version to execute", "required": false, "allowEmptyValue": false, "schema": { "type": "string", "default": "latest" } }, { "name": "context", "in": "query", "description": "Specify the context this runbook is executed in", "required": false, "allowEmptyValue": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Runbook executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseFarbExecute" }, "example": { "runbookInstanceId": "0123456789abcdef0123456789abcdef" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestRunbookExecute" } } }, "description": "Parameters and their values for running the runbook." } } }, "/runbooks/import": { "post": { "summary": "Import runbooks", "description": "# Import Runbooks\n\nImport one or more runbooks that have been previously exported. In order to use this call, it's best to use\ninput previously generated with the *exportFormat* mode of a get runbooks call. Using this API endpoint creates\nnew runbooks and new automations. Existing runbooks in the library will not be replaced. By default, the new\nrunbooks will be created as drafts. Learn more about this feature on page \"Export and import runbooks\".\n\n\n## Parameters\n\n* **publish**: Set to *true* in order to directly publish the imported runbooks. May not be set, if the approval\nfeature is enabled. In order to be able to import runbooks which make use of the nested runbooks feature, this\nmust be set to _true_, otherwise runbooks referencing other runbooks cannot be created.\n* **verbose**: Set to *true* in order to get a more verbose API response which includes error messages if\ncertain runbooks failed to import.\n* **encryption**: Specify the encryption token which was provided to you on export and was used to encrypt\nsensitive data. May not be combined with **ignoreEncryptedData**.\n* **ignoreEncryptedData**: Set to *true* in order to proceed with import even if sensitive data cannot be restored\ndue to a missing encryption token. The encrypted sensitive data will be ignored on import. May not be combined\nwith **encryption**.\n* **runbooks**: Define the runbooks to be imported. This array can contain any number of runbooks. To achieve\nthe best result, directly use the data from a previous export operation.\n\n\n## Response\n\nThe response will always be in application/json format.\n\n* **201**: The call was successful. At least one of the runbooks has been imported. The output contains the JSON\n representation of the runbooks created.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again. None of the\nsupplied inputs could be imported as a runbook.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered\ncorrectly.\n* **412**: The input contained automations, but the corresponding connection has not been setup. Setup the\nconnection and then try again.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM\nsupport.\n", "operationId": "importRunbook", "tags": [ "Runbook" ], "parameters": [ { "name": "publish", "in": "query", "description": "Define to publish new runbook directly", "required": false, "allowEmptyValue": false, "schema": { "type": "boolean" } }, { "name": "verbose", "in": "query", "description": "Define to get more verbose API response", "required": false, "allowEmptyValue": false, "schema": { "type": "boolean" } }, { "name": "encryption", "in": "query", "description": "Specify the encryption token provided on export that was used to encrypt sensitive data", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "ignoreEncryptedData", "in": "query", "description": "Define to import runbooks even if sensitive data cannot be restored", "required": false, "allowEmptyValue": false, "schema": { "type": "boolean" } } ], "responses": { "201": { "description": "Runbooks created", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/responseRunbooksCreated" }, { "$ref": "#/components/schemas/responseRunbooksCreatedVerbose" } ] }, "example": [ { "_id": "9b82f71d273674926a5af82503dbc48b", "_rev": "1-12c66db025c3c39ebe1213916e9c4fab", "parameters": [], "steps": [ { "number": 1, "title": "Log in", "type": "manual", "description": "Log on to the system using SSH" }, { "number": 2, "title": "Resolve issue", "type": "manual", "description": "Perform the necessary steps to resolve the issue" } ], "name": "Generic runbook example", "description": "A generic example for a runbook.", "tags": [ "generic", "example" ], "readOnly": { "_createdAt": "2016-10-23T16:30:28.386Z", "_modifiedAt": "2016-10-25T12:10:87.997Z", "_createdBy": "johndoe@ibm.com", "_modifiedBy": "janedoe@ibm.com", "_runbookId": "7ef63332-5a3e-40f7-a923-af3ffb6795d3", "_type": "runbook", "_dataModel": 3, "_version": 1, "_tenantId": "82162ab32902edef239abved2354edb1", "_state": "approved", "_canBeAutomated": false, "_isLatest": true } } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/errorModelBadRequest" }, { "$ref": "#/components/schemas/responseRunbooksCreated" }, { "$ref": "#/components/schemas/responseRunbooksCreatedVerbose" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestRunbookImport" } } }, "description": "Runbooks to be imported", "required": true } } }, "/runbooks/loadExamples": { "post": { "tags": [ "Runbook" ], "summary": "Load example package", "description": "# Load runbook examples\n\nLoad the runbook example package into your subscription. The examples\nwill be created as drafts. Previously loaded examples are deleted,\nbefore the example from the package are added to your runbook library.\n\n\n## Response\n\n* **200**: The call was successful. The examples have been added to your\nrunbook library.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **403**: The user is lacking the appropriate rights to conduct this\noperation.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "loadExamples", "responses": { "200": { "description": "Reload of runbook examples started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseLoadExamples" }, "example": { "code": 200, "message": "ARBR204I Reloading of runbooks examples has just started" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/runbookinstances": { "get": { "summary": "Get all runbook instances", "description": "# Get multiple runbook instances\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the v2 API endpoint `/aiops/api/v2/configuration/runbook-executions`. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nUse this API endpoint to retrieve several runbook instances at once. A runbook instance is the execution record of one runbook execution. It contains information about which parameters were used, who executed the runbook, and when the execution happened. This call supports multiple query parameters, which can be combined to narrow down the output to the desired runbook instances. The output in JSON format will always be an array.\n\nEach call we retrieve a maximum of 1000 instances. If a particular query matches more than 1000 instances the response will contain a header with the name 'bookmark'. You can either send this bookmark or an offset with your request as the pagination parameter to paginate through the results. In order to use the bookmark for subsequent calls, the query parameters must not change in between.\n\nYou need to have at least the author role to be able to see all runbook instances, regardless of ownership. Accounts with user role only, will only be able to see runbook instances on which they can claim ownership.\n\n**Note**: The default for querying runbook instances is to retrieve the instances from the last seven days. Use the query parameters *from* and *to* to get instances from a different time frame.\n\n## Query parameters\n* **from**: Optional. Only display runbook instances started after the value from this field. You can use a string representing a time (for example, \"2022-03-15\") or a timestamp. If no value is set, the default is seven days before the current time.\n* **to**: Optional. Only display runbook instances started before the value from this field. You can use a string representing a time (for example, \"2022-03-15\") or a timestamp. If no value is set, the default is the current time.\n* **owner**: Optional. Accepts a user name or a comma-separated list of user names. Restricts the output to runbook instances created one of the defined users.\n* **runbook**: Optional. Accepts a runbookId or a comma-separated list of runbookIds. Will only display the runbook instances matching a supplied runbookId. Use API endpoints from the runbooks section to retrieve suitable runbook ID(s).\n* **version**: Optional. Accepts a number. Will only display the runbook instances matching the defined version number.\n* **context**: Optional. Accepts a context string or a comma-separated list of context strings. Will only display the runbook instances matching a supplied context.\n* **name**: Optional. Accepts a comma-separated list of Regular Expressions. Restricts the output to runbook instances in which the runbook name matches at least one of the Regular Expressions. *Note: As the list is separated by commas, the Regular Expressions for this option cannot use the comma to define quantifiers. Doing so will result in an error.*\n* **status**: Optional. Accepts a status or a comma-separated list of status. Restricts the output to runbook instances matching the status. The following values are allowed: *in progress*, *complete*, *success*, *failure*, *canceled*. *complete* displays all terminated runbooks, no matter whether they were successful or have been canceled. *canceled* covers all canceled runbooks, no matter which cancellation reason was given. If a list is used as input, instances matching any of the supplied values will be returned.\n* **type**: Optional. Filters the output either to manual (*manual*) or fully automated runbook instances (*automated*).\n* **fields**: Optional. Use \"fields\" to restrict the output to the properties specified in this query parameter. It accepts a comma separated list. All properties not in the list will not be displayed. This can be used to efficiently reduce the amount of transferred data and makes reading and automated parsing easier.\n* **pagination**: Optional. Use a previously received continuation bookmark or a page index (where pagination=0 identifies the first page).\n\nAll query parameters can be combined to retrieve the desired data.\n\n## Output Data Format\nThis call supports two different types of output, based on the Media Type/Accept header of the request. The first option and default is *application/json* which creates output similar to those of most\nother Runbook Automation API calls. The other option is *text/html* which produces HTML output, which can easily be displayed with a browser.\n\n## Response\n\n* **200**: The call was successful. See the output of the command for\nthe retrieved data.\n* **400**: The input was invalid. Read the error message and adjust your\ninput before trying again.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "getRunbookInstanceAll", "tags": [ "Runbook instance" ], "parameters": [ { "name": "from", "in": "query", "description": "Define time filter 'from'", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Define time filter 'to'", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "description": "Filter by owner(s)", "required": false, "schema": { "type": "string" } }, { "name": "runbook", "in": "query", "description": "Filter by runbook ID(s)", "required": false, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Filter by runbook version", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "context", "in": "query", "description": "Filter by context string(s)", "required": false, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "RegEx search for runbook name(s)", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by runbook instance status", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by manual or automated creation", "required": false, "schema": { "type": "string", "enum": [ "manual", "automated" ] } }, { "name": "fields", "in": "query", "description": "Limit the content of the runbook instances to the following fields", "required": false, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "description": "Paginate through the results", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseRunbookInstancesGet" }, "example": [ { "_id": "4e999512bfc4d3bf33dd86088969db30", "_type": "runbookInstance", "_dataModel": 2, "_runbookId": "c14fea67-79de-4b19-b657-e135812bee8e", "_runbookVersion": 1, "_runbookName": "Resolve KB123456 issue on test server", "_createdAt": "2018-03-27T11:16:51.404Z", "_createdBy": "max.mustermann@de.ibm.com", "_modifiedAt": "2018-03-30T14:08:00.808Z", "_modifiedBy": "max.mustermann@de.ibm.com", "_context": "alert:a6cb5ef4-3717-4089-a81f-a7d4763886ff", "_triggeredAutomatically": false, "_automationErrors": "Will only be filled/present in case of FARB executions", "parameters": [ { "name": "serverName", "value": "st456.ibm.com" } ], "history": [ { "action": "complete", "step": 1, "processedAt": 1508339876543, "processedBy": "max.mustermann@de.ibm.com", "parameters": [ { "name": "serverName", "value": "st456.ibm.com" } ] } ], "automationInformation": { "1": { "automationId": "741085209630aced741085209630aced", "automationInstanceId": "555741085209555aced741555209630a", "mappingId": 1, "parameterMappings": [ "…" ], "result": { "status": "successful", "startTime": "2017-10-18T17:17:56.543Z", "output": "Command completed successfully!", "executionTime": 23, "returnCode": 0, "data": "Command completed successfully!" } } }, "status": "complete", "rating": 4, "comment": "This runbook solved the issue", "note": "Don't forget to execute all steps" } ] }, "text/html": { "schema": { "$ref": "#/components/schemas/responseRunbookInstancesGetHtml" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "post": { "summary": "Create a runbook instance", "description": "# Execute a runbook\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the following v2 API endpoints:\n\n*`/aiops/api/v2/configuration/runbook-executions`\n\n*`/aiops/api/v2/configuration/runbook/{id}/executions` (does not support **data** parameter).\n\nFor more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nManually execute a runbook and thereby create a runbook instance for\nthat operation. Calling this API endpoint creates a new execution\nrecord for a specific runbook with specific parameters. The newly\ncreated runbook instance will be of type `manual` and initialized on\nstep 1 of the runbook. You can use the `patch` operation to modify the\nrunbook instance and advance it towards a completed execution.\n\nAccounts with the user role can only execute the latest version of a\nrunbook. You need to have at least the author role to be able to execute\ndraft or older versions of a runbook. If the group feature is enabled,\ncertain users might not have access to all runbooks.\n\n**Note**: The runbook ID necessary for this call is the field with the\nname \"_runbookID\" from any operation retrieving runbooks. You cannot use\nthe document id (typically labeled as \"_id\") as identifier.\n\n## Parameters\n\n* **runbookId**: Execute the runbook with this runbookId.\n* **version**: Optional. Execute a specific version of the runbook. The\ndefault in case this parameter is not specified is the latest version.\nTo execute the draft version of the runbook, specify **0** as the\nversion number.\n* **parameters**: Define the values of the parameters for this runbook execution. Depending on the format\ndefinition of the parameters, each parameter might enforce a specific format and may or may not be mandatory to\nspecify. For every parameter of the runbook not send in this request, the default value will be sent instead, if\nthe parameter has one. If no default value is defined an empty string will be sent instead. Definition of\nparameters and their values is done as an array of objects.\n * **name**: The name of the runbook parameter.\n * **value**: The value of the runbook parameter for this runbook execution.\n* **context**: Optional. Execute this runbook in a specific context.\nThis context can later be used for more fine-grained analysis of\nrunbook execution, for example calculating statistics for a specific runbook\nand context.\nSupported prefixes: `alert:`, `story:`, `policy:`\n* **updateTimeline**: Optional. Specify whether this instance should update the Alert/Story timeline.\nDepends on **context** to contain an Alert or Story ID.\nDefaults to true.\n\n## Response\n\n* **201**: The call was successful. A new runbook instance has been\ncreated.\n* **400**: The input was invalid. Read the error message and adjust your\ninput before trying again.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **402**: The monthly limit of runbook executions in your public cloud\nsubscription is exceeded.\n* **403**: The user is lacking the appropriate rights to conduct this\noperation.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "createRunbookInstance", "tags": [ "Runbook instance" ], "parameters": [ { "name": "runbookId", "in": "query", "description": "Runbook to execute", "required": true, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Version to execute", "required": false, "schema": { "type": "integer" } }, { "name": "context", "in": "query", "description": "Specify the context this runbook is executed in", "required": false, "allowEmptyValue": true, "schema": { "type": "string" } }, { "name": "updateTimeline", "in": "query", "description": "Specify whether this instance should update the alert/story timeline", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "201": { "description": "Runbook instance created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseRunbookInstanceGet" }, "examples": { "response": { "value": [ { "_id": "4e999512bfc4d3bf33dd86088969db30", "_rev": "6-79c2c7a02b83df30477cb8e4eb7d8c3f", "_type": "runbookInstance", "_dataModel": 3, "_runbookId": "c14fea67-79de-4b19-b657-e135812bee8e", "_runbookVersion": 1, "_runbookName": "Resolve KB123456 issue on test server", "_createdAt": 1508339699429, "_createdBy": "max.mustermann@de.ibm.com", "_modifiedAt": 1508339876543, "_modifiedBy": "max.mustermann@de.ibm.com", "_context": "alert:a6cb5ef4-3717-4089-a81f-a7d4763886ff", "_triggeredAutomatically": false, "_automationErrors": "Will only be filled/present in case of FARB executions", "parameters": [ { "name": "serverName", "value": "st456.ibm.com" } ], "history": [ { "action": "complete", "step": 1, "processedAt": 1508339876543, "processedBy": "max.mustermann@de.ibm.com", "parameters": [ { "name": "serverName", "value": "st456.ibm.com" } ] } ], "automationInformation": { "1": { "automationId": "741085209630aced741085209630aced", "automationInstanceId": "555741085209555aced741555209630a", "mappingId": 1, "parameterMappings": [ "…" ], "result": { "status": "successful", "startTime": "2017-10-18T17:17:56.543Z", "output": "Command completed successfully!", "executionTime": 23, "returnCode": 0, "data": "Command completed successfully!" } } }, "status": "complete", "rating": 4, "comment": "This runbook solved the issue", "note": "Don't forget to execute all steps" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestParameters" } } }, "description": "Parameters and their values for running the runbook." } } }, "/runbookinstances/{runbookInstanceId}": { "get": { "summary": "Get a single runbook instance", "description": "# Get runbook instance\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the following v2 API endpoints:\n\n*`/aiops/api/v2/configuration/runbook-executions/{runbookInstanceId}`\n\n*`/aiops/api/v2/configuration/runbooks/{id}/executions` (does not support **data** parameter)\n\nFor more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nRetrieve a single runbook instance identified by the runbook instance id. Searches the execution records of all\nrunbooks for an execution record with the matching runbook instance id. The data is returned as JSON. In order to\nretrieve runbook instances created by another user you need to have author, approver, or manager role. Accounts\nwith user role can only retrieve runbook instances created by themselves. This call also allows specification of\nthe amount of data to be returned. By default, only the runbook instance itself is returned. In case you request\nadditional data like the runbook and/or the automation instance and those cannot be retrieved for any reason,\nthe call will present just the retrievable data instead.\n\n**Note**: The runbook instance ID necessary for this call is the field with the name \"_id\" from any operation\nretrieving runbook instances.\n\n## Output Data Format\n\nThis call supports two different types of output, based on the Media Type/Accept header of the request. The first\noption and default is *application/json* which creates output similar to those of most other Runbook Automation\nAPI calls. The other option is *text/html* which produces HTML output, which can easily be displayed with a browser.\n\n## Parameters\n\n* **runbookInstanceId**: Identify the runbook instance to be retrieved.\n* **data**: Optional. Controls how much data is retrieved. By default only the runbook instance data is retrieved. Specify *runbook* to also retrieve complete runbook data, *automation* to retrieve automation data or *full* to retrieve both. Retrieving additional data will increase the response time of this operation.\n\n## Response\n\n* **200**: The call was successful. See the output for the requested\ndata.\n* **404**: A runbook instance with the supplied runbook instance id\ncould not be found.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "getRunbookInstance", "tags": [ "Runbook instance" ], "parameters": [ { "name": "runbookInstanceId", "in": "path", "description": "ID of the runbook instance", "required": true, "schema": { "type": "string" } }, { "name": "data", "in": "query", "description": "Control the amount of data per instance", "required": false, "schema": { "type": "string", "enum": [ "minimal", "runbook", "automation", "full" ] } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseRunbookInstanceGet" } }, "text/html": { "schema": { "$ref": "#/components/schemas/responseRunbookInstanceGetHtml" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "patch": { "summary": "Change an existing runbook instance", "description": "# Change a runbook instance\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the v2 API endpoint `/aiops/api/v2/configuration/runbook-executions/{runbookInstanceId}`. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nUse this API endpoint to modify existing runbook instances. The following actions associated with runbook\ninstances are realized with this call:\n\n* Changing the runbook parameters for this execution\n* Completing a runbook step\n* Going back one runbook step\n* Pausing a runbook execution\n* Resuming a runbook execution\n* Cancellation of a runbook execution\n* Completion of a runbook execution\n* Providing feedback via success indication, note, and rating\n* Adding and updating data about executed automations\n\nDepending on the state of the runbook instance certain actions might not be available. For example a runbook\ncannot be completed unless it reached the last step. Issuing a patch command on the runbook instance will only\nchange the values provided and will only execute the actions indicated by the request. For example, if no\n`parameters` property is supplied, the parameters will remain unchanged. Actions which change the current step\nof the runbook, will automatically set the state of the runbook from 'paused' to 'in progress', unless the same\nrequest would terminate the instance.\n\n**Note**: The runbook instance ID necessary for this call is the field with the name \"_id\" from any operation\nretrieving runbook instances.\n\n\n## Parameters\n\n* **runbookInstanceId**: Identify the runbook instance to be changed.\n* **runbookInstance**: The change operations to be executed for this\ncall. All values are optional. Specify only those that will effect the\ndesired change.\n * **parameters**: Array of name/value objects. Redefine the runbook parameters for this runbook execution.\n * **name**: The name of the runbook parameter.\n * **value**: The value of the runbook parameters for this runbook execution.\n * **completeStep**: Boolean. If set to `true` the runbook will advance by one step.\n * **previousStep**: Boolean. If set to `true` the runbook will go back one step.\n * **goToStep**: Integer. If set, will set the current active step to the number. Specify the number of runbook steps + 1 to perform a \"go to end of runbook\" action.\n * **pause**: Pause this runbook instance\n * **resume**: Resume this runbook instance\n * **status**: String. Terminates the runbook with the provided status. Must be one of `success`, `failure`, `have errors`, `wrong runbook`, `resolved before end`, `not needed`, `other`. The last five values indicate a cancellation.\n * **note**: String. Set a personal note attached to this runbook execution.\n * **comment**: String. Provide a comment upon runbook completion.\n * **rating**: Integer. Provide a rating between 1-5 upon runbook completion.\n * **automationErrors**: Reserved keyword for automated runbook execution. Do not specify this.\n * **automationInformation**: Object. Passes information about automations executed within the scope of this runbook instance into the runbook instance.\n\n## Additional Input Rules\n\nNot every combination of the aforementioned input is allowed as there\nare additional restrictions how runbook instances can be changed. The\nfollowing rules are also enforced for this operation:\n\n* Runbook instances can only be changed before they entered a terminated\nstate.\n* You may not specify parameters which are not defined as runbook\nparameters in the runbook.\n* \"rating\" must be a value between 1 and 5.\n* \"completeStep\" and \"previousStep\" may not be both set to `true`.\n* If the current step of the runbook instance is the first step, you\ncannot set \"previousStep\" to `true`.\n* If the last step of the runbook has already been executed, you cannot\nset \"completeStep\" to `true`.\n* If the last step of the runbook has not been executed yet, you cannot\nset a completion status, note, comment, or rating.\n* \"comment\" or \"rating\" may only be set, if the \"status\" is also set.\n* \"automationErrors\" may only be set, if the type of execution is\n`automated`.\n* \"goToStep\" may only be set to a number which correlates to a step.\nAdditionally it cannot be combined with \"completeStep\" or\n\"previousStep\".\n\n## Response\n\n* **200**: The call was successful. The runbook instance has been\nchanged.\n* **400**: The input was invalid. Read the error message and adjust your\ninput before trying again.\n* **401**: The request was not authorized. Make sure your API key is\nvalid and the user and password are entered correctly.\n* **403**: The user is lacking the appropriate rights to conduct this\noperation.\n* **404**: A runbook instance with the supplied runbook instance id\ncannot be found.\n* **409**: The runbook instance is currently locked by another user.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "patchRunbookInstance", "tags": [ "Runbook instance" ], "parameters": [ { "name": "runbookInstanceId", "in": "path", "description": "ID of the runbook instance", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseRunbookInstanceGet" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestRunbookInstancePatch" } } }, "description": "The change operations to this runbook instance", "required": true } }, "delete": { "summary": "Delete a single runbook instance", "description": "# Delete runbook instance\n\n**IMPORTANT**: This endpoint is deprecated and replaced by the v2 API endpoint `/aiops/api/v2/configuration/runbook-executions/{runbookInstanceId}`. For more information, see Runbooks in the Cloud Pak for AIOps v2 APIs.\n\n---\n\nDelete a single runbook instance identified by the runbook instance id.\nFor auditing purposes it is recommended to store the content of the runbook instances before deleting it from the system.\nDeleting a runbook instance will also affect the calculation of statistics for the runbook.\n\n**Note**: The runbook instance ID necessary for this call is the field with the name \"_id\" from any operation retrieving runbook instances.\n\n## Cascade delete\n\nUse the cascade option in order to directly delete the automation instances referenced in this runbook instance as well.\nAn automation instance, that cannot be found (for example because it has been deleted before) will be ignored and the operation continues.\nIf a different error occurs during this operation, the runbook instance will not be deleted.\n\n## Authorization\nIn order to delete a runbook instance the manager role is required.\n\n## Parameters\n* **runbookInstanceId**: Identify the runbook instance to be deleted.\n\n## Response\n* **204**: The call was successful.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **403**: The user does not possess the necessary rights to perform this operation.\n* **404**: A runbook instance with the supplied runbook instance id could not be found.\n* **409**: The runbook instances is currently locked and cannot be deleted. Try again later.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "operationId": "deleteRunbookInstance", "tags": [ "Runbook instance" ], "parameters": [ { "name": "runbookInstanceId", "in": "path", "description": "ID of the runbook instance", "required": true, "schema": { "type": "string" } }, { "name": "cascade", "in": "query", "description": "Cascade delete automation instances", "required": false, "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/actions": { "get": { "summary": "Get all actions", "operationId": "getActionAll", "description": "# Get multiple Actions\n\nUse this API endpoint to retrieve several actions at once. This call supports multiple query parameters to\nfilter the output to the desired actions.\n\n## Query parameters\n\nBy default the latest versions of all actions are returned. Use the following query parameters to limit the\nnumber of actions displayed and shape the output the way you need it.\n\n* **version**: Optional. Define which version or which versions of the actions should be returned.\n * **draft** – return only the drafts of the actions. Drafts always have the version '0'. Every actions always has a draft version. In case no changes have been applied after publishing/approving the content of the draft will be equal to the one of the latest version.\n * **approved** – return only the latest approved/published version. An action draft without an approved/published version will not show up in the result of this call.\n * **latest** – this is the default setting. Return only the latest version of an action. If an action has no approved/published version, the draft will be included in the result.\n * **all** – return all versions. This option will return all versions from each action.\n* **fields**: Optional. Restrict the output to the fields specified in this query parameter. You can define any number of fields in a comma separated list. All fields not present in this call will be stripped away. Using this option reduces the amount of transferred data and may yield increased performance.\n* **filterById**: Optional. Comma-separated list of actions IDs. Restrict the returned runbooks to those\ncontained in this list. Each action ID may also define a version using the notation\n`@`. Note however that *filterById* and *version* query parameters are used in\nconjunction. That means a specific action will only be returned, if the specific action is both included via\nthe *version* filter and included via the *filterById* filter. In order to only use *filterById* for arbitrarily\nselecting action versions set *version* to *all*.\n* **filterByTag**: Optional. Restrict the returned actions to those that have the\nspecified tag. Actions without that tag will not be retrieved.\n* **context**: Reserved for future use.\n* **exportFormat**: Reserved for future use.\n\n\n## Access Rights\n\nAccess to actions is limited for users with the user role. Users with roles of author, approver, or manager can\nalways access all actions and all versions of an action. The following list provides details, how restrictions\nfor the user role apply.\n * **Drafts**: The User Role cannot access any draft.\n * **Visibility**: Actions and action versions which cannot be accessed will be filtered out automatically.\n\n## Response\n\nThe response will always be in application/json format.\n* **200**: The call was successful. See the output for the requested data.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "tags": [ "Action" ], "parameters": [ { "name": "version", "in": "query", "description": "Select the versions to retrieve", "required": false, "schema": { "type": "string", "enum": [ "draft", "approved", "latest", "all" ] } }, { "name": "fields", "in": "query", "description": "Limit the content of the runbooks to the following fields", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "filterById", "in": "query", "description": "Filter the actions by IDs (comma-separated list)", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "filterByTag", "in": "query", "description": "Filter the actions by tag", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionsGet" }, "example": { "actions": [ { "_createdAt": "2016-10-23T16:30:28.386Z", "_modifiedAt": "2016-10-25T12:10:87.997Z", "_createdBy": "johndoe@ibm.com", "_modifiedBy": "janedoe@ibm.com", "_type": "action", "_actionType": "script", "_version": "2,", "_state": "published", "_isLatest": true, "_actionId": "7ef63332-5a3e-40f7-a923-af3ffb6795d3", "name": "Create new version of custom app 'xdr_up'", "description": "Performs build, packinging and other steps to create a new version of 'xdr_up'", "prerequisites": "Connectivity to build server and source code repository", "tags": [ "build", "versioning", "cicd" ], "script": { "contentBase64": "XCNcIS9iaW4vc2ggXG4gZWNobyAnVGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUnCg==", "contentPlain": "#!/bin/sh \n echo 'This is just an example'", "shell": "bash" }, "parameters": [ { "name": "hostname", "description": "The hostname of the system to run this script action on", "default": "buildserver01", "type": "string", "minLength": 3, "maxLength": 64 }, { "name": "user", "description": "The user connecting to the system to run this script action", "default": "builduser01", "type": "string", "minLength": 8, "maxLength": 32 } ] }, { "_actionId": "3cf67150-8b53-4ce1-abb6-9aa494e89d76", "_type": "action", "_actionType": "http", "_createdAt": "2022-08-01T15:57:23.723Z", "_modifiedAt": "2022-08-01T16:13:05.234Z", "_createdBy": "johndoe@de.ibm.com", "_modifiedBy": "janedoe@de.ibm.com", "_version": 2, "_state": "published", "_isLatest": true, "name": "Open GitHub Issue - v2", "description": "Creates a new GitHub issue following the template defined in this automation.", "parameters": [ { "name": "$user", "description": "The username associated to the GitHub API access token", "type": "string" }, { "name": "$pass", "description": "The API token/password to access the GitHub API", "type": "string" }, { "name": "$account", "description": "The account under which the GitHub repo is present", "type": "string" }, { "name": "$repo", "description": "The name of the GitHub repository", "type": "string" }, { "name": "$title", "description": "The title of the GitHub issue", "type": "string" }, { "name": "$label", "default": "bug", "description": "An optional label to classify the issue", "type": "string" }, { "name": "$issue", "description": "A texual description of the problem. Describe what is the problem and the difference to the expectation", "type": "string" }, { "name": "$author", "description": "The name of the person reporting this issue", "type": "string" } ], "http": { "host": "https://api.github.com/repos/$account/$repo/issues", "body": "{ \"title\" : \"$title\", \"labels\": [ \"$label\" ], \"body\" : \"# New Issue created by Automation via IBM Cloud Pak for AIOps\\n* Reported by: $author\\n* Issue: $issue\\n\" }", "method": "POST", "ignoreCertErrors": false, "username": "$user" } } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "post": { "summary": "Create a new action", "operationId": "createAction", "description": "# Create a new action\n\nUse this API endpoint to create a new action. You need to define the contents of the new action in the body of\nthis request as a JSON document.\n\n## JSON body\n\nSpecify the input JSON to define a new action. The following properties can be set for all types of actions:\n\n* **name**: The name of the action. This parameter is *mandatory*. Action names may contain up to 200 characters.\n* **description**: Optional. The description of the action. Define what the action is about and additional information to identify or execute the action.\n* **prerequisites**: Optional. Additional description of the prerequisites of the action. Define what is need in order to execute the action.\n* **outputFilter**. Optional. Defines how the output of this action should be filtered.\n * syntax: Choose between one of the three supported output filtering modes: *jsonpath*, *xpath*, or *regularexpression*.\n * query: The query string for the chosen filtering mode. Make sure the string entered here is a valid search term for the type of syntax.\n* **parameters**: Define any parameters you want to use in the action. All properties except 'name' are optional. Action types may require specific parameters to be present. See section below for more information.\n * name: The name of the parameter. A parameter name is mandatory.\n * description: Textual description for what the parameter is used in this action.\n * default: If no other value is specified, the default will be used. The Runbook Automation UI will prefill input fields with the value specified here.\n * type: Define the type of the parameter. The following types are supported: 'string' (default), 'integer', 'boolean', 'array'.\n * enum: Restrict the allowed entry to any values specified in this array. Only supported for parameters of type 'string' or 'integer'.\n * enumLabels: Define an additional set of descriptive texts for your 'enum' values. If no 'enum' is defined, this value is ignored and stripped away.\n * minLength: Set the minimum number of characters for a parameter of type 'string'.\n * maxLength: Set the maximum number of characters for a parameter of type 'string'.\n * minimum: Set the minimum value for a parameter of type 'integer'.\n * maximum: Set the maximum value for a parameter of type 'integer'.\n * minItems: Set the minimum number of items a parameter of type 'array' must contain.\n * maxItems: Set the maximum number of items a parameter of type 'array' may contain.\n * items: Define the allowed items inside a parameter of type 'array'.\n * type: May be either 'string', 'integer', or 'boolean'. Defines one type for all array entries.\n * enum: Restrict the allowed entry to any values specified in this array. Only supported for parameters of type 'string' or 'integer'.\n * enumLabels: Define an additional set of descriptive texts for your 'enum' values. If no 'enum' is defined, this value is ignored and stripped away.\n * format: Provide an additional format for the parameter to further describe the parameter. Supported values are:\n * password: The content is sensitive.\n* **tags**: Tags are defined as an array of strings. Each tag may contain up to 30 characters. You can define any number of tags. Defining tags makes it easier to find the correct action.\n\n### Additional properties for **Script** actions\n\nScript actions need additional properties for the type and content of the script to be executed. These\nproperties are defined in the *script* object.\n\n* **shell**: Define the script shell for this script automation. Values may either be *bash* for scripts on\nLinux/Unix like systems and *powershell* for scripts running on Microsoft Windows.\n* **content**: Defines the content of the script for this script automation.\n* **encoding**: Optional. Set to \"base64\" it defines the input as a base64 encoded string. This allows you to\ndefine script content without the need to escape special characters or to use a binary file with non-printing\ncharacters in it.\n\nFor Actions of type \"script\" the following parameters will always be defined, unless you define them in the\nparameters yourself:\n\n* **target** of type \"string\".\n* **user** of type \"string\".\n\n### Additional properties for **HTTP** actions\n\nHTTP actions need additional properties to define the HTTP request to be sent. Of these properties only *host*\nand *method* are mandatory. You can replace content of the properties with parameter values by using the\nfollowing notation: ${parameterName}. If you are using this notation to use a parameter, a parameter with this\nname must also be defined. These properties are defined in the *http* object.\n\n* **host**: Defines the URL this HTTP Automation will send the request to.\n* **method**: Defines the HTTP method to be used. The following values are supported: *GET*, *PATCH*, *POST*,\n*PUT*, *DELETE*, *OPTIONS*, *HEAD*, *TRACE*.\n* **body**: Optional. Defines the body of the HTTP request.\n* **ignoreCertErrors**: Optional. Boolean value, if set to *true* the HTTP automation will ignore all errors\nrelating to certificates.\n* **username**: Optional. Defines the username of the HTTP authorization header.\n* **password**: Optional: Defines the password of the HTTP authorization header.\n\n### Additional properties for **Client** actions\n\nClient actions need an additional *host* property to define the target the client will be sent to. \nYou can replace content of the properties with parameter values by using the\nfollowing notation: ${parameterName}. If you are using this notation to use a parameter, a parameter with this\nname must also be defined. These properties are defined in the *client* object.\n\n* **host**: Defines the URL this HTTP Automation will send the request to.\n\n### Parameters for Output Filter\n\nOutput filters for an action can be set up with a static definition of the filter via the *outputFilter*\nproperty. In order to instead set up a filter which is controlled by parameter, define parameters with the name\n*filter-query* and *filter-syntax* instead. The presence of any of those two parameters will override the static\nvalue of the *outputFilter* definition. Output filtering will be active, if the *outputFilter* together with the\n*parameters* contain at least one definition for a query and at least one definition for a syntax.\n\n\n## Query parameters\n\nBy default a new action is created as a draft. You may set the query parameter **publish** to `true`. If\ndone so, the action will be published directly.\n\n\n## Response\n\nThe response will always be in application/json format.\n\n* **201**: This indicates a successful action creation. The output will contain _actionId, which you might\nneed for further API operations. Use this ID to identify the action.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "tags": [ "Action" ], "parameters": [ { "name": "publish", "in": "query", "description": "Define to publish new action directly", "required": false, "schema": { "type": "boolean" } } ], "responses": { "201": { "description": "Action created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionCreate" }, "example": { "_actionId": "7ef63332-5a3e-40f7-a923-af3ffb6795d3" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestActionCreate" }, "example": { "name": "Create new version of custom app 'xdr_up'", "description": "Performs build, packinging and other steps to create a new version of 'xdr_up'", "prerequisites": "Connectivity to build server and source code repository", "script": { "shell": "bash", "content": "#!/bin/sh \n buildPackage.sh $version" }, "tags": [ "build", "versioning", "cicd" ], "parameters": [ { "name": "hostname", "description": "The hostname of the system to run this script action on", "default": "buildserver01", "type": "string", "minLength": 3, "maxLength": 64 }, { "name": "user", "description": "The user connecting to the system to run this script action", "default": "builduser01", "type": "string", "minLength": 8, "maxLength": 32 }, { "name": "version", "description": "The version to tag this build with", "type": "integer", "minimum": 0 } ] } } }, "description": "Definition and content of the new action", "required": true } } }, "/actions/{actionId}": { "get": { "summary": "Retrieve a single action", "description": "# Get action\n\nRetrieve one or more versions of an action identified by the actionId. Searches the action repository for a\nsingle action with the supplied actionId. If found, the data is returned.\n\n**Note**: The action ID necessary for this call is the field with the name \"_actionId\" from any operation\nretrieving actions.\n\n## Parameters\n\n* **actionId**: The ID to identify the action. Use the field \"_actionId\".\n* **version**: Optional. This parameter identifies the version to be retrieved. It allows either an integer to\nretrieve a specific version or the keyword \"all\" to get all versions of the action. If not specified the latest\nversion is returned by default. To retrieve the draft specify version as \"0\".\n* **fields**: Optional. Control the output of the command by restricting the displayed fields to the ones of\nthis comma-separated list. This option may not be combined with \"stats\", \"context\" or \"exportFormat\".\n* **stats**: Optional. If set to \"true\" the output will also contain the statistical information of this\naction, including sucess rate, number of executions and their result categories. Enabling this will cause more\ndata to be collected and generally increases the response time. This option may not be combined with \"fields\"\nor \"exportFormat\".\n* **context**: Reserved for future use.\n* **references**: Reserved for future use.\n* **exportFormat**: Reserved for future use.\n\n## Response\n\n* **200**: The call was successful. The requested data is returned to the caller.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **403**: The user is lacking the appropriate rights to conduct this operation.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "operationId": "getAction", "tags": [ "Action" ], "parameters": [ { "name": "actionId", "in": "path", "description": "ID of the action to get", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Specify the version to get", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Limit the content of the action to the following fields", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "stats", "in": "query", "description": "Include action statistics", "required": false, "allowEmptyValue": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionGet" }, "example": { "_createdAt": "2016-10-23T16:30:28.386Z", "_modifiedAt": "2016-10-25T12:10:87.997Z", "_createdBy": "johndoe@ibm.com", "_modifiedBy": "janedoe@ibm.com", "_type": "action", "_actionType": "script", "_version": "2,", "_state": "published", "_isLatest": true, "_actionId": "7ef63332-5a3e-40f7-a923-af3ffb6795d3", "name": "Create new version of custom app 'xdr_up'", "description": "Performs build, packinging and other steps to create a new version of 'xdr_up'", "prerequisites": "Connectivity to build server and source code repository", "tags": [ "build", "versioning", "cicd" ], "script": { "contentBase64": "XCNcIS9iaW4vc2ggXG4gZWNobyAnVGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUnCg==", "contentPlain": "#!/bin/sh \n echo 'This is just an example'", "shell": "bash" }, "parameters": [ { "name": "hostname", "description": "The hostname of the system to run this script action on", "default": "buildserver01", "type": "string", "minLength": 3, "maxLength": 64 }, { "name": "user", "description": "The user connecting to the system to run this script action", "default": "builduser01", "type": "string", "minLength": 8, "maxLength": 32 } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "put": { "summary": "Change an action", "description": "# Change action\n\nChange the content or state of a single action identified by the actionId. Use this call for all changes to\nexisting actions. These possible changes include: Changing the meta data of an action, creating a new version,\nand changing the content of the action. It cannot be used to create a new runbook.\n\nNote: The action ID necessary for this call is the field with the name \"_actionId\" from any operation retrieving\nactions.\n\n## JSON body\n\nCheck the description of \"Create Action\". It contains the full description of the JSON body input for this operation.\n\n## Query parameters\n\nBy default changing an action updates the draft only. If you want to create a new version you may set the query\nparameter **publish** to `true`. If done so, the changed action will be published directly.\n\n## Response\n\nThe response will always be in application/json format.\n\n* **200**: The call was successful. The action has been changed.\n* **201**: The call was successful. A new version of the action has been created.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **403**: The user is lacking the appropriate rights to conduct this operation.\n* **404**: An action with the supplied actionId cannot be found.\n* **409**: The action is currently locked by another user.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "operationId": "putAction", "tags": [ "Action" ], "parameters": [ { "name": "actionId", "in": "path", "description": "ID of the action to change", "required": true, "schema": { "type": "string" } }, { "name": "publish", "in": "query", "description": "Define to publish changed action directly", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Action changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionCreate" } } } }, "201": { "description": "Action created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionCreate" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "Locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestActionCreate" }, "example": { "name": "Create new version of custom app 'xdr_up'", "description": "Performs build, packinging and other steps to create a new version of 'xdr_up'", "prerequisites": "Connectivity to build server and source code repository", "script": { "shell": "bash", "content": "#!/bin/sh \n buildPackage.sh $version" }, "tags": [ "build", "versioning", "cicd" ], "parameters": [ { "name": "hostname", "description": "The hostname of the system to run this script action on", "default": "buildserver01", "type": "string", "minLength": 3, "maxLength": 64 }, { "name": "user", "description": "The user connecting to the system to run this script action", "default": "builduser01", "type": "string", "minLength": 8, "maxLength": 32 }, { "name": "version", "description": "The version to tag this build with", "type": "integer", "minimum": 0 } ] } } }, "description": "Definition and content of the new action", "required": true } }, "patch": { "summary": "Partially change an action", "description": "# Partially change action\n\nChange the content or state of a single action identified by the actionId. Use this call for all changes to\nexisting actions. These possible changes include: Changing the meta data of an action, creating a new version,\nand changing the content of the action. It cannot be used to create a new action. Until published or\napproved, all changes will affect only the draft version of the action.\n\nThis call accepts partial updates which will be merged with the current draft version. Unspecified properties of the action will remain unchanged.\n\nNote: The action ID necessary for this call is the field with the name \"_actionId\" from any operation retrieving\nactions.\n\n## Query parameters\n\nBy default changing an action updates the draft only. If you want to create a new version you may set the query\nparameter **publish** to `true`. If done so, the changed action will be published directly.\n\n## Examples\n\n* Change the description of an action, but keep all other properties of\n the action unchanged:\n ```\n {\n \"description\" : \"This action updates a server's HTTPS module.\"\n }\n ```\n* Delete the existing set of parameters:\n ```\n {\n \"parameters\" : [],\n }\n ```\n* Delete HTTP action headers, but keep the rest unchanged:\n ```\n {\n \"http\" : {\n \"headers\": \"\"\n }\n }\n ```\n\n## Additional Input Rules\n\nNot every combination of input conforming to the schema is allowed as there are additional restrictions how actions can be created/updated.\nThe following rules are also enforced for this operation.\n\n* If the query parameter \"publish\" is set to true, the user doing the request must have the permission to publish an action.\n* An action's type may not be changed using this endpoint.\n* Setting a string value to an empty string will result in that field being removed from the action definition (as long as that is permitted in the data model).\n* Parameters can not be changed partially - changing them will always override the entire array.\n\n## Response\n\nThe response will always be in application/json format.\n\n* **200**: The call was successful. The action has been changed.\n* **201**: The call was successful. A new version of the action has been created.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **403**: The user is lacking the appropriate rights to conduct this operation.\n* **404**: An action with the supplied actionId cannot be found.\n* **409**: The action is currently locked by another user.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "operationId": "patchAction", "tags": [ "Action" ], "parameters": [ { "name": "actionId", "in": "path", "description": "ID of the action to change", "required": true, "schema": { "type": "string" } }, { "name": "publish", "in": "query", "description": "Define to publish changed action directly", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Action changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionCreate" } } } }, "201": { "description": "Action created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionCreate" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "Locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestActionPatch" }, "example": { "description": "Performs build, packinging and other steps to create a new version of 'xdr_up'", "script": { "shell": "bash", "content": "#!/bin/sh \n buildPackage.sh $version" }, "parameters": [ { "name": "hostname", "description": "The hostname of the system to run this script action on", "default": "buildserver01", "type": "string", "minLength": 3, "maxLength": 64 }, { "name": "user", "description": "The user connecting to the system to run this script action", "default": "builduser01", "type": "string", "minLength": 8, "maxLength": 32 } ] } } }, "description": "Updated partial content of the new action", "required": true } }, "delete": { "summary": "Delete a single action", "description": "# Delete action\n\nCompletey delete an action.\n\nThis call deletes all versions of the action including the draft. This action is not reversible. In case this\naction is referenced by other runbooks, this call will fail with an 412 error code. The error message will\ncontain information as to which runbooks are referencing this action. Either remove all references before trying\nthis call again or use the \"force\" option. Using \"force\" will allow you to delete this action, even when it is\nreferenced by other runbooks. However it will leave all runbooks referencing this runbook in an erroneous state,\nin which they cannot be run.\n\n## Parameters\n\n* **actionId**: The ID to identify the action to be deleted. Use the field \"_actionId\".\n* **force**: Optional. Force a deletion, even if the actions is referenced somewhere else.\n\n## Response\n\n* **203**: The call was successful. The action is deleted.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered\ncorrectly.\n* **403**: The user is lacking the appropriate rights to conduct this operation.\n* **404**: An Action with the specified actionId does not exist.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM\nsupport.\n", "operationId": "deleteAction", "tags": [ "Action" ], "parameters": [ { "name": "actionId", "in": "path", "description": "ID of the action to delete", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "description": "Optional. Force a deletion, even if the action is referenced somewhere else.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/actioninstances": { "get": { "summary": "Get all action instances", "operationId": "getActionInstanceAll", "description": "# Get multiple Action instances\n\nRetrieve several actions instances at once. An action instance is the execution record of one action execution.\nIt contains information about who executed the action, and when the execution happened. It does not include\ncertain action instance fields like output, parsingError and parameters. This call supports multiple query\nparameters, which can be combined to narrow down the output to the desired action instances.\n\nYou need to have at least the author role to be able to see all action instances, regardless of ownership.\nAccounts with user role only, will only be able to see action instances on which they can claim ownership.\n\n**Note**: The default for querying action instances is to retrieve the instances from the last seven days. Use\nthe query parameters *from* and *to* to get instances from a different time frame.\n\n## Query parameters\n\n* **from**: Optional. Only display action instances started after the value from this field. You can use a string representing a time (for example, \"2022-03-15\") or a timestamp. If no value is set, the default is seven days before the current time.\n* **to**: Optional. Only display action instances started before the value from this field. You can use a string representing a time (for example, \"2022-03-15\") or a timestamp. If no value is set, the default is the current time.\n* **owner**: Optional. Accepts a user name or a comma-separated list of user names. Restricts the output to action instances created by one of the defined users.\n* **action**: Optional. Accepts an action ID or a comma-separated list of action IDs. Will only display the action instances matching a supplied action ID. Use API endpoints from the actions section to retrieve suitable action IDs.\n* **status**: Optional. Restricts the output to action instances matching the chosen status. The following values are allowed: *executing*, *successful*, *unsuccessful*, *failed*.\n* **type**: Optional. Restricts the output to action instances matching the chosen type. The following values are allowed: *http*, *script*, *awx*, *client*, *predefined*.\n* **fields**: Optional. Use *fields* to restrict the output to the properties specified in this query parameter. Accepts a comma separated list. All properties not in the list will not be displayed.\n* **context**: Optional. Restricts the output to action instances with (at least one) matching context. Accepts a comma separated list.\n\nAll query parameters can be combined to retrieve the desired data.\n\n## Response\n\nThe response will always be in application/json format.\n* **200**: The call was successful. See the output for the requested data.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "tags": [ "Action instance" ], "parameters": [ { "name": "from", "in": "query", "description": "Define time filter 'from'", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Define time filter 'to'", "required": false, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "description": "Filter by owner(s)", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by action type", "required": false, "schema": { "type": "string", "enum": [ "http", "script", "awx", "client", "predefined" ] } }, { "name": "status", "in": "query", "description": "Filter by action instance status", "required": false, "schema": { "type": "string", "enum": [ "executing", "successful", "unsuccessful", "failed" ] } }, { "name": "action", "in": "query", "description": "Filter by action ID(s)", "required": false, "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Limit the content of the action instances to the following fields", "required": false, "allowEmptyValue": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionInstanceGetAll" }, "example": { "instances": [ { "_type": "actionInstance", "_actionInstanceId": "2282ac4d8c5af35300693b072fee00a9", "_actionId": "22d4a3bdf72839d49736bb778c3ec231", "_actionVersion": 1, "_actionType": "script", "_createdAt": "2020-01-20T11:47:47.712Z", "_createdBy": "johndoe@ibm.com", "status": "failed", "executionTime": 2, "rating": 1 }, { "_type": "actionInstance", "_actionInstanceId": "eb86037f9ec5c3a3f7b3d98333dd0be7", "_actionId": "e2f1fe6b5a4305d7b548081c2bcdaf61", "_actionVersion": 2, "_actionType": "http", "_createdAt": "2019-10-10T09:36:21.223Z", "_createdBy": "janedoe@ibm.com", "status": "successful", "executionTime": 1, "rating": 5, "comment": "Worked well", "returnCode": 200 } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "post": { "summary": "Create an action instance", "description": "# Execute an action\n\nExecute an action and thereby create an action instance for\nthat operation. Calling this API endpoint creates a new execution\nrecord for a specific action with specific parameters. Once kicked\noff you can use the `get` operation on the action instance to monitor\nits execution status.\n\nAccounts with the user role can only execute published versions of an\naction. You need to have at least the author role to be able to execute\na draft action.\n\n**Note**: The action ID necessary for this call is the field with the\nname \"_actionId\" from any operation retrieving actions.\n\n## Parameters\n\n* **actionId**: Execute the action with this actionId.\n* **version**: Optional. Execute a specific version of an action. The\ndefault in case this parameter is not specified is the latest version.\nTo execute the draft version of the action, specify **0** as the\nversion number.\n* **sync**: Optional. Execute this action synchronously. By default all executions are asynchronous.\nWhen set to true, the response will wait until either the syncTimeout has been reached or the action\nhas terminated. The response will contain the instance including status and output.\n* **timeout**: Deprecated. Use 'syncTimeout' instead.\n* **syncTimeout**: Set a request timeout in ms for synchronous executions - this has no effect on asynchronous ones.\nThis does not limit how long the execution will run, it only limits the request to ensure a response is sent within the specified time.\nDefaults to 30000.\n* **parameters**: Define the values of the parameters for this action execution. Depending on the format\ndefinition of the parameters, each parameter might enforce a specific format and may or may not be mandatory to\nspecify. For every parameter of the action not send in this request, the default value will be used instead, if\nthe parameter has one. If no default value is defined an empty string will be used instead. Definition of\nparameters and their values is done as an array of objects.\n * **name**: The name of the action parameter.\n * **value**: The value of the action parameter for this action execution.\n* **context**: Optional. Create an action instance in a specific context.\nThis context can later be used for more fine-grained analysis of\naction execution and tie it to specific other elements like Alerts or Stories in AIManager.\nSupported prefixes: `alert:`, `story:`, `policy:`\n* **updateTimeline**: Optional. Specify whether this instance should update the Alert/Story timeline.\nDepends on **context** to contain an Alert or Story ID.\nDefaults to true.\n\n## Response\n\n* **201**: The call was successful. A new action instance has been created.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **403**: The user is lacking the appropriate rights to conduct this operation.\n* **404**: An action with the specified ID and version was not found.\n* **500**: An internal error happened. A correlationId is provided.\nInclude this ID in any request towards IBM support.\n", "operationId": "createActionInstance", "tags": [ "Action instance" ], "parameters": [ { "name": "actionId", "in": "query", "description": "Action to execute", "required": true, "allowEmptyValue": false, "schema": { "type": "string" } }, { "name": "version", "in": "query", "description": "Version to execute", "required": false, "schema": { "type": "integer" } }, { "name": "sync", "in": "query", "description": "Execute the action synchronously", "required": false, "schema": { "type": "boolean" } }, { "name": "timeout", "in": "query", "description": "Deprecated. Use 'syncTimeout' instead.", "required": false, "schema": { "type": "integer" }, "deprecated": true }, { "name": "syncTimeout", "in": "query", "description": "Request timeout for synchronous execution request (only used if sync is true)", "required": false, "schema": { "type": "integer" } }, { "name": "context", "in": "query", "description": "Specify the context this action is executed in", "required": false, "schema": { "type": "string" } }, { "name": "updateTimeline", "in": "query", "description": "Specify whether this instance should update the alert/story timeline", "required": false, "allowEmptyValue": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "201": { "description": "Action instance created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionInstanceCreate" }, "examples": { "response": { "value": [ { "_actionInstanceId": "25543bbe2e945d6a5bde7d13ba009301" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestActionInstanceCreate" } } }, "description": "Parameters and their values for running the action." } } }, "/actioninstances/{actionInstanceId}": { "get": { "summary": "Get action instance", "operationId": "getActionInstance", "description": "# Get action instance\n\nRetrieve a single action instance identified by the action instance id. Searches the execution records of all\nactions for an execution record with the matching action instance id. In order to retrieve action instances\ncreated by another user you need to have author, approver, or manager role. Accounts with user role can only\nretrieve action instances created by themselves.\n\n## Data\n\nThis call supports different levels of data returned. The faster option *default* will return the action\ninstance data, while the option *full* will also additionally retrieve the data of the action itself, which will\ntake more time.\n\n**Note**: If the Action Instance is the execution record of an action's draft version, the action will never be\nincluded, even if *full* is defined.\n\n## Response\n\n* **200**: The call was successful. See the output for the requested data.\n* **404**: An action instance with the supplied action instance id could not be found.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "tags": [ "Action instance" ], "parameters": [ { "name": "actionInstanceId", "in": "path", "description": "ID of the action instance", "required": true, "schema": { "type": "string" } }, { "name": "data", "in": "query", "description": "Defines which data should be retrieved.", "required": false, "schema": { "type": "string", "enum": [ "default", "full" ] } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionInstanceGet" }, "example": { "_type": "actionInstance", "_actionInstanceId": "eb86037f9ec5c3a3f7b3d98333dd0be7", "_actionId": "e2f1fe6b5a4305d7b548081c2bcdaf61", "_actionVersion": 2, "_actionType": "http", "_createdAt": "2019-10-10T09:36:21.223Z", "_createdBy": "janedoe@ibm.com", "status": "successful", "output": { "timestamp": "2019-10-10T09:36+0000", "branch": "HEAD", "commit": "a1dd7c474d5844a4ab387a01be25e8a3", "name": "rba-rbs", "version": "1.28.0" }, "executionTime": 1, "rating": 5, "comment": "Worked well", "returnCode": 200 } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "patch": { "summary": "Change action instance", "operationId": "patchActionInstance", "description": "# Patch action instance\n\nChanges a single action instance. Action instances can only be changed after the associated automation action\nhas finished. Use this endpoint to give feedback via comments and rating to action instances.\n\n## Response\n\n* **200**: The call was successful. Action instance has been changed.\n* **400**: The input was invalid. Read the error message and adjust your input before trying again.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **404**: An action instance with the specified ID was not found.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "tags": [ "Action instance" ], "parameters": [ { "name": "actionInstanceId", "in": "path", "description": "ID of the action instance", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestActionInstancePatch" } } }, "description": "Changes to be made to the action instance", "required": true }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseActionInstanceGet" }, "example": { "_type": "actionInstance", "_actionInstanceId": "eb86037f9ec5c3a3f7b3d98333dd0be7", "_actionId": "e2f1fe6b5a4305d7b548081c2bcdaf61", "_actionVersion": 2, "_actionType": "http", "_createdAt": "2019-10-10T09:36:21.223Z", "_createdBy": "janedoe@ibm.com", "status": "successful", "output": { "timestamp": "2019-10-10T09:36+0000", "branch": "HEAD", "commit": "a1dd7c474d5844a4ab387a01be25e8a3", "name": "rba-rbs", "version": "1.28.0" }, "executionTime": 1, "rating": 5, "comment": "Automation action worked well and solved the issue.", "returnCode": 200 } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "delete": { "summary": "Delete a single action instance", "operationId": "deleteActionInstance", "description": "# Delete action instance\n\nDelete a single action instance identified by the action instance id.\nFor auditing purposes it is recommended to store the content of the action instances before deleting it from the system.\nDeleting an action instance will also affect the calculation of statistics for the action.\n\n**Note**: The action instance ID necessary for this call is the field with the name \"_actionInstanceId\" from any\noperation retrieving action instances.\n\n## Authorization\nIn order to delete an action instance the manager role is required.\n\n## Parameters\n* **actionInstanceId**: Identify the action instance to be deleted.\n\n## Response\n* **204**: The call was successful.\n* **401**: The request was not authorized. Make sure your API key is valid and the user and password are entered correctly.\n* **403**: The user does not possess the necessary rights to perform this operation.\n* **404**: An action instance with the supplied action instance id could not be found.\n* **500**: An internal error happened. A correlationId is provided. Include this ID in any request towards IBM support.\n", "tags": [ "Action instance" ], "parameters": [ { "name": "actionInstanceId", "in": "path", "description": "ID of the action instance", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/configuration": { "get": { "summary": "Get configuration", "description": "# Get configuration for current subscription\n\nThe configuration is displayed as a JSON and includes configuration options for the following features:\n\n## groups\n\nThis boolean parameter defines whether or not the group feature is enabled. When enabled you are able to assign\nusers and runbooks to runbooks in order to restrict operator access. Learn more about the group feature on page \"Assigning runbooks to groups\".\n\n## approvals\n\nThe boolean parameters defined whether or not the approval feature is enabled. When enabled runbooks cannot be\npublished directly, but need an approval first. Learn more about the approval feature on page \"Runbook approval process\".\n\n## runbookExpirationTime\n\nThis integer value is only relevant if approvals are enabled. It marks the period in days when an approved\nrunbook should be marked expired. This enforces regular revalidation of runbooks. Specify '0' to disable\nrunbook expiration.\n\n## impact\n\nThis object value has five properties: active, url, user, password, and certificate. Use *active* to enable or disable the\nImpact connection. The values for *url*, *user*, and *password* are mandatory, once the connection is active.\nThe *certificate* is optional for adding server authentication to the https requests. For security reasons, the password\nwill never be sent from the system to the user.\n\n## github\n\nThis object has eight properties: active, api, token, owner, repo, folder, branch and certificate. Use *active* to enable or disable the GitHub connection.\nThe values *api*, *token*, *owner* and *repo* are mandatory, once the connection is active.\nThe configuration value *api* defines the API to be used ([GitHub Public](https://docs.github.com/en/rest/reference/enterprise-admin#endpoint-urls)/[Enterprise](https://docs.github.com/en/enterprise-server@2.22/rest/reference/enterprise-admin#endpoint-urls)), for example, https://api.github.com or http(s)://[hostname]/api/v3.\nThe configuration value *token* defines the personal access token with at least read permission to the defined owner and repo defined.\nThe configuration value *owner* defines the owner/organization of the GitHub URL, for example, myorg from the URL https://github.com/myorg/myrepo.\nThe configuration value *repo* defines the repository to use within the owner/organization of the GitHub URL, for example, myrepo from the URL https://github.com/myorg/myrepo.\nThe configuration value *folder* defines the folder within a given repo to scan for runbook automation data (default: root directory of the repository).\nThe configuration value *branch* defines the branch to use in the defined GitHub repository (default: Default branch of the repository).\nThe configuration value *certificate* is optional for adding server authentication to the https requests.\n\n## script\n\nThis object has the following properties: active, keys, jumpserver.\nThe object *keys* contains a set of named keys. Each key can contain the following properties: *priority*, *group*, *publickey*, *error*.\nThe value *priority* can be used to configure which key should be tried first. Lower numbers indicate higher priority. Using priority is optional. Keys without priority will be tried last. It is allowed to use the same priority for multiple keys if there is no specific order which should be enforced.\nThe value *group* can be used to limit usage of this key to a specific user group.\nThe value *publickey* contains the public key which needs to be configured in the target's *authorized_keys* file.\nThe value *error* indicates that there is an error with this specific key and that it cannot be used. Usually there is only either *publickey* or *error*.\nThe object *jumpserver* contains the following properties: active, hostname, port, username.\nThe values *hostname* and *port* define the jumpserver to be use.\nThe value *username* defines the unix user to use when connecting to the jumpserver.\n", "operationId": "getConfiguration", "tags": [ "Configuration" ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseConfiguration" }, "example": { "_createdAt": 1550677394166, "_createdBy": "max.mustermann@de.ibm.com", "_modifiedAt": 1550677418268, "_modifiedBy": "lena.mustermann@de.ibm.com", "groups": false, "approvals": true, "runbookExpirationTime": 365, "impact": { "active": true, "url": "https://myImpact04:16311", "user": "adminMax", "certificate": "" }, "github": { "active": true, "api": "https://api.github.com", "token": "xxxxxxxxxxxxxxxxxxxx", "owner": "myorg", "repo": "myrepo", "folder": "runbooks", "branch": "main", "certificate": "" }, "script": { "active": true, "keys": { "default": { "priority": 1, "publickey": "ssh-rsa xxxxxxx " }, "alternative": { "priority": 2, "publickey": "ssh-rsa yyyyyyy " } }, "jumpserver": { "active": true, "hostname": "myjumpserver.mycompany", "port": 22, "username": "unixuser" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "patch": { "summary": "Change configuration", "description": "# Change configuration for current subscription.\n\nChange the existing configuration for the current subscription. Each subscription always has exactly one\nconfiguration object, so it does not need to be created. Values which are not defined will remain unchanged.\nThe following keywords can be changed:\n * groups\n * approvals\n * runbookExpirationTime\n * impact\n * impact.active\n * impact.url\n * impact.user\n * impact.password\n * impact.certificate\n * github\n * github.active\n * github.api\n * github.token\n * github.owner\n * github.repo\n * github.folder\n * github.branch\n * github.certificate\n * script\n * script.active\n * script.keys\n * script.keys.*keyname*\n * script.keys.*keyname*.priority\n * script.keys.*keyname*.group\n * script.keys.*keyname*.privatekey\n * script.keys.*keyname*.passphrase\n * script.keys.*keyname*.generate\n * script.keys.*keyname*.delete\n * script.jumpserver\n * script.jumpserver.active\n * script.jumpserver.hostname\n * script.jumpserver.port\n * script.jumpserver.username\n * script.jumpserver.password\n * script.jumpserver.useSshKey\n * ansible\n * ansible.active\n * ansible.url\n * ansible.user\n * ansible.password\n * ansible.token\n * ansible.certificate\n\n## groups\n\nThis boolean parameter defines whether or not the group feature is enabled. When enabled you are able to assign\nusers and runbooks to runbooks in order to restrict operator access. Learn more about the group feature on page \"Assigning runbooks to groups\".\n\n## approvals\n\nThe boolean parameters defined whether or not the approval feature is enabled. When enabled runbooks cannot be\npublished directly, but need an approval first. Learn more about the approval feature on page \"Runbook approval process\".\n\n## runbookExpirationTime\n\nThis integer value is only relevant if approvals are enabled. It marks the period in days when an approved\nrunbook should be marked expired. This enforces regular revalidation of runbooks. Specify '0' to disable\nrunbook expiration.\n\n## impact\n\nThis object value has five properties: active, url, user, password, and certificate. Use *active* to enable or disable the\nImpact connection. You can change each of these properties individually. Disabling the Impact connection by sending\n`{ \"impact\" : { \"active\" : false } }` will delete all other values from previous settings and set them to their default unset stage.\nThe *certificate* is optional for adding server authentication to the https requests. For security reasons, the password will never\nbe sent from the system to the user.\n\n## github\n\nThis object value has eight properties: active, api, token, owner, repo, folder, branch and certificate. Use *active* to enable or disable the\nGitHub connection. You can change each of these properties individually. Disabling the GitHub connection by sending\n`{ \"github\" : { \"active\" : false } }` will delete all other values from previous settings and set them to their default unset stage.\nIf the api property is changed, the token needs to be supplied again.\nThe *certificate* is optional for adding server authentication to the https requests. For security reasons, the token will never\nbe sent from the system to the user.\n\n## script\n\nThis object value has the properties: active, keys and jumpserver.\nUse *active* to enable or disable the Script connection. Disabling the Script connection by sending `{ \"script\" : { \"active\" : false } }` will delete all other values from previous settings and set them to their default unset stage.\nUse *keys* to individually create, modify or delete named keys with the properties *generate*, *priority*, *group*, *privatekey*, *passphrase* and *delete*.\nSetting the *generate* property on a key will trigger (re-)generation of the key. Supported values for generate are *rsa-2048*, *rsa-3072*, *rsa-4096*, *ecdsa-256*, *ecdsa-384*, *ecdsa-521* and *ed25519*. Note that *ed25519* is not available when the cluster is in FIPS mode.\nUse *priority* on a key to configure which key to try first. Lower numbers indicate higher priority. Using priority is optional. Keys without priority will be tried last. It is allowed to use the same priority for multiple keys if there is no specific order which should be enforced.\nUse *group* on a key to limit usage of this key to a specific user group. Set it to empty string to remove existing group limitation.\nSet *privatekey* and *passphrase* on a key to import an existing key. Private keys that are not encrypted do not require a passphrase to be set. Note that *privatekey* and *passphrase* can be imported in separate API calls. When importing them in separate API calls the encrypted key will only work once both are specified.\nSetting the *delete* property on a key to *true* will trigger deleting the key. Has no effect if the named key does not exist.\nUse *jumpserver* to configure a jumpserver with the properties active, hostname, port, username and password (or useSshKey to use the existing SSH keys to authenticate instead of a password).\nUse *active* to enable or disable the jumpserver. Disabling the jumpserver by sending `{ \"script\" : { \"jumpserver\" : { \"active\" : false } } }` will delete all other jumpserver values from previous settings and set them to their default unset stage.\nIf the hostname, port or username is changed, the password needs to be supplied again.\nFor security reasons, the privatekey or passphrase from keys or the password of the jumpserver will never be sent from the system to the user.\n\n*Note*: If multiple keys exist in the script configuration they are tried in the specified order until a working key is found. This may result in expected failed authentication attempts. Consider adjusting existing security monitoring tools accordingly.\n\n## ansible\n\nThis object value has six properties: active, url, user, password, token and certificate.\nUse *active* to enable or disable the Ansible connection. Disabling the Ansible connection by sending `{ \"ansible\" : { \"active\" : false } }` will delete all other values from previous settings and set them to their default unset stage.\nUse either *user* and *password* or *token* to configure authentication. If any other properties are changed, the password or token needs to be supplied again.\nThe *certificate* is optional for adding server authentication to the https requests. For security reasons, the password or token will never be sent from the system to the user.\n\n## Additional input rules\n\n * If impact.active is *true*, the values for impact.url, impact.user, and impact.password also need to be set. *Note*: You can still change the user, name, and password individually once the Impact connection has been defined.\n * If impact.active is *false*, no other properties for impact may be set.\n * If github.active is *true*, the values for github.api, github.token, github.owner, github.repo also need to be set. The properties github.folder and github.branch are optional, if not set defaults are used.\n *Note*: You can still change the api, token, owner, repo, folder and branch individually once the GitHub connection has been defined.\n * If github.active is *false*, no other properties for github may be set.\n * If script.active is *false*, no other properties for script may be set.\n * If script.jumpserver.active is *false*, no other properties for script.jumpserver may be set.\n", "operationId": "patchConfiguration", "tags": [ "Configuration" ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseConfiguration" }, "example": { "_createdAt": 1550677394166, "_createdBy": "max.mustermann@de.ibm.com", "_modifiedAt": 1550677418268, "_modifiedBy": "lena.mustermann@de.ibm.com", "groups": false, "approvals": true, "runbookExpirationTime": 365, "impact": { "active": true, "url": "https://impactServer01:16311", "user": "adminMax", "certificate": "" }, "github": { "active": true, "api": "https://api.github.com", "owner": "myorg", "repo": "myrepo", "folder": "runbooks", "branch": "main", "certificate": "" }, "script": { "active": true, "keys": { "default": { "priority": 1, "publickey": "ssh-rsa xxxxxxx " }, "alternative": { "priority": 2, "publickey": "ssh-rsa yyyyyyy " } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModelBadRequest" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/requestConfigurationPatch" } } }, "description": "Values to change in the configuration", "required": true } } }, "/users": { "get": { "summary": "Get all users", "description": "Get a list of users in the current subscription. Optionally the list can\nbe filtered by the query parameter \"role\", which accepts a comma\nseparated list of roles (user, author, approver, manager). Only users\nwith at least one of the specified roles will be displayed.\n", "operationId": "getUsers", "tags": [ "User" ], "parameters": [ { "name": "role", "in": "query", "description": "List only users with these roles", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseUsers" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/tags": { "get": { "summary": "Get all tags", "description": "# Get all tags used in either the runbook library or the action library\n\nThis call retrieves all unique tags used in the runbook library or the action library. It supports different parameters to refine the result.\n\n## Query Parameters\n\n* version\n * **approved** [default value] – Only recognize tags used the latest approved/published versions of runbooks or actions.\n * **latest** – Recognize tags used in the latest version of each runbook or action.\n * **all** - Gather tags from all runbook or action versions and drafts.\n* source\n * **runbooks** [default value] - Only return tags used in runbooks.\n * **actions** - Only return tags used in actions.\n", "operationId": "tagAll", "tags": [ "Tag" ], "parameters": [ { "name": "version", "in": "query", "description": "Select the runbook or action versions to retrieve tags from", "required": false, "schema": { "type": "string", "enum": [ "approved", "latest", "all" ], "default": "approved" } }, { "name": "source", "in": "query", "description": "Select whether tags should be retrieved from runbooks or from actions", "required": false, "schema": { "type": "string", "enum": [ "runbooks", "actions" ], "default": "runbooks" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/statistics/runbookinstances": { "get": { "summary": "Retrieve usage statistics for runbookinstances", "description": "# Usage Statistics\n\nRetrieve usage statistics of your Runbook Automation subscription. This\ncall retrieves statistics concerning the number of runbook instances.\nEach runbook instance represents one runbook execution. Only executions\non published/approved runbooks are added, executions on draft versions\nof runbooks are ignored. You can use the optional parameters **from**\nand **to** to define a time frame. The output will contain a JSON object\nwith the fields **startTime**, **endTime**, and\n**productionExecutions**.\n\n## Parameters\n\n* **from**: Optional. Only display statistics for operations started after the value from this field. You can\nuse a string representing a time (for example, \"2022-03-15\") or a timestamp. If no value is set, the default is set to\n1970-01-01.\n* **to**: Optional. Only display statistics for operations started before the value from this field. You can use\na string representing a time (for example, \"2022-03-15\") or a timestamp. If no value is set, the default is set to the\ncurrent time.\n* **startTime**: Optional. See **from**. If both are defined, **from**\ntakes precedence.\n* **endTime**: Optional. See **to**. If both are defined, **to** takes\nprecedence.\n", "operationId": "getUsageStatistics", "tags": [ "Statistics" ], "parameters": [ { "name": "from", "in": "query", "description": "Select the start time for the usage time frame.", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Select the end time for the usage time frame.", "required": false, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Select the start time for the usage time frame.", "required": false, "schema": { "type": "string" } }, { "name": "endTime", "in": "query", "description": "Select the end time for the usage time frame.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseStatisticsRunbookInstancesGet" }, "examples": { "response": { "value": [ { "startTime": "2017-11-01T00:00:00.000Z", "endTime": "2017-12-01T00:00:00.000Z", "productionExecutions": 1387 } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/status": { "get": { "summary": "Get the status of Runbook Automation", "description": "# Checks the connection status to all Runbook Automation components\n\nThis call can be used in two separate ways. First by not supplying a connection or leaving it empty, it will\nprovide an overview status of all components and services. Second by defining the connection query parameter you\ncan get more detailed status information for one specific connection.\n\n## Overview mode\n\nIf connections are defined, the status of the connection is also retrieved. The check includes Runbook Automation micro\nservices including the database service and all connections. Connections include Ansible connection,\nImpact connection and script connection.\n\nThe output is a JSON object with properties for each connection checked:\n\n* **rbs**: Runbook service\n* **as**: Automation service\n* **db**: Database connection\n* **connection**: Connection information\n * **AWX**: Ansible connection\n * **IMPACT**: Impact connection\n * **SCRIPT**: Script connection\n* **errors**: If errors occur, the error codes are displayed in an array here.\n\nFor every service a **0** indicates good status, **1** indicates an error, and **2** indicates this service is\nnot part of the deployment.\n\nFor connections a **0** indicates good status, a **1** indicates an error in the connection, and **2**\nindicates this connection is not configured.\n\n## Detail mode\n\n**GitHub connection**: When requesting the details for the GitHub connection the result will contain the\nfollowing information as a JSON object:\n\n* type - String. The name of the connection, in this case *github*\n* status - Integer. Status of the connection following the pattern from before.\n* runbooks - Integer. The number of runbooks present in your defined GitHub connection.\n* warnings - Object. This contains a key-value object with the keys being the filenames of all files in the\nfolder not containing valid runbooks. The value will contain the error message why this particular file cannot\nbe imported as a runbook.\n\n**Impact connection**: Not implemented, yet.\n\n**Ansible connection**: Not implemented, yet.\n\n**Script connection**: Not implemented, yet.\n", "parameters": [ { "name": "connection", "in": "query", "description": "Define to get detailed information on one connection.", "required": false, "schema": { "type": "string", "enum": [ "awx", "github", "impact", "script" ] } } ], "operationId": "getStatus", "tags": [ "Status" ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseStatus" }, "examples": { "overview": { "value": { "rbs": 0, "db": 0, "as": 0, "connection": { "AWX": 1, "IMPACT": 2, "SCRIPT": 0 }, "errors": [ "Wrong Ansible credentials" ] } }, "github": { "value": { "type": "github", "status": 0, "runbooks": 97, "warnings": { "readme.md": "Cannot parse" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } } }, "servers": [ { "url": "/api/v1/rba" } ], "components": { "schemas": { "responseFarbExecute": { "type": "object", "properties": { "runbookInstanceId": { "type": "string" } } }, "responseLoadExamples": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "responseRunbooksCreated": { "type": "array", "items": { "$ref": "#/components/schemas/responseRunbookCreated" } }, "responseRunbooksCreatedVerbose": { "type": "object", "properties": { "importedRunbooks": { "$ref": "#/components/schemas/responseRunbooksCreated" }, "failedRunbooks": { "type": "array", "items": { "type": "object", "properties": { "runbookName": { "type": "string" }, "error": { "type": "string" } } } } } }, "responseRunbookCreated": { "type": "object", "required": [ "runbookId", "runbookUrl", "_createdAt", "_createdBy", "_modifiedAt", "_modifiedBy" ], "properties": { "runbookId": { "type": "string" }, "runbookUrl": { "type": "string" }, "_createdAt": { "type": "string", "format": "date-time" }, "_createdBy": { "type": "string" }, "_modifiedAt": { "type": "string", "format": "date-time" }, "_modifiedBy": { "type": "string" } } }, "responseRunbookPatch": { "type": "object", "required": [ "runbookId", "runbookUrl", "_createdAt", "_createdBy", "_modifiedAt", "_modifiedBy" ], "properties": { "runbookId": { "type": "string" }, "runbookUrl": { "type": "string" }, "_createdAt": { "type": "string", "format": "date-time" }, "_createdBy": { "type": "string" }, "_modifiedAt": { "type": "string", "format": "date-time" }, "_modifiedBy": { "type": "string" } } }, "requestRunbookImport": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/requestRunbookCreate" } }, { "type": "array", "items": { "type": "object" } } ] }, "requestRunbookCreate": { "type": "object", "additionalProperties": false, "required": [ "name", "steps" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "exampleName": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/runbookStep" } }, "approval": { "$ref": "#/components/schemas/requestRunbookApproval" }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "automationMappings": { "$ref": "#/components/schemas/runbookAutomationMappings" }, "automations": { "type": "object" }, "_runbookId": { "type": "string" } } }, "requestRunbookExecute": { "type": "object", "additionalProperties": false, "required": [ "parameters" ], "properties": { "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/executeRunbookParameter" } } } }, "responseRunbookGet": { "type": "array", "items": { "$ref": "#/components/schemas/responseRunbookGetSingle" } }, "responseRunbookGetSingle": { "type": "object", "required": [ "name", "description", "steps", "readOnly" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/runbookStep" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "tags": { "type": "array", "items": { "type": "string" } }, "stats": { "$ref": "#/components/schemas/runbookStatistics" }, "contextStats": { "$ref": "#/components/schemas/runbookStatistics" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/runbookReference" } }, "readOnly": { "$ref": "#/components/schemas/runbookReadOnly" }, "automationMappings": { "$ref": "#/components/schemas/runbookAutomationMappings" }, "_createdAt": { "type": "string", "format": "date-time" }, "_modifiedAt": { "type": "string", "format": "date-time" }, "_createdBy": { "type": "string" }, "_modifiedBy": { "type": "string" }, "_type": { "type": "string" }, "_version": { "type": "integer" }, "_runbookId": { "type": "string" }, "_tenantId": { "type": "string" }, "_state": { "type": "string", "enum": [ "draft", "pending", "rejected", "approved" ] }, "_canBeAutomated": { "type": "boolean" }, "_isLatest": { "type": "boolean" } } }, "responseRunbookInstanceGet": { "type": "object", "properties": { "_id": { "type": "string", "description": "Database document ID" }, "_rev": { "type": "string", "description": "Database document revision" }, "_type": { "type": "string", "description": "Type of the document, in this case runbookInstance" }, "_dataModel": { "type": "integer", "description": "Version of the data model" }, "_runbookId": { "type": "string", "description": "ID of executed runbook" }, "_runbookVersion": { "type": "integer", "description": "Version of executed runbook" }, "_runbookName": { "type": "string", "description": "Name of executed runbook" }, "_context": { "type": "string", "description": "Context for this runbook instance" }, "_createdAt": { "type": "integer", "description": "Timestamp when the runbook instance was created" }, "_createdBy": { "type": "string", "description": "User ID which created this runbook instance" }, "_modifiedAt": { "type": "integer", "description": "Timestamp when the runbook instance was last changed" }, "_modifiedBy": { "type": "string", "description": "User ID which last changed this runbook instance" }, "_triggeredAutomatically": { "type": "boolean", "description": "Signals if this instance has been triggered automatically" }, "_automationErrors": { "type": "string", "description": "For automated runs, error messages of executed automations will be written here" }, "automationInformation": { "type": "object", "description": "Object with step number as key and automation details inside an object" }, "parameters": { "type": "array", "description": "Parameters for the runbook instance", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "history": { "type": "array", "description": "Array with the history of changes to this runbook instance", "items": { "$ref": "#/components/schemas/historyItem" } }, "status": { "type": "string", "enum": [ "in progress", "success", "failure", "paused", "have errors", "wrong runbook", "resolved before end", "not needed", "other" ] }, "rating": { "type": "integer", "description": "The rating of the runbook by the user", "minimum": 1, "maximum": 5 }, "comment": { "type": "string", "description": "A comment on the runbook by the user" }, "note": { "type": "string", "description": "Notes of the operator during execution" } } }, "responseRunbookInstanceGetHtml": { "type": "string" }, "responseRunbooksGet": { "type": "array", "items": { "$ref": "#/components/schemas/responseRunbookGetSingle" } }, "requestActionInstanceCreate": { "type": "object", "additionalProperties": false, "required": [ "parameters" ], "properties": { "parameters": { "$ref": "#/components/schemas/requestParameters" } } }, "responseActionsGet": { "type": "object", "required": [ "actions" ], "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/responseActionGetSingle" } } } }, "responseActionGet": { "anyOf": [ { "$ref": "#/components/schemas/responseActionGetSingle" }, { "$ref": "#/components/schemas/responseActionsGet" } ] }, "responseActionGetSingle": { "type": "object", "required": [ "name", "description", "parameters" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "prerequisites": { "type": "string" }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "tags": { "type": "array", "items": { "type": "string" } }, "stats": { "$ref": "#/components/schemas/actionStatistics" }, "contextStats": { "$ref": "#/components/schemas/actionStatistics" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/runbookReference" } }, "http": { "type": "object", "properties": { "host": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "PATCH", "POST", "PUT", "DELETE", "OPTIONS", "HEAD", "TRACE" ] }, "headers": { "type": "string" }, "body": { "type": "string" }, "ignoreCertErrors": { "type": "boolean" }, "username": { "type": "string" } } }, "script": { "type": "object", "properties": { "contentBase64": { "type": "string" }, "contentPlain": { "type": "string" }, "shell": { "type": "string", "enum": [ "bash", "powershell" ] } } }, "awx": { "type": "object", "properties": { "templateId": { "type": "integer" }, "templateType": { "type": "string", "enum": [ "job", "workflow" ] } } }, "client": { "type": "object", "properties": { "host": { "type": "string" } } }, "outputFilter": { "type": "object", "additionalProperties": false, "properties": { "syntax": { "type": "string", "enum": [ "jsonpath", "xpath", "regularexpression" ] }, "query": { "type": "string" } } }, "_createdAt": { "type": "string", "format": "date-time" }, "_modifiedAt": { "type": "string", "format": "date-time" }, "_createdBy": { "type": "string" }, "_modifiedBy": { "type": "string" }, "_type": { "type": "string" }, "_version": { "type": "integer" }, "_actionId": { "type": "string" }, "_actionType": { "type": "string", "enum": [ "script", "http", "awx", "client", "predefined" ] }, "_state": { "type": "string", "enum": [ "draft", "pending", "rejected", "published" ] }, "_isLatest": { "type": "boolean" }, "_isOutputFilterActive": { "type": "boolean" } } }, "responseActionInstanceCreate": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "_actionInstanceId": { "type": "string" } } }, { "$ref": "#/components/schemas/responseActionInstanceGet" } ] }, "responseActionCreate": { "type": "object", "properties": { "_actionId": { "type": "string" } } }, "requestActionCreate": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "name", "parameters", "script" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "prerequisites": { "type": "string" }, "script": { "type": "object", "required": [ "shell", "content" ], "properties": { "shell": { "type": "string", "enum": [ "bash", "powershell" ] }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "base64" ] } } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 } }, "outputFilter": { "type": "object", "additionalProperties": false, "properties": { "syntax": { "type": "string", "enum": [ "jsonpath", "xpath", "regularexpression" ] }, "query": { "type": "string" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "name", "parameters", "http" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "prerequisites": { "type": "string" }, "http": { "type": "object", "required": [ "host", "method" ], "properties": { "host": { "type": "string" }, "body": { "type": "string" }, "headers": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "PATCH", "POST", "PUT", "DELETE", "OPTIONS", "HEAD", "TRACE" ] }, "ignoreCertErrors": { "type": "boolean" }, "username": { "type": "string" }, "password": { "type": "string" } } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 } }, "outputFilter": { "type": "object", "additionalProperties": false, "properties": { "syntax": { "type": "string", "enum": [ "jsonpath", "xpath", "regularexpression" ] }, "query": { "type": "string" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "name", "parameters", "client" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "prerequisites": { "type": "string" }, "client": { "type": "object", "required": [ "host" ], "properties": { "host": { "type": "string" } } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 } } } } ] }, "requestActionPatch": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "prerequisites": { "type": "string" }, "script": { "type": "object", "properties": { "shell": { "type": "string", "enum": [ "bash", "powershell" ] }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "base64" ] } } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 } }, "outputFilter": { "type": "object", "properties": { "syntax": { "type": "string", "enum": [ "jsonpath", "xpath", "regularexpression" ] }, "query": { "type": "string" } } } } }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "prerequisites": { "type": "string" }, "http": { "type": "object", "properties": { "host": { "type": "string" }, "body": { "type": "string" }, "headers": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "PATCH", "POST", "PUT", "DELETE", "OPTIONS", "HEAD", "TRACE" ] }, "ignoreCertErrors": { "type": "boolean" }, "username": { "type": "string" }, "password": { "type": "string" } } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 30 } }, "outputFilter": { "type": "object", "properties": { "syntax": { "type": "string", "enum": [ "jsonpath", "xpath", "regularexpression" ] }, "query": { "type": "string" } } } } } ] }, "responseActionInstanceGetAll": { "type": "object", "additionalProperties": false, "required": [ "instances" ], "properties": { "instances": { "type": "array", "items": { "$ref": "#/components/schemas/responseActionInstanceGet" } } } }, "responseActionInstanceGet": { "type": "object", "required": [ "_createdAt", "_createdBy", "_actionInstanceId", "_actionId", "_actionVersion", "_actionType", "_type", "status" ], "additionalProperties": false, "properties": { "_createdAt": { "type": "string", "format": "date-time" }, "_createdBy": { "type": "string" }, "_actionInstanceId": { "type": "string" }, "_actionId": { "type": "string" }, "_actionVersion": { "type": "integer" }, "_actionType": { "type": "string", "enum": [ "awx", "http", "script", "client", "predefined" ] }, "_type": { "type": "string", "enum": [ "actionInstance" ] }, "_context": { "type": "string", "description": "The context this action instance was created in" }, "status": { "type": "string", "enum": [ "executing", "successful", "unsuccessful", "failed" ] }, "output": { "type": "string" }, "originalOutput": { "type": "string" }, "parsingError": { "type": "string" }, "executionTime": { "type": "integer", "minimum": 0 }, "returnCode": { "type": "integer" }, "parameters": { "type": "object" }, "rating": { "type": "integer", "description": "The rating of the action by the user", "minimum": 1, "maximum": 5 }, "comment": { "type": "string", "description": "A comment on the action by the user" }, "providerInstanceId": { "type": "string", "description": "The provider's instance ID (when available)" }, "action": { "$ref": "#/components/schemas/responseActionGetSingle" } } }, "requestActionInstancePatch": { "type": "object", "properties": { "rating": { "type": "integer", "description": "The rating of the action by the user", "minimum": 1, "maximum": 5 }, "comment": { "type": "string", "description": "A comment on the action by the user" } } }, "historyItem": { "type": "object", "required": [ "action", "step" ], "properties": { "action": { "type": "string", "enum": [ "complete", "back" ] }, "step": { "type": "integer" }, "processedAt": { "type": "integer" }, "processedBy": { "type": "string" }, "parameters": { "type": "object" } } }, "responseRunbookInstancesGet": { "type": "array", "items": { "$ref": "#/components/schemas/responseRunbookInstanceGet" } }, "responseRunbookInstancesGetHtml": { "type": "array", "items": { "$ref": "#/components/schemas/responseRunbookInstanceGetHtml" } }, "runbookStatus": { "type": "string", "description": "Status of the given approval", "enum": [ "draft", "pending", "approved", "rejected" ] }, "runbookStep": { "oneOf": [ { "$ref": "#/components/schemas/runbookStepManual" }, { "$ref": "#/components/schemas/runbookStepRunbook" }, { "$ref": "#/components/schemas/runbookStepAutomation" } ] }, "runbookStepManual": { "type": "object", "additionalProperties": false, "required": [ "number", "description" ], "properties": { "number": { "type": "integer", "minimum": 1 }, "nestedNumber": { "type": "string" }, "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "manual", "converted" ] }, "origin": { "$ref": "#/components/schemas/runbookStepOrigin" } } }, "runbookStepRunbook": { "type": "object", "additionalProperties": false, "required": [ "number", "runbookId", "type" ], "properties": { "number": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "maxLength": 200 }, "type": { "type": "string", "enum": [ "runbook" ] }, "runbookId": { "type": "string" }, "runbookVersion": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "enum": [ "latest" ] } ] }, "mappings": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameterMapping" } } } }, "runbookStepAutomation": { "type": "object", "additionalProperties": false, "required": [ "number", "automationId", "type" ], "properties": { "number": { "type": "integer", "minimum": 1 }, "nestedNumber": { "type": "string" }, "title": { "type": "string", "maxLength": 200 }, "type": { "type": "string", "enum": [ "automation" ] }, "automationId": { "type": "string" }, "mappings": { "type": "array", "items": { "$ref": "#/components/schemas/automationParameterMapping" } }, "origin": { "$ref": "#/components/schemas/runbookStepOrigin" }, "goto": { "type": "object", "additionalProperties": false, "required": [ "successful", "unsuccessful" ], "properties": { "successful": { "type": "number" }, "unsuccessful": { "type": "number" } } }, "branching": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "condition", "target" ], "properties": { "condition": { "type": "string" }, "target": { "type": "number" } } } } } }, "runbookStepOrigin": { "type": "object", "additionalProperties": false, "required": [ "runbookId", "runbookName", "runbookVersion", "stepNumber" ], "properties": { "runbookId": { "type": "string" }, "runbookName": { "type": "string" }, "runbookVersion": { "type": "integer" }, "stepNumber": { "type": "integer" } } }, "runbookReadOnly": { "type": "object", "required": [ "_createdAt", "_createdBy", "_modifiedAt", "_modifiedBy", "_type", "_version", "_runbookId", "_tenantId", "_state" ], "properties": { "_createdAt": { "type": "string", "format": "date-time" }, "_modifiedAt": { "type": "string", "format": "date-time" }, "_createdBy": { "type": "string" }, "_modifiedBy": { "type": "string" }, "_type": { "type": "string", "enum": [ "runbook", "automation", "trigger", "runbookInstance", "automationInstance" ] }, "_version": { "type": "integer" }, "_runbookId": { "type": "string" }, "_tenantId": { "type": "string" }, "_state": { "type": "string", "enum": [ "draft", "pending", "rejected", "approved" ] }, "_canBeAutomated": { "type": "boolean" }, "_isLatest": { "type": "boolean" } } }, "runbookParameter": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the parameter.", "minLength": 1, "maxLength": 200, "pattern": "^[^\\\\<>\\s&]+$" }, "description": { "type": "string", "description": "An optional description, explaining the purpose of this." }, "defaultValue": { "deprecated": true, "description": "Deprecated. Use \"default\" instead. Define a default value. This value will override \"default\". Can only be used for parameters of type string.", "type": "string" }, "type": { "type": "string", "description": "Define the type for this parameter. If no value is set, \"string\" is assumed.", "default": "string", "enum": [ "string", "integer", "array", "boolean" ] }, "enum": { "description": "Optional. Limit the potential input to a set of allowed values. If no value is set, the input is not limited.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "integer" } } ] }, "enumLabels": { "description": "Optional. Contains human readable labels for enumerations, for example, if the base enumeration consists of ID numbers. Requires \"enum\" to be defined.", "type": "array", "items": { "type": "string" } }, "default": { "description": "Defines a default value, which will be used, if no other input is made." }, "isNotReqOnStart": { "deprecated": true, "type": "boolean", "default": false, "description": "Deprecated. This option will set minLength to 0. Will only work, if type is 'string'. Cannot be combined with minLength." }, "minLength": { "type": "integer", "description": "Optional. Define a minimum length for a parameter of type \"string\". If no value is set, the string doesn't have a minimum length and becomes optional." }, "maxLength": { "type": "integer", "description": "Optional. Define a maximum length for a parameter of type \"string\". If no value is set, the length of a string parameter is unlimited." }, "minimum": { "type": "integer", "description": "Optional. Define a minimum value for a parameter of type \"integer\". If no value is set, the minimum of an integer parameter is boundless." }, "maximum": { "type": "integer", "description": "Optional. Define a maximum value for a parameter of type \"integer\". If no value is set, the maximum of an integer parameter is boundless." }, "minItems": { "type": "integer", "description": "Optional. Define a minimum array length for a parameter of type \"array\". If no value is set, the minimum size of an array parameter is '0'." }, "maxItems": { "type": "integer", "description": "Optional. Define a maximum array length for a parameter of type \"array\". If no value is set, the maximum size of an array parameter is boundless." }, "items": { "type": "object", "description": "Optional. Define the schema for each array item. If no value is set, each item will be of type \"string\".", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "Optional. Define the type for each array item. If no value is set, \"string\" is assumed.", "default": "string", "enum": [ "string", "integer", "boolean" ] }, "enum": { "description": "Optional. Limit the potential input to a set of allowed values. If no value is set, the input is not limited.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "integer" } } ] }, "enumLabels": { "description": "Optional. Contains human readable labels for enumerations, for example, if the base enumeration consists of ID numbers. Requires \"enum\" to be defined.", "type": "array", "items": { "type": "string" } } } }, "format": { "type": "string", "description": "Optional. Define a specific format for a parameter to narrow down content and format. If no value is set, no additional format is used.", "enum": [ "password", "multiline" ] } } }, "runbookReference": { "type": "object", "required": [ "runbookId", "runbookVersion", "stepNumber" ], "properties": { "runbookId": { "description": "The Runbook ID of the runbook referencing the requested runbook.", "type": "string" }, "runbookVersion": { "description": "The version number defined in the referencing runbook pointing to the requested runbook.", "type": "integer" }, "stepNumber": { "description": "Number of the step in the referencing runbook pointing to the requested runbook.", "type": "integer" } } }, "runbookStatistics": { "type": "object", "required": [ "runs", "comments" ], "properties": { "runs": { "type": "object", "title": "runbookRuns", "properties": { "success": { "type": "integer", "description": "This value shows the number of runbook executions for this runbook with a successful conclusion." }, "failure": { "type": "integer", "description": "This value shows the number of runbook executions for this runbook indicating a failure." }, "cancel": { "type": "integer", "description": "This value shows the number of runbook executions for this runbook that have been canceled before finishing." }, "inprogress": { "type": "integer", "description": "This value shows the number of runbook executions for this runbook currently in progress." }, "paused": { "type": "integer", "description": "This value shows the number of runbook executions for this runbook that have been paused." }, "total": { "type": "integer", "description": "This value shows the number of runbook executions for this runbook independently of the state." } } }, "comments": { "type": "integer", "description": "This value shows the number of comments on execution records of this object." }, "ratingavg": { "type": "number", "description": "Shows the average rating of this rating. Ratings go from *1* (worst) to *5* (best)." }, "runspercent": { "type": "integer" }, "approxTime": { "type": "integer" } } }, "actionStatistics": { "type": "object", "additionalProperties": false, "properties": { "runs": { "type": "object", "additionalProperties": false, "properties": { "successful": { "type": "integer", "description": "The number of successful executions for this action." }, "failed": { "type": "integer", "description": "The number of failed executions for this action." }, "canceled": { "type": "integer", "description": "The number of canceled executions for this action." }, "unsuccessful": { "type": "integer", "description": "The number of unsuccessful executions for this action." }, "unknown": { "type": "integer", "description": "The number of executions for this actions in an unknown state." }, "total": { "type": "integer", "description": "The total number of executions for this action independently of the state." } } }, "comments": { "type": "integer", "description": "The number of comments on execution records of this object." }, "ratingavg": { "type": "number", "description": "Shows the average rating of execution records for this action. Ratings go from *1* (worst) to *5* (best)." }, "runspercent": { "type": "integer", "description": "The percentage value (0-100) of successful runs compared to all successful and unsuccessful runs. Does not incorporate failed, unknown, or canceled runs." }, "executionTime": { "type": "integer", "description": "Average run time duration in seconds." }, "executionMinTime": { "type": "integer", "description": "Fastest run time duration in seconds." }, "executionMaxTime": { "type": "integer", "description": "Slowest run time duration in seconds." } } }, "executeRunbookParameter": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "value": { "type": "string" } } }, "runbookAutomationMappings": { "type": "array", "deprecated": true, "items": { "$ref": "#/components/schemas/automationMapping" } }, "automationMapping": { "type": "object", "deprecated": true, "additionalProperties": false, "required": [ "mappingId", "parameterMappings" ], "properties": { "mappingId": { "type": "string" }, "parameterMappings": { "type": "array", "items": { "$ref": "#/components/schemas/automationParameterMapping" } } } }, "automationParameterMapping": { "type": "object", "additionalProperties": false, "required": [ "automationParameterName", "parameterMappingType" ], "properties": { "automationParameterName": { "type": "string" }, "parameterMappingType": { "type": "string", "enum": [ "parameter", "fixed", "useDefaultFromAutomation", "automationOutput", "userName" ] }, "parameterValue": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "boolean" }, { "type": "array", "items": {} } ] } } }, "runbookParameterMapping": { "type": "object", "additionalProperties": false, "required": [ "nestedRunbookParameterName", "parameterMappingType" ], "properties": { "nestedRunbookParameterName": { "type": "string" }, "parameterMappingType": { "type": "string", "enum": [ "parameter", "fixed", "useDefaultFromNestedRunbook", "automationOutput", "userName" ] }, "parameterValue": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "boolean" }, { "type": "array", "items": {} } ] } } }, "requestRunbookApproval": { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "submit", "cancel", "reject", "approve" ], "description": "Approval action of this request" }, "comment": { "type": "string", "default": "Comment for approve/reject action" }, "email": { "type": "string", "default": "max.mustermann@de.ibm.com", "description": "ID of the approval assignee (not necessarily an email address)" } } }, "responseRunbookApproval": { "type": "object", "required": [ "email", "status" ], "properties": { "email": { "type": "string", "default": "max.mustermann@de.ibm.com", "description": "ID of the approval assignee (not necessarily an email address)" }, "comment": { "type": "string", "default": "Great runbook!" }, "ts": { "type": "integer", "default": 1478249767726 }, "status": { "type": "string", "description": "Status of the given approval", "enum": [ "pending", "approved", "rejected" ] } } }, "responseConfiguration": { "type": "object", "required": [ "_createdAt", "_createdBy", "_modifiedAt", "_modifiedBy", "groups", "approvals", "runbookExpirationTime", "impact", "github", "script" ], "properties": { "_createdAt": { "type": "string", "format": "date-time" }, "_createdBy": { "type": "string" }, "_modifiedAt": { "type": "string", "format": "date-time" }, "_modifiedBy": { "type": "string" }, "groups": { "type": "boolean" }, "approvals": { "type": "boolean" }, "runbookExpirationTime": { "type": "integer" }, "impact": { "type": "object", "additionalProperties": false, "required": [ "active" ], "properties": { "active": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "user": { "type": "string" }, "certificate": { "type": "string" } } }, "github": { "type": "object", "additionalProperties": false, "required": [ "active" ], "properties": { "active": { "type": "boolean" }, "api": { "type": "string" }, "owner": { "type": "string" }, "repo": { "type": "string" }, "folder": { "type": "string" }, "branch": { "type": "string" }, "certificate": { "type": "string" } } }, "script": { "type": "object", "additionalProperties": false, "required": [ "active" ], "properties": { "active": { "type": "boolean" }, "keys": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "priority": { "type": "integer", "minimum": 0 }, "group": { "type": "string" }, "publickey": { "type": "string" }, "error": { "type": "string" } } } }, "jumpserver": { "type": "object", "additionalProperties": false, "required": [ "active" ], "properties": { "active": { "type": "boolean" }, "hostname": { "type": "string" }, "port": { "type": "number" }, "username": { "type": "string" } } } } } } }, "requestConfigurationPatch": { "type": "object", "additionalProperties": false, "properties": { "runbookExpirationTime": { "type": "number", "minimum": 0, "maximum": 10000 }, "groups": { "type": "boolean" }, "approvals": { "type": "boolean" }, "impact": { "type": "object", "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "user": { "type": "string" }, "password": { "type": "string" }, "certificate": { "type": "string" } } }, "github": { "type": "object", "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "api": { "type": "string" }, "token": { "type": "string" }, "owner": { "type": "string" }, "repo": { "type": "string" }, "branch": { "type": "string" }, "folder": { "type": "string" }, "certificate": { "type": "string" } } }, "script": { "type": "object", "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "keys": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "priority": { "type": "integer", "minimum": 0 }, "group": { "type": "string" }, "privatekey": { "type": "string" }, "passphrase": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "generate" ], "properties": { "priority": { "type": "integer", "minimum": 0 }, "group": { "type": "string" }, "generate": { "type": "string", "enum": [ "rsa-2048", "rsa-3072", "rsa-4096", "ecdsa-256", "ecdsa-384", "ecdsa-521", "ed25519" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "delete" ], "properties": { "delete": { "type": "boolean" } } } ] } }, "jumpserver": { "type": "object", "additionalProperties": false, "required": [ "active" ], "properties": { "active": { "type": "boolean" }, "hostname": { "type": "string" }, "port": { "type": "number" }, "username": { "type": "string" }, "password": { "type": "string" }, "useSshKey": { "type": "boolean" } } } } }, "ansible": { "type": "object", "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "url": { "type": "string" }, "user": { "type": "string" }, "password": { "type": "string" }, "token": { "type": "string" }, "certificate": { "type": "string" } } } } }, "requestRunbookPatch": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/runbookStep" } }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/runbookParameter" } }, "approval": { "$ref": "#/components/schemas/requestRunbookApproval" }, "tags": { "type": "array", "items": { "type": "string" } }, "automationMappings": { "$ref": "#/components/schemas/runbookAutomationMappings" } } }, "requestRunbookInstancePatch": { "type": "object", "additionalProperties": false, "properties": { "parameters": { "$ref": "#/components/schemas/requestParameters" }, "completeStep": { "type": "boolean" }, "previousStep": { "type": "boolean" }, "goToStep": { "type": "integer" }, "pause": { "type": "boolean" }, "resume": { "type": "boolean" }, "status": { "type": "string", "enum": [ "success", "failure", "have errors", "wrong runbook", "resolved before end", "not needed", "other" ] }, "note": { "type": "string" }, "comment": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "automationInformation": { "type": "object", "additionalProperties": false, "required": [ "automationId", "automationInstanceId" ], "properties": { "automationId": { "type": "string" }, "automationInstanceId": { "type": "string" }, "mappingId": { "type": "integer", "deprecated": true }, "stepNumber": { "type": "integer", "deprecated": true }, "parameterMappings": { "type": "array", "items": { "$ref": "#/components/schemas/automationMapping" } }, "result": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "successful", "unsuccessful", "failed", "executing", "unknown" ] }, "startTime": { "type": "string" }, "output": { "type": "string" }, "data": { "type": "string" }, "returnCode": { "type": "integer" }, "executionTime": { "type": "integer" } } } } }, "automationErrors": { "type": "string" } } }, "responseUsers": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "fullName": { "type": "string" } } } }, "responseStatisticsRunbookInstancesGet": { "type": "object", "properties": { "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "productionExecutions": { "type": "integer" } } }, "responseStatus": { "oneOf": [ { "$ref": "#/components/schemas/responseStatusOverview" }, { "$ref": "#/components/schemas/responseStatusGitHub" } ] }, "responseStatusOverview": { "type": "object", "properties": { "rbs": { "type": "integer", "enum": [ 0, 1, 2 ] }, "db": { "type": "integer", "enum": [ 0, 1, 2 ] }, "as": { "type": "integer", "enum": [ 0, 1, 2 ] }, "connection": { "type": "object", "properties": { "AWX": { "type": "integer", "enum": [ 0, 1, 2 ] }, "IMPACT": { "type": "integer", "enum": [ 0, 1, 2 ] }, "SCRIPT": { "type": "integer", "enum": [ 0, 1, 2 ] } } }, "errors": { "type": "array", "items": { "type": "string" } } } }, "responseStatusGitHub": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "integer", "enum": [ 0, 1, 2 ] }, "runbooks": { "type": "integer" }, "warnings": { "type": "object" } } }, "errorModel": { "type": "object", "required": [ "errorMessage", "errorCode", "correlationId" ], "properties": { "errorMessage": { "description": "Human-readable, translated error message", "type": "string" }, "errorCode": { "description": "Machine-readable error identification", "type": "string" }, "correlationId": { "description": "Identification for server-side logs relating to this error", "type": "string" } } }, "errorModelBadRequest": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "dataPath": { "type": "string" }, "schemaPath": { "type": "string" }, "params": { "type": "object" }, "message": { "type": "string" } } } } } }, "requestParameters": { "type": "array", "additionalProperties": false, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "boolean" }, { "type": "array", "items": {} } ] } } } } } } }