Building Apps with Kianda’s Low-Code Platform

• 1: Field widget development
• 2: Rule widget development
• 3: Page (Dashboard) Widget Development
• 4: Global CSS file
• 5: Global JavaScript file
• 6: List widget template customisation
• 7: Kianda as a Progressive Web Application (PWA)
• 8: Webhooks
• 9: Introduction to Ember.js in Kianda
• 10: Custom Connector Development
• 10.1: Microservice Creation
• 10.2: Sample schemas
• 10.3: Steps to create a custom connector
• 10.4: Sample code for a microservice

{{#if (eq displayMode "design")}}
  {{input required=field.required maxlength="4" type="text" value=field.text class="form-control"}}
{{/if}}

{{#if (eq displayMode "edit")}}
  {{input required=field.required maxlength="4" type="text" value=field.text class="form-control"}}
{{/if}}

{{#if (eq displayMode "settings")}}
  <!-- Add UI for settings here if needed -->
{{/if}}

{{#if (eq displayMode "display")}}
  <p class="text-muted">{{field.text}}</p>
{{/if}}

{
  edit: function() {
    // Code for edit mode
  },
  display: function() {
    // Code for display mode
  },
  settings: function() {
    // Code for settings mode
  }
}

1 - Field widget development

A custom field widget renders and edits data in a Kianda form. It can provide a simple input, manage a structured value such as a location or a collection of uploaded files, or integrate an external control such as a payment element. Its main responsibility is to keep the field model consistent with what the user sees and enters.

This guide builds a complete Reference text field and a complete Geolocation field. It then develops a public-file upload example and explains the component patterns needed for a Stripe integration. Along the way, it covers display modes, change notifications, configuration validation, process APIs, and child fields.

The examples target Kianda’s Ember.js widget environment. They use classic Ember components, Handlebars templates, and native JavaScript Promises.

How a field widget works

A widget has two authoring surfaces:

Kianda supplies the component with field, the field model being rendered, and displayMode, which selects the appropriate view. The associated process is available through this.get("field.process").

Field widgets and rule widgets share Ember component techniques, but have different runtime responsibilities:

A field widget does not call process.save() to persist its changes. It updates field data in the current process instance. The process’s Save rule or surrounding save/commit workflow handles persistence. A remote upload or payment may have an immediate external effect, independently of whether the process is subsequently saved.

1. Create a field widget

You need access to Administration > Developer, normally through an Administrator or Developer role.

1. Open Administration > Developer and click New widget.
2. Enter a title, choose a unique ID and icon, and select Field as the widget type.
3. Open the Widget UI and Widget Code editors.
4. Add the template and JavaScript from the first example below.
5. Click Update to compile the widget.
6. Open a test process in Administration > Designer. Add the widget from Controls > Custom and configure it.

Author the JavaScript as an Ember component module. Kianda creates and renders the component; you do not need to instantiate it yourself.

import Ember from "ember";

export default Ember.Component.extend({
  // Component properties, methods, and actions go here.
});

Use normal method syntax for component methods so that this refers to the component instance. Arrow functions are useful inside methods for callbacks that need to retain that instance.

2. Build a complete Reference text field

This first widget stores the same string in field.text and field.value. Its settings let the designer choose a placeholder. It demonstrates the complete path from user input to field data and attached rules.

Widget UI

Paste this complete template into Widget UI:

{{#if (eq this.displayMode "design")}}
  <input
    type="text"
    class="form-control"
    aria-label={{this.field.title}}
    placeholder={{this.field.settings.placeholder}}
    disabled>
{{/if}}

{{#if (eq this.displayMode "edit")}}
  <input
    type="text"
    class="form-control"
    aria-label={{this.field.title}}
    value={{this.field.text}}
    placeholder={{this.field.settings.placeholder}}
    required={{this.field.required}}
    onchange={{action "updateText"}}>
{{/if}}

{{#if (eq this.displayMode "display")}}
  {{#if this.field.text}}
    <span>{{this.field.text}}</span>
  {{else}}
    <span class="text-muted">No reference entered.</span>
  {{/if}}
{{/if}}

{{#if (eq this.displayMode "settings")}}
  <div class="form-group">
    <label for={{concat this.elementId "-placeholder"}}>Placeholder</label>
    {{input
      id=(concat this.elementId "-placeholder")
      type="text"
      class="form-control"
      value=this.field.settings.placeholder}}
    <p class="help-block">A hint shown when the input is empty.</p>
  </div>
{{/if}}

The eq helper comes from the available ember-truth-helpers addon. Each branch uses one of Kianda’s exact mode strings. The Designer preview is a disabled input; the read-only view displays the stored text.

Widget Code

Paste this complete module into Widget Code:

import Ember from "ember";

export default Ember.Component.extend({
  settings() {
    const field = this.get("field");

    if (field.get("settings.placeholder") === undefined) {
      field.set("settings.placeholder", "Enter a reference");
    }
  },

  actions: {
    updateText(event) {
      if (this.get("displayMode") !== "edit" ||
          this.get("field.enabled") === false ||
          this.get("field.visible") === false) {
        return;
      }

      const field = this.get("field");
      const value = event.target.value;

      field.set("text", value);
      field.set("value", value);
    }
  }
});

The native change event passes its event object to the action. Reading event.target.value makes the input source explicit. For this text input, the change is committed when the user finishes editing and leaves the input. If you choose oninput instead, updates occur while typing and can run attached rules on every keystroke.

The order of the setters is deliberate: set the readable text first, then set the value. Kianda observes field.value to trigger the field’s rules, so those rules should see the corresponding text when they run. Replacing the top-level value already provides the notification; there is no additional notifyPropertyChange() call here.

settings() supplies a Designer default only when the property is absent. An intentionally empty placeholder survives reopening the configuration. It does not initialize or overwrite the user’s runtime value.

Try the complete widget

1. Click Update, add the field to a test process, and open its settings.
2. Change the placeholder, save the field configuration, and save the process design.
3. Preview the process. Enter a reference and leave the input. Inspect the field: both text and value should contain the entered string.
4. Attach a simple rule to the field and verify that committing an edit triggers it.
5. Make the field required. Clear the input and verify that the normal submission workflow detects the missing value.
6. Disable the field through Designer or a rule. It should render its stored text through the display branch.
7. Save the process instance through its normal workflow, reopen it, and confirm that the value is retained.

3. Understand the field model

The widget operates on an Ember Data field model. You do not need to reproduce the model definition in your widget. These are the properties most relevant to authors:

Typical widgets respect visible, enabled, and required. Designers choose their initial values; specialized rules can change them during execution. Do not repurpose these flags as component-local loading or error state.

Decide what belongs in the model

Use the field attributes for data that should be part of the process:

• A reference field can use the same string for text and value.
• A location field can store coordinates in value and a formatted coordinate string in text.
• An upload field can store file references in value and filenames in text.
• A compound control can own real child models through fields.

Use component properties such as isBusy, errorMessage, or selectedTab for temporary UI state. Keep browser objects, DOM nodes, upload File objects, service instances, and SDK instances on the component. Store serializable results in the field model.

Keep Designer choices in field.settings. The model already initializes this object; assigning a new empty settings object during rendering would discard saved configuration. The property field.settings and the component method settings() are different things: one holds data, and the other is a convenience hook for the configuration UI.

Rendering, rule notification, and saving

These are related but separate behaviours:

None of these operations saves the process instance by itself.

A custom field that intentionally stores its data only as text can notify the observed property explicitly:

field.set("text", nextText);
field.notifyPropertyChange("value");

Kianda’s process.setField() does this internally for built-in text-only controls when appropriate. Directly setting a custom widget’s field.text does not gain that behaviour automatically.

Treat a notification as a deliberate point at which attached rules can run. Finish the associated text and data updates first. Avoid adding an extra notification after a top-level value replacement, and avoid initialization code that rewrites the field value on every render.

4. Render the four modes and use lifecycle hooks

this.get("displayMode") is always available on the field component.

Keep active uploads, payment controls, location acquisition, and other user operations in the editable view. The Designer preview should help a designer understand the widget without initiating those operations.

Kianda’s convenience hooks

On component insertion, Kianda invokes the convenience method for the current mode if you have defined it:

There is no design() convenience method. Render the design view through the template and use normal Ember lifecycle techniques when additional behaviour is needed.

These methods are insertion conveniences, not a promise-based execution pipeline. Kianda does not await Promises returned by field mode hooks. Declaring async edit() does not pause rendering, submission, or the rule engine. Start asynchronous work with explicit error handling and represent pending state in the component.

Do not assume that a convenience method will run whenever displayMode changes. If a long-lived resource must stop when a field becomes read-only, respond to that change explicitly and also clean it up when the component is destroyed. The Geolocation example demonstrates this.

Normal Ember hooks remain available

Use init() for per-instance component setup, such as allocating an array or initializing integration state. Call this._super(...arguments) when overriding an inherited lifecycle hook.

Mount a library that needs a DOM container after insertion, through edit() or an appropriate didInsertElement() implementation. init() runs before the DOM is available. If you override didInsertElement(), retain the superclass call; do not also invoke the same mode method manually and initialize the control twice.

Use willDestroyElement() to release DOM-related resources, listeners, watches, and timers. Match model-event subscriptions with cleanup as well, as shown in the next section. Ember’s component lifecycle documentation explains insertion and destruction hooks.

Native browser and external-library callbacks should enter Ember’s run loop before changing bound state. Use Ember.run(() => { ... }), and check that the component still exists and belongs to the intended field before applying a delayed result. See the Ember 2.18 run-loop guide.

5. Validate configuration and runtime input

Configuration validation and runtime missing-input validation serve different purposes. A valid Designer configuration does not establish that a user has entered a valid runtime result.

Required settings controls

Use required=true on Ember inputs or platform pickers when a Designer setting is mandatory. Native HTML inputs can use required="required" for the same required-input check.

For example, a control that copies file details into two utility fields could use this settings fragment:

{{#if (eq this.displayMode "settings")}}
  <div class="form-group">
    <label>Filename field</label>
    {{field-picker
      process=this.field.process
      required=true
      allowText=false
      selectForms=false
      selectFields=true
      value=this.field.settings.filenameField}}
  </div>

  <div class="form-group {{this.mappingErrorClass}}">
    <label>File URL field</label>
    {{field-picker
      process=this.field.process
      required=true
      allowText=false
      selectForms=false
      selectFields=true
      value=this.field.settings.fileUrlField}}
  </div>
{{/if}}

The required pickers prevent saving configuration with missing selections. For a relationship between settings, such as requiring two different destination fields, subscribe to the field model’s saving event.

Custom configuration checks with saving

The event receives the same validation argument contract used for custom rules:

• Set args.isError = true to reject the configuration save.
• Append a clear message to args.errors.
• Preserve errors already added by other validators.

The following component methods implement the additional check for the settings fragment above. Merge them into that widget’s component; retain any other initialization already performed by its settings() method.

import Ember from "ember";

export default Ember.Component.extend({
  mappingErrorClass: "",

  settings() {
    this._detachSettingsValidation();
    this.set("mappingErrorClass", "");
    this._settingsField = this.get("field");
    this._settingsField.on("saving", this, this._validateSettings);
  },

  _validateSettings(args) {
    const field = this._settingsField;
    const filenameRef = field.get("settings.filenameField");
    const urlRef = field.get("settings.fileUrlField");
    let message = null;

    if (!filenameRef || !urlRef ||
        filenameRef.type !== "field" || urlRef.type !== "field" ||
        !filenameRef.name || !urlRef.name) {
      message = "Select a filename field and a file URL field.";
    } else if (filenameRef.name === urlRef.name) {
      message = "Filename and file URL must use different fields.";
    } else if (filenameRef.name === field.get("name") ||
               urlRef.name === field.get("name")) {
      message = "Choose utility fields other than this upload field.";
    }

    this.set("mappingErrorClass", message ? "has-error" : "");

    if (message) {
      args.isError = true;
      args.errors.push(message);
    }
  },

  _detachSettingsValidation() {
    if (this._settingsField) {
      this._settingsField.off("saving", this, this._validateSettings);
      this._settingsField = null;
    }
  },

  willDestroy() {
    this._detachSettingsValidation();
    this._super(...arguments);
  }
});

Using a stable function reference makes it possible to remove exactly the listener this component added. Detaching before registering also prevents duplicated validation if settings initialization repeats. This follows Ember’s Evented on/off contract.

Perform these checks synchronously. Do not assume that the saving event waits for asynchronous validation. If configuration needs remote information, load it in the settings UI beforehand and validate the resulting state when saving.

Runtime required fields

During submission, Kianda uses field.required and the contents of field.text/field.value to determine whether required input is missing. A custom control must populate these attributes with meaningful data for the commit workflow to work correctly.

Keep pending and error messages in component properties. Storing "Uploading..." or "Location permission denied" in field.text can leave a nonempty field even though the requested input was never obtained. Clearing a value should also clear any text that would falsely suggest the field still has a result.

A nonempty object can still be incomplete for your business purpose. For example, a payment reference with a pending status is not proof of a successful payment. Use Validate input and appropriate conditions for this kind of pre-validation before dependent actions run.

A component-local isBusy, hasErrors, or errorMessage flag does not automatically block the process’s submission workflow. If an operation must finish before submission, make that requirement explicit in process data and validation rules. Decide whether a previous valid result remains acceptable while a replacement is being acquired.

6. Work with structured values and child fields

Replace a structured value

Replacing the top-level value is often the clearest way to publish a complete logical update. This example assumes uploaded contains a validated upload result:

const previousFiles = field.get("value") || [];
const nextFiles = previousFiles.concat([{
  filename: uploaded.filename,
  fileUrl: uploaded.fileUrl
}]);

field.set("text", nextFiles.map(file => file.filename).join(", "));
field.set("value", nextFiles);

This widget’s value contract is an array. Validate or migrate older values if an existing widget previously used a different shape. The new array reference supplies the top-level change notification.

Mutate an existing value

If you keep the same object or array, make Ember-aware changes and explicitly notify value after finishing. For an already initialized file-reference array:

const files = Ember.A(field.get("value"));

files.pushObject({
  filename: uploaded.filename,
  fileUrl: uploaded.fileUrl
});

field.set("text", files.map(file => file.filename).join(", "));
field.notifyPropertyChange("value");

For an existing object, use Ember.set(object, "property", newValue) for observed nested properties, then update any summary text and call field.notifyPropertyChange("value") once the logical change is ready.

Kianda’s built-in file-upload control uses this notification pattern for its array of file references. Nested changes remain tracked as data; the explicit notification is needed to tell the rule engine that the containing field’s logical value changed.

Do not call both replacement and explicit notification for the same update. Also review rules that write to their own triggering field: a value change can trigger another execution and create a loop. Updating several related fields is not an atomic transaction; rules on each field may observe intermediate state.

Use real child field models when needed

An object property inside field.value is different from a child field model. Use child models when the pieces of a compound control need their own field identities, metadata, or rules.

The parent field’s relationship is fields. Its inverse on each child is parentField. Do not invent a subFields relationship on the field model; a table-row helper with that name is a separate structure.

The following method can be added to a parent component that injects the store service. It returns an existing longitude child or creates it once:

import Ember from "ember";

export default Ember.Component.extend({
  store: Ember.inject.service("store"),

  async ensureLongitudeField() {
    const parent = this.get("field");
    const children = await parent.get("fields");

    if (this.isDestroying || this.isDestroyed ||
        this.get("field") !== parent) {
      return;
    }

    const childName = parent.get("name") + "_longitude";
    let child = children.findBy("name", childName);

    if (!child) {
      child = this.get("store").createRecord("field", {
        title: "Longitude",
        name: childName,
        type: "fields/field-textbox",
        settings: {}
      });

      children.addObject(child);
    }

    return child;
  }
});

Call this from the parent control’s deliberate initialization flow, and await it within that flow. Handle errors there. Do not create children unconditionally on every render or while merely displaying an existing value. The parent and derived child names must remain unique in the process design.

Adding the child through fields uses the model’s inverse relationship. Do not call child.save() or process.save() from this initialization. The normal design or instance save workflow handles persistence.

An alternative is to have the designer select existing utility fields with field-picker. This is useful when those fields already participate in process rules or reporting. The parent then updates the selected models through the process APIs.

7. Resolve the process and referenced fields

Access the wrapping process from the field:

const process = await this.get("field.process");

if (!process) {
  throw new Error("The field's process is not available.");
}

This fragment belongs inside an asynchronous method. The property is normally already resolved, but it can require awaiting at the time of access. await works for either case. Do not copy ad hoc .content unwrapping into every widget; the field model already resolves the wrapping process in its computed property.

Field references from the settings UI

field-picker stores a reference, not the live Ember Data field model. A reference usually includes name, text, type, and fieldType. The reference’s text is its selection label; use the process APIs to read the field’s current data.

With allowText=true, a picker can also contain a literal reference such as { text: "Site", type: "text" }. A destination picker should use allowText=false because a destination must resolve to a real field.

Use a model’s get("value") or get("text") to read its current attributes after resolving it. Check for a missing reference or removed field before accessing it.

For example, this method fragment updates the destination chosen in field.settings.destination. The calling action should await it and handle any error:

async function writeDestination(component, value, text) {
  const ownerField = component.get("field");
  const process = await ownerField.get("process");
  const reference = ownerField.get("settings.destination");

  if (component.isDestroying || component.isDestroyed ||
      component.get("field") !== ownerField ||
      component.get("displayMode") !== "edit" ||
      ownerField.get("enabled") === false ||
      ownerField.get("visible") === false) {
    return;
  }

  if (!process || !reference || reference.type !== "field") {
    throw new Error("Choose a destination field.");
  }

  const destination = process.findFieldByRef(reference);

  if (!destination || destination === ownerField) {
    throw new Error("Choose an existing destination other than this field.");
  }

  await process.setField(destination, value, text);
}

process.setField() triggers rules associated with the affected field. It can return a Promise when, for example, a data-source-backed list or user picker must finish resolving data. Await it whenever subsequent work depends on completion.

Awaiting this API within your own action sequences that action’s work. It does not make Kianda await the entire field component or automatically delay process submission.

8. Build a complete Geolocation field

This example develops the geo-location pattern into a widget that captures location on an explicit user action, optionally watches for updates, and releases the browser watch when it is no longer needed.

Its value contract is:

{
  "latitude": 53.3498,
  "longitude": -6.2603,
  "accuracy": 12
}

The readable coordinates are also stored in field.text. This structured schema is the contract for this tutorial widget. When updating an installed widget that previously stored a comma-separated string, preserve its existing schema or deliberately migrate its consumers and saved data.

Browser geolocation requires a secure context and user permission, and can be restricted by the embedding page’s permissions policy. watchPosition() returns a watch identifier that must be passed to clearWatch() when finished. See the browser geolocation reference.

Widget UI

{{#if (eq this.displayMode "design")}}
  <p class="text-muted">A user can capture a location with this field.</p>
{{/if}}

{{#if (eq this.displayMode "edit")}}
  <p>
    {{#if this.field.text}}
      {{this.field.text}}
    {{else}}
      No location captured.
    {{/if}}
  </p>

  <button
    type="button"
    class="btn btn-default"
    disabled={{this.isBusy}}
    onclick={{action "capture"}}>
    {{#if this.isBusy}}Acquiring location…{{else}}Capture location{{/if}}
  </button>

  {{#if this.isWatching}}
    <button type="button" class="btn btn-default" onclick={{action "stop"}}>
      Stop watching
    </button>
  {{/if}}

  {{#if this.errorMessage}}
    <p class="text-danger" role="alert">{{this.errorMessage}}</p>
  {{/if}}
{{/if}}

{{#if (eq this.displayMode "display")}}
  <p>
    {{#if this.field.text}}
      {{this.field.text}}
    {{else}}
      No location captured.
    {{/if}}
  </p>
{{/if}}

{{#if (eq this.displayMode "settings")}}
  <div class="form-group">
    <label>Continue watching after the first location?</label>
    {{radio-button
      name=(concat this.elementId "-watch-position")
      label="Yes"
      value="yes"
      group=this.field.settings.watchPosition}}
    {{radio-button
      name=(concat this.elementId "-watch-position")
      label="No"
      value="no"
      group=this.field.settings.watchPosition}}
    <p class="help-block">
      Each accepted location update changes the field value and can run its rules.
    </p>
  </div>
{{/if}}

Widget Code

import Ember from "ember";

export default Ember.Component.extend({
  isBusy: false,
  isWatching: false,
  errorMessage: null,
  _watchId: null,
  _requestId: 0,

  settings() {
    const field = this.get("field");

    if (field.get("settings.watchPosition") === undefined) {
      field.set("settings.watchPosition", "no");
    }
  },

  _isEditable() {
    return !this.isDestroying && !this.isDestroyed &&
      this.get("displayMode") === "edit" &&
      this.get("field.enabled") !== false &&
      this.get("field.visible") !== false;
  },

  _accepts(requestId, field) {
    return this._isEditable() && this._requestId === requestId &&
      this.get("field") === field;
  },

  _stopLocation() {
    this._requestId += 1;

    if (this._watchId !== null) {
      navigator.geolocation.clearWatch(this._watchId);
      this._watchId = null;
    }

    if (!this.isDestroying && !this.isDestroyed) {
      this.setProperties({ isBusy: false, isWatching: false });
    }
  },

  stopWhenContextChanges: Ember.observer(
    "displayMode", "field", "field.enabled", "field.visible", function () {
      this._stopLocation();
    }
  ),

  willDestroyElement() {
    this._stopLocation();
    this._super(...arguments);
  },

  actions: {
    capture() {
      if (!this._isEditable()) {
        return;
      }

      this._stopLocation();
      this.set("errorMessage", null);

      if (typeof navigator === "undefined" || !navigator.geolocation) {
        this.set("errorMessage", "Geolocation is not available in this browser.");
        return;
      }

      const requestId = this._requestId;
      const field = this.get("field");
      const watch = field.get("settings.watchPosition") === "yes";
      this.setProperties({ isBusy: true, isWatching: watch });

      const success = position => Ember.run(() => {
        if (!this._accepts(requestId, field)) {
          return;
        }

        const coords = position.coords;
        const value = {
          latitude: coords.latitude,
          longitude: coords.longitude,
          accuracy: coords.accuracy
        };

        this.setProperties({ isBusy: false, errorMessage: null });
        field.set("text", value.latitude + ", " + value.longitude);
        field.set("value", value);
      });

      const failure = error => Ember.run(() => {
        if (!this._accepts(requestId, field)) {
          return;
        }

        this._stopLocation();
        this.set("errorMessage", error.message || "Unable to retrieve your location.");
      });

      const options = {
        enableHighAccuracy: true,
        timeout: 15000,
        maximumAge: 0
      };

      try {
        if (watch) {
          this._watchId = navigator.geolocation.watchPosition(success, failure, options);
        } else {
          navigator.geolocation.getCurrentPosition(success, failure, options);
        }
      } catch (error) {
        failure(error);
      }
    },

    stop() {
      this._stopLocation();
    }
  }
});

Why the example manages callbacks explicitly

The browser can return a position after the user has moved to another form or after a rule has disabled the field. _accepts() checks the request number, the current field model, editability, and component lifetime before allowing a result to update data.

Stopping or replacing a request increments _requestId, so an older callback is ignored. For a watch, the code also calls clearWatch(). Checking the identifier against null is deliberate: a valid identifier of 0 must still be cleared. A single-position request has no equivalent cancellation method here; its late result is simply ignored.

The context observer stops location work when the field or display context changes. Destruction performs the same cleanup. This does not depend on edit() or display() being called again on a mode transition.

In the success callback, component-local state is updated before writing field.value. A rule triggered by the value change may immediately hide or otherwise remove the field, so there is no subsequent component update that assumes the control is still rendered.

Each accepted browser reading replaces the structured value and can trigger attached rules. Watch mode uses one acquisition path rather than starting both a single request and a watch. If the process only needs a final location, leave watching off. Add sampling or meaningful-change thresholds when continuous updates would trigger more work than the workflow needs.

An error remains in errorMessage; it never becomes the field’s coordinate data. The example retains the last successful location if a later attempt fails. If the process requires a fresh capture for each submission, model and validate that requirement explicitly, for example by storing and checking an acquisition timestamp in an extended value contract.

Test this widget

Test acquisition, denied permission, unavailable location, and a timeout. Verify that Designer preview and read-only display do not request location. Enable watching, then stop it, disable the field, and leave the form. In each case, later callbacks should leave the model unchanged. Finally, test two instances on the same form and check that they do not share watch state.

9. Build an asynchronous public-file upload field

An upload control connects two operations: uploading a browser File to a service, and publishing the resulting file reference into the Kianda field model. A successful upload must populate the uploader’s own field if its display view, required validation, and attached rules depend on that result.

The following example is a case study adapted from an existing Kianda widget named upload-public-file. The complete component is included here. It stores a single completed upload as { filename, fileUrl } in field.value and the filename in field.text.

Integration dependencies

The upload transport uses the application adapter, session authorization pattern, and /kianda-files/file response shape used by that implementation. These details are integration dependencies, not a promise that every Kianda deployment exposes an identical public files SDK. Adapt _uploadPublicFile() when your endpoint or authentication contract differs.

This version targets an existing public folder selected in its settings. The request explicitly uses isPublic=true; use it for files intended to be public. A completed upload exists in the remote file service even if the user later closes the form without saving the process.

Widget UI

{{#if (eq this.displayMode "design")}}
  <p class="text-muted">Upload a file to the configured public folder.</p>
{{/if}}

{{#if (eq this.displayMode "edit")}}
  <label for={{concat this.elementId "-file"}}>Choose a public file</label>
  <input
    id={{concat this.elementId "-file"}}
    type="file"
    accept={{this.field.settings.accept}}
    disabled={{this.isBusy}}
    onchange={{action "upload"}}>

  {{#if this.isBusy}}
    <p role="status">Uploading…</p>
  {{/if}}
  {{#if this.errorMessage}}
    <p class="text-danger" role="alert">{{this.errorMessage}}</p>
  {{/if}}
  {{#if this.field.text}}
    <p>Stored file: {{this.field.text}}</p>
  {{/if}}
{{/if}}

{{#if (eq this.displayMode "display")}}
  {{#if this.field.text}}
    <span>{{this.field.text}}</span>
  {{else}}
    <span class="text-muted">No file uploaded.</span>
  {{/if}}
{{/if}}

{{#if (eq this.displayMode "settings")}}
  <div class="form-group">
    <label for={{concat this.elementId "-folder"}}>Existing public folder</label>
    {{input
      id=(concat this.elementId "-folder")
      type="text"
      class="form-control"
      required=true
      value=this.field.settings.folderPath}}
  </div>
  <div class="form-group">
    <label for={{concat this.elementId "-accept"}}>File chooser filter</label>
    {{input
      id=(concat this.elementId "-accept")
      type="text"
      class="form-control"
      value=this.field.settings.accept}}
    <p class="help-block">For example, .pdf or .pdf,.png.</p>
  </div>
{{/if}}

The file selector receives the native event directly. It does not use window.event, and it is only active in edit mode.

The selector intentionally does not bind its native required attribute to field.required. After reopening an instance, a browser file input is empty even when the Kianda field already contains a valid uploaded-file reference. Unconditionally requiring a new local file would force an unnecessary replacement. The field’s stored result participates in Kianda’s required-value validation.

The accept attribute guides the chooser; the receiving service must enforce file requirements. See the file input reference.

Widget Code

import Ember from "ember";

export default Ember.Component.extend({
  store: Ember.inject.service("store"),
  isBusy: false,
  errorMessage: null,
  _requestId: 0,

  settings() {
    const field = this.get("field");

    if (field.get("settings.accept") === undefined) {
      field.set("settings.accept", ".pdf");
    }
  },

  _isEditable() {
    return !this.isDestroying && !this.isDestroyed &&
      this.get("displayMode") === "edit" &&
      this.get("field.enabled") !== false &&
      this.get("field.visible") !== false;
  },

  _accepts(requestId, field) {
    return this._isEditable() && this._requestId === requestId &&
      this.get("field") === field;
  },

  _invalidateUpload() {
    this._requestId += 1;

    if (!this.isDestroying && !this.isDestroyed) {
      this.set("isBusy", false);
    }
  },

  invalidateWhenContextChanges: Ember.observer(
    "displayMode", "field", "field.enabled", "field.visible", function () {
      this._invalidateUpload();
    }
  ),

  willDestroyElement() {
    this._invalidateUpload();
    this._super(...arguments);
  },

  async _uploadPublicFile(file, folderPath) {
    const adapter = this.get("store").adapterFor("application");
    const session = this.get("store.session");
    const headers = new Headers();

    // This integration uses the sample's synchronous authorization callback.
    session.authorize(adapter.get("authorizer"), (name, value) => {
      headers.append(name, value);
    });

    const url = adapter.buildURL() +
      "/kianda-files/file?isPublic=true&folderPath=" +
      encodeURIComponent(folderPath) + "&name=" + encodeURIComponent(file.name);

    const data = new FormData();
    data.append("file", file);

    const response = await fetch(url, {
      method: "POST",
      headers: headers,
      body: data
    });

    if (!response.ok) {
      throw new Error("Upload failed (HTTP " + response.status + ").");
    }

    const result = await response.json();
    const uploaded = result && result.files && result.files[0];

    if (!result || result.success !== true || !uploaded ||
        typeof uploaded.name !== "string" || !uploaded.name ||
        typeof uploaded.path !== "string" || !uploaded.path) {
      throw new Error("The upload service did not return a valid file reference.");
    }

    return { filename: uploaded.name, fileUrl: uploaded.path };
  },

  actions: {
    async upload(event) {
      const input = event.target;
      const file = input.files && input.files[0];

      // Keep the File object, but allow the same file to be selected for a retry.
      input.value = "";

      if (!file || !this._isEditable() || this.get("isBusy")) {
        return;
      }

      const field = this.get("field");
      const folderPath = String(field.get("settings.folderPath") || "").trim();

      if (!folderPath) {
        this.set("errorMessage", "Configure an existing public folder first.");
        return;
      }

      const requestId = ++this._requestId;
      this.setProperties({ isBusy: true, errorMessage: null });

      try {
        const uploaded = await this._uploadPublicFile(file, folderPath);

        Ember.run(() => {
          if (!this._accepts(requestId, field)) {
            return;
          }

          this.setProperties({ isBusy: false, errorMessage: null });
          field.set("text", uploaded.filename);
          field.set("value", uploaded);
        });
      } catch (error) {
        Ember.run(() => {
          if (!this._accepts(requestId, field)) {
            return;
          }

          this.setProperties({
            isBusy: false,
            errorMessage: error.message || "The file could not be uploaded."
          });
        });
      }
    }
  }
});

The authorization callback above follows the source widget’s session integration. If your session API supplies authorization asynchronously, obtain and await that authorization before starting fetch().

The helper checks both HTTP status and the application response. fetch() does not reject simply because a server returns an HTTP error. When sending FormData, let the browser generate the multipart Content-Type boundary rather than setting that header yourself. These behaviours are covered in the Fetch guide and FormData guide.

If your widget also creates folders, validate the file selection and configuration before making that request, encode folder parameters, and check the folder operation’s application result before uploading. Define how your endpoint treats an already-existing folder instead of assuming every folder response indicates success.

Coordinate upload results with the process

The component only publishes a completed file reference. During the request, loading and failure state stay local. A failed replacement leaves the previous successful upload in the field. If the workflow requires the replacement to finish, add explicit validation for that requirement; isBusy alone does not prevent submission.

The request counter prevents a late result from being applied after the field becomes read-only, is replaced, or is destroyed. It does not cancel or reverse an upload already accepted by the service. A process save also does not wait for this component’s request merely because its action is asynchronous.

To mirror the result into utility fields, add field-picker settings such as those in section 5, resolve the references through field.process, and await each process.setField() call. Validate both destinations before starting the upload. Perform any required copies before publishing the uploader’s final field.value if its attached rules depend on those copies.

Each target update can run that target’s rules. There is no atomic update across the upload service, the utility fields, and the uploader. Handle partial completion in the surrounding workflow when those operations must stay coordinated.

10. Integrate an external control: the Stripe example

This case study draws on an existing Kianda widget named stripe-card. Its Designer settings identify customer and pricing fields, injected services communicate with a connector, and an external SDK renders into the component’s DOM. The relevant architecture and lessons are described below; the original payment implementation is not needed to follow them.

A payment implementation also has its own backend and SDK contract. The example’s connector operations, payment protocol, and legacy confirmation flow should be reviewed as an application integration. They are not additional Kianda field lifecycle hooks.

Give each view a clear purpose

Initialize, mount, and clean up deliberately

Use these steps for an SDK-backed field:

1. Resolve configuration and services. Validate required field references and load the integration configuration. Inject services through Ember.inject.service(...) where needed.
2. Load the SDK once through a shared loader. Cache an in-flight load Promise so multiple instances do not independently repeat script loading. Handle load failure and define retry behaviour.
3. Wait until the component has a DOM container. Start editable initialization from edit() or the appropriate insertion hook. Do not mount an external element inside async init().
4. Recheck the context after asynchronous work. The component must still exist, refer to the same field, and be editable before mounting or applying a result.
5. Scope DOM access to the component. For example, resolve a .payment-container beneath this.element. Do not rely on one global ID shared by multiple field instances.
6. Release the external control and listeners. Tear down when leaving the relevant mode and on destruction. If the component later becomes editable again, initialize a fresh external control as needed.

For Stripe, load Stripe.js directly from Stripe as described in its current integration guide. Its mount() method accepts a DOM container, and destroy() disposes of an Element. A destroyed Element cannot be remounted.

Kianda does not await the field’s initialization hook. The component must catch initialization errors, show a loading/error state, and prevent its own payment action until its dependencies are ready. Component readiness is separate from process submission validation.

Keep payment data and field state consistent

An external Element does not automatically synchronize its state into the Kianda model. Translate an appropriate integration result into field.text and field.value using the same notification rules as every other custom field.

Keep card-entry data in Stripe’s hosted control. Store suitable references and status information in the process, and keep secret-key operations in the backend. A label such as "Payment successful" in the browser is not the authority for fulfillment: use server-confirmed payment state and the integration’s webhook workflow. Stripe’s payment-status guidance explains how to respond to confirmed outcomes even when the customer leaves the page.

If you store an in-progress payment reference, configure business validation against the required status. A nonempty object alone can satisfy a missing-input check while the payment still needs action.

Review the legacy example before adopting its payment flow

Several implementation details in the earlier stripe-card pattern need deliberate treatment:

• Initialization must exclude Designer preview. Skipping only settings and display still allows work in design mode. Check explicitly for edit.
• A command string in field.value is an application convention. A value such as "start_payment" triggers the normal field-value observer and also occupies persisted business data. Prefer an explicit component action for a user operation. If an application retains a command convention, coordinate consumption, rule triggering, and validation explicitly.
• Sequence asynchronous stages through methods you can await. Do not assume dispatching an action through this.send(...) makes the surrounding flow wait for payment completion. Catch errors where the component owns the operation.
• Use the confirmation flow for the chosen Stripe integration. Do not copy the legacy confirmPaymentIntent(...) call or replace its name without reviewing the backend protocol. Stripe’s current documentation distinguishes integration-specific flows; its card PaymentIntent confirmation reference describes one such path.
• Prefer the SDK’s supported authentication handling. A hand-built iframe/modal flow adds lifecycle and message-handling obligations. If an integration genuinely needs postMessage, verify the sender’s origin and source, validate the payload, and remove the listener during teardown. See the browser messaging reference.

This case study explains the field-component responsibilities. A deployable payment flow additionally needs the matching connector/backend implementation and verification against the Stripe API version and integration being used.

11. Reuse platform components and Ember features

Custom field templates can use ordinary HTML, Ember’s native helpers, and Kianda components. Bind configuration controls to field.settings; bind user input to the field data contract or route it through an action when you need to coordinate text, value, and notifications.

Common platform components

For example, the following are settings fragments for a widget that selects a source, recipients, and message content:

{{field-picker
  process=this.field.process
  required=true
  allowText=false
  selectForms=false
  selectFields=true
  selectTable=true
  showButtons=true
  value=this.field.settings.selectedField}}

{{person-picker value=this.field.settings.users}}

{{rich-text
  contents=this.field.settings.message
  height=220
  sanitize=true
  showCodeview=false
  showImageDialog=true
  showFontName=false}}

Putting these controls in the settings branch changes Designer configuration. If you instead use a picker or editor for runtime field input, ensure its changes update the intended field.value and field.text contract. A binding into a nested property does not automatically provide the containing field’s rule notification.

Available addons and conventions

The environment described in this guide includes:

Use classic Ember properties, computed properties, actions, observers where appropriate, and service injection. Allocate mutable component-local arrays or objects per instance in init() rather than sharing a single mutable object on the component definition. Prefer native Promises and async/await for new asynchronous code.

Keep styles scoped to the widget’s root or a distinctive CSS class. Use component-instance IDs such as this.elementId when associating labels, inputs, or radio groups. Use escaped template expressions for text such as filenames and error messages; render intended rich content through the appropriate rich-text component and its sanitization options.

The examples use Ember 2.18 component and template syntax. Do not assume that APIs from newer Ember applications, such as Octane-style tracked properties, are available in this environment. See the Ember 2.18 component guide and service guide for the corresponding framework conventions.

12. Compile, debug, and verify the widget

Clicking Update in Developer precompiles the widget with Babel and generates a source map (.map) under public files. Use browser developer tools to inspect the loaded code, network requests, and asynchronous errors. The custom-widget debugging guide explains how to work with custom widget source.

Test configuration in Designer and runtime behaviour in a process instance. Saving widget code, saving a process design, and saving an instance’s data are distinct operations.

What to verify before reuse

Use the rule debugger when a value update triggers unexpected rule behaviour. Trace the value notification and the affected field’s rules. Repeated execution often comes from redundant notifications or a rule that writes back into its own trigger path.

Common problems

Related documentation

• Rule widget development
• Custom controls
• Control properties
• Validate input
• Field Display mode
• Custom widget debugging
• Ember 2.18 component lifecycle

2 - Rule widget development

A custom rule widget implements a reusable business action in Kianda. It can transform field values, update process data, copy table rows, or call a service. Process designers configure the action and attach it to a process, form, or field using the rule designer.

This guide shows how to build a complete Format text rule, add configuration validation, and develop an asynchronous Generate custom ID rule. It also explains the runtime context, field APIs, reusable UI components, and patterns needed for more advanced rules.

The examples target Kianda’s Ember.js widget environment and use classic Ember components, Handlebars, and native JavaScript Promises.

How a rule widget works

A rule widget has two parts:

At design time, Kianda can render the complete component and its template. You can use Ember properties, computed properties, actions, lifecycle hooks, and other components to build the settings interface.

At runtime, Kianda resolves and instantiates the component class, supplies its execution context, and calls execute(). It does not render the rule’s Handlebars template. The action runs, completes, and returns control to the rule engine.

This is the main distinction from a field widget: a field widget provides a control that is rendered in a form; a rule widget performs an action. A rule may update a field that is already rendered, but its own template is the rule’s configuration interface.

Execution and persistence

Keep these behaviours in mind throughout development:

• execute() is the only runtime entry point. It may be synchronous or asynchronous. The engine waits for a returned Promise to settle. Prefer async execute() for work that may be asynchronous.
• Return values are ignored. Returning false, an object, or a calculated value does not communicate a result or stop the rule sequence. Write business results into the appropriate process, form, or field model.
• Process changes are normally saved by a Save rule. A custom rule usually modifies the current process instance. It does not need to save the instance itself. An external API call can have its own immediate side effects, independently of a later process save.
• Errors do not stop subsequent rules. If execution throws or its returned Promise rejects, Kianda logs the error, records it on the rule, and displays it to the end user in an interactive session. The engine then continues execution. Configure conditions on later rules when they depend on this action succeeding.

1. Create a rule widget

You need access to Administration > Developer, normally through an Administrator or Developer role. You should be familiar with JavaScript and HTML; the examples introduce the Ember and Handlebars conventions they use.

1. Open Administration > Developer.
2. Click New widget.
3. Enter a title, such as Format text, and choose its unique ID and icon.
4. Select Rule as the widget type and confirm the dialog.
5. Open the widget’s Widget UI and Widget Code editors.

Use the JavaScript module structure below. Kianda loads the component; you do not need to create or mount a component instance yourself.

import Ember from "ember";

export default Ember.Component.extend({
  settings() {
    // Called when the rule opens for configuration in Designer.
  },

  execute() {
    // Called by the rule engine when the rule runs.
  }
});

this inside these methods is the component instance. Use this.get("rule") and this.get("process") to access the supplied models. Define these methods using normal function or method syntax; an arrow function used as the method itself would capture a different this.

2. Build a complete Format text rule

This rule reads either a field’s displayed text or literal text entered by the designer, trims surrounding whitespace, optionally converts it to uppercase, and writes the result into a destination text field.

It demonstrates three useful patterns: storing configuration in rule.settings, resolving a field-or-text reference, and awaiting a field update.

Widget UI

Paste this complete template into Widget UI:

<div class="form-group">
  <label class="control-label">Text to format</label>
  {{field-picker
    process=process
    required=true
    allowText=true
    selectForms=false
    selectFields=true
    value=rule.settings.source}}
  <p class="help-block">Choose a field or enter literal text.</p>
</div>

<div class="form-group">
  <label class="control-label">Letter case</label>
  {{radio-button
    default=true
    name="formatTextCase"
    label="Keep existing case"
    value="preserve"
    group=rule.settings.caseMode}}
  {{radio-button
    name="formatTextCase"
    label="Uppercase"
    value="upper"
    group=rule.settings.caseMode}}
</div>

<div class="form-group {{errors.destination}}">
  <label class="control-label">Destination text field</label>
  {{field-picker
    process=process
    required=true
    allowText=false
    selectForms=false
    selectFields=true
    value=rule.settings.destination}}
  <p class="help-block">Select a text field different from the source.</p>
</div>

The inputs bind to the rule’s settings. The component’s field property represents the field that triggers the rule, if any; it is not the place to store rule configuration.

allowText=true allows the source to be a field reference or literal text. The destination uses allowText=false because the rule must update a real field. required=true prevents the rule configuration from being saved without the required input. The optional errors.destination class is used by the custom validation example later in this guide.

Widget Code

Paste this complete module into Widget Code:

import Ember from "ember";

export default Ember.Component.extend({
  settings() {
    const rule = this.get("rule");

    if (rule.get("settings.caseMode") === undefined) {
      rule.set("settings.caseMode", "preserve");
    }
  },

  async execute() {
    const process = this.get("process");
    const rule = this.get("rule");
    const sourceRef = rule.get("settings.source");
    const destinationRef = rule.get("settings.destination");
    const caseMode = rule.get("settings.caseMode") || "preserve";

    if (!sourceRef ||
        (sourceRef.type !== "field" && sourceRef.type !== "text")) {
      throw new Error("Format text: select a source field or enter text.");
    }

    if (!destinationRef || destinationRef.type !== "field") {
      throw new Error("Format text: select a destination field.");
    }

    const destination = process.findFieldByRef(destinationRef);

    if (!destination) {
      throw new Error("Format text: the destination field no longer exists.");
    }

    if (sourceRef.type === "field" &&
        sourceRef.name === destinationRef.name) {
      throw new Error("Format text: source and destination must be different.");
    }

    const sourceText = process.getFieldRefText(sourceRef);

    if (sourceText === undefined || sourceText === null) {
      throw new Error("Format text: the source text could not be read.");
    }

    if (caseMode !== "preserve" && caseMode !== "upper") {
      throw new Error("Format text: the configured letter case is invalid.");
    }

    let result = String(sourceText).trim();

    if (caseMode === "upper") {
      result = result.toUpperCase();
    }

    await process.setField(destination, result);
  }
});

Why the example uses async

process.setField() can return a Promise when the destination needs to resolve data, such as a list connected to a data source or a user picker. Awaiting the call keeps this rule’s completion tied to the field update. await also accepts a synchronous result, so the same pattern works for ordinary text fields.

The settings() method only supplies an editing default. The runtime also has a fallback for caseMode, because execute() must work from the saved configuration without relying on the settings UI having run in the runtime component.

Configure and test the rule

1. Click Update to compile the widget.
2. Open a test process in Administration > Designer.
3. Add two text fields, such as Source text and Formatted text, and a button called Format. Save the process design so its fields are available for selection.
4. Select the Format button and add Format text from Rules > Custom.
5. Select the source field, choose Uppercase, and select the destination text field. Save the rule configuration and the process design.
6. Preview the process. Enter inspection due in the source field, then click Format. The destination should become INSPECTION DUE.
7. Reopen the rule’s configuration and try a literal source instead of a field. Verify that it produces the same kind of output.

The changed destination value is part of the current process instance. Use the process’s normal Save rule to persist it; for example, place a Save rule after the formatting action if that is the intended workflow.

Start by attaching the example to a separate button. Setting a field triggers rules associated with that field. A rule that writes back to its own triggering field, or a pair of rules that repeatedly update each other, can create a recursive execution loop. The source/destination check above catches one configuration mistake; it does not prevent every possible rule cycle.

3. Understand the runtime context

Kianda supplies the following component properties when it executes a rule:

For example, the Format text rule is attached to a button, but updates the destination selected by the designer. Reading this.get("field") would identify the button rather than the destination.

The runtime loads the class through Kianda’s component factory. DOM creation is not part of that execution path: do not require this.element, a rendered template, a button click inside the settings UI, or didInsertElement() to prepare values needed by execute().

Relevant rule model properties

The rule model is an Ember model. Access its properties with rule.get(...) and update settings with rule.set(...) so Ember observes the changes.

For a normal widget, focus on your own settings and execution logic. The engine handles the rule’s standard orchestration properties; you do not need to reproduce that orchestration in every execute() method.

The engine also writes execution diagnostics into the settings hash:

Treat these as engine-managed diagnostics. Do not use the same names for custom configuration, overwrite the entire settings hash, or set these properties to signal success or failure. Let execute() complete or throw instead. Do not assume a previous error is cleared unless you have verified that behaviour for the runtime you are inspecting.

4. Read and update fields

A field picker stores a reference, not the live field model. A typical field reference contains:

For example, a literal selection may be stored as:

{
  "type": "text",
  "text": "Site"
}

Retain the reference produced by the picker. Resolve it against the current process when executing the rule; do not cache a live field model from the Designer component for later execution.

Field API reference

For fields with separate display text and underlying values, preserve that distinction. A list can display a label while storing an identifier; user pickers, file fields, and other specialised fields can use richer values. Do not assume that every value is a string, or that display text is interchangeable with it.

For example, this fragment inside an async execute() copies the underlying value and display text between compatible fields:

const process = this.get("process");
const rule = this.get("rule");
const source = process.findFieldByName(rule.get("settings.source.name"));
const destination = process.findFieldByName(
  rule.get("settings.destination.name")
);

if (!source || !destination) {
  throw new Error("Copy field: source or destination could not be found.");
}

await process.setField(
  destination,
  source.get("value"),
  source.get("text")
);

Use this form only when the destination accepts the source’s value shape. The Format text tutorial deliberately uses displayed text and writes a plain string to a text field.

Prefer process.setField() for field data changes so the platform handles value resolution and related rules. Changing a DOM element only changes its presentation; it does not reliably update the process model. Directly assigning a model’s text or value also does not express the same platform operation as setField().

5. Initialise and validate configuration

Kianda automatically creates rule.settings. Use the widget’s settings() method to initialise missing configuration when the rule opens in Designer.

Initialise each setting independently, and preserve values already chosen by the designer:

settings() {
  const rule = this.get("rule");

  if (rule.get("settings.inputMapping") === undefined) {
    rule.set("settings.inputMapping", [{}]);
  }

  if (rule.get("settings.outputMapping") === undefined) {
    rule.set("settings.outputMapping", []);
  }

  if (rule.get("settings.errorMapping") === undefined) {
    rule.set("settings.errorMapping", []);
  }
}

This is a component-method fragment illustrating mapping configuration. The property names are chosen by that widget; they do not automatically create mapping behaviour. Your UI and executor must use the settings you define.

Required inputs and the saving event

Inputs and field pickers with required=true prevent an incomplete rule configuration from being saved. Use the rule model’s saving event for checks that involve multiple settings or business rules, such as requiring different source and destination fields or at least one key column.

When the designer saves the rule configuration, the handler receives an argument object. To reject that save:

1. Set args.isError = true.
2. Append a useful message to args.errors.
3. Optionally set component properties that highlight the relevant controls.

Keep this handler synchronous. Preserve errors added by other handlers: do not reset args.isError to false or replace args.errors. This event validates the rule’s configuration in Designer; it is separate from a Save rule that persists a process instance.

Add semantic validation to Format text

The following is an extension to the Format text component, not a separate module. Replace its existing settings() method with the version below and add the other members inside the same Ember.Component.extend({ ... }) object. Keep its execute() method unchanged.

_settingsRule: null,

settings() {
  this._detachSettingsValidation();

  const rule = this.get("rule");

  if (rule.get("settings.caseMode") === undefined) {
    rule.set("settings.caseMode", "preserve");
  }

  this.set("errors", {});
  this._settingsRule = rule;
  rule.on("saving", this, this._validateSettings);
},

_validateSettings(args) {
  const rule = this._settingsRule;
  const source = rule.get("settings.source");
  const destination = rule.get("settings.destination");

  this.set("errors", {});

  if (source && destination &&
      source.type === "field" &&
      source.name === destination.name) {
    this.set("errors.destination", "has-error");
    args.isError = true;
    args.errors.push("Source and destination must be different fields.");
  }
},

_detachSettingsValidation() {
  if (this._settingsRule) {
    this._settingsRule.off("saving", this, this._validateSettings);
    this._settingsRule = null;
  }
},

willDestroy() {
  this._detachSettingsValidation();
  this._super(...arguments);
}

The template already binds errors.destination to the destination control’s wrapper. This handler uses that property to add a has-error class.

The named callback and matching on/off calls avoid accumulating listeners when the settings editor is opened repeatedly. Cleanup remembers the model that received the listener, so it removes the handler from that same model. These subscription methods are documented in the Ember 2.18 Evented API.

Runtime checks are still necessary. A field may have been removed, or an older saved configuration may not contain a setting added in a newer widget version. Designer validation improves configuration quality; it does not replace validation inside execute().

6. Write asynchronous rules

Prefer async execute() and native Promises for asynchronous work. Kianda also supports a non-async execute() that returns a Promise. The important requirement is that all work needed for completion belongs to the returned asynchronous operation.

Avoid introducing RSVP Promises into new widget examples. Native async/await is the recommended authoring pattern. When integrating a callback-based API, adapt its documented completion and error callbacks to a native Promise and await it. Do not assume that declaring the outer method async automatically waits for callbacks started inside it.

Also avoid array.forEach(async function (...) { ... }) for work that must finish before the rule returns. Use a loop with await for sequential work. Parallel operations require deliberate coordination, especially when they change the same process fields or share table row context.

Example: Generate a custom ID

This example generates a value such as INCIDENT_2026_00042. The designer supplies a prefix/namespace and a destination text field. The rule resolves date tags and expressions, requests a counter value for that namespace, pads the numeric suffix to a minimum of five digits, and updates the field.

The example uses Kianda’s kiandaforms/common expression helper and the /api/counter/up endpoint. Those calls provide the counter-specific behaviour; the component structure and asynchronous execution pattern apply to other integrations too.

Create a second rule widget named Generate custom ID.

Widget UI

<div class="form-group">
  <label class="control-label">ID prefix / counter namespace</label>
  {{input
    type="text"
    required=true
    class="form-control"
    placeholder="INCIDENT_{YYYY}_"
    value=rule.settings.namespace}}
  <p class="help-block">
    Supported date tags: {YYYY}, {YY}, {MM}, {MMM}, {MMMM}.
    Kianda field expressions such as [FieldName] can also be used.
  </p>
</div>

<div class="form-group">
  <label class="control-label">Destination text field</label>
  {{field-picker
    process=process
    required=true
    allowText=false
    selectForms=false
    selectFields=true
    value=rule.settings.field}}
</div>

Widget Code

import Ember from "ember";

export default Ember.Component.extend({
  async execute() {
    const process = this.get("process");
    const rule = this.get("rule");
    const destinationRef = rule.get("settings.field");

    if (!destinationRef || destinationRef.type !== "field") {
      throw new Error("Generate custom ID: select a destination field.");
    }

    const destination = process.findFieldByRef(destinationRef);

    if (!destination) {
      throw new Error("Generate custom ID: the destination field was not found.");
    }

    let namespace = rule.get("settings.namespace");

    if (typeof namespace !== "string" || namespace.trim() === "") {
      throw new Error("Generate custom ID: enter an ID prefix.");
    }

    // Use one captured date for every tag in this execution.
    const now = moment();

    namespace = namespace.trim().replace(
      /\{(YYYY|MMMM|MMM|MM|YY)\}/g,
      function (match, token) {
        return now.format(token);
      }
    );

    const common = require("kiandaforms/common").default;
    namespace = common.evaluateExpression(namespace, process, true);

    if (namespace === undefined || namespace === null ||
        String(namespace).trim() === "") {
      throw new Error("Generate custom ID: the prefix resolved to an empty value.");
    }

    namespace = String(namespace).trim();

    let response;

    try {
      // A data object lets jQuery encode the namespace as a query parameter.
      response = await $.getJSON("/api/counter/up", { namespace: namespace });
    } catch (requestError) {
      const status = requestError && requestError.status;
      const detail = status ? " (HTTP " + status + ")" : "";
      throw new Error("Generate custom ID: the counter request failed" + detail + ".");
    }

    if (!response || response.success !== true ||
        response.value === undefined || response.value === null) {
      throw new Error("Generate custom ID: the counter did not return a value.");
    }

    let suffix = String(response.value);

    if (!/^\d+$/.test(suffix)) {
      throw new Error("Generate custom ID: the counter value is not a non-negative integer.");
    }

    // Five digits is a minimum width; larger values are not truncated.
    while (suffix.length < 5) {
      suffix = "0" + suffix;
    }

    await process.setField(destination, namespace + suffix);
  }
});

This module needs no settings() method because it does not initialise defaults or register custom configuration behaviour. Its required controls provide the initial Designer checks, and execute() validates again before requesting a counter value.

Several implementation details matter:

• The date replacement is global, so a tag used more than once is replaced throughout the prefix. moment() is captured once, preventing different date lookups within the same execution.
• [FieldName] expressions are resolved through the Kianda expression helper after the date tags. Do not evaluate a designer’s expression with JavaScript eval().
• The namespace is passed as request data, so characters such as & and # are encoded instead of altering the query string.
• HTTP success is distinct from application success. A response with success: false must be treated as a failed operation.
• The field assignment is awaited as well as the HTTP request.

The date tags use the execution environment’s Moment date and locale settings. If the ID scheme needs a fixed timezone or locale, define that requirement explicitly rather than assuming browser and background-task defaults are identical.

Choose when generation should occur

Configure the rule’s conditions so it generates an ID only when the intended action requires one—for example, when the destination is empty. Repeated execution can request another counter value and overwrite the destination. An empty-field condition helps control normal workflow execution but is not a concurrency guarantee.

A counter request has a server-side effect before the process instance is saved. A later failure, cancelled form, or repeated request can consume a value without retaining the generated ID. This widget does not promise gapless numbering, exactly-once allocation, or automatic rollback of counter values.

For a test run, configure INCIDENT_{YYYY}_, select a text destination, and execute the rule from a separate button. Verify the date prefix, numeric suffix, and subsequent persistence through the normal process save. The suffix depends on the namespace’s current counter state, so it need not start at 00001.

Error handling and dependent rules

Throw an Error with a useful message when the rule cannot perform its action. If you catch an error to add context, rethrow when the operation should still be reported as failed. A catch block that only logs and then returns makes the executor appear to have completed successfully.

Kianda captures execution failures in the event logs and rule.settings.lastError. Successful execution records rule.settings.lastExecuted. In an interactive session, an execution error is also shown to the end user.

The engine continues to subsequent rules after a failure. Neither throw nor return false cancels the overall sequence. Where later actions depend on success, design explicit conditions around the result or a dedicated outcome field. If you use an outcome field, reset it at the beginning of each attempt and set it to success only after all required work completes; otherwise a previous successful value may incorrectly allow later actions.

Also account for partial changes: if an action updates two fields and fails while updating a third, throwing an error does not imply that the first two updates or an external API operation were rolled back. Decide how later Save rules and other business actions should handle that state.

7. Build richer settings interfaces

The .hbs template is a normal Ember component template. Use HTML and native Ember helpers alongside Kianda’s reusable components. Keep persistent configuration on rule.settings; use component properties for temporary UI state such as expanded sections and validation highlights.

Common platform components

Field picker

This configuration exposes field/table selection and stores the selected reference on the rule:

{{field-picker
  required=true
  allowText=false
  selectForms=false
  selectFields=true
  selectTable=true
  showButtons=true
  value=rule.settings.selectedField
  process=process}}

Use the picker options appropriate to the operation. For example, the table-copy widget restricts its choices to the table component types:

{{field-picker
  required=true
  includes='["fields/field-table", "fields/field-table2"]'
  allowText=false
  value=rule.settings.tableFrom
  process=process}}

Use allowText=true for source inputs that can accept a constant. Resolve such inputs with process.getFieldRefText() instead of assuming every reference has a field name.

Radio buttons

Buttons in one option group share a name and bind to the same group property. Their value properties represent the stored choice; their labels are the text shown to the designer.

{{radio-button
  default=true
  name="copyMode"
  label="Override"
  value="override"
  group=rule.settings.copyMode}}
{{radio-button
  name="copyMode"
  label="Append"
  value="append"
  group=rule.settings.copyMode}}

This is a UI example; the widget’s execute() must implement the selected behaviour. Use settings() to supply missing stored defaults where needed, and keep an appropriate runtime fallback for older configurations.

Person picker

For a simple selection stored on the rule:

{{person-picker value=rule.settings.users}}

More advanced configurations can use options such as showPrincipalMenu, showPerson, showGroup, showPartner, principalType, memberOf, and maxSelectedItems. Bind the settings your rule needs, and handle the returned selection’s structure in your executor. Do not assume that the returned value is a single username string.

Rich-text editor

{{rich-text
  class="modern-richtext-editor"
  contents=rule.settings.message
  height=220
  sanitize=true
  showCodeview=false
  showImageDialog=true
  showFontName=false}}

This stores the editor contents in the rule’s configuration. Rendering an editor does not send a message or update a process field; the executor must use the configured contents for the intended action.

Conditional UI and component actions

Use ember-truth-helpers to show settings that are relevant to the selected mode:

{{#if (or (eq rule.settings.copyMode "unique")
          (eq rule.settings.copyMode "merge"))}}
  <p class="help-block">Select at least one destination key column.</p>
{{/if}}

For repeatable configuration items, use component actions and Ember-aware array updates. This component fragment adds and removes entries from a list of selected key columns:

actions: {
  addColumn() {
    let columns = this.get("rule.settings.keyColumns");

    if (!columns) {
      columns = Ember.A();
      this.set("rule.settings.keyColumns", columns);
    }

    Ember.A(columns).pushObject({ field: null });
  },

  removeColumn(column) {
    const columns = this.get("rule.settings.keyColumns");

    if (columns) {
      Ember.A(columns).removeObject(column);
    }
  }
}

Buttons in the settings template can invoke those actions:

{{#each rule.settings.keyColumns as |column|}}
  <div class="form-group">
    {{field-picker
      process=process
      allowText=false
      required=true
      value=column.field}}
    <button type="button" class="btn btn-default"
      {{action "removeColumn" column}}>Remove</button>
  </div>
{{/each}}

<button type="button" class="btn btn-primary"
  {{action "addColumn"}}>Add key column</button>

The excerpt illustrates editing a list of references. A table-specific UI should additionally restrict those choices to the destination table’s columns. The executor must validate that the selected keys belong to its destination and are included in the mapping.

Available addons

The environment covered by this guide includes:

Use the available platform components before introducing another UI dependency. The Ember 2.18 component guides provide additional background on classic component development.

8. Develop table-processing rules carefully

A rule such as Copy unique rows combines several techniques: source and destination table pickers, a conditions editor, input/output mapping, mode selection, and repeatable key-column settings.

Its Designer UI can use rules/rule-conditions to edit a filter and input-mapping to configure column mappings. These components prepare configuration; the runtime code still needs to evaluate conditions and apply the mappings.

For example, the conditions editor can bind a serialised filter to the rule:

{{rules/rule-conditions
  btnText="Copy row conditions"
  leftUseList=true
  leftNodeList=rule.settings.tableFrom.rows
  conditions=rule.settings.filter
  process=process
  serialize=true}}