API Migration Guide: Rollout Question Update

Overview

This document outlines the changes to the rollout question field and provides guidance for API clients to migrate from the old version to the new one.

Summary of Changes

The rollout question has been completely redesigned to follow Technology Readiness Levels (TRL) instead of the previous product stage definitions.

Question Label Change

Old: "How would you define the stage of the product/service roll-out?"
New: "What is the state of readiness of the product/service?"

Value Mapping Changes

The rollout field now supports 10 types instead of 4, with the following migration path:

Old Value	Old Description	New Value	New Description
type1	Planning: the roll-out process has still to begin	type2	Technology/process concept formulated
type2	Prototype: we have the first version of the product (alpha or beta) for testing/display purposes	type6	Technology/process demonstrated in relevant environment
type3	MVP: We have a minimum viable product released on the market	type7	Prototype demonstration in operational environment
type4	Market: the complete version of the product is offered to the market	type9	Actual system proven in operational environment

New Available Values

The complete list of new rollout values:

type1: Basic principles observed
type2: Technology/process concept formulated
type3: Experimental proof of concept
type4: Technology/process validated in lab
type5: Technology/process validated in relevant environment
type6: Technology/process demonstrated in relevant environment
type7: Prototype demonstration in operational environment
type8: System complete and qualified
type9: Actual system proven in operational environment
type10: No special technology or process needed to serve clients

Affected API Endpoints

1. Get Company Questionnaire

GET /api/v3/companies/{cid}/questionnaires

Response Change: The rollout field in the response will now return one of the new type values (type1-type10).

2. Update Company Questionnaire

POST /api/v3/companies/{cid}/questionnaires

Request Change: When sending the rollout field, you must use one of the new type values (type1-type10).

Example Request Body:

{
  "rollout": "type7",
  // ... other questionnaire fields
}

Migration Steps for API Clients

1. Update Value Mappings

If your application stores or displays rollout values, update your mappings:

// Old mapping
const oldRolloutLabels = {
  'type1': 'Planning',
  'type2': 'Prototype',
  'type3': 'MVP',
  'type4': 'Market'
};

// New mapping
const newRolloutLabels = {
  'type1': 'Basic principles',
  'type2': 'Concept formulated',
  'type3': 'Proof of concept',
  'type4': 'Lab validated',
  'type5': 'Validated in environment',
  'type6': 'Demonstrated in environment',
  'type7': 'Prototype in operation',
  'type8': 'System qualified',
  'type9': 'System proven',
  'type10': 'No special tech needed'
};

2. Handle Existing Data

For existing companies in your system:

Companies previously at type1 are now at type2
Companies previously at type2 are now at type6
Companies previously at type3 are now at type7
Companies previously at type4 are now at type9

3. Update UI Elements

If you have forms or displays showing rollout options:

Update the question label
Add the new options (type1, type3, type4, type5, type8, type10)
Update the descriptions for all options

4. Validation Updates

The API now accepts values from type1 to type10. Ensure your validation rules accept all these values.

Backward Compatibility

Important: The old values (type1-type4) are no longer valid. The database has been migrated, and the API will only accept and return the new values.

Timeline

Testing Environment (Obiwan): Available from Monday, June 23, 2025 at 15:00 CET (Rotterdam time)
Production Deployment: Wednesday, June 25, 2025 at 15:00 CET (Rotterdam time)
Action Required: Clients should test their integrations in Obiwan before the production deployment
Migration Window: Clients have until Wednesday, June 25, 2025 at 15:00 CET to prepare for the changes

Support

For questions or issues related to this migration, please contact the Equidam API support team.
No newline at end of file