Functional flows/acceptance criteria for fetch available appointments

[kkuo]

1. When I provide a primaryReferenceNumber and a locationIdentifier, I should receive a successful response with the response defined in the spec.

[dutabado]

criteria i think we should add:

Core Scenarios

• When provided valid identifiers,
  and the response will be returned asynchronously,
  then I should receive a PENDING result with a valid requestId

• When provided valid identifiers,
  and no appointments are available,
  then I should receive a SUCCESS result with an empty array of appointments

• When provided valid identifiers,
  and an exact date restriction,
  then I should receive a SUCCESS result that only includes appointments on the specified date

• When provided valid identifiers,
  and an date range restriction,
  then I should receive a SUCCESS result that only includes appointments within the specified dates (inclusive)

Error Scenarios

• When provided an identifier for a load that doesn't exist,
  then I should receive a failure result
  and the FAILURE result should include an EntityNotFoundError that includes the identifier that can't be found

• When provided an identifier for a stop that doesn't exist,
  then I should receive a failure result
  and the FAILURE result should include an a EntityNotFoundError that includes the identifier that can't be found

• When a load identifier isn't included in the request,
  then I should receive a failure result
  and the FAILURE result should include an InvalidArgumentError that specifies the missing identifier

• When a stop identifier isn't included in the request,
  then I should receive a failure result
  and the FAILURE result should include an InvalidArgumentError that specifies the missing identifier

• When a malformed identifier is included in the request,
  then I should receive a failure result
  and the FAILURE result should include an InvalidArgumentError that specifies the malformed identifier and the value provided

• When multiple, valid load identifiers for different loads are included in the request,
  then I should receive a failure result
  and the FAILURE result should include an ???

• When multiple, valid load identifiers for different stops are included in the request,
  then I should receive a failure result
  and the FAILURE result should include an ???

• When provided valid identifiers,
  and an date range restriction,
  and the end date is before the start date,
  then I should receive a failure result
  and the FAILURE result should include an InvalidArgumentArror that specifies the end date is before the start

[kkuo]

Webhook Scenarios

• When I have a fetch-available-appointments webhook event registered with the TMS,
  then I should receive the results via the callBackURL that I have registered with the TMS,
  and I should receive a SUCCESS from my synchronous request with an empty or null list of availableAppointments

• When I have a fetch-available-appointments webhook event registered with the TMS,
  and TMS fails to call the callbackURL that I have registered at the TMS,
  then I should receive a synchronous FAILURE code so that I am aware of the problem with the webhook and take appropriate actions

@dutabado @miller79 what are your thoughts if the callback URL has an error and the TMS can't make a call to it. How is that error surfaced to the client? Should I just take out the above bullet point since it is undefined?

• When I have a fetch-available-appointments webhook event registered with the TMS,
  and one of the failures described in the Error Scenarios applies,
  then I should be notified of the error via the registered callbackURL and not through the synchronous request that I am making.

Callback Header Scenarios

• When I provide a callback URL in the request header,
  and my request is valid,
  then I should receive a SUCCESS from my synchronous request with an empty or null list of availableAppointments

• When I have a fetch-available-appointments webhook event registered with the TMS,
  and TMS fails to call the callbackURL that I have registered at the TMS,
  then I should receive a synchronous FAILURE code so that I am aware of the problem with the webhook and take appropriate actions

@dutabado @miller79 ^^ Same for callback URLs

• When I provide a callbackURL in my request header,
  and one of the failures described in the Error Scenarios applies,
  then I should be notified of the error via the callbackURL provided and not through the synchronous request that I am making.

[dutabado]

How is that error surfaced to the client? Should I just take out the above bullet point since it is undefined?

yeah, i don't know that the TMS can do anything here. this is why i was thinking it might make sense to have some sort of status field on the webhooks so the client can regularly check for broken webhooks

[dutabado]

then I should receive a synchronous FAILURE code so that I am aware of the problem with the webhook and take appropriate actions

or were you suggesting the if the TMS knows the webhook is invalid or doesn't exist, that it should fail any synchronous calls that rely on webhooks?

[kkuo]

then I should receive a synchronous FAILURE code so that I am aware of the problem with the webhook and take appropriate actions

or were you suggesting the if the TMS knows the webhook is invalid or doesn't exist, that it should fail any synchronous calls that rely on webhooks?

I'm not sure this flow is correct or logic but this is what I was thinking

1. callers call fetchAvailableAppointments
2. TMS has a status for the registered callback. see the status is invalid, fails the synchronous request so the caller knows about it.
3. Otherwise if the callback fails when the response is ready but there is no way for the TMS to indicate that to the client