Introduction

In this tutorial, you are going to see an example of how to orchestrate several API calls to define a more complex, controlled behavior.

As an example, you will make a flow that controls the entire validation process of a "shopping cart" for an online store. You will also have seven available APIs with the following operations:

• Management Modules:
  
  • API - Users
    • Operation - Get user by ID
  • API - Shipping Orders
    
    • Operation - Shipping address validation
  • API - Payments
    
    • Operation - Validate payment
    • Operation - Cancel payment
  • API - Inventory
    
    • Operation - Check item list
    • Operation - Cancel order
  • API - Orders
    
    • Operation - Create order
• Internal tools
  
  • API - Send mail
    
    • Operation - Send error mail
    • Operation - Send confirmation mail
  • API - Backoffice
    • Operation - Create incidence

Flow for this Example

By orchestrating the operations of the different APIs, you can create the proposed flow as an example.

The flow you will follow will be:

1. Validate User.
2. Validate shipping address.
3. Validate payment.
4. Check item list.
5. Create order.
6. Send confirmation email to the user.

You will also see how to control errors in case operations fail for whatever reason. If this happens, the process willl be undone and the user notified. In case of serious error, you will create an incidence in the system so that it is recorded and the support team can act on it.

Process

To do this, follow the next steps:

1. Select the "FlowEngine Management" option from the Development menu:
   
   
   
   
2. Select the domain belonging to your user:
   
   
   
   
3. Once you are in the domain, define the message that your flow will receive. Create an "inject" node to manually launch the flow, and another "function" node with the contents of the shopping cart:
   
   
   The contents of the "Function" node will be:
   
   
   
   
   
4. Once you have your input information defined, validate the user by calling the "Get User By ID" operation of the "Users -V1" API. To do this, drag a node, type "OnesaitPlatform Rest API invoker":
   
   By double clicking on the added node, fill in the required fields by selecting the API and operation previously explained. Firstly, select the API from the available list:
   
   
   
   
   And once you have set the API, you can see the list of operations:
   
   
   Once you have the operation selected, the fields required by the operation will appear. In this case, you will have to indicate which one is the id. Since the user ID is in the message entering the flow (msg.checkout.user), indicate this in the node:
   
   
   
   If you click "Done", you will see that the node has now more outputs. Each output represents a statusCode of the API operation call. We can see this value by placing the mouse over the outputs:
   
   
   
   The number of outputs (and the statusCode value) will depend on what has been defined in the operation. For the rest of the example, in all API invocations, the upper pin will always be the correct execution output (200). The rest represent different errors such as "item not found" (404), "server error" (500), etc.
   
   In the case of this operation, all user information (address, email, telephone, ...) will be returned in the outgoing message's payload.
   
   
5. You have already validated the user. Now you will validate the user's address. Before creating the next invocation node, you will store the user's complete information in another field of the message different from payload, so that it is not overwritten. To do this, store it in "msg.user" in a "Function" node:
   
   
   
   Following the same steps as in the previous point, create the call to the address validation operation:
   
   
   
   As you can see in the previous image, the operation, being POST, requires the BODY field, where you will indicate where to get the address. The user information is exactly what the previous invocation returned in the msg.payload. The user API manages the data through an ontology and the result of the msg.payload is:
   
   
   
   According to this, in the input parameter "body", specify where to find the address in the message, which is: msg.payload.StoreUsers.address
   
   
6. Once the shipping address is validated, validate the payment, passing as a parameter the payment information that you had stored in msg.checkout.payment.
   
   
   
   
7. Next, call the Inventory API to validate the purchase items. The order information is found in msg.checkout.order:
   
   
   
   
8. After validating the order elements, invoke the Orders API to generate the order in the system. This operation requires two parameters: user and body (elements in the order):
   
   
   
   
9. After creating the order, you now have to send the confirmation mail to the user. The mail notification operation requires that you pass, in the body, a JSON with the fields "user" containing the user's complete information, and the field "order" that will be a list of the purchased items. Firstly, prepare the msg.payload to contain such information:
   
   
   
   and invoke the email notification API:
   
   

With what has been done so far, you would have the whole sequence of invocations to the APIs, assuming that no operation fails. Remember that the other outputs of the invoking nodes that are not being used, represent (in this case) errors when calling the operation.

Following the same steps that you have done before, you can complete the flow, capturing the error outputs as follows:

Within the complete flow, you can add three sections:

• Rollback in case of error, corresponding to this section:
  
  
  
  
• Should any rollback operation fails, consider that it is an incidence for the support team, thus you must invoke the API that registers the incidents in the system:
  
  
  
  
• In any case, the user is notified of the error: