From 4733f93048f65e85a8d9b4f867f2f7a1f2811764 Mon Sep 17 00:00:00 2001 From: adcoelho Date: Wed, 18 Oct 2023 15:37:06 +0200 Subject: [PATCH 1/3] Update the custom fields api documentation. --- .../plugins/cases/docs/openapi/bundled.json | 130 ++++++++++++++---- .../plugins/cases/docs/openapi/bundled.yaml | 97 ++++++++++--- .../case_configure_response_properties.yaml | 9 +- .../schemas/custom_fields_configuration.yaml | 23 ++++ .../schemas/custom_fields_property.yaml | 35 ++--- .../set_case_configuration_request.yaml | 9 +- .../openapi/paths/api@cases@configure.yaml | 12 +- 7 files changed, 245 insertions(+), 70 deletions(-) create mode 100644 x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_configuration.yaml diff --git a/x-pack/plugins/cases/docs/openapi/bundled.json b/x-pack/plugins/cases/docs/openapi/bundled.json index 9ef79cb9203ed..0164e59a4d93a 100644 --- a/x-pack/plugins/cases/docs/openapi/bundled.json +++ b/x-pack/plugins/cases/docs/openapi/bundled.json @@ -537,6 +537,13 @@ "version": { "type": "string", "example": "WzIwNzMsMV0=" + }, + "customFields": { + "description": "An array containing the custom fields in the configuration.", + "type": "array", + "items": { + "$ref": "#/components/schemas/custom_fields_configuration" + } } } } @@ -562,7 +569,7 @@ ] }, "post": { - "summary": "Sets external connection details, such as the closure type and default connector for cases in the default space.", + "summary": "Creates a case specific configuration that includes external connection details and custom fields.", "operationId": "setCaseConfigurationDefaultSpace", "description": "You must have `all` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the case configuration. Connectors are used to interface with external systems. You must create a connector before you can use it in your cases. Refer to the add connectors API. If you set a default connector, it is automatically selected when you create cases in Kibana. If you use the create case API, however, you must still specify all of the connector details.\n", "tags": [ @@ -716,6 +723,13 @@ "version": { "type": "string", "example": "WzIwNzMsMV0=" + }, + "customFields": { + "description": "An array containing the custom fields in the configuration.", + "type": "array", + "items": { + "$ref": "#/components/schemas/custom_fields_configuration" + } } } }, @@ -906,6 +920,13 @@ "version": { "type": "string", "example": "WzIwNzMsMV0=" + }, + "customFields": { + "description": "An array containing the custom fields in the configuration.", + "type": "array", + "items": { + "$ref": "#/components/schemas/custom_fields_configuration" + } } } } @@ -2367,6 +2388,13 @@ "version": { "type": "string", "example": "WzIwNzMsMV0=" + }, + "customFields": { + "description": "An array containing the custom fields in the configuration.", + "type": "array", + "items": { + "$ref": "#/components/schemas/custom_fields_configuration" + } } } } @@ -2549,6 +2577,13 @@ "version": { "type": "string", "example": "WzIwNzMsMV0=" + }, + "customFields": { + "description": "An array containing the custom fields in the configuration.", + "type": "array", + "items": { + "$ref": "#/components/schemas/custom_fields_configuration" + } } } }, @@ -2742,6 +2777,13 @@ "version": { "type": "string", "example": "WzIwNzMsMV0=" + }, + "customFields": { + "description": "An array containing the custom fields in the configuration.", + "type": "array", + "items": { + "$ref": "#/components/schemas/custom_fields_configuration" + } } } } @@ -4581,9 +4623,10 @@ }, "custom_fields_property": { "type": "array", - "description": "Values for custom fields of a case", + "description": "Values for custom fields of a case.", "minItems": 0, - "maxItems": 5, + "maxItems": 10, + "x-technical-preview": true, "items": { "type": "object", "required": [ @@ -4593,36 +4636,31 @@ ], "properties": { "key": { - "description": "The key identifying the custom field.", + "description": "The key identifying the custom field. Must be unique. Must exist in the configuration.", "type": "string" }, "type": { - "description": "The type of the custom field. Should match the key and how the custom field was configured", + "description": "The type of the custom field. Should match the key/type pair in the configuration.", + "enum": [ + "text", + "toggle" + ], "type": "string" }, - "field": { - "description": "An object containing the value of the field.", - "type": "object", - "required": [ - "value" - ], - "properties": { - "value": { - "description": "The value of the field.", + "value": { + "anyOf": [ + { + "type": "string", "nullable": true, - "type": "array", - "items": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "boolean" - } - ] - } + "minLength": 1, + "maxLength": 160 + }, + { + "type": "boolean", + "nullable": true } - } + ], + "description": "The value of the custom field. Cannot be explicitly set to null if the field is configured as required. However, existing cases when the custom field was created will have this value null as default.\n" } } } @@ -5387,6 +5425,37 @@ ], "example": ".none" }, + "custom_fields_configuration": { + "type": "object", + "description": "An object defining a custom field.", + "x-technical-preview": true, + "properties": { + "key": { + "type": "string", + "description": "Internal identifier for the custom field. Must be lower case and only composed of a-z, 0-9, '_', or '-' characters. Will be used in API calls to refer to this specific custom field. Must be unique.", + "minLength": 1, + "maxLength": 36 + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "The label used to display the custom field in the Case's pages." + }, + "required": { + "type": "boolean", + "description": "Defines if the custom field is required on case creation." + }, + "type": { + "type": "string", + "enum": [ + "text", + "toggle" + ], + "description": "The type of the custom field." + } + } + }, "set_case_configuration_request": { "title": "Set case configuration request", "description": "External connection details, such as the closure type and default connector for cases.", @@ -5446,6 +5515,15 @@ "required": [ "syncAlerts" ] + }, + "customFields": { + "description": "An array containing the custom fields.", + "type": "array", + "minItems": 0, + "maxItems": 10, + "items": { + "$ref": "#/components/schemas/custom_fields_configuration" + } } } }, diff --git a/x-pack/plugins/cases/docs/openapi/bundled.yaml b/x-pack/plugins/cases/docs/openapi/bundled.yaml index c24f9f3c67fa3..22cc9689acade 100644 --- a/x-pack/plugins/cases/docs/openapi/bundled.yaml +++ b/x-pack/plugins/cases/docs/openapi/bundled.yaml @@ -331,6 +331,11 @@ paths: version: type: string example: WzIwNzMsMV0= + customFields: + description: An array containing the custom fields in the configuration. + type: array + items: + $ref: '#/components/schemas/custom_fields_configuration' '401': description: Authorization information is missing or invalid. content: @@ -340,7 +345,7 @@ paths: servers: - url: https://localhost:5601 post: - summary: Sets external connection details, such as the closure type and default connector for cases in the default space. + summary: Creates a case specific configuration that includes external connection details and custom fields. operationId: setCaseConfigurationDefaultSpace description: | You must have `all` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the case configuration. Connectors are used to interface with external systems. You must create a connector before you can use it in your cases. Refer to the add connectors API. If you set a default connector, it is automatically selected when you create cases in Kibana. If you use the create case API, however, you must still specify all of the connector details. @@ -455,6 +460,11 @@ paths: version: type: string example: WzIwNzMsMV0= + customFields: + description: An array containing the custom fields in the configuration. + type: array + items: + $ref: '#/components/schemas/custom_fields_configuration' examples: setCaseConfigResponse: $ref: '#/components/examples/set_case_configuration_response' @@ -585,6 +595,11 @@ paths: version: type: string example: WzIwNzMsMV0= + customFields: + description: An array containing the custom fields in the configuration. + type: array + items: + $ref: '#/components/schemas/custom_fields_configuration' '401': description: Authorization information is missing or invalid. content: @@ -1445,6 +1460,11 @@ paths: version: type: string example: WzIwNzMsMV0= + customFields: + description: An array containing the custom fields in the configuration. + type: array + items: + $ref: '#/components/schemas/custom_fields_configuration' '401': description: Authorization information is missing or invalid. content: @@ -1570,6 +1590,11 @@ paths: version: type: string example: WzIwNzMsMV0= + customFields: + description: An array containing the custom fields in the configuration. + type: array + items: + $ref: '#/components/schemas/custom_fields_configuration' examples: setCaseConfigResponse: $ref: '#/components/examples/set_case_configuration_response' @@ -1701,6 +1726,11 @@ paths: version: type: string example: WzIwNzMsMV0= + customFields: + description: An array containing the custom fields in the configuration. + type: array + items: + $ref: '#/components/schemas/custom_fields_configuration' '401': description: Authorization information is missing or invalid. content: @@ -2892,9 +2922,10 @@ components: default: low custom_fields_property: type: array - description: Values for custom fields of a case + description: Values for custom fields of a case. minItems: 0 - maxItems: 5 + maxItems: 10 + x-technical-preview: true items: type: object required: @@ -2903,25 +2934,24 @@ components: - field properties: key: - description: The key identifying the custom field. + description: The key identifying the custom field. Must be unique. Must exist in the configuration. type: string type: - description: The type of the custom field. Should match the key and how the custom field was configured + description: The type of the custom field. Should match the key/type pair in the configuration. + enum: + - text + - toggle type: string - field: - description: An object containing the value of the field. - type: object - required: - - value - properties: - value: - description: The value of the field. + value: + anyOf: + - type: string nullable: true - type: array - items: - anyOf: - - type: string - - type: boolean + minLength: 1 + maxLength: 160 + - type: boolean + nullable: true + description: | + The value of the custom field. Cannot be explicitly set to null if the field is configured as required. However, existing cases when the custom field was created will have this value null as default. create_case_request: title: Create case request description: The create case API request body varies depending on the type of connector. @@ -3464,6 +3494,30 @@ components: - .servicenow-sir - .swimlane example: .none + custom_fields_configuration: + type: object + description: An object defining a custom field. + x-technical-preview: true + properties: + key: + type: string + description: Internal identifier for the custom field. Must be lower case and only composed of a-z, 0-9, '_', or '-' characters. Will be used in API calls to refer to this specific custom field. Must be unique. + minLength: 1 + maxLength: 36 + label: + type: string + minLength: 1 + maxLength: 50 + description: The label used to display the custom field in the Case's pages. + required: + type: boolean + description: Defines if the custom field is required on case creation. + type: + type: string + enum: + - text + - toggle + description: The type of the custom field. set_case_configuration_request: title: Set case configuration request description: External connection details, such as the closure type and default connector for cases. @@ -3510,6 +3564,13 @@ components: example: true required: - syncAlerts + customFields: + description: An array containing the custom fields. + type: array + minItems: 0 + maxItems: 10 + items: + $ref: '#/components/schemas/custom_fields_configuration' update_case_configuration_request: title: Update case configuration request description: External connection details, such as the closure type and default connector for cases. diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/case_configure_response_properties.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/case_configure_response_properties.yaml index 90c969990f2e5..1728ac86eeb35 100644 --- a/x-pack/plugins/cases/docs/openapi/components/schemas/case_configure_response_properties.yaml +++ b/x-pack/plugins/cases/docs/openapi/components/schemas/case_configure_response_properties.yaml @@ -1,6 +1,6 @@ closure_type: $ref: 'closure_types.yaml' -connector: +connector: type: object properties: $ref: 'case_configure_connector_properties.yaml' @@ -47,4 +47,9 @@ updated_by: nullable: true version: type: string - example: WzIwNzMsMV0= \ No newline at end of file + example: WzIwNzMsMV0= +customFields: + description: An array containing the custom fields in the configuration. + type: array + items: + $ref: 'custom_fields_configuration.yaml' diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_configuration.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_configuration.yaml new file mode 100644 index 0000000000000..bbb9a7ccef45b --- /dev/null +++ b/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_configuration.yaml @@ -0,0 +1,23 @@ +type: object +description: An object defining a custom field. +x-technical-preview: true +properties: + key: + type: string + description: Internal identifier for the custom field. Must be lower case and only composed of a-z, 0-9, '_', or '-' characters. Will be used in API calls to refer to this specific custom field. Must be unique. + minLength: 1 + maxLength: 36 + label: + type: string + minLength: 1 + maxLength: 50 + description: The label used to display the custom field in the Case's pages. + required: + type: boolean + description: Defines if the custom field is required on case creation. + type: + type: string + enum: + - text + - toggle + description: The type of the custom field. diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml index 2b682960bd1f0..47231dea4e0e5 100644 --- a/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml +++ b/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml @@ -1,7 +1,8 @@ type: array -description: Values for custom fields of a case +description: Values for custom fields of a case. minItems: 0 -maxItems: 5 +maxItems: 10 +x-technical-preview: true items: type: object required: @@ -10,22 +11,22 @@ items: - field properties: key: - description: The key identifying the custom field. + description: The key identifying the custom field. Must be unique. Must exist in the configuration. type: string type: - description: The type of the custom field. Should match the key and how the custom field was configured + description: The type of the custom field. Should match the key/type pair in the configuration. + enum: + - text + - toggle type: string - field: - description: An object containing the value of the field. - type: object - required: - - value - properties: - value: - description: The value of the field. + value: + anyOf: + - type: string nullable: true - type: array - items: - anyOf: - - type: string - - type: boolean + minLength: 1 + maxLength: 160 + - type: boolean + nullable: true + description: > + The value of the custom field. Cannot be explicitly set to null if the field is configured as required. + However, existing cases when the custom field was created will have this value null as default. diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/set_case_configuration_request.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/set_case_configuration_request.yaml index 44a3a8709a939..0e5b679e631cb 100644 --- a/x-pack/plugins/cases/docs/openapi/components/schemas/set_case_configuration_request.yaml +++ b/x-pack/plugins/cases/docs/openapi/components/schemas/set_case_configuration_request.yaml @@ -28,5 +28,12 @@ properties: description: Turns alert syncing on or off. type: boolean example: true - required: + required: - syncAlerts + customFields: + description: An array containing the custom fields. + type: array + minItems: 0 + maxItems: 10 + items: + $ref: 'custom_fields_configuration.yaml' diff --git a/x-pack/plugins/cases/docs/openapi/paths/api@cases@configure.yaml b/x-pack/plugins/cases/docs/openapi/paths/api@cases@configure.yaml index ebbae5e333103..153ec5c43f566 100644 --- a/x-pack/plugins/cases/docs/openapi/paths/api@cases@configure.yaml +++ b/x-pack/plugins/cases/docs/openapi/paths/api@cases@configure.yaml @@ -16,7 +16,7 @@ get: application/json: schema: type: array - items: + items: type: object properties: $ref: '../components/schemas/case_configure_response_properties.yaml' @@ -27,10 +27,10 @@ get: schema: $ref: '../components/schemas/4xx_response.yaml' servers: - - url: https://localhost:5601 + - url: https://localhost:5601 post: - summary: Sets external connection details, such as the closure type and default connector for cases in the default space. + summary: Creates a case specific configuration that includes external connection details and custom fields. operationId: setCaseConfigurationDefaultSpace description: > You must have `all` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the case configuration. @@ -54,7 +54,7 @@ post: '200': description: Indicates a successful call. content: - application/json: + application/json: schema: type: object properties: @@ -69,6 +69,6 @@ post: schema: $ref: '../components/schemas/4xx_response.yaml' servers: - - url: https://localhost:5601 + - url: https://localhost:5601 servers: - - url: https://localhost:5601 \ No newline at end of file + - url: https://localhost:5601 From 6e6a51c33ac4cabd0ac2fb8ab69d24e6e3f77074 Mon Sep 17 00:00:00 2001 From: adcoelho Date: Wed, 18 Oct 2023 15:55:47 +0200 Subject: [PATCH 2/3] PR comments --- x-pack/plugins/cases/docs/openapi/bundled.json | 2 +- x-pack/plugins/cases/docs/openapi/bundled.yaml | 2 +- .../openapi/components/schemas/custom_fields_configuration.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/x-pack/plugins/cases/docs/openapi/bundled.json b/x-pack/plugins/cases/docs/openapi/bundled.json index 0164e59a4d93a..082fa768b34b3 100644 --- a/x-pack/plugins/cases/docs/openapi/bundled.json +++ b/x-pack/plugins/cases/docs/openapi/bundled.json @@ -5444,7 +5444,7 @@ }, "required": { "type": "boolean", - "description": "Defines if the custom field is required on case creation." + "description": "Defines if the custom field can be set to null on create/update cases." }, "type": { "type": "string", diff --git a/x-pack/plugins/cases/docs/openapi/bundled.yaml b/x-pack/plugins/cases/docs/openapi/bundled.yaml index 22cc9689acade..95dc2b10baf3b 100644 --- a/x-pack/plugins/cases/docs/openapi/bundled.yaml +++ b/x-pack/plugins/cases/docs/openapi/bundled.yaml @@ -3511,7 +3511,7 @@ components: description: The label used to display the custom field in the Case's pages. required: type: boolean - description: Defines if the custom field is required on case creation. + description: Defines if the custom field can be set to null on create/update cases. type: type: string enum: diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_configuration.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_configuration.yaml index bbb9a7ccef45b..c2c7371a9fbd4 100644 --- a/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_configuration.yaml +++ b/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_configuration.yaml @@ -14,7 +14,7 @@ properties: description: The label used to display the custom field in the Case's pages. required: type: boolean - description: Defines if the custom field is required on case creation. + description: Defines if the custom field can be set to null on create/update cases. type: type: string enum: From 1bc8073bfed9b1d71151fff9cf1ce774b5bf95b6 Mon Sep 17 00:00:00 2001 From: adcoelho Date: Thu, 19 Oct 2023 16:16:21 +0200 Subject: [PATCH 3/3] PR comments --- x-pack/plugins/cases/docs/openapi/bundled.json | 3 ++- x-pack/plugins/cases/docs/openapi/bundled.yaml | 3 ++- .../openapi/components/schemas/custom_fields_property.yaml | 2 +- .../components/schemas/set_case_configuration_request.yaml | 1 + 4 files changed, 6 insertions(+), 3 deletions(-) diff --git a/x-pack/plugins/cases/docs/openapi/bundled.json b/x-pack/plugins/cases/docs/openapi/bundled.json index 082fa768b34b3..2f6fcd39c663a 100644 --- a/x-pack/plugins/cases/docs/openapi/bundled.json +++ b/x-pack/plugins/cases/docs/openapi/bundled.json @@ -4623,7 +4623,7 @@ }, "custom_fields_property": { "type": "array", - "description": "Values for custom fields of a case.", + "description": "Values for custom fields of a case. Any missing optional custom field(keys) in the request will be set to null.", "minItems": 0, "maxItems": 10, "x-technical-preview": true, @@ -5518,6 +5518,7 @@ }, "customFields": { "description": "An array containing the custom fields.", + "x-technical-preview": true, "type": "array", "minItems": 0, "maxItems": 10, diff --git a/x-pack/plugins/cases/docs/openapi/bundled.yaml b/x-pack/plugins/cases/docs/openapi/bundled.yaml index 95dc2b10baf3b..d6d9f5494a509 100644 --- a/x-pack/plugins/cases/docs/openapi/bundled.yaml +++ b/x-pack/plugins/cases/docs/openapi/bundled.yaml @@ -2922,7 +2922,7 @@ components: default: low custom_fields_property: type: array - description: Values for custom fields of a case. + description: Values for custom fields of a case. Any missing optional custom field(keys) in the request will be set to null. minItems: 0 maxItems: 10 x-technical-preview: true @@ -3566,6 +3566,7 @@ components: - syncAlerts customFields: description: An array containing the custom fields. + x-technical-preview: true type: array minItems: 0 maxItems: 10 diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml index 47231dea4e0e5..7bf407305f60b 100644 --- a/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml +++ b/x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml @@ -1,5 +1,5 @@ type: array -description: Values for custom fields of a case. +description: Values for custom fields of a case. Any missing optional custom field(keys) in the request will be set to null. minItems: 0 maxItems: 10 x-technical-preview: true diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/set_case_configuration_request.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/set_case_configuration_request.yaml index 0e5b679e631cb..d42d01a79f083 100644 --- a/x-pack/plugins/cases/docs/openapi/components/schemas/set_case_configuration_request.yaml +++ b/x-pack/plugins/cases/docs/openapi/components/schemas/set_case_configuration_request.yaml @@ -32,6 +32,7 @@ properties: - syncAlerts customFields: description: An array containing the custom fields. + x-technical-preview: true type: array minItems: 0 maxItems: 10