groeimetai/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"
      }
    })
}

// SERVER SCRIPT
if (input && input.action === "save_incident") {
  var gr = new GlideRecord("incident")
  gr.initialize()
  gr.setValue("short_description", input.incident_data.short_description)
  data.new_sys_id = gr.insert()
  data.success = !!data.new_sys_id
}

Validation Checklist

Before deploying a widget, verify:

• [ ] Every data.property in server is used in HTML or client
• [ ] Every ng-click="c.method()" has matching c.method in client
• [ ] Every c.server.get({action: 'x'}) has matching if(input.action === 'x') in server
• [ ] No orphaned methods or unused data properties
• [ ] All data.* properties are initialized in server (even if empty)

Common Failures

Action Name Mismatch

// CLIENT - sends 'saveIncident'
c.server.get({ action: "saveIncident" })

// SERVER - expects 'save_incident' (MISMATCH!)
if (input.action === "save_incident") {
}

Method Name Mismatch

<!-- HTML - calls saveData() -->
<button ng-click="c.saveData()">Save</button>

// CLIENT - defines save() (MISMATCH!)
c.save = function () {}

Undefined Data Properties

<!-- HTML - references user.email -->
<span>{{data.user.email}}</span>

// SERVER - only sets user.name (user.email is undefined!)
data.user = { name: userName }

Angular Directives Reference

| Directive | Purpose | | ------------------- | ---------------------------------------- | | ng-if | Conditionally render element | | ng-show/ng-hide | Toggle visibility (element stays in DOM) | | ng-repeat | Iterate over array | | ng-click | Handle click events | | ng-model | Two-way data binding | | ng-class | Dynamic CSS classes | | ng-disabled | Disable form elements |