Functional Specification for an Integration or Modification (IDK-11)
Template IDK-11, version 1.0. Phase: Establish Solution.
How to use this template
Use one specification per integration or modification in the CRIM log (template IDK-10). Configurations and reports use template IDK-12 instead.
Do not start this document until the CRIM log shows the decision "Approved for specification". Do not start development until sections 13 and 14 are signed.
Write sections 1 to 4 in business language so the process owner can approve them. Sections 5 to 9 may be technical.
Section 11 is not optional. An integration or modification without a stated update impact will surprise someone at the first release update.
Keep this document current after go-live. Support receives the latest version at handover, together with the test scenarios in section 10.
Replace every [...] field. Delete the rows marked Example: before approval.
Template metadata
Field
Value
Template ID
IDK-11
Phase
Establish Solution
Owner
Application consultant, with the technical solution manager
Approver
Customer process owner and customer project manager, commercial approval by both project managers, steering group authorisation
Qualification gate
Solution Established
Version
1.0
Document control
Field
Value
Project
[Project name]
CRIM log ID
[ID]
Type
[Integration / Modification]
Interface register ID (integrations)
[ID]
Solution area and process
[Area, process, link to process model]
Author
[Name, role]
Technical designer
[Name]
Status
[Draft / In review / Approved / Revised]
Storage location
[Link]
Version
Date
Author
Change
Approved by
0.1
[YYYY-MM-DD]
[Name]
First draft
[x.y]
[YYYY-MM-DD]
[Name]
[Change]
[Name]
1. Business need
State the need, not the solution. Name who has the need and what happens to the business if it is not met.
Item
Description
Need
Example: Buyers must see supplier order confirmations in IFS Cloud without keying them in, so that late or changed dates are visible on the day the supplier reports them
Who has the need
Example: Buyers at all sites, purchasing manager
Consequence if not met
Example: Confirmed dates stay in e-mail, planning runs on wanted dates, late deliveries are found at the dock
Book of Rules reference
[Document, decision ID]
Benefit the sponsor expects
[Text, link to business case item if any]
2. Process context
Item
Description
Process and step affected
[Process, step in the process model]
Roles affected
[Business roles]
Sites and companies in scope
[List]
Upstream dependency
[What must have happened before]
Downstream effect
[What uses the result]
Other CRIM objects related
[IDs]
3. Current standard behaviour
Describe what standard IFS Cloud does today for this step. Verify it in the project environment before writing. Do not describe it from memory or from a previous version.
Item
Description
Standard functionality reviewed
Example: Manual entry of confirmed date and quantity on the purchase order line. Standard inbound message handling for order confirmations through IFS Connect.
Environment and version where it was verified
[Environment name, release and service update level]
Shown to
[Names, date]
Why standard is not sufficient
Example: The supplier portal cannot produce the standard message format, and manual entry does not scale with the number of lines
Standard alternatives rejected, with reason
[Alternative, reason]
4. Required behaviour
Number each requirement. Each one must be testable and must map to at least one scenario in section 10.
Req ID
Requirement
Priority
Source
Example: R1
When the supplier portal reports a confirmation, the matching purchase order line shows the confirmed delivery date and quantity
Must
Book of Rules PUR-D07
Example: R2
A confirmation that does not match an open line is not applied. It is listed for the buyer with the reason.
Must
Workshop [YYYY-MM-DD]
[ID]
[Requirement]
[Must / Should / Could]
[Source]
Out of scope for this specification: [list explicitly].
5. Functional design
5.1 Overview
[Short narrative of the solution, with a flow diagram or link. State where each part runs: inside IFS Cloud, in middleware, in the other system.]
5.2 Design steps
Step
Actor or component
Action
Result
Example: 1
Supplier portal
Publishes a confirmation with order number, line, release, date and quantity
Message available to the integration layer
Example: 2
Integration layer
Looks up the purchase order line through the projection, checks status and open quantity
Line found, or error per section 8
Example: 3
Integration layer
Calls the standard action that confirms the line
Standard business logic validates and updates the line
[n]
[Actor]
[Action]
[Result]
5.3 User-visible changes
Page or lobby
Change
Roles that see it
[Page]
[Change, or "none"]
[Roles]
5.4 Design principles applied
Updates go through standard projections and their business logic. No direct database writes.
Prefer configuration and published interfaces over changed application code. State the tailoring level from the CRIM log: [Interface extension / Modification].
[Project-specific principle]
6. Data and projections used
Confirm projection, entity set and action names in the API Explorer of the project environment. Names below are placeholders until verified.
Projection
Entity set or action
Operation
Fields read or written
Verified in environment, date
Example: [Purchase order handling projection]
[Purchase order line entity set]
Read
Order number, line, release, status, wanted date, open quantity
[Environment], [YYYY-MM-DD]
Example: [Purchase order handling projection]
[Confirm line action]
Write
Confirmed date, confirmed quantity
[Environment], [YYYY-MM-DD]
[Projection]
[Entity set / action]
[Read / Write]
[Fields]
[Verified]
Field mapping:
Source field
Target field
Transformation or rule
Mandatory
[Field]
[Field]
[Rule]
[Yes / No]
Custom fields, custom entities or configuration needed by this design: [list with CRIM IDs, or "none"].
7. Security
Item
Description
Integration account
[Account name. One account per integration, never a named person.]
Authentication method
[For example OAuth client credentials through the IFS identity provider]
Permission set
[Name. Grants only the projections and actions in section 6.]
Read-only or write
[Read-only / Write. Write access needs the steering group authorisation recorded in section 13.]
Credentials custodian
[Role that stores and rotates the secret]
Rotation and revocation
[How the secret is rotated, how access is removed at decommissioning]
Personal or sensitive data carried
[None / description, with the privacy owner's approval reference]
Network path
[Source, target, ports, encryption in transit]
Logging
[What is logged, where, retention, confirmation that logs hold keys only and no business content if required]
8. Error handling
Error ID
Situation
Detection
System response
Who is notified and how
Recovery
Example: E1
Order line not found or already closed
Lookup returns no open line
Message parked with reason, nothing updated
Buyer, through [lobby element / e-mail event]
Buyer corrects reference in the portal, message is reprocessed
Example: E2
IFS Cloud not reachable
Call fails or times out
Retry [agree in project] times, then park
Integration owner, through monitoring alert
Automatic reprocessing when the connection returns
[ID]
[Situation]
[Detection]
[Response]
[Notification]
[Recovery]
Rules: no message is lost silently, no message is applied twice, and every parked message has an owner.
9. Volumes and performance
Fill in with figures from the business. Do not estimate them in the project team.
Measure
Value
Source of the figure
Transactions per day, normal
[agree in project]
[Name, role]
Transactions per day, peak
[agree in project]
[Name, role]
Largest single message or file
[agree in project]
[Name, role]
Required processing time
[agree in project]
[Name, role]
Operating window
[agree in project]
[Name, role]
Growth expected
[agree in project]
[Name, role]
Volume test required before SAT: [Yes / No, reference to test plan].
10. Test scenarios
Cover the common flow first, then normal exceptions, then specific exceptions. These scenarios become the test specification handed to support.
Test ID
Covers
Class
Preconditions and data
Steps
Expected result
Result, tester, date
Example: T1
R1
Common
Released purchase order with one open line
Publish a confirmation for the full quantity with a date later than wanted
Line shows confirmed date and quantity. Order history shows the change. No error parked.
[Pass / Fail], [Name], [YYYY-MM-DD]
Example: T2
R2, E1
Normal exception
Purchase order line already closed
Publish a confirmation for that line
Nothing updated. Message parked with reason. Buyer sees it in [place].
[ID]
[Req IDs]
[Common / Normal exception / Specific exception]
[Data]
[Steps]
[Expected]
Test environments: unit test in [environment], integration test in [environment], included in SAT script [ID]. Tests run with the real integration account and permission set, not with an administrator account.
11. Update impact
Item
Description
Tailoring level
[Interface extension / Modification, from the CRIM log]
Delivered objects touched
[Projections, entities, pages, code modules]
What must be re-verified at each release update
Example: Names and signatures of the entity sets and actions in section 6, behaviour of the confirm action, permission set grants, scenarios T1 and T2
What must be checked at each service update
[Usually a smoke test of scenario T1, state it]
Rebuild or uplift needed at release update
[No for Interface extension / Yes for Modification, with estimated effort [agree in project]]
Owner of re-verification
[Customer role after go-live]
Exit condition
[Under what circumstances this object can be retired, for example when standard covers the need]
12. Deployment and handover
Item
Description
Delivery route
[Build Place to Use Place environments for code, configuration packages for configuration, deployment of external components]
Cutover steps needed
[Entries to add to the cutover plan]
Monitoring after go-live
[What is monitored, by whom]
Support owner
[Role]
Handover content
This specification, the test scenarios in section 10, the interface register row, credentials custodian details
13. Estimate and commercial approval
Development does not start before this section is complete.
Item
Value
Estimate for specification, build, test, documentation
[agree in project]
Estimate for recurring update effort
[agree in project]
Assumptions and exclusions
[Text]
Change request reference
[ID]
Steering group authorisation
[Meeting date, minute reference]
Role
Name
Decision
Date
Signature
Supplier project manager
[Name]
[Approved / Rejected]
[YYYY-MM-DD]
Customer project manager
[Name]
Customer sponsor (if required by the contract)
[Name]
14. Approval
By approving, the customer confirms that sections 1 to 4 describe the need and the required behaviour correctly, that the test scenarios in section 10 are the basis for acceptance, and that the update impact in section 11 is understood.