Getting data and logic of complex screen forms

Alina Prilipukhova

Leading analyst at Yuztech Group

Hi all! My name is Alina. I have been working as an analyst for more than 3 years, now at Yuztech Group with the product Teal Echar. This is a staff loyalty and motivation program that allows you to reduce the cost of attracting new employees and retain current employees.

This article will be useful, first of all, for business and system analysts, as well as for designers, project managers and even testers. Analysts will be able to reflect on the described approaches in the context of their immediate tasks, designers will be able to think about at what point to decide on the appearance of components for loading and errors, project managers will be able to think about estimating the time spent on similar tasks, and testers will be able to think about the structure of test plans for testing such EFs.

Introduction

Today we’ll talk about screen forms (hereinafter – EF), for rendering which you need to obtain data from several sources. This raises a number of questions that need to be answered before starting development. For example:

1. Should I receive data within one or more endpoints?

2. Where to implement business logic (on the front end or on the back end)?

3. Do data source systems have an SLA (from the English Service Level Agreement) and does it satisfy us as a consumer?

The number of questions depends on the features of our system and data source systems. Without answers to them, it is impossible to even create a final design, since the designer will not be able to select the correct components that illustrate the loading of the EF and errors.

What to consider before making a decision

First, we find out from customers the business requirements and the scenario of how the user will work with the EF. The options can be divided into the following:

1. The user needs to display the entire EF. He cannot proceed to the next step until he sees all the data on the EF;

2. Not the entire EF can be displayed to the user. To proceed to the next step, it is important that some parts of it are loaded, and the rest is just a recommendation.

It is important to discuss and record with customers the maximum loading time for EFs, as well as what we do if we end up with an error.

Secondly, we learn about the SLA of data source systems. Let me make a reservation that we are looking at a situation where data source systems already have an API for integrating with them and obtaining the data we need.

So, a situation may arise that the data source system simply does not have an SLA or the existing SLA does not specify aspects that are interesting to us. We need to know the guaranteed response time when accessing endpoints, established timeout settings, deadlines for eliminating critical incidents, rules for updating the API at the request of consumers – all this should be kept in mind when making the final decision.

If we cannot be given guarantees, but only some average response time obtained from the results of load testing, and the maximum system unavailability time derived from recent incidents, then if the response time exceeds the average value or the system unavailability time exceeds the expected time, we will ask no one. There is a risk of exceeding the permissible maximum loading time of our EF.

Third, we examine accepted design patterns within our system and/or organization. Someone might be surprised by the question related to where to implement business logic, because they involuntarily ask for the answer: “On the backend, of course, what are we talking about.” Mostly, I came across approaches where the presence of business logic on the front end was strictly prohibited. The reason was its complexity and the frequent reuse of the same data in different parts of the application, which should not have been different. All business logic was moved to the backend, and endpoints were reused.

However, in my practice, there was a case when EF No. 1 contained EF No. 2 and, based on the data that came to EF No. 2, the status of the entity was displayed on EF No. 1. The business logic in both EFs was identical and we did not plan to change it in the foreseeable future, and the data source system was very mature and guaranteed us all the aspects of interest.

We made the decision to embed one EF into another, rather than reuse endpoints, because if a new attribute appeared on EF No. 2, then it had to simultaneously appear on EF No. 1, and they also had to be uniform in design. That is, we would have to monitor the actions of the neighboring team and modify our EF in accordance with their changes (EF No. 2 was actively filled with data during that period) when we needed only a few attributes to display the status of the entity.

For further discussion, as an example, let us present an EF consisting of 5 parts. We obtain data for the 1st, 2nd and 3rd parts from source “A”, for the 4th – from source “B”, and the 5th part is a kind of traffic light, which, based on the data of the remaining 4- x parts show green, yellow or red.

Let's start designing

Let's consider the option when we receive data for the entire form within one endpoint.

The diagram shows only the main scenario (without nuances associated with pagination, etc.), if we requested the data and successfully received it. What to do if an error occurs depends on whether the EF needs to be displayed to the user in its entirety or whether partial display of data is allowed.

If you absolutely need to display the EF completely, then if an error occurs at any stage of the data retrieval scenario, you can “put” the entire request into error, since if at least one of the data source systems has not responded to us, then we can no longer calculate the “traffic light” for the 5th part of the EF.

If it is not possible to display the entire EF, and we have received data that must be returned to the user, then we can return a successful response, and instead of the data that did not arrive, “put” an exception(s) in the response.

For example, we do not care about the value of “traffic light” and the data from the data source system “B”. The information from data source system “A” is critical. We can put an array of exceptions objects in the endpoint, which we will fill if an error occurs when accessing “B”. It is also important here to know the logging requirements so that the exceptions object array contains all the necessary attributes for writing to the log log.

This is not the end of the scenario. The user sees the EF, where in my example 1-3 of its parts are displayed, and decides that he does not have enough information to move to the next step. We thought about such a case in advance and added a “Repeat” button to the EF, but what happens when you click on it? Will we re-request all the information in full? What if we have a case where the data is completely independent of each other and it is not critical for us that part of the EF is obtained in X hours YY minutes, and part in X hours YY minutes + several minutes?

You can come up with some kind of query parameter in the form of ENUM and list in it a list of source systems from which we want to receive data, but in such a situation I would suggest splitting the data retrieval into several endpoints. If we have a separate endpoint for retrieving data from the source system “B”, when we click on the “Repeat” button, we will send a simple request directly to “B”.

Wait, how can you comply with the requirement for mandatory display of the EF in full in the case of several endpoints? Very simple: display data only when a successful response is received from all endpoints.

As for the 5th part of the EF, I would highlight a separate endpoint for obtaining the “traffic light” value, since the logic for calculating this attribute may become more complicated or new attributes may be added to the EF, the values ​​of which depend on data from different systems – sources. At the stage of development of the EF, which I described as an example, it is possible to move the logic to the front end, but it will be difficult to maintain with further scaling.

Conclusion

In order to properly design an EF, we need to thoroughly prepare: discuss business requirements with the customer, study the systems from which we are going to receive data, as well as design patterns and best practices. It’s worth starting even before preparing the final design in order to correctly depict all the states of the EF. How to receive data (within one or more endpoints) and on which side to put the logic depends on many factors, each of which should be taken into account when making the final decision.