As a new integration analyst at Archers, I have gained insights into the diverse aspects and responsibilities that come with this role. One of the primary responsibilities of an integration analyst is to document (non-functional) requirements. In this blog, I will share my insights into this process and provide some tips for effective documentation.
A requirement is a usable representation of a need, that focuses on understanding the value that could be delivered if the requirement is fulfilled. There are different types of requirements, including functional requirements and non-functional requirements.
- Functional requirements describe the behavior of the solution, including any processing and underlying calculations that need to take place.
- Non-functional requirements describe the attributes and standards that the solution must meet, as well as any implementation constraints that the solution must adhere to.
Business users typically have a clear idea of what a solution should do when they come up with a question, making functional requirements easy to obtain. However, answering the question of how the solution should perform can be challenging and harder to answer. It is crucial to consider non-functional requirements because neglecting them may result in a solution that either does not work or does not meet expectations. This could lead to a bad or non-existent user experience, causing users to stop using the solution altogether.
How to go about non-functional requirements
As mentioned in the previous paragraph, obtaining information about non-functional requirements can be challenging, but is absolutely necessary. One useful approach is to use an overview of non-functional requirements categories, such as an NFR category mindmap to ensure that no important requirements are overlooked. While not all categories will always be applicable, having an overview of potential NFRs can help in selecting those needed for a specific solution.
In the field of integration, NFRs that are particularly important are data freshness, volume, message size, availability, audit, (data) security, and degradation of service.
Data freshness refers to the frequency of data exchange between applications. For example, a master system managing customers might need to inform slave systems when creating or updating customers. The required data freshness determines, for example, if real-time integration is necessary or if a daily extract from the master of new and changed customers is sufficient for updating the slave system.
Volume refers to the expected amount, both on average and at peak times, of business objects that will be exchanged through a certain integration, or the expected number of integration executions. Imagine a service / API in your landscape that provides access to a contract. It is important to estimate the frequency of access requests. This is often hard to establish. This information can be gathered from integration logs or by consulting organization members. It is crucial to consider both average and peak volumes (as some flows will for example have higher volumes at the end of the month). Additionally, anticipating future volume growth due to organizational growth or seasonal fluctuations is essential.
Message size refers to the expected message size. This depends on the business object size and the number of objects per message. It is also affected by the choice between sending delta data (updated data) only or a full load (the full set of data, including updated and not updated data). Knowing the expected message size is important because some network components have size limits, and large messages can negatively impact performance.
Availability refers to the required availability of integrations, services and APIs within the landscape. Maintenance windows may cause components to be unavailable, directly impacting application functionality. Therefore, a clear understanding of the required availability is crucial.
Audit refers to logging user actions and transactions. It is crucial to determine the extent to which the actions of the users must be logged and must be auditable. Depending on the circumstances, a full log of all activities may be necessary, while in other cases, logging only exceptions may suffice. Furthermore, it is important to note that different parties, both internal (company policy) and external (e.g. legislation, partners), may impose audit requirements.
Security involves ensuring the protection of integration flows and APIs. Key aspects include authentication (OpenID Connect) and authorization (OAuth2), as well as traffic management.
Data security, including compliance with GDPR, refers to determining which data can be shared with whom and how it should be shared. In some cases, obtaining written approval from the individuals concerned may be necessary, while in other cases, a simple notice may suffice. Additionally, it is critical to consider the manner in which data will be shared. For instance, it may be necessary to use encryption when transmitting data to ensure that it is not readable during transmission, thus safeguarding it in the event of interception.
Degradation of service
Degradation of service occurs when certain components required for integration flows are unavailable. For instance, if the API gateway is functional but the backend application utilized to implement the API is not available, it can cause issues. Typically, an HTTP status code of 500 (internal server error) is sent when working with an API, but there are other potential solutions. One approach is to use internal asynchronous decoupling, enabling the API gateway to handle messages even when the backend application is unavailable.
It is essential to gather information on non-functional requirements from all relevant stakeholders involved in a project. When obtaining information, those who will be strongly affected by the decisions taken need to be considered. These are not always the most influential stakeholders, but might be those who have less influence.
To ensure that the most affected stakeholders are included, the Stakeholder Rainbow technique can be used. This method involves classifying stakeholders according to the extent to which they can be affected by a problem or action. When obtaining non-functional requirements, representation in the different areas is necessary, and those most affected must be involved.
Another technique that can be used to ensure comprehensive coverage of all non-functional requirements (NFRs) and stakeholders is the Stakeholder Matrix. This tool provides a structured overview of the NFR categories that require information gathering and the relevant stakeholders that should be involved. This approach offers a clear overview of the link between the different stakeholders and NFRs, which enables identification of any potential gaps in NFR coverage.
When gathering requirements for a project, it is vital not to overlook the non-functional requirements (NFRs) necessary for building a successful solution, as they may not arise spontaneously.
Basing NFR elicitation on categories can help avoid missing essential NFRs. An effective tool to ensure the identification of all critical NFRs is an NFR category mind map. Additionally, it is crucial to involve all relevant stakeholders in elicitation. The use of a stakeholder rainbow or stakeholder matrix can facilitate the inclusion of all necessary stakeholders.
Do you need help obtaining and documenting non-functional requirements to make your integrations work? Feel free to contact us!