Improve OnCall API/Terraform documentation (parameters & examples)

[ghost]

What would you like to see!

It is not very clear how to set an oncall shift rotation besides common examples in the Terraform provider and the docs.

For example: the duration parameter in on_call_shifts API endpoint does not explain its units or accepted values: https://grafana.com/docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/on_call_shifts/

Parameter	Unique	Required	Description
duration	No	Yes	Duration of the event.

I was able to extrapolate from other API endpoint that the parameter unit is seconds but it would be nice to have it in the docs.

Also, it would be really helpful to have more Terraform provider examples to set more complex shift schedules using calendar type schedules, i.e.: using duration, frequency, by_day and other parameters.

Lets say we have a rotation like this:

• Mon-Fri 5AM to 10AM: covered by Alice.
• Mon-Fri 10AM to 3PM: Alice and Bob switching between Primary and Secondary oncall, each day.
• Mon-Fri 3PM to 8PM: covered by Bob.
• Off hours (after 8PM until 5AM) and weekends: Alice and Bob switching between Primary and Secondary, each week.

Thanks in advance!

Product Area

Terraform

Anything else to add?

Grafana OnCall v1.3.68.

No response

[github-actions[bot]]

The current version of Grafana OnCall, at the time this issue was opened, is v1.3.68. If your issue pertains to an older version of Grafana OnCall, please be sure to list it in the PR description. Thank you :smile:!

[ghost]

Added reference for Grafana OnCall v1.3.68.