Project Delivery Process D602

D602 - Finalise interface design

DEFINITION

Finalise the design of the extraction, validation, translation, summarisation, control and input systems for data interfaces.

SUMMARY

The purpose of this activity is to:

• specify the function and processing characteristics of an interface to another application (either internal or external),
• define the physical media and data content format,
• document responsibility and operating procedures governing the interface.

Interfaces will have been defined in principle during the earlier requirements and conceptual design work (processes R110 and D160).  The needs may have been detailed further during associated elements in the functional design work during Process D400.

From these details, the full detail of each interface is examined in terms of the requirements, options, agreed approach and detail of the design.  The results are published in a Technical IP - one per interface.

Key elements of this process are to:

• identify and resolve remaining issues regarding the function or operation of the interface,
• provide technical and functional information needed by programmers to develop software implementing the interface.

This process is a specific variant of Process D600 - “Create detailed specifications for non-Application Software Implementation IT development work” which may be read for further general information.

PATH PLANNING GUIDANCE

This process is optional.  It is used where data will be extracted, converted or input by automated methods to or from other computer systems.

DEPENDENCIES

Prerequisites (Finish-Start):

• Integration & Interface Review (R110)

Prerequisites (Finish-Finish):

• Consider, review and plan approach to integration (D160)

Dependent procedures (Finish-Finish):

• Instigate non-Application Software Implementation parallel tasks (D650) - where programming work will be outside the scope of the project team
• Modify existing non application software (D656) - for components of the work not using Application Software facilities
• Modify package software (D658) - for components of the work using Application Software facilities

Dependent procedures (Finish-Start):

• Build of corresponding programs / modules etc

RECEIVABLES

• Definition of Requirements (DoR)
• Delivery Approach Definition (DAD) or similar definition of conceptual design
• Integration Issues IP
• documentation for the other application(s) involved
• site standards and procedures
• physical data model

DELIVERABLES

• Interface Design - Technical Implementation Paper per interface

TOOLS

• Application Development Standards - Coding Standards
• Application Development Standards - Naming Standards
• Application Development Standards - File Definition Standards
• Skeleton Implementation Paper
• Guidelines: “Modelling Techniques”
• Guidelines: “Custom Development”
• IP Guidelines: “IP-Data Conversion”
• IP Guidelines: “IP-Database”
• IP Guidelines: “IP-Languages”
• IP Guidelines: “IP-Handover”
• IP Guidelines: “SIIPS 2 Feeder systems”
• Examples: “Interfaces and output files worksheet”
• Examples: “Conversion Worksheet”
• Examples: “Contingency Plan”
• Guidelines: “SAP development workbench” (to be written)

DETAILED DESCRIPTION OF TASKS

Requirements

The requirements for the interface may be found in the earlier requirements work (eg Integration & Interface Review - Process R110), conceptual design, or areas of specific functional design during the design/prototyping processes - see Process D400.  These needs should be confirmed and reviewed as appropriate to ensure that the final details are frozen for the build processes.  Note that prototyping work is often continuing at this time, so it can be important to check that the interface requirements are stable before finalising the design.

Options

Full options should be considered, for example:

• custom built programs
• use of package facilities
• use of interfacing tools
• use of manual re-entry.

Consider and report on the relative merits of these approaches, particularly in terms of costs, benefits, lead times, resource requirements, quality and risk.

Recommendation

Agree the preferred course of action for each interface with the responsible managers in the client organisation (and/or external bodies where appropriate).

Finalise Interface Design

The purpose of this activity is to specify the function and processing characteristics of the interface.  The detail should define the processing rules, extraction criteria, translation requirements, summarisation rules, controls, physical media and data content format.

Interfaces can be implemented in several ways in the Application Software package:

• batch input processing (BDC), in which case sequential datasets would be read into transactions and dynpros or written to an external file,
• CPI-C or RFC
• PC upload or download,
• Application Link Enabling (ALE),
• hard coded writing into the database

The design of each interface would depend on the chosen method of interfacing. Each interface needs  a detailed description, based on the chosen method:

• the data fields to be interfaced, their source, format, and medium,
• any conversion or translation routines (eg rules for summarising accounts or translation of customer ID codes)
• volume and periodicity of the interface,
• the destination of the data and any plausibility checks to be performed,
• how to handle error situations if the interface fails,
• control routines to be performed to ensure that all data has been transported correctly into the destination system,
• the processing rules for the interface.

Clear documentation of responsibilities and operating procedures governing the interface should be provided including the following information:

• Module Name and Reference ID
• Business Process Reference ID
• Other application systems affected
• Type (database, transaction, batch file, etc.)
• Device (file, program-program, POS, etc.)
• Source
• Purpose
• Frequency
• Data elements
• Grouping (sort sequence)
• Control report format and content
• Record

This information should be provided for each individual interface.  There should be sufficient detail in the technical interface specifications and graphical layout to provide effective technical reference for the programmer.

The Technical Implementation Paper

The key deliverable from this process is normally a technical Implementation Paper (or Brief Implementation Paper).

The objectives of an Implementation Paper are:

• to assist key management and team members to understand and agree upon the business requirements for the topic,
• to explore all options to address the business requirement (including procedural, process redesign, non-automated solutions),
• to indicate the preferred solution and to identify why that recommendation is being made such that key management and team members will understand and accept the recommendation,
• to define how the recommendation will be implemented in sufficient detail that no further design decisions will need to be taken (ie no further consultation, agreement or sign off is required),
• to highlight any unresolved issues which may affect the various details, recommendations and decisions presented in the paper - such outstanding issues should normally be resolved before the paper is finalised.

The use and format of an Implementation Paper is considered in detail in the Process D400 - Design / Prototype.  The comments in D400 apply equally to Technical Implementation Papers, and should be read in conjunction with this Process.  Alternatively, if a brief approach has been agreed and is appropriate, the Brief Implementation Paper approach can be used instead- see Process D450.

In addition to the generic comments about Implementation Papers, the following additional comments apply to Technical Implementation Papers:

• Detailed requirements should still address business needs, but are more likely to contain technical information where the technical detail is a genuine requirement, for example the precise data format required for an automated input to a package.  Accordingly, it is normal to see a wider range of techniques used to record such needs and some very detailed low-level information.  For example, technical papers often contain:
• data dictionary entries, record layouts, data models, database definitions etc
• system specification documentation for other systems involved
• details of any special techniques or approaches required to exploit the coherence of the overall technical solution, eg using the package’s built-in database, data dictionary or 4GL tools
• detailed translation tables to convert from old data to new
• validation rules and tables
• details of timing, size, performance requirements
• backup, recovery
• details of standard automated controls and standard clerical procedures required to control the programming suites.
• Options will vary considerably and normally include full automation and full manual treatment of the requirements.
• Full systems integration is increasingly becoming a user demand, and the techniques to achieve it are constantly improving.  This evolution tends to add greatly to the complexity of the most-functional options.  Full integration cannot normally be achieved unless it was planned and designed into all the systems involved.  Very often, the Implementation Paper will need to convince the management that full integration is too costly in terms of time, effort and money.
• The option may sometimes include whether to accept the package’s functionality or whether to undertake modifications to the package itself.
• Options may include options as to who does the work, eg should it be subcontracted out to the vendor.
• Given that custom programming can often be expensive, time consuming and high-risk, very serious consideration must be given to evaluating the options and forming a recommendation.
• The options frequently cross system and organisational boundaries and imply work on other computer systems affecting other IT teams and user departments - these issues must be included in the considerations, particularly any lead time or availability constraints.
• Existing computer systems are often badly understood and poorly documented.  Substantial work may be necessary to evaluate work required unless there is an effective existing system maintenance function covering the area.  Always check the facts carefully.
• The detailed instructions will often be very technical in nature.  They should give enough detail so that further research and agreement is not necessary.
• Large tables of facts may be best presented as appendices, eg validation tables, conversion tables, record layouts etc

It is not necessary to provide a full detailed program design specification as this should be defined as part of the non-Application Software  work, performed in accordance with the agreed approach to custom development.  The program designer would normally take the Technical Implementation Paper as the statement of user requirements.