Introduction

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

As an example, we you will make a flow that controls the entire validation process of a "shopping cart" for an online store. We You will also have 7 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, we you can create the proposed flow as an example.

The flow we 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.

We You will also see how to control errors in case operations fail for whatever reason. If this should happenhappens, we will undo the process willl be undone and notify the user notified. In case of serious error, we 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, we will follow the next steps:

1. Select the "FlowEngine Management" option from the Development menu:
   
   
   
   
2. Select the domain belonging to our your user:
   
   
   
   
3. Once we you are in the domain, define the message that our your flow would will receive. We will create Create an "inject" node to manually launch the flow, and another "function" none node with the contents of the shopping cart:
   
   
   The content contents of the "Function" node will be:
   
   
   
   
   
4. Once we you have our your input information defined, we will validate the user by calling the "Get User By ID" operation of the "Users -V1" API. To do this we will , drag a node, type "OnesaitPlatform Rest API invoker":
   
   By double clicking on the added node, we will fill in the required fields by selecting the API and operation previously explained. Firstly, we select the API from the available list:
   
   
   
   
   And once we you have set the API, we you can see the list of operations:
   
   
   Once we you have the operation selected, the fields required by the operation will appear. In our this case we , you will have to indicate which one is the id. Since the user ID is in the message entering the flow (msg.checkout.user), we will indicate this in the node:
   
   
   
   If we you click "Done", we 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. We You have already validated the user. Now we you will validate her the user's address. Before creating the next invocation node, we you will store the user's complete information in another field of the message different than from payload, so that the later it is not overwritten. To do this, in a "Function" node, we will store it in "msg.user" in a "Function" node:
   
   
   
   Following the same steps as in the previous point, we will 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 we you will indicate where to get the address. The user information is just exactly what the previous invocation returned to us 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" we will , specify where to find the address in the message, which is here: msg.payload.StoreUsers.address
   
   
6. Once the shipping address is validated, we will validate the payment, passing as a parameter the payment information that we you had stored in msg.checkout.payment.
   
   
   
   
7. Next, we will call the Inventory API to validate the purchase items. The order information is found in msg.checkout.order:
   
   
   
   
8. After validating the order elements, we will invoke the Orders API to generate the order in the system. This operation requires two parameters: user and body (elements in the order elements):
   
   
   
   
9. After creating the order, we you now have to send the confirmation mail to the user. The mail notification operation requires that we 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, we will prepare the msg.payload to contain such information:
   
   
   
   and we will invoke the email notification API:
   
   

...

With what has been done so far, we 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 our this case) errors when calling the operation.

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

Within the complete flow, we have added 3 you can add three sections:

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