Draft changes planned for Change request redesign epic

This document details the V6 API changes planned to be implemented in Street Manager for the Change request redesign epic. THIS DOCUMENT IS A DRAFT PLAN, IMPLEMENTATION MAY RESULT IN CHANGES.

Change request endpoints

We will add a new set of Change request endpoints that will be similar to the current alteration endpoints with some differences in functionality. NOTE: these endpoints will also support the changes detailed in the Clash and collaboration management epic.

Audit events

New AuditEventTypes will be created to support the change request redesign, these will align with the current alteration events, for example

  1. alteration_submitted => change_request_submitted
  2. alteration_refused => change_request_refused
  3. alteration_granted => change_request_granted
  4. alteration_granted_with_duration_challenge => change_request_granted_with_duration_challenge
  5. alteration_deemed => change_request_deemed
  6. alteration_cancelled => change_request_cancelled
  7. alteration_applied_auto => change_request_applied_auto
  8. alteration_duration_challenge_accepted => change_request_duration_challenge_accepted
  9. alteration_duration_challenge_not_accepted => change_request_duration_challenge_not_accepted
  10. alteration_duration_challenge_non_acceptance_response => change_request_duration_challenge_non_acceptance_response
  11. alteration_revoked => change_request_revoked

AuditObjectTypes will remain unchanged and the change_request value will be reused for new change request as well as for the current alterations.

Permit change requests

Permit change requests allows promoters and HA users the ability to alter a permit once it’s been created. Not all properties of a permit are changeable and thus depending on what’s been changed and by who, the type of permit alterations are:

  1. Promoter change request: Promoter submitted change request after permit has been granted or in-progress.
  2. Promoter imposed change: Promoter submitted change request before permit has been granted or in response to a permit modification request.
  3. Work extension: Promoter submitted change request to alter the proposed end date on an in-progress work.
  4. HA imposed change: HA users impose changes to permit conditions after permit is granted or in-progress.
  5. HA change request: Currently in the road map for future release.
  6. Duration challenge: A work extension which has been challenged by the HA with a reasonable_period_end_date.

Creating a change request will return a changeRequestReferenceNumber which can be used to retrieve an individual alteration via the GET endpoint provided.

While HA imposed changes are applied to the permit automatically, promoter change requests need to be granted (or deemed) before the changes are applied to the target permit.

Create change request endpoint

POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests

Creates a permit change request. The request body can take all editable fields on the permit however only the ones that are changing should be provided, these changes will be ‘applied’ to the current permit version before validation to ensure the changes requested would not result in an invalid scenario for example if the traffic_management_type is changed and the emergency_contact_name is not already set then it will throw a validation error. When a promoter uses this endpoint, the change request will have an ChangeRequestType of PROMOTER_CHANGE_REQUEST in the case that they do not extend the end date of the permit while it in in progress, or WORK_EXTENSION in the case that they do. Once the change request is create it is required to be assessed by the associated HA. NOTE: This has significant differences from the current alteration endpoint - The new permit version will not be created when a change request is raised, it will instead be created when granted (or deemed) and the changes will be applied to the current permit version.

Impose change endpoint

POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests/impose

This endpoint allows HA users to impose changes to permit conditions. The ChangeRequestType in this case will be HA_IMPOSED_CHANGE. When an HA imposes a change that change is automatically applied to the permit. It will continue to have a status of Submitted but the permit will reflect the changes submitted.

Update change request status endpoint

PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests/{changeRequestReferenceNumber}/status

The sequence section shows how a change request can be assessed and actioned at various stages by promoters and highway authorities. This endpoint drives all of these functions. Work extensions or change request that have changed the reasonable period end date can be duration challenged by highway authorities.

NOTE: This has significant differences from the current alteration endpoint - The changes will be applied to the current permit version rather than the version that existed when the change request was raised. Once the permit has been assessed the current permit details will be recorded and its details become fixed.

Get change request endpoint

GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests/{changeRequestReferenceNumber}

This change request endpoint returns both the current and the proposed changes of a permit in addition to the reason for the change request, assessment information and other information relevant to the change request. NOTE: This has significant differences from the current alteration endpoint - This endpoint will return the current permit details which may change over time, the alteration endpoint returns the original permit details recorded at the point of alteration creation, which never changes. Once the permit has been assessed the current permit details will always return the version that existed at the point of assessment.

Duration challenge non acceptance

The PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests/{changeRequestReferenceNumber}/duration-challenge-review endpoint will allow the Planner to accept or not accept a duration challenge on a change request; if the Planner does not accept the duration challenge, a reason must be given. Relevant fields are returned in the PermitChangeRequestResponse.

The PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests/{changeRequestReferenceNumber}/duration-challenge-non-acceptance-response endpoint will allow the Highway Authority user to respond to a duration challenge review requested by a promoter. The Highway Authority can choose to update the reasonable period end date, or to keep the date as submitted when providing the original duration challenge details. Relevant fields are returned in the PermitChangeRequestResponse.