Agent Skills: Widget Coherence for ServiceNow Service Portal

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 |