Draft changes planned for Clash and collaboration management epic

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

V6 API changes

POST Work/Permit/Alteration endpoints

New fields added to the requests to support Clash and collaboration management. Applies to POST /work, POST /works/{workReferenceNumber}/permits and POST /works/{workReferenceNumber/permits/{permitReferenceNumber}/alterations to support collaboration management that will be validated if the existing collaborative_working field is set to true.

Fields relating to collaboration management.

  1. is_primary_promoter?: null | boolean - Used to indicate if you are the Primary or Secondary promoter collaborating.
  2. collaboration_types?: null | CollaborationType[] - Uses the existing CollaborationType enum but now an array rather than a single value.
  3. primary_promoter_permit_reference_number?: null | string - If secondary promoter (is_primary_promoter = false) then this is used to link to the Primary promoter permit (if known) - NOTE: In V5 collaborative_works was used to provide the work reference number.
  4. collaboration_contact_name?: null | string - Contact info relating to the collaboration, it is required if either collaborative_working or is_primary_promoter is provided.
  5. collaboration_contact_email?: null | string - Contact info relating to the collaboration, it is required if either collaborative_working or is_primary_promoter is provided and collaboration_contact_phone_number is not provided.
  6. collaboration_contact_phone_number?: null | string - Contact info relating to the collaboration, it is required if either collaborative_working or is_primary_promoter is provided and collaboration_contact_email is not provided.
  7. estimated_number_of_network_days_saved?: null | number - Required if secondary promoter (is_primary_promoter = false).
  8. others_can_collaborate_on_work?: null | boolean - Can be used to indicate if the permit is available for collaboration.
  9. reason_for_non_collaboration?: null | string - Required if others_can_collaborate_on_work is false.
  10. can_collaborate_on_work_additional_details?: null | string - Required if others_can_collaborate_on_work is true.

We will also record if potential clashes exist on the USRN at the point of creation - See GET /potential-clashes endpoint.

GET /potential-clashes

New endpoint to check if there are other works on as specific USRN between the proposed dates. It accepts usrn, start_date and end_date as mandatory query params and returns an array of work_reference_number, start_date and end_date (limited to 25).

GET Work/Permit/Alteration endpoints

New fields added to the WorkResponse (active_permit), PermitResponse and PermitAlterationResponse (original and proposed) to support collaboration management.

Fields relating to collaboration management.

  1. is_primary_promoter?: null | boolean - Used to indicate if you are the Primary or Secondary promoter collaborating.
  2. collaboration_types?: null | CollaborationType[] - Uses the existing CollaborationType enum but now an array rather than a single value.
  3. primary_promoter_permit_reference_number?: null | string - If secondary promoter (is_primary_promoter = false) then this is used to link to the Primary promoter permit (if known) - NOTE: In V5 collaborative_works was used to provide the work reference number.
  4. collaboration_contact_name?: null | string - Contact info relating to the collaboration.
  5. collaboration_contact_email?: null | string - Contact info relating to the collaboration.
  6. collaboration_contact_phone_number?: null | string - Contact info relating to the collaboration.
  7. estimated_number_of_network_days_saved?: null | number - Required if secondary promoter (is_primary_promoter = false).
  8. others_can_collaborate_on_work?: null | boolean - Can be used to indicate if the permit is available for collaboration.
  9. reason_for_non_collaboration?: null | string - Required if others_can_collaborate_on_work is false.
  10. can_collaborate_on_work_additional_details?: null | string - Required if others_can_collaborate_on_work is true.

Fields relating to clash management.

  1. potential_clash_identified?: null | boolean - If there were clashes detected on the USRN - See GET /potential-clashes endpoint.

V5 API changes

No Changes to the V5 interfaces expected however it should allow the creation of a CR created in V6 without updated to new fields (should ignore) and the collaboration_type field will be populated with the highest value in the collaboration_types array.