[Cases] Update the custom fields api documentation.

[adcoelho]

Summary

This PR updates the documentation with the custom fields logic that was implemented recently in the custom fields feature branch.

[elasticmachine]

Pinging @elastic/response-ops (Team:ResponseOps)

[elasticmachine]

Pinging @elastic/response-ops-cases (Feature:Cases)

[cnasikas]

Thanks Antonio for updating the docs. I have some observations/questions (sorry for my lack of knowledge):

• Should we update the types for the create/update Case APIs?
• I think we should tell users how we treat optional fields when are missing from the create/update Case APIs?
• How I can visualize the changes in the docs?

[cnasikas]

This is not entirely true because we do not persist the null value in ES. Though our APIs will return null. I am not sure if we have to be explicit about it. wdyt? cc @lcawl

[adcoelho]

How about:

The value of the custom field. Cannot be explicitly set to null if the field is configured as required. However, cases that had been created before the custom field was added will have this value undefined in elastic search and return null as default when trying to access them via API or UI.

[lcawl]

Here's what I'm currently proposing in #169327:

The custom field value.
If the custom field is required, it cannot be explicitly set to null.
However, for cases that existed when the required custom field was added, the default value stored in Elasticsearch is undefined.
The value returned in the API and user interface in this case is null.

[adcoelho]

Should we update the types for the create/update Case APIs?

That comes from x-pack/plugins/cases/docs/openapi/components/schemas/custom_fields_property.yaml already updated in this PR.

I think we should tell users how we treat optional fields when are missing from the create/update Case APIs?

This is an explanation more about what the user doesn't send so where would that make sense? Maybe here?

How I can visualize the changes in the docs?

@lcawl ? 😅

[adcoelho]

I think we should tell users how we treat optional fields when are missing from the create/update Case APIs?

I updated the description here.

[lcawl]

Looks like we were both working on this yesterday (my PR: #169327). I will compare to see if we can merge our efforts.

[kibana-ci]

💔 Build Failed

• Buildkite Build
• Commit: 1bc8073
• Interpreting CI Failures

Failed CI Steps

• Investigations - Security Solution Cypress Tests #5
• Investigations - Security Solution Cypress Tests #5
• Investigations - Security Solution Cypress Tests #7
• Defend Workflows Cypress Tests, burning changed specs #1
• Security Solution Cypress tests, burning changed specs #1

Test Failures

• [job] [logs] Investigations - Security Solution Cypress Tests #5 / Fields Browser Fields Browser rendering "before each" hook for "displays a search results label with the expected count of fields matching the filter input" "before each" hook for "displays a search results label with the expected count of fields matching the filter input"
• [job] [logs] Investigations - Security Solution Cypress Tests #7 / Save Timeline Prompts "before each" hook for "Changed & unsaved timeline should prompt when user navigates away within security solution where timelines are disabled eg. admin screen" "before each" hook for "Changed & unsaved timeline should prompt when user navigates away within security solution where timelines are disabled eg. admin screen"

Metrics [docs]

✅ unchanged

History

• 💛 Build #169040 was flaky 6e6a51c

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @adcoelho

[lcawl]

• How I can visualize the changes in the docs?

I removed the previews in #168761, so these specs must be viewed in external viewers for now. The first priority in our new docs site is displaying the serverless APIs, so these case APIs are not visible there yet.