The Form Context

Every form script in Dynamics 365 CE, no matter what it's trying to accomplish, starts from the same single object: the form context. Whether you're reading a value, hiding a section, or checking whether the record is new, you go through this one object to do it. It's the foundation everything else in this course builds on.

One remote control for the whole screen

Picture a TV remote: one control, with a button for everything you're allowed to do to the screen in front of you. The form context works the same way for a Dynamics 365 CE form.

Your script never reaches directly into the page's raw HTML to change what the user sees. Instead, it calls methods on the form context — a consistent set of "buttons" for reading values, changing values, and adjusting what's visible, no matter which table's form you're scripting.

Where the form context comes from

Almost every form event handler receives an execution context as its first parameter. You get the form context by calling executionContext.getFormContext() on it.

From there, two areas matter most:

• Attributes — a field's underlying data value ("the number 42")
• Controls — how that field is actually rendered on the form ("the visible box on screen showing 42")

That split matters: you can, for instance, hide a control without touching the underlying attribute value at all.

function onLoadHandler(executionContext) {
  var formContext = executionContext.getFormContext();

  // Read a value via the attribute
  var priority = formContext.getAttribute("prioritycode").getValue();

  // Set a different field's value
  if (priority === 1) {
    formContext.getAttribute("escalated").setValue(true);
  }

  // Show or hide a control
  formContext.getControl("internalnotes").setVisible(priority === 1);
}

The most-used formContext methods (cheat sheet)

You don't need to memorize the entire Client API to be productive — a small set of methods covers most real scripts. These are the exact method names Microsoft's documentation uses, grouped by which part of the form context they live on.

Attribute methods — formContext.getAttribute("fieldname")

An attribute represents a field's underlying data — the value itself, independent of how (or whether) it's displayed.

Control methods — formContext.getControl("fieldname")

A control represents how a field is displayed — the visible box on the form, separate from the data inside it.

Entity/data methods — formContext.data.entity and formContext.data

UI methods — formContext.ui

function lockDiscountField(executionContext) {
  var formContext = executionContext.getFormContext();
  var control = formContext.getControl("discountpercent");

  control.setDisabled(true);
  control.setNotification("Locked after approval", "discount-locked");

  formContext.ui.setFormNotification(
    "This deal has been approved and can no longer be edited.",
    "WARNING",
    "approved-banner"
  );
}

A note on Xrm.Page

Older Dynamics 365 CE code, blog posts, or a colleague's script from a few years back will very likely use Xrm.Page instead of a form context parameter. Xrm.Page was the earlier way of reaching the same information — a single global object standing in for "the form currently open."

It still works in many environments for backward compatibility. But Microsoft's current guidance is the form context pattern shown above, passed explicitly into each handler through the execution context. You'll still recognize Xrm.Page on sight — it's reaching for the same remote control, just through an older doorway.

What else lives on the form context

Beyond attributes and controls, the form context also exposes form-level information:

• Whether the record is new or has unsaved changes, via formContext.data.entity
• The current form's type
• A formContext.ui area for tabs, sections, and the form's overall notification area

You won't use all of it in every script. But knowing it's all reachable from one starting object — rather than scattered across a dozen different entry points — is exactly what makes the form context predictable once you've used it a few times.