DNO Integration

Overview

The DNO (Distribution Network Operator) integration submits grid connection applications to ENA Connect as part of an order's workflow. It is used for installations that require notification or approval from a UK network operator, typically EV chargers, solar PV, battery storage, and heat pumps.

The integration is implemented as a background event on a workflow step. When the step reaches the configured state, Installer.com renders a Handlebars payload from the order's custom fields and posts it to ENA Connect.

How It Works

Authentication

You do not need your own ENA Connect account. Installer.com provides you with an ENA Connect API token, which you configure on the background event's headers template (typically as X-API-Key). All requests, including file uploads, share the same token.

Contact your account manager to receive a token for your organisation.

Configuring the background event

Handlebars in the payload

The payload is a JSON string rendered with Handlebars at submission time. The same template features documented in Webhooks → Handlebars syntax apply here: variable interpolation, dot notation, and {{#if}} / {{#each}} blocks.

In addition to the standard variables, the DNO integration provides a dnoFile helper for attaching files from the order to the application.

dnoFile helper

{{dnoFile <customId>}} reads a file-type custom field from the order, uploads each file to ENA Connect as part of submission, and returns the URLs ENA Connect issues for those uploaded files. Use it inside an {{#each}} block to emit one entry per uploaded file, or with {{#if @first}} to pick only the first file:

"cutOutImages": [
    {{#each {{dnoFile cut-out-image-upload}}}}
        {{#if @first}} { "fileUrl": "{{this}}" } {{/if}}
    {{/each}}
]

Required custom fields

The DNO payload pulls values from the order's custom fields. The exact set depends on the application class, but a typical EVCP-AC submission expects the following custom IDs on the order template:

The customer and installer details ({{order.*}}, {{actor.installer.*}}) are sourced from the order and the installer actor on the workflow, so no extra custom fields are required for those.

Example payload

The payload below is a complete EVCP_AC application for ENA Connect. Adjust the applicationClass, lcts, deviceClass, and deviceType for other device types.

{
    "applicationClass": "DEMAND_GENERAL",
    "applicationClassVersion": 1,
    "lcts": [
        "EVCP_AC"
    ],
    "subInstallerUsername": "{{actor.installer.organizationName}}",
    "installerCustomerDetails": {
        "installerName": "{{actor.installer.organizationResponsibleFirstName}} {{actor.installer.organizationResponsibleLastName}}",
        "installerCompany": "{{actor.installer.organizationName}}",
        "installerPhone": "{{actor.installer.organizationResponsiblePhoneNumber}}",
        "customerPhone": "{{order.phoneNumber}}",
        "installerEmail": "{{actor.installer.organizationResponsibleEmail}}",
        "customerName": "{{order.contactPersonName}}",
        "customerEmail": "{{order.email}}",
        "mainAddress": "{{order.address}}",
        "installationPostCode": "{{order.postalCode}}",
        "mpan": "{{customFields.mpan}}"
    },
    "supplyDetails": {
        "declaredVoltageAtConnectionPoint": "{{customFields.declared-voltage-at-connection-point}}",
        "phaseCode": {{customFields.number-of-phases}},
        "isCtMetered": {{#if customFields.is-ct-metered}}true{{else}}false{{/if}},
        "premisesCutOutRating": {{customFields.premises-cut-out-rating}},
        "isLoopedSupply": {{#if customFields.is-the-service-looped}}true{{else}}false{{/if}},
        "isNoSafetyConcerns": {{#if customFields.is-no-safety-concerns}}true{{else}}false{{/if}},
        {{#if customFields.max-import-capacity}}"maxImportCapacity": "{{customFields.max-import-capacity}}",{{/if}}
        "isNoIssues": {{#if customFields.is-no-issues}}true{{else}}false{{/if}},
        "isImportLimitingDevicePresent": {{#if customFields.is-import-limiting-device-present}}true{{else}}false{{/if}}
    },
    "devicesToInstall": [
        {
            "deviceClass": "DEMAND_DEVICE_GENERAL_ENA_REGISTERED",
            "deviceType": "EVCP_AC",
            "deviceSysRef": "{{customFields.device-sys-ref}}",
            "targetInstallDate": "{{customFields.proposed-date-install}}",
            "enaLctDataset": "EVAC",
            "powerFactor": 1
        }
    ],
    "existingDevices": [],
    "newPremisesMaxDemand": {
        "newPremisesMaxDemand": "{{customFields.new-premises-max-demand}}"
    },
    "cutOutImages": [
        {{#each {{dnoFile cut-out-image-upload}}}}
            {{#if @first}} { "fileUrl": "{{this}}"} {{/if}}
        {{/each}}
    ],
    "additionalAttachments": []
}

The {{actor.installer.*}} variables resolve from the actor with slug installer on the workflow. The slug must match the actor configured on your workflow, typically populated by a preceding Dispatching step. Rename it if your template uses a different slug.

Polling and auto-completion

After a submit background event succeeds, the response from ENA Connect (including the applicationId) is stored on the workflow as workflow.eventData.<eventKey>, where <eventKey> is the data key you configure on the event. With the conventional key dno_application_submit, the application ID becomes available at:

{{workflow.eventData.dno_application_submit.applicationId}}

A second background event polls ENA Connect on a schedule against the stored application ID:

GET https://hybrid.connect-direct.energynetworks.org/connection-application/v2/applications?applicationId={{workflow.eventData.dno_application_submit.applicationId}}

Each poll inspects the response and compares it against two configurable lists on the event:

If the status doesn't match either list, the poll reschedules itself and runs again on the configured interval. Because the step auto-completes on approval, no manual action is required on the order once the application has been submitted: booking and installation can proceed as soon as ENA Connect approves the application.

Expiration

Polling does not run forever. Each background event has an expires after value (default: 7 days from when the step became active). If ENA Connect has not returned a terminal status before that window elapses, the workflow step transitions to expired and polling stops. Configure the expiry on the background event to match your DNO's expected processing time.

Monitoring submissions

Each background event execution is logged on the workflow step with the rendered payload, the HTTP response, and any error returned by ENA Connect. Open the step in the Routing App and inspect the background event history to see the submission status.

For programmatic monitoring, subscribe to workflow webhooks (see Webhooks) on the same step to be notified when the step completes after a successful submission.

Troubleshooting

If issues persist, contact support with the order ID and the background event execution timestamp.