Checklist for vendor evaluation of mobile integrations

Checklist for vendor evaluation of mobile integrations

When evaluating vendors for mobile integrations with legacy systems, it is crucial to focus on documentation and maintainability. This helps ensure a sustainable and manageable integration.

• Ensure detailed documentation of data flows and audit trails in accordance with ISO standards.
• Ask for integration decisions to be recorded in machine-readable ADRs.
• Evaluate whether the vendor provides an operational runbook with emergency procedures.
• Assess the vendor's experience with integration patterns such as BFF and ACL.

Why documentation and maintainability are essential for mobile integrations

In a mobile integration with a legacy system, the maintenance question does not rest solely with the mobile application. The connection also affects existing data, processes, and the way incidents are investigated and resolved. Documentation serves as the integration's practical memory: it makes visible which data is available, what terms and fields mean, and which actions are needed when the connection no longer works as expected.

Current data dictionaries and operational runbooks have a direct operational effect. When these are missing or outdated, the time required to resolve an incident can increase from minutes to hours or days. As a result, operational end users lose productive time. The problem is not solely that information is missing; the route to recovery is also unclear. During an incident, a management team must then determine again which data is involved, where the cause may lie, and which recovery action fits within the existing environment. A runbook records precisely the control steps, checks, and recovery procedures needed in such a situation.

In this context, maintainability means that an integration remains transferable when the original vendor, developers, or project members are not immediately available. Documentation makes the connection traceable for an internal management organisation rather than dependent on verbal knowledge. This limits the handover burden and makes maintenance less dependent on assumptions about the original decisions.

For transactional mobile environments in which a great deal of data is written and offline synchronisation takes place, the documentation must be even more specific. Formal descriptions of statuses and detailed rules for resolving conflicts are then needed to preserve data integrity in the legacy database. Without this documentation, it remains unclear how two differing versions of the same data are handled when a mobile device reconnects.

Vendor evaluation therefore goes beyond the question of whether a mobile interface can be delivered. The relevant question is whether the vendor documents the operation, data meaning, and recovery method in such a way that your organisation can manage the integration after delivery as well.

Sources for this section: nen.nl

Risks of insufficient documentation in mobile integrations

Insufficient documentation in a mobile integration often arises not because nothing has been recorded at all, but because the documentation does not answer the questions that arise later during change, handover, or management. For example, a description of an interface without the rationale behind a design decision leaves unexplained why data was transformed, why a particular authentication change was implemented, or which alternatives were rejected. Especially in a legacy context, such choices cannot be assessed in isolation.

Machine-readable Architecture Decision Records, or ADRs, record this rationale in a structured way. They document the motivation for interface decisions, changes in data payloads, and changes in authentication. This records not only the current technical form, but also the reasoning that led to that form. For an internal management organisation, this makes a handover more verifiable: it does not have to ask the original vendor solely what was decided at the time, but can find the decision-making in a usable format.

The second layer concerns the contract between the mobile application and the integration. API specifications should be documented according to OpenAPI Specification 3.1.0 and the GDS API Standards. This documentation includes error handling in accordance with RFC 7807 and complete validation rules for data payloads. This distinction is relevant: an API description that only shows the names of operations still leaves open which data is valid and how an error is returned. Complete validation rules and a documented error format limit this ambiguity.

The risks of inadequate documentation therefore lie in two different gaps. Without ADRs, the historical and architectural explanation of changes is missing. Without a detailed API specification, a precise, verifiable picture of the interface and its validation behaviour is missing. Both gaps can put the transferability of the integration under pressure, but they require a different assessment during vendor selection.

Therefore, do not only ask a vendor whether documentation will be available, but distinguish which decisions will be recorded in ADRs and which interface agreements will be included in the API specification. This makes documentation verifiable as a delivery outcome, rather than a general commitment.

Sources for this section: nen.nl, www.gov.uk

Essential documentation checks for mobile integrations

Documentation is only useful when its content aligns with the actual integration and when the receiving organisation can assess the content. Vendor validation should therefore not consist solely of an assessment at the end of a project. The handover can be arranged as a continuous part of the collaboration, with moments when documentation is explained, discussed, and tested for usefulness in internal management.

A concrete contractual indication of this is the inclusion of ongoing handover workshops. This gives knowledge transfer a recognisable place in the assignment, rather than making it an activity addressed only once delivery has already been planned. The workshops provide room to review documentation with the involved teams and to revisit questions about management, security, and architecture while the work is still being developed.

The active involvement of internal security and architecture teams during the Definition of Done forms a second verification. These teams are not merely recipients of documents; their involvement makes it possible to assess whether the described solution aligns with internal requirements and the existing environment. Through their participation in completion criteria, it becomes clearer when a component is genuinely transferable. A document that is technically available but has not been reviewed by the relevant internal disciplines provides less assurance of its practical usefulness.

For a closed third-party legacy package, the integration pattern also deserves explicit documentation. In that situation, a mobile integration partner can document non-invasive patterns, such as Change Data Capture or webhook emulation. The value of this verification does not lie in prescribing a single pattern, but in making the chosen approach and its boundaries visible within a system that cannot be freely modified.

A useful assessment question is therefore: does the assignment specify when the handover takes place, who from security and architecture participates in the assessment, and how the chosen approach for a closed legacy package is described? If these three points do not have a concrete place in advance, maintainability remains highly dependent on the vendor's explanations afterwards.

Sources for this section: nen.nl

Checklist for assessing vendors on documentation and maintainability

Use this check as an additional selection requirement when the mobile integration falls under a strict enterprise compliance and privacy regime, such as in healthcare or finance. Do not allow the vendor to settle for a general statement about documentation; ask which documentation will be delivered during the assignment, how it will be assessed, and whether the content demonstrably aligns with ISO/IEC 25010 and ISO/IEC/IEEE 42010. The check focuses on documented data flows, pseudonymisation, and audit trails; it therefore assesses the documentation of the integration itself, not just the mobile front end.

• Check for demonstrable documentation of data and verifiability. Ask whether the vendor documents the data flows of the mobile integration, including the complete route of data through the connection. Have them explicitly state how end-to-end pseudonymisation is documented and which audit-trail mechanisms are described. In environments with strict compliance and privacy requirements, this documentation should be demonstrable and related to ISO/IEC 25010 and ISO/IEC/IEEE 42010. Assess not only whether documents exist, but also whether they are sufficiently concrete to determine which data flow, pseudonymisation step, and audit trail belong to the integration. A vendor that can demonstrate this makes the documentation verifiable within the requirements of the relevant environment.

Sources for this section: www.gov.uk

Avoiding mistakes when skipping documentation checks

A recognisable risk in vendor selection is that delivery is equated with a change in source code. This overlooks the question of whether the internal IT team can subsequently manage the mobile integration operationally. Documentation checks should therefore assess whether management knowledge is genuinely available as a delivery outcome, not merely whether a technical change has been implemented.

• Recognise runbook illiteracy as an exclusion signal. This pattern arises when a vendor considers the assignment complete as soon as a Git commit has been made, without handing over tested operational management documentation, incident matrices, or recovery procedures to the IT team. The result is not a shortage of source code, but a shortage of usable information for the team that must handle incidents and management work. During the assessment, therefore determine whether operational documents form part of the delivery, whether their content has been tested for usefulness, and whether incident scenarios and recovery procedures are explicitly handed over to the IT team. A vendor that does not include this handover in the delivery leaves a boundary between development and management unresolved, which will later become visible in operational work.

Sources for this section: nen.nl

Frequently asked questions about documentation and maintainability

A common question in a vendor evaluation is whether extensive documentation can already be fully committed to in advance. Another question is how internal IT and security teams can assess the credibility of a proposal before the actual legacy environment has been examined in depth. Both questions concern the same uncertainty: documentation can only become precise once the actual data payloads and technical situation are known.

• Why is a vendor that does not want to provide a fixed price without technical exploration a relevant signal? When a vendor refuses a fixed-price delivery without prior technical discovery and payload inspection of the actual legacy systems, it acknowledges that the scope of the integration depends on concrete technical information. This is relevant to documentation and maintainability because the content of the documentation must align with the actual systems and data payloads, not with assumptions from an initial request. For internal IT and security teams, this provides a practical validation point: they can check whether technical discovery and inspection of the actual data payloads have been identified as prior activities, and whether the vendor makes the pricing and delivery agreement dependent on them. A proposal that already presents a fixed delivery price without this exploration reveals less about how the vendor handles unknown characteristics of the existing environment. The question is therefore not whether a fixed price is undesirable in itself, but whether it is only discussed after the relevant technical foundation has been investigated.

Sources for this section: nen.nl

Key decision rules for vendor selection

Make the vendor choice dependent on evidence that can be assessed before the assignment begins. A vendor does not need to have the documentation for your future integration ready in advance, but can show what documentation looks like in comparable deliveries. This shifts the assessment from a promise about maintainability to visible artefacts and a verifiable way of working.

• Proactively ask for anonymised examples and assess their coherence. An appropriate selection signal is that the vendor voluntarily provides anonymised examples of previous Architecture Decision Records, OpenAPI contracts, and operational incident runbooks. These three types of evidence each serve a different purpose. ADRs show that architectural decisions and their rationale are documented. OpenAPI contracts show how interface agreements are documented. Operational incident runbooks demonstrate that management and incident handling are treated as delivery components. Assess the examples not as generic marketing material, but as an indication of whether the vendor can consistently produce and hand over these artefacts. If one of these forms is consistently missing, part of the maintenance chain remains invisible: the rationale for decisions, the contractual interface agreements, or the operational response. This may later require additional effort in management, change, or incident handling, thereby causing operational costs.

Sources for this section: www.gov.uk