The onOrderManagement callback

When the Assistant detects that the user is trying to view or cancel their orders, it invokes the callback associated with the order management user journey. The callback looks like this:

OrderManagementUserJourney.AppState onOrderManagement(OrderInfo orderInfo, OrderManagementUserJourney userJourney);

onOrderManagement: async (orderInfo, orderMangementUserJourney)

onOrderManagement: async (orderInfo, orderMangementUserJourney)

When this callback is invoked, the app is expected to:

1. Use the OrderInfo parameter to check if the user is interested to view or cancel their past orders

2. Open the corresponding order page using the index field in the OrderInfo parameter

3. Based on the condition of the specific order, set appropriate conditions in the Assistant

4. Finally, return the AppState that the app transitioned to.

For example, for a given onOrderManagement callback invocation, if the user asked for viewing a specific order, and if that order did not exist, the app would set the condition to OrderNotFound and return AppState as VIEW_ORDER, as shown below:

public OrderManagementUserJourney.AppState onOrderManagement(OrderInfo orderInfo, OrderManagementUserJourney userJourney) {
   int orderIndex = orderInfo.getOrderIndex();
   
   if (!checkOrder(orderIndex)) { // Order does not exist
      userJourney.setViewOrderNotFound(orderIndex);
   } else {   
      userJourney.setViewSuccess();
   }
   return OrderManagementUserJourney.AppState.VIEW_ORDER;
}

onOrderManagement: async (orderInfo, orderMangementUserJourney) => {
  var orderIndex = orderInfo.orderIndex;
   
  if (!checkOrder(orderIndex)) { // Order does not exist
    userJourney.setViewOrderNotFound(orderIndex);
  } else {   
    userJourney.setViewSuccess();
  }
  return OrderManagementUserJourney.AppState.VIEW_ORDER;
},

onManageOrder: async (orderInfo, orderMangementUserJourney) => {
  const orderIndex = orderInfo.orderIndex;
   
  if (!checkOrder(orderIndex)) { // Order does not exist
    userJourney.setOrderNotFound(orderIndex);
  } else {   
    userJourney.setViewSuccess();
  }
  return OrderManagementUserJourney.AppStates.VIEW_ORDER;
},

Sample Utterances that could trigger Order Management

The following are some examples of commands that could trigger this user journey

• "show my orders"

• "where is my last order"

• "cancel my first order"

OrderInfo Parameter

The OrderInfo parameter contains the breakdown of the original order request. It has the following structure:

Class OrderInfo {
	int getOrderIndex(); // The index of the order
	OrderAction getOrderAction();
	ConfirmationStatus getCancelConfirmationStatus();
​
	enum OrderAction {
		VIEW,
		CANCEL
	},
	
	enum ConfirmationStatus {
	  UNKNOWN,    // When the user requested for cancelation, initially the confirmation status would be UNKNOWN
	  CONFIRMED,  // When the user has explicilty confirmed the cancellation, 
	  DENIED      // When the user has explicilty denied the cancellation 
	}
}

{
  "action": <string value>,             // One of "VIEW, CANCEL"
  "confirmationStatus": <string value>, // One of "UNKNOWN, CONFIRMED, DENIED"
  "index": <int>                        // one of -1, 0,...
}

{
  "action": <string value>,             // One of "VIEW, CANCEL"
  "confirmationStatus": <string value>, // One of "UNKNOWN, CONFIRMED, DENIED"
  "index": <int>                        // one of -1, 0,...
}

So when the user speaks "show my last order",

• Index = -1

• OrderAction = VIEW

When the user speaks "cancel my order"

• Index = 0

• OrderAction = CANCEL

• ConfirmationStatus = UNKNOWN

Supported AppStates

The following AppStates are supported:

• VIEW_ORDER: To be returned when the app is able to handle the order request and transitions to the orders page.

• CANCEL_ORDER: To be returned when the app is able to handle the cancel request and navigates to the cancel orders page

• UNSUPPORTED: To be returned when the app is not ready to handle orders yet. The Assistant will speak out an appropriate prompt to the user.

Supported AppState conditions

The following AppState conditions are supported for each of the AppStates supported by the Assistant

Handling cancellations effectively

When the user is trying to cancel an order, the ideal workflow is that the app would want the user to confirm before actually canceling the order. Typically this would be done in a multi-modal fashion, i.e. the app would inform the Assistant to ask for confirmation via voice, while the app also shows a dialog box for the user to visually confirm the same.

Alternately, the app could choose to not show any confirmation and just directly cancel the order (if the order could be found)

Handling cancel confirmations

When the user initially requests for a cancellation, the Assistant sets the ConfirmationStatus (inside the OrderInfo parameter) to UNKNOWN. The app could then do the following:

• If ConfirmationStatus == UNKNOWN, call setCancelConfirmationRequiredfor the AppState condition and return CANCEL_ORDER as the AppState

  • The Assistant will then ask the user to confirm the cancellation of the order and the same user journey callback will be invoked again (with the ConfirmationStatus set to CONFIRMED or DENIED)

• If the ConfirmationStatus == CONFIRMED, the app should attempt to cancel the order and if that was:

  • Successful : Call setUserConfirmedCancel for the app state condition and return CANCEL_ORDER as the AppState.

  • Failure : Call setCancelFailure for the AppState condition and return CANCEL_ORDER as the AppState.

• If the ConfirmationStatus == DENIED, the app should call setUserDeniedCancel for the AppState condition and return CANCEL_ORDER as the AppState.

Assistant Prompts

Based on the App State and the Condition that was set, the Assistant will speak out an appropriate message to the user. You can examine the default set of prompts configured for the Assistant through the Console and also customize it to your needs. Refer to the Customizing the Assistant section for details.