openapi: 3.1.0
info:
  version: 1.0.0
  title: CityFibre - Partner Installation
  termsOfService: https://www.cityfibre.com
  contact:
    name: API Development Team
    email: service-api@cityfibre.com
    url: https://www.cityfibre.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: https://cdn.cityfibre.com/Interface/logo_blue.svg
  description: >
    # Introduction


    CityFibre has implemented an automated process to accommodate the dispatch
    of Job Packs related to the installation of FTTH/P services. This requires
    the Partner to follow the same process in terms of the integration points,
    message types and message payloads relayed between each party.

    The implementation is based on JSON over RPC and has a common definition for
    inbound and outbound calls.


    # FTTH/P Installation


    ## General Process Flows


    <h3> 
      Standard Installation Flow
    </h3>


    <figure align="center">
      <img alt="Standard Installation Flow" src="/Standard_Installation_Flow.png" />
      <figcaption style="font-size: 12px">Standard Installation Flow</figcaption>
    </figure>


    - CityFibre sends createJob for each job pack due. N.B. this can be at any
    point from when the Service Order was received to the day prior to
    installation.

    - Installation Partner responds with providerJobId

    - Installation Partner assigns the job to an engineer and sends notifyJob
    with Engineer Details

    - On the day of installation
      - Installation Partner sends notifyJob when the engineer has indicated that they are en-route to the installation with coordinates/time
      - Installation Partner sends notifyJob when the engineer has indicated that they are onsite with coordinates/time
      - Installation Partner sends notifyJob when the Engineer scans QR Code on the ONT, with the ONT FSAN and Serial Number
      - CityFibre sends notifyJob when ONT is provisioned
      - After additional install steps/tests, Installer sends back closeJob with question based closure and appropriate close and secondary close code with description

    # Installation Closure Codes and Description


    | Closure Codes |
    Description                                                             |

    | ------------- |
    ----------------------------------------------------------------------- |

    | SP            | Service
    Provided                                                        |

    | PSP           | Partial install, CPE Install
    failed                                     |

    | HAZ           | Site
    Unsafe                                                             |

    | RNA/NA        | No Access
    (Rectifiable)                                                 |

    | NAPUV         | No Access (Not
    Rectifiable)                                             |

    | ASQ           | Sales
    Query                                                             |

    | UNF           | Unforeseen Circumstance e.g. Tree Line of
    Sight                         |

    | MBORC         | Unable to Attend (Notice
    Given)                                         |

    | FTA           | Unable to Attend (No
    Notice)                                            |

    | CON           | Fault at Node (or between Toby and
    Node)                                |

    | POP           | Fault at POP (or between Node and
    POP)                                  |

    | ONT           | Fault at ONT or between Toby and
    ONT                                    |

    | CPR           | Fault at Pole (Cherry Picker
    required)                                  |

    | NTR           | No Truck
    Roll                                                           |

    | REVCOMP       |
    Success                                                                 |

    | REVCPR        | Fault at Pole (Cherry Picker
    Required)                                  |

    | REVASQ        | Sales
    Query                                                             |

    | REVHAZ        | Site
    Unsafe                                                             |

    | REVNA         | No
    Access                                                               |

    | REVUNF        | Unforeseen Circumstance e.g. Tree Line of
    Sight                         |

    | REVPOP        | Fault at POP (or between Node and
    POP)                                  |

    | REVCON        | Fault at Node (or between Toby and Node) Traditional build
    - CF Network |

    | REVONT        | Fault at ONT or between Toby and
    ONT                                    |

    | REVASS        | Additional
    Assistance                                                   |

    | EXTCOMP       |
    Success                                                                 |

    | EXTHAZ        | Site
    Unsafe                                                             |

    | EXTCON        | Fault at Node (or between Toby and
    Node)                                |

    | EXTPOP        | Fault at POP (or between Node and
    POP)                                  |

    | EXTASQ        | Sales
    Query                                                             |

    | CIVCOMP       | Civils
    Complete                                                         |

    | CIVCON        | Civils
    Restriction                                                      |

    | CIVNA         | No Access to
    Network                                                    |

    | CIVWAY        | Permission
    Refused                                                      |

    | CIVQUO        | Quote Not
    Approved                                                      |

    | Other reason  | Other codes sent, we will process as ‘Other
    reason’                     |


    # Installation Secondary Closure Codes and Description


    The codes and descriptions below should be included on the closeJob
    notification when closureCode is either CON or POP. The secondary closure
    code provides additional detail as to the closure reason.


    | Closure Code | Secondary Closure Code | Secondary Closure Code
    Description                           |

    | ------------ | ---------------------- |
    ------------------------------------------------------------ |

    | CON          | CON01                  | Incomplete
    Network                                           |

    | CON          | CON02                  | No Infrastructure
    present                                    |

    | CON          | CON03                  | Openreach D
    Pole                                             |

    | CON          | CON04                  | No Capacity at SN/ASN
    Available                              |

    | CON          | CON05                  | Toby Move
    required                                           |

    | CON          | CON06                  | Line of Sight
    issue                                          |

    | CON          | CON07                  | Blockage - Gel
    Wrap                                          |

    | CON          | CON08                  | Blockage - Lead In
    (Openreach)                               |

    | CON          | CON09                  | Unable to blow fibre between the
    Secondary Node cab and Toby |

    | POP          | POP01                  | No Light
    (SN/PN)                                             |

    | POP          | POP02                  | No Light
    (ASN)                                               |

    | POP          | POP03                  | Light reading out of scope (High
    or Low optical signal)      |

    | REVCPR       | REVCPR01               | Specialist Hoist
    Required                                    |

    | REVASQ       | REVASQ01               | Cancelled
    Already                                            |

    | REVASQ       | REVASQ02               | Changed My
    Mind                                              |

    | REVHAZ       | REVHAZ01               | Customer
    Behaviour                                           |

    | REVHAZ       | REVHAZ02               | Pet
    Behaviour                                                |

    | REVHAZ       | REVHAZ03               | Environment
    Unsuitable                                       |

    | REVNA        | REVNA01                | Customer Not
    In                                              |

    | REVNA        | REVNA02                | Customer
    Ill                                                 |

    | REVUNF       | REVUNF                 | Tree Line Of
    Sight                                           |

    | REVPOP       | REVPOP01               | No Light
    (SN/PN)                                             |

    | REVPOP       | REVPOP02               | No Light
    (ASN)                                               |

    | REVPOP       | REVPOP03               | Light reading out of scope (High
    or Low optical signal)      |

    | REVCON       | REVCON01               | Blockage - Gel
    Wrap                                          |

    | REVCON       | REVCON02               | Blockage - Lead In
    (Openreach)                               |

    | REVCON       | REVCON03               | Unable to blow fibre between the
    Secondary Node cab and Toby |

    | REVONT       | REVONT01               | ONT
    Issue                                                    |

    | EXTHAZ       | EXTHAZ01               | Customer
    Behaviour                                           |

    | EXTHAZ       | EXTHAZ02               | Pet
    Behaviour                                                |

    | EXTHAZ       | EXTHAZ03               | Environment
    Unsuitable                                       |

    | EXTHAZ       | EXTHAZ04               |
    Scaffolding                                                  |

    | EXTHAZ       | EXTHAZ05               |
    Asbestos                                                     |

    | EXTHAZ       | EXTHAZ06               | Traffic Management
    required                                  |

    | EXTHAZ       | EXTHAZ07               | Flat
    Roof                                                    |

    | EXTHAZ       | EXTHAZ08               | Confined Space - Safe working not
    achievable                 |

    | EXTCON       | EXTCON01               | Incomplete
    Network                                           |

    | EXTCON       | EXTCON02               | No Infrastructure
    present                                    |

    | EXTCON       | EXTCON03               | Openreach D
    Pole                                             |

    | EXTCON       | EXTCON04               | No Capacity at SN/ASN
    Available                              |

    | EXTCON       | EXTCON06               | Line of Sight
    issue                                          |

    | EXTCON       | EXTCON07               | Blockage - Gel
    Wrap                                          |

    | EXTCON       | EXTCON08               | Blockage - Lead In
    (Openreach)                               |

    | EXTCON       | EXTCON09               | Unable to blow fibre between the
    Secondary Node cab and Toby |

    | EXTCON       | EXTCON10               | Network Adjustment Required -
    Chamber (PIA)                  |

    | EXTCON       | EXTCON11               | Network Adjustment Required - Pole
    (PIA)                     |

    | EXTCON       | EXTCON12               | Fault between Mice Joint and
    Secondary node                  |

    | EXTCON       | EXTCON13               | Unable to blow fibre - Greater
    than 350m                     |

    | EXTCON       | EXTCON14               | Unable to Blow Fibre - Network
    Point to Pole                 |

    | EXTCON       | EXTCON15               | Electricity
    Pole                                             |

    | EXTCON       | EXTCON16               | Pole top Fixing Missing - Multi
    Span Route                   |

    | EXTCON       | EXTCON17               | Blockage - Box to Box (PIA
    Network)                          |

    | EXTCON       | EXTCON18               | Blockage - Box to Pole (PIA
    Network)                         |

    | EXTCON       | EXTCON19               | Splitter capacity - full -
    Additional splitter               |

    | EXTPOP       | EXTPOP01               | No Light
    (SN/PN)                                             |

    | EXTPOP       | EXTPOP02               | No Light
    (ASN)                                               |

    | EXTPOP       | EXTPOP03               | Light reading out of scope (High
    or Low optical signal)      |

    | EXTASQ       | EXTASQ02               | Never
    Ordered                                                |

    | EXTASQ       | EXTASQ07               | Cancelled
    Already                                            |

    | EXTASQ       | EXTASQ08               | Changed My
    Mind                                              |

    | EXTASQ       | EXTASQ09               | Refused Enablement
    Works                                     |

    | CIVCOMP      | CIVCOMP01              | Civils Complete - BFT
    Installed                              |

    | CIVCOMP      | CIVCOMP02              | Civils Complete - Splicing
    Required                          |

    | CIVCOMP      | CIVCOMP03              | Civils Complete - Customer
    Live                              |

    | CIVCOMP      | CIVCOMP04              | Civils Complete - Fibre
    Blown                                |

    | CIVCOMP      | CIVCOMP05              | Civils Complete - No Dry
    Install                             |

    | CIVCOMP      | CIVCOMP06              | No Civils Required - BFT
    Installed                           |

    | CIVCOMP      | CIVCOMP07              | No Civils Required - Splicing
    Required                       |

    | CIVCOMP      | CIVCOMP08              | No Civils Required - Customer
    Live                           |

    | CIVCOMP      | CIVCOMP09              | No Civils Required - Fibre
    Blown                             |

    | CIVCOMP      | CIVCOMP10              | No Civils Required - No Dry
    Install                          |

    | CIVCON       | CIVCON01               | Civils Restriction -
    Embargo                                 |

    | CIVCON       | CIVCON02               | Civils Restriction - Heritage /
    Listed Area                  |

    | CIVCON       | CIVCON03               | Civils Restriction - Local
    Authority                         |

    | CIVCON       | CIVCON04               | Civils Restriction - Third Party
    Works                       |

    | CIVCON       | CIVCON05               | Missing
    Network/Infrastructure                               |

    | CIVCON       | CIVCON06               | Permission
    Refused                                           |

    | CIVNA        | CIVNA01                | No Access to
    Network                                         |

    | CIVWAY       | CIVWAY                 | Permission Refused -
    Wayleave                                |

    | CIVQUO       | CIVQUO                 | Quote Not
    Approved                                           |


    # Installation Question Based Closure


    For further details please refer to separately provided Question Based
    Closure Matrix – which details the relationship between closure and
    secondary closure codes, question and answer definitions and question flow.


    ## Questions and Answers


    ```

    "questions_answers":
            [
                {
                    "question": "Did Sponge Pass?",
                    "question_code": "1100",
                    "answer": "Yes",
                    "response_received": "2018-01-02T09:32:33+00:00",
                    "source": "notifyJob"            },
    ```


    The question should match the text from the related question

    The question code should match the ID of the related question

    The answer should match the answer of the related question

    The source should match the point in the journey it was sent, either
    “notifyJob” or “closeJob”


    ## Photos


    ```

    "questions_answers": [
            {
                "question": "Time of first call Mandatory Photos of call log & Photos of door/house",
                "question_code": "4900",
                "answer": "07:56",
                "response_received": "2023-09-25T11:37:10.9362823+01:00",
                "source": "Closure",
                "files": [
                    {
                        "name": "example.jpg",
                        "url": "",
                        "object_path": "s3://URLcode.enta.cloud/example.jpg"
                    }
                ]
            },
    ```


    Files can optionally be included with each structured response, defined in
    an array. Each file listed should include the following details:


    - name

    - type

    - object_path

    - url (optional)
      The object_path parameter should be the full S3 endpoint including the filename.

    The url is an optional field which if included should be a url which can be
    used to retrieve the file using a standard http (GET) request. This may be a
    pre-signed URL generated from S3.

    </br><ins>Note</ins> that the S3 bucket will be shared with the Installation
    Partner by CityFibre in advance.


    # Property Flags


    | Property Flag Code |
    Description                                                                              
    |

    | ------------------ |
    -----------------------------------------------------------------------------------------
    |

    | CHP                | Cherrypicker
    needed                                                                      
    |

    | DAN                | Dangerous property
    location                                                               |

    | DTL                | Indicates that the length of the driveway to the
    premise is longer than the typical 10m   |

    | SUR                | Indicates 10 day lead time on install and that a
    survey is required prior to installation |

    | MDU                | Indicates premises is within a Multi Dwelling
    Unit                                        |

    | WSD                | indicates that the premises shares a drive with
    neighbouring premises                     |


    # ONT Provisioning


    | ID (non technical identifier) | Success |
    Details                                                                                                    
    | ONT Vendors     |
    Description                                                            |

    | ----------------------------- | ------- |
    -----------------------------------------------------------------------------------------------------------
    | --------------- |
    ---------------------------------------------------------------------- |

    | 1                             | True    | ONT Successfully
    Provisioned                                                                               
    | Nokia and Calix | Configuration has been successfully pushed to
    device                   |

    | 2                             | True    | ONT Install
    Successful                                                                                     
    | Nokia and Calix | Equivalent green light meaning successful
    install                      |

    | 3                             | False   | ONT Provision Failed. Contact
    Order
    Desk                                                                    |
    Nokia and Calix | Issue during provision that needs
    intervention                         |

    | 4                             | False   | Delay – Retrying in 5
    minutes                                                                              
    | Nokia and Calix | Provision will be reattempted in 5
    minutes                             |

    | 5                             | False   | ONT Provision Failed. Incorrect
    Device Type Used                                                           
    | Nokia and Calix | ONT Type used does not match the OLT
    type                              |

    | 6                             | False   | ONT Provision Failed. Incorrect
    provisioning details entered. FSAN or Serial Number incorrect              
    | Nokia and Calix | FSAN/Serial Number entered doesn’t match required
    format               |

    | 7                             | False   | ONT Provision Failed. Duplicate
    Device. Device has been scanned against existing open Installation Activity
    | Nokia and Calix | Device has already been used and is recognised against
    another service |


    # Integration sequence diagrams


    ## Before Installation


    <h3>
      Create Job
    </h3>


    <figure align="center">
      <img alt="Before_Installation_Create_Job" src="/Before_Installation_Create_Job.png" />
      <figcaption style="font-size: 12px">Before Installation Start Create Job</figcaption>
    </figure>


    <h3>
      Cancel Job
    </h3>


    <figure align="center">
      <img alt="Before_Installation_Start_Cancel_Job" src="/Before_Installation_Start_Cancel_Job.png" />
      <figcaption style="font-size: 12px">Before Installation Start Cancel Job</figcaption>
    </figure>


    ## Day of Installation


    <h3>
      Notify Job
    </h3>


    <figure align="center">
      <img alt="Day_of_Install_Notifications" src="/Day_of_Install_Notifications.png" />
      <figcaption style="font-size: 12px">During Installation Notifications</figcaption>
    </figure>


    # Authentication


    Authentication is by means of HTTPS client certificate. It is also
    restricted to pre-agreed source IP addresses.


    <SecurityDefinitions>

    </SecurityDefinitions>


    # Network Configuration


    Cityfibre provides two fixed-address API endpoints for redundancy:


    ```

        api-gw1.cityfibre.com 52.51.45.11 (IPv6: 2a05:d018:9a3:b500::100)

        api-gw2.cityfibre.com 52.58.75.78 (IPv6: 2a05:d014:b31:f200::100)
    ```


    Messages may be POSTed to either of these. For convenience there is also a
    round-robin DNS entry:

    api-gw.cityfibre.com (resolves to both addresses)


    Required firewall configuration is as follows.


    The CityFibre endpoint is:
    [https://api-gw.cityfibre.com:41223/prod/ftth-installer](https://api-gw.cityfibre.com:41223/prod/ftth-installer)
servers:
  - url: https://api-gw.cityfibre.com:41223/prod/api2
    description: Main (production) server
  - url: https://api-gw.cityfibre.com:41223/cfstaging/api2
    description: CFStaging server
  - url: https://api-gw.cityfibre.com:41223/cfsit/api2
    description: CFSit server
x-tagGroups:
  - name: API
    tags:
      - Notify
      - Close
  - name: Webhooks
    tags:
      - Installation
paths:
  /notifyJob:
    post:
      summary: Notify job
      description: |
        notifications related to a job.
      operationId: notifyJob
      tags:
        - Notify
      security:
        - Certificate: []
      requestBody:
        $ref: '#/components/requestBodies/notifyJob'
      responses:
        '200':
          $ref: '#/components/responses/notifyJob'
  /closeJob:
    post:
      summary: Close job
      description: |
        Payload to close a job.
      operationId: installationCloseJob
      tags:
        - Close
      security:
        - Certificate: []
      requestBody:
        $ref: '#/components/requestBodies/closeJob'
      responses:
        '200':
          $ref: '#/components/responses/closeJob'
  /createJob:
    post:
      summary: Create job
      description: |
        Payload to create a job.
      operationId: installationCreateJob
      tags:
        - Installation
      security:
        - Certificate: []
      requestBody:
        $ref: '#/components/requestBodies/createJob'
      responses:
        '200':
          $ref: '#/components/responses/createJob'
  /cancelJob:
    post:
      summary: Cancel job
      description: |
        Payload to cancel a job.
      operationId: installationCancelJob
      tags:
        - Installation
      security:
        - Certificate: []
      requestBody:
        $ref: '#/components/requestBodies/cancelJob'
      responses:
        '200':
          $ref: '#/components/responses/cancelJob'
components:
  securitySchemes:
    Certificate:
      type: mutualTLS
      description: MutualTLS Certificate
  schemas:
    jobHeader:
      type: object
      properties:
        serviceId:
          type: string
        requestorJobId:
          type: string
        providerJobId:
          type: string
        buyerReferenceId:
          type: string
        eventTimestamp:
          type: string
        providerDunsId:
          type: string
        requestorDunsId:
          type: string
    engineerDetails:
      type: object
      properties:
        firstName:
          type: string
          description: The engineer's first name
          example: First
        surname:
          type: string
          description: The engineer's surname
          example: Last
        telephoneNumber:
          type: string
          description: The engineer's telephone number
          example: 7788899988
        employeeNumber:
          type: string
          description: The engineer's employee number
          example: 123456
    travelDetails:
      type: object
      properties:
        arrivalTime:
          type: string
          description: The arrival time
          example: '2022-03-05T08:04:29.26'
        status:
          type: string
          description: The status
          example: onway
        currentLocation:
          type: object
          description: The current location
          properties:
            latitude:
              type: number
              description: The latitude
              example: 52.123456
            longitude:
              type: number
              description: The longitude
              example: -0.123456
    ontDetails:
      type: object
      properties:
        serialNumber:
          type: string
          description: The serial number of the ONT
          example: http://calix.com?fs=ALCLFCA46744&sn=ALCLFCA46744
        make:
          type: string
          description: The make of the ONT
          example: Nokia XS-010X-Q
        model:
          type: string
          description: The model of the ONT
          example: Nokia XS-010X-Q
    notifyJob:
      oneOf:
        - type: object
          title: Engineer details
          required:
            - jobHeader
            - engineerDetails
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
            engineerDetails:
              $ref: '#/components/schemas/engineerDetails'
        - type: object
          title: Engineer en-route
          required:
            - travelDetails
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
            engineerDetails:
              $ref: '#/components/schemas/engineerDetails'
            travelDetails:
              $ref: '#/components/schemas/travelDetails'
        - type: object
          title: Engineer Onsite
          required:
            - travelDetails
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
            engineerDetails:
              $ref: '#/components/schemas/engineerDetails'
            travelDetails:
              $ref: '#/components/schemas/travelDetails'
        - type: object
          title: ONT FSAN and Serial Number and Make Model
          required:
            - jobHeader
            - ontDetails
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
            ontDetails:
              $ref: '#/components/schemas/ontDetails'
    networkConfigComplete:
      type: object
      properties:
        details:
          type: string
          description: The details
          example: ONT Serial Number Set
        success:
          type: boolean
          description: Whether it was a success
    notifyJob-2:
      oneOf:
        - type: object
          title: ONT_Set
          required:
            - jobHeader
            - networkConfigComplete
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
            networkConfigComplete:
              $ref: '#/components/schemas/networkConfigComplete'
        - type: object
          title: ONT_Provision_Failed
          required:
            - jobHeader
            - networkConfigComplete
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
            networkConfigComplete:
              $ref: '#/components/schemas/networkConfigComplete'
    installType:
      type: object
      properties:
        cityCode:
          type: string
        jobCodes:
          type: array
          items:
            type: string
    closureDetails:
      type: object
      required:
        - closureCode
        - secondaryClosureCode
        - secondaryClosureCodeDescription
        - closureNotes
        - complete
      properties:
        closureCode:
          type: string
        secondaryClosureCode:
          type: string
        secondaryClosureCodeDescription:
          type: string
        closureNotes:
          type: string
        complete:
          type: string
    testResults:
      type: object
      required:
        - speedUpstream
        - speedDownstream
        - lightLevel
      properties:
        speedUpstream:
          type: integer
        speedDownstream:
          type: integer
        lightLevel:
          type: number
    nodeDetails:
      type: object
      required:
        - aerialInstallation
        - aerialPoleCableCount
        - aerialSplitterCount
        - patchMadeInCabinet
      properties:
        aerialInstallation:
          type: string
        aerialPoleCableCount:
          type: integer
        aerialSplitterCount:
          type: integer
        patchMadeInCabinet:
          type: string
    closureDocuments:
      type: object
      required:
        - preInstallAgreementPDF
        - postInstallAgreementPDF
        - wayleaveJpeg
        - exfoTestPDF
      properties:
        preInstallAgreementPDF:
          type: string
          format: binary
        postInstallAgreementPDF:
          type: string
          format: binary
        wayleaveJpeg:
          type: string
          format: binary
        exfoTestPDF:
          type: string
          format: binary
    closeJob:
      type: object
      required:
        - id
        - jsonrpc
        - method
        - params
      properties:
        id:
          type: integer
        jsonrpc:
          type: string
        method:
          type: string
        params:
          type: object
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
            installType:
              $ref: '#/components/schemas/installType'
            ontDetails:
              type: object
              properties:
                serialNumber:
                  type: string
            activityStartTime:
              type: string
              format: date-time
            activityEndTime:
              type: string
              format: date-time
            closureDetails:
              $ref: '#/components/schemas/closureDetails'
            testResults:
              $ref: '#/components/schemas/testResults'
            nodeDetails:
              $ref: '#/components/schemas/nodeDetails'
            closureDocuments:
              $ref: '#/components/schemas/closureDocuments'
    closeJob-2:
      title: Close Job Response
      type: object
    contactDetails:
      type: object
      properties:
        name:
          type: string
        telephoneNumber:
          type: string
    appointmentTime:
      type: string
      format: date-time
    accessRestrictions:
      type: string
    hazards:
      type: string
    siteAddress:
      type: object
      properties:
        locationId:
          type: string
        buildingNumber:
          type: string
        thoroughfareName:
          type: string
        dependentLocality:
          type: string
        postTown:
          type: string
        postcode:
          type: string
    coordinates:
      type: object
      properties:
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
    cabinetAddress:
      type: object
      properties:
        locationId:
          type: string
        thoroughfareName:
          type: string
        dependentLocality:
          type: string
        postTown:
          type: string
        postcode:
          type: string
    installInformation:
      type: object
      properties:
        cabinetSplitterPort:
          type: string
        lineProfile:
          type: string
        communicationsServiceProvider:
          type: string
    attachments:
      type: array
      items:
        type: object
        properties:
          title:
            type: string
          contentType:
            type: string
          content:
            type: string
    notes:
      type: array
      items:
        type: object
        properties:
          timestamp:
            type: string
            format: date-time
          installationNotes:
            type: string
          text:
            type: string
    confidenceFactor:
      type: integer
      description: Confidence factor of the work order.
    dropArchitectureType:
      type: string
      description: Type of drop architecture.
    networkTechnologyType:
      type: string
      description: Type of network technology.
    ontVendor:
      type: string
      description: ONT vendor type.
    emergencyResponseServicesJobDetails:
      type: object
      description: Details of emergency response services for the job.
      properties:
        iTaskRef:
          type: string
          description: Reference to the iTask.
        incidentRef:
          type: string
          description: Reference to the incident.
        faultDescription:
          type: string
          description: Description of the fault.
        accessNeeded:
          type: boolean
          description: Indicates if access is needed.
    propertyFlags:
      type: string
      description: Property flags associated with the work order.
    projectReference:
      type: string
      description: Name of the project related to the work order.
    permittedONTs:
      type: string
      description: Permitted ONTs type of the work order.
    ispMigration:
      type: boolean
      description: Indicates whether the work order involves ISP migration.
    description:
      type: string
      description: Description of the work order.
    response:
      type: object
      properties:
        jsonrpc:
          type: string
        result:
          type: object
          properties:
            providerJobId:
              type: string
        id:
          type: string
    createJob:
      type: object
      required:
        - id
        - sent
        - method
        - ref
        - content
        - response
      properties:
        id:
          type: integer
        sent:
          type: string
          format: date-time
        method:
          type: string
        ref:
          type: string
        content:
          type: object
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
            siteContactDetails:
              $ref: '#/components/schemas/contactDetails'
            appointmentTime:
              $ref: '#/components/schemas/appointmentTime'
            accessRestrictions:
              $ref: '#/components/schemas/accessRestrictions'
            hazards:
              $ref: '#/components/schemas/hazards'
            installType:
              $ref: '#/components/schemas/installType'
            siteAddress:
              $ref: '#/components/schemas/siteAddress'
            siteCoordinates:
              $ref: '#/components/schemas/coordinates'
            cabinetAddress:
              $ref: '#/components/schemas/cabinetAddress'
            cabinetCoordinates:
              $ref: '#/components/schemas/coordinates'
            installInformation:
              $ref: '#/components/schemas/installInformation'
            attachments:
              $ref: '#/components/schemas/attachments'
            additionalSiteContactDetails:
              type: array
              items:
                $ref: '#/components/schemas/contactDetails'
            notes:
              $ref: '#/components/schemas/notes'
            confidenceFactor:
              $ref: '#/components/schemas/confidenceFactor'
            dropArchitectureType:
              $ref: '#/components/schemas/dropArchitectureType'
            networkTechnologyType:
              $ref: '#/components/schemas/networkTechnologyType'
            ontVendor:
              $ref: '#/components/schemas/ontVendor'
            emergencyResponseServicesJobDetails:
              $ref: '#/components/schemas/emergencyResponseServicesJobDetails'
            propertyFlags:
              $ref: '#/components/schemas/propertyFlags'
            projectReference:
              $ref: '#/components/schemas/projectReference'
            permittedONTs:
              $ref: '#/components/schemas/permittedONTs'
            ispMigration:
              $ref: '#/components/schemas/ispMigration'
            description:
              $ref: '#/components/schemas/description'
        response:
          $ref: '#/components/schemas/response'
    createJob-2:
      title: Create Job Response
      type: object
    cancelJob:
      type: object
      required:
        - id
        - sent
        - method
        - ref
        - content
        - response
      properties:
        id:
          type: integer
        sent:
          type: string
          format: date-time
        method:
          type: string
        ref:
          type: string
        content:
          type: object
          properties:
            jobHeader:
              $ref: '#/components/schemas/jobHeader'
        response:
          $ref: '#/components/schemas/response'
    cancelJob-2:
      title: Cancel Job Response
      type: object
  requestBodies:
    notifyJob:
      description: Job notifications sent by installer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/notifyJob'
          examples:
            Engineer details:
              value:
                id: 1
                jsonrpc: '2.0'
                method: notifyJob
                params:
                  jobHeader:
                    requestorDunsId: CF12345678
                    providerDunsId: ' P987654321'
                    serviceId: ' S12345'
                    requestorJobId: GVFSWHEFL9Y1FZF84ZF63KF2FUOK0F0N
                    providerJobId: '115543'
                    eventTimestamp: '2022-03-05T15:16:45.8587916+01:00'
                  engineerDetails:
                    firstName: First
                    surname: Last
                    telephoneNumber: '07788899988'
                    employeeNumber: '123456'
            Engineer en-route:
              value:
                id: 1
                jsonrpc: '2.0'
                method: notifyJob
                params:
                  jobHeader:
                    requestorDunsId: CF12345678
                    providerDunsId: ' P987654321'
                    serviceId: ' S12345'
                    requestorJobId: GVFSWHEFL9Y1FZF84ZF63KF2FUOK0F0N
                    providerJobId: '115543'
                    eventTimestamp: '2022-03-05T15:16:45.8587916+01:00'
                  engineerDetails:
                    firstName: First
                    surname: Last
                    telephoneNumber: '07788899988'
                    employeeNumber: '123456'
                  travelDetails:
                    arrivalTime: '2022-03-05T08:04:29.26'
                    status: onway
                    currentLocation:
                      latitude: 52.123456
                      longitude: -0.123456
            Engineer Onsite:
              value:
                id: 1
                jsonrpc: '2.0'
                method: notifyJob
                params:
                  jobHeader:
                    requestorDunsId: CF12345678
                    providerDunsId: ' P987654321'
                    serviceId: ' S12345'
                    requestorJobId: GVFSWHEFL9Y1FZF84ZF63KF2FUOK0F0N
                    providerJobId: '115543'
                    eventTimestamp: '2022-03-05T15:16:45.8587916+01:00'
                  engineerDetails:
                    firstName: First
                    surname: Last
                    telephoneNumber: '07788899988'
                    employeeNumber: '123456'
                  travelDetails:
                    arrivalTime: '2022-03-05T08:04:29.26'
                    status: onsite
                    currentLocation:
                      latitude: 52.123456
                      longitude: -0.123456
            ONT FSAN and Serial Number and Make Model:
              value:
                jobHeader:
                  requestorDunsId: CF12345678
                  providerDunsId: K987654321
                  serviceId: S483315
                  requestorJobId: 9OQCV4KRKSMD7RFSI8O9VS2SIFYATLQP
                  providerJobId: '1933017'
                  eventTimestamp: '2023-09-27T08:47:15.4322716+01:00'
                ontDetails:
                  serialNumber: http://calix.com?fs=ALCLFCA46744&sn=ALCLFCA46744
                  make: Nokia XS-010X-Q
                  model: Nokia XS-010X-Q
    closeJob:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/closeJob'
          examples:
            CloseJob:
              value:
                id: 1
                jsonrpc: '2.0'
                method: closeJob
                params:
                  jobHeader:
                    requestorDunsId: CF12345678
                    providerDunsId: P987654321
                    serviceId: S12345
                    requestorJobId: GVFSWHEFL9Y1FZF84ZF63KF2FUOK0F0N
                    providerJobId: '115516'
                    eventTimestamp: '2022-03-28T13:07:17.4709569+01:00'
                  installType:
                    jobCodes:
                      - ResExtInstall1
                      - CPEInst1
                    cityCode: MK
                  ontDetails:
                    serialNumber: http://calix.com?fs=CXNK00123456&sn=371903456123
                  activityStartTime: '2022-03-28T12:07:18.15'
                  activityEndTime: '2022-03-28T12:53:36.43'
                  closureDetails:
                    closureCode: CON
                    secondaryClosureCode: CON01
                    secondaryClosureCodeDescription: Incomplete Network
                    closureNotes: >-
                      Q50m fibre reel 1m bft 10m patchlead to wallbox ont in
                      position as agreed prior to install all light readings are
                      in speck customer happy with all install 
                    complete: 'True'
                  testResults:
                    speedUpstream: 109
                    speedDownstream: 76
                    lightLevel: 17.3
                  nodeDetails:
                    aerialInstallation: 'False'
                    aerialPoleCableCount: 0
                    aerialSplitterCount: 0
                    patchMadeInCabinet: 'True'
                  closureDocuments:
                    preInstallAgreementPDF: JVBERi0xLjQKMSAwIG9iago8PAovV
                    postInstallAgreementPDF: JVBERi0xLjQKMSAwIG9iago8PAovV
                    wayleaveJpeg: ''
                    exfoTestPDF: ''
    createJob:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/createJob'
          examples:
            CreateJob:
              value:
                id: 2
                sent: 2022-03-18T17:39:21+0000
                method: createJob
                ref: S114677
                content:
                  jobHeader:
                    serviceId: S114677
                    requestorJobId: GVFSWHEFL9Y1FZF84ZF63KF2FUOK0F0N
                    providerJobId: ''
                    buyerReferenceId: ABCD123456
                    eventTimestamp: 2022-03-18T10:39:21+0000
                    providerDunsId: P12345678
                    requestorDunsId: CF12345678
                  siteContactDetails:
                    name: Jane Smith
                    telephoneNumber: '07654321987'
                  appointmentTime: 2022-02-16T08:00:00+0000
                  requiredBy: '2024-09-15'
                  accessRestrictions: Brick Wall
                  hazards: Noisy Migration
                  installType:
                    cityCode: MK
                    jobCodes:
                      - fttpers
                  siteAddress:
                    locationId: a09D000002OR784IAD
                    buildingNumber: '79'
                    thoroughfareName: CORN HILL
                    dependentLocality: TWO MILE ASH
                    postTown: MILTON KEYNES
                    postcode: MK8 8EZ
                  siteCoordinates:
                    latitude: 52.037429
                    longitude: -0.804712
                  cabinetAddress:
                    locationId: MK-1-PN81-SN5
                    thoroughfareName: STONE HILL
                    dependentLocality: TWO MILE ASH
                    postTown: Milton Keynes
                    postcode: MK8 8DN
                  cabinetCoordinates:
                    latitude: 52.036904
                    longitude: -0.8063591078
                  installInformation:
                    cabinetSplitterPort: MK-1-PN81-SN5-CP1-5-PT05
                    lineProfile: G110/15/30
                    communicationsServiceProvider: ISP1
                  attachments:
                    - title: MK-016328 Post Install Agreement 2022-02-16.pdf
                      contentType: application/pdf
                      content: JVBERi0xLjQKMSAwIG9iago8PAovVGl0bGUgKP7/KQovQ3JlYXRvciAo
                  additionalSiteContactDetails:
                    - name: John Smith
                      telephoneNumber: '07654321988'
                  notes:
                    - timestamp: 2022-03-18T10:39:21+0000
                      installationNotes: Please install Router Type WIFI2, record barcode
                      text: 'Demand Point Type: SDU'
                  confidenceFactor: 10
                  dropArchitectureType: DPA
                  networkTechnologyType: XGS-PON
                  ontVendor: Calix
                  emergencyResponseServicesJobDetails:
                    iTaskRef: REFERENCE_TO_ITASK
                    incidentRef: REFERENCE_TO_INCIDENT
                    faultDescription: FAULT_DESCRIPTION
                    accessNeeded: true
                  propertyFlags: CHP DAN
                  projectReference: name of the project related to the workorder
                  permittedONTs: permitted ONTs type of the workorder
                  ispMigration: ispMigration of the workorder
                  description: Description of the workorder
                response:
                  jsonrpc: '2.0'
                  result:
                    providerJobId: VF322324
                  id: '1'
    cancelJob:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/cancelJob'
          examples:
            CancelJob:
              value:
                id: 2
                sent: 2022-03-18T17:39:21+0000
                method: cancelJob
                ref: S114677
                content:
                  jobHeader:
                    serviceId: S114677
                    requestorJobId: GVFSWHEFL9Y1FZF84ZF63KF2FUOK0F0N
                    providerJobId: '1234567'
                    buyerReferenceId: ABCD123456
                    eventTimestamp: 2022-03-18T17:39:21+0000
                    providerDunsId: P12345678
                    requestorDunsId: CF12345678
                response:
                  jsonrpc: '2.0'
                  result: {}
                  id: '1'
  responses:
    notifyJob:
      description: Job notifications sent by cityfibre
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/notifyJob-2'
          examples:
            ONT Set:
              value:
                id: 3
                sent: 2022-03-18T17:39:21+0000
                method: notifyJob
                ref: S114677
                content:
                  jobHeader:
                    requestorDunsId: CF12345678
                    providerDunsId: P987654321
                    serviceId: S12345
                    requestorJobId: GVFSWHEFL9Y1FZF84ZF63KF2FUOK0F0N
                    providerJobId: '115517'
                    eventTimestamp: 2022-03-05T08:57:31+0100
                  networkConfigComplete:
                    details: ONT Serial Number Set
                    success: true
                response:
                  jsonrpc: '2.0'
                  result: {}
                  id: '1'
            ONT Provision Failed:
              value:
                id: 3
                sent: 2022-03-18T17:39:21+0000
                method: notifyJob
                ref: S114677
                content:
                  jobHeader:
                    requestorDunsId: CF12345678
                    providerDunsId: P987654321
                    serviceId: S12345
                    requestorJobId: GVFSWHEFL9Y1FZF84ZF63KF2FUOK0F0N
                    providerJobId: '115517'
                    eventTimestamp: 2022-03-05T08:57:31+0100
                  networkConfigComplete:
                    details: ' ONT Provision Failed. Contact Order Desk '
                    success: false
                response:
                  jsonrpc: '2.0'
                  result: {}
                  id: '1'
    closeJob:
      description: Acknowledgement of the message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/closeJob-2'
    createJob:
      description: Acknowledgement of the message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/createJob-2'
    cancelJob:
      description: Acknowledgement of the message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/cancelJob-2'
