docs: clarify service event rules time frame parameters

[pdecat]

Usage of Unix timestamp here is confusing, as that usually means the number of (milli-)seconds that have elapsed since the Unix Epoch (January 1st, 1970 at UTC).

Note that official API docs do not mention Unix or timestamp:

              "time_frame": {
                "description": "Time-based conditions for limiting when the rule is active.",
                "type": "object",
                "properties": {
                  "active_between": {
                    "type": "object",
                    "required": [
                      "start_time",
                      "end_time"
                    ],
                    "description": "A fixed window of time during which the rule is active.",
                    "properties": {
                      "start_time": {
                        "type": "integer",
                        "description": "The start time in milliseconds."
                      },
                      "end_time": {
                        "type": "integer",
                        "description": "End time in milliseconds."
                      }
                    }
                  },
                  "scheduled_weekly": {
                    "type": "object",
                    "required": [
                      "start_time",
                      "duration",
                      "timezone",
                      "weekdays"
                    ],
                    "description": "A reccuring window of time based on the day of the week, during which the rule is active.",
                    "properties": {
                      "start_time": {
                        "type": "integer",
                        "description": "The amount of milliseconds into the day at which the window starts."
                      },
                      "duration": {
                        "type": "integer",
                        "description": "The duration of the window in milliseconds."
                      },
                      "timezone": {
                        "type": "string",
                        "description": "The timezone."
                      },
                      "weekdays": {
                        "type": "array",
                        "description": "An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday.",
                        "items": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              },

https://github.com/PagerDuty/api-schema/blob/main/reference/REST/openapiv3.json
https://developer.pagerduty.com/api-reference/reference/REST/openapiv3.json/paths/~1services~1%7Bid%7D~1rules/post

[pdecat]

Maybe also say time instead of timestamp (which by itself is also meant to be absolute) like in official API documentation:

Suggested change

	* `start_time` - Time when the schedule will start. Timestamp in milliseconds relative to the beginning of the day. For example, if you have a rule with a `start_time` of `0` and a `duration` of `60,000` then that rule would be active from `00:00` to `00:01`. If the `start_time` was `3,600,000` the it would be active starting at `01:00`.
	* `start_time` - Time when the schedule will start. Time in milliseconds relative to the beginning of the day. For example, if you have a rule with a `start_time` of `0` and a `duration` of `60,000` then that rule would be active from `00:00` to `00:01`. If the `start_time` was `3,600,000` the it would be active starting at `01:00`.

[pdecat]

Maybe also say time instead of timestamp (which by itself is also meant to be absolute) like in official API documentation:

Suggested change

	* `start_time` - Beginning of the scheduled time when the rule should execute. Timestamp in milliseconds relative to the beginning of the day.
	* `end_time` - Ending of the scheduled time when the rule should execute. Timestamp in milliseconds relative to the beginning of the day.
	* `start_time` - Beginning of the scheduled time when the rule should execute. Time in milliseconds relative to the beginning of the day.
	* `end_time` - Ending of the scheduled time when the rule should execute. Time in milliseconds relative to the beginning of the day.

[metavida]

Ah ha! I didn't realize that there were multiple spots in the terraform docs where we describe an event rule's start_at value! I'd previously clarified the wording of this portion of the API here: #340

I feel very strongly that we should adjust the wording & code samples on this page to match the wording & code samples on ruleset_rule.html.markdown page to help our customers avoid bugs. For example: https://github.com/metavida/terraform-provider-pagerduty/blob/e3f0ec6f1dc89847061d18c7e874e77b90cd7dc3/website/docs/r/ruleset_rule.html.markdown?plain=1#L148-L150

Let me know if you've got any questions.

[pdecat]

So you are saying these are actual Unix timestamps, and it's the official API reference that needs clarification?

https://github.com/PagerDuty/api-schema/blob/main/reference/REST/openapiv3.json
https://developer.pagerduty.com/api-reference/reference/REST/openapiv3.json/paths/~1services~1%7Bid%7D~1rules/post

[metavida]

Yes, I can confirm that the start_at values are indeed Unix timestamps in milliseconds and that the official API documentation (e.g. https://developer.pagerduty.com/api-reference/b3A6Mjc0ODIwNw-create-an-event-rule-on-a-service ) should definitely be corrected too.

You can observe this, in practice, by fetching the schedule of an event rule that you create in the UI. Here's a rule with a recurring schedule that created just now via the UI:

And here's what the API response for that rule looks like:

$ curl -Ss --request GET "https://api.pagerduty.com/services/$SERVICE_ID/rules" --header "Authorization: Token token=$PD_API_KEY" | jq '.rules[0].time_frame'
{
  "active_between": null,
  "scheduled_weekly": {
    "duration": 28800000,
    "start_time": 1633968000000,
    "timezone": "America/Los_Angeles",
    "weekdays": [
      1,
      3,
      5
    ]
  }
}

$ date -r 1633968000   
Mon Oct 11 09:00:00 PDT 2021

So the UI set the the start_time to the Unix timestamp in milliseconds with today's date and the time of 9am when PDT offset is applied.

I don't know the history of how this API's structure came to be, but my guess is that it's a case where the customer-facing API ended up exposing the UI implementation and/or storage implementation details a bit more directly than is helpful.

Next steps

What your preferred path forward?

1. You can update this PR to adopt the wording from PR Improve the ruleset_rule time_frame documentation #340
2. We can close this PR and we can open a ticket to have PagerDuty update this terraform documentation
3. Something else?

I've already opened up a ticket to get the REST API docs updated appropriately (because I don't think docs can accept an open-source PR).

Last, but not least, thanks for opening this PR & raising all these documentation inconsistencies!

[pdecat]

Thanks, I'll update the documentation accordingly in this PR. In the meantime, I've marked it as draft to prevent it from being merged as is.