widget-coherence

Widget Coherence for ServiceNow Service Portal

Service Portal widgets MUST have perfect communication between Server Script, Client Controller, and HTML Template. This is not optional - widgets fail when these components don't talk to each other correctly.

The Three-Way Contract

Every widget requires synchronized communication:

1. Server Script Must:

• Initialize ALL data.* properties that HTML will reference
• Handle EVERY input.action that client sends via c.server.get()
• Return data in the format the client expects

2. Client Controller Must:

• Implement EVERY method called by ng-click in HTML
• Use c.server.get({action: 'name'}) for server communication
• Update c.data when server responds

3. HTML Template Must:

• Only reference data.* properties that server provides
• Only call methods defined in client controller
• Use correct Angular directives and bindings

Data Flow Patterns

Server → Client → HTML

// SERVER SCRIPT
;(function () {
  data.incidents = []
  data.loading = true

  var gr = new GlideRecord("incident")
  gr.addQuery("active", true)
  gr.setLimit(10)
  gr.query()

  while (gr.next()) {
    data.incidents.push({
      sys_id: gr.getUniqueValue(),
      number: gr.getValue("number"),
      short_description: gr.getValue("short_description"),
    })
  }
  data.loading = false
})()

// CLIENT CONTROLLER
api.controller = function ($scope) {
  var c = this

  c.selectIncident = function (incident) {
    c.selectedIncident = incident
  }
}

<!-- HTML TEMPLATE -->
<div ng-if="data.loading">Loading...</div>
<div ng-if="!data.loading">
  <div ng-repeat="incident in data.incidents" ng-click="c.selectIncident(incident)">
    {{incident.number}}: {{incident.short_description}}
  </div>
</div>

Client → Server (Actions)

// CLIENT CONTROLLER
c.saveIncident = function () {
  c.server
    .get({
      action: "save_incident",
      incident_data: c.formData,
    })
    .then(function (response) {
      if (response.data.success) {
        c.data.message = "Saved successfully"
      }
    })
}