Note: Nintex Apps data centers are located in West US and Australia (AUS). In-region processing of Nintex Apps data is only available in these regions.

Note: 

All code samples below refer to the skuid object.

In the v2 API, this object is not directly accessible when working within a browser console—or when referring to another Nintex Apps page runtime.

If you are experiencing issues, use the skuid.runtime API to target the appropriate page context.

skuid.events

skuid.events.publish(event,data)

Publishes an Event

Arguments:
  • event ( string ) -- The name of the event that you are publishing. We recommend namespacing your event names to prevent conflicts, e.g. "acme.chart.refresh" instead of "chartRefresh"
  • data ( array ) -- (Optional) A JavaScript Array containing any additional data that you want to provide to subscribers when your event is published. The items in the Array will become arguments passed in to functions that have subscribed to this event. We recommend that your Array contain only one item, and that this item be a JavaScript object.

skuid.events.subscribe(event,callback)

Establishes an Event subscription

Arguments: Returns object:
  • event ( string ) -- The name of the event that you are subscribing to, e.g. "chart.refresh", "models.loaded"
  • callback ( function(data) ) -- A function to call whenever the specified event is published. Depending on the event, this function may be passed a single argument or multiple arguments of data associated with the event.

A subscription "handle" which can be used to unsubscribe

Note:  If using the Publish event action, this API can only subscribe to events published to All active pages.

skuid.events.subscribeOnce(event,callback)

Subscribe for a single event --- after it happens once, unsubscribe

Arguments:
  • event ( string ) -- The name of the event that you are subscribing to, e.g. "chart.refresh", "models.loaded"
  • callback ( function(data) ) -- A function to call whenever the specified event is published. Depending on the event type, this function may be passed a single argument containing additional data about the event.

skuid.events.unsubscribe(subscription)

Removes a particular event subscription, such that the registered callback will no longer be invoked when the associated event is published.

Arguments:
  • subscription ( object|array ) -- A single subscription returned from calling subscribe(), or an Array of such subscriptions.

Nintex Apps Events Reference

The following is a list of the standard Events published by Nintex Apps. For each Event, two pieces of information are provided:

  1. The situation in which Nintex Apps publishes the event
  2. The additional data that Nintex Apps provides to event subscribers

Models

Rows

Property Type Required Description
skuid.events.models.cancelled object No

Published:

at the end of a call to model.cancel() or skuid.model.cancel([modelsArray]) call, after all changes have been thrown out of the models and any original data has been restored

Data:

  • models (): A JavaScript object containing the names of the Nintex Apps models which were canceled as its keys and the actual skuid.model.Model objects as its values.
  • initiatorId ( string ): The page-unique ID of the Ui Component, if any, that originally called the cancel() method.
skuid.events.models.loaded object No

Published:

at the end of a successful call to model.updateData() or skuid.model.updateData([modelsArray]) call, after the models have been updated to include the new data retrieved from the server at the end of a successful call to model.load() or skuid.model.load([modelsArray]) call, after the models have been updated to include the new data retrieved from the server

Data:

  • models (): A JavaScript object containing the names of the Nintex Apps models which were loaded or updated as its keys and the actual skuid.model.Model objects as its values.
  • initiatorId ( string ): The page-unique ID of the Ui Component, if any, that originally called the updateData() or load() method.
skuid.events.models.saveInitiated object No

Published:

while a call to model.save() or skuid.model.save([modelsArray]) is still in progress and before any validation has been performed

Data:

  • models (): A JavaScript object containing the names of the Nintex Apps models as its keys and the actual skuid.model.Model objects as its values.

  • initiatorId ( string ): The page-unique ID of the Ui Component, if any, that originally initiated the save. This is generally present, and is usually the ID of a skuid.ui.Editor, useful for preventing infinite loops.

    For example, your component is involved in two save operations: it causes a model to save, but it also wants to subscribe to the save event as a way of responding to save events triggered by a different Ui Component on the same model. In this instance, it is helpful to know whether it was your component, or a different component, which initiated the save operation.

skuid.events.models.saved array of Message objects No

Published:

after a call to model.save() or skuid.model.save([modelsArray]) has finished, and—if the save was successful—after the models have been adjusted to reflect the successful changes, whether inserts, updates, or deletes, to the models involved

Note:  Check the totalsuccess property to confirm that the save operation was successful.

Data:

  • messages (): An array containing a Message object for any messages that were applied during the save

  • models ( object ): A JavaScript object containing the names of the Nintex Apps models as its keys and the actual skuid.model.Model objects as its values.

  • initiatorId ( string ): The page-unique ID of the Ui Component, if any, that originally initiated the save. This is generally present, and is usually the ID of a skuid.ui.Editor, useful for preventing infinite loops.

    For example, your component is involved in two save operations: it causes a model to save, but it also wants to subscribe to the save event as a way of responding to save events triggered by a different Ui Component on the same model. In this instance, it is helpful to know whether it was your component, or a different component, which initiated the save operation.

  • totalsuccess ( boolean ): A Boolean that is true only if all save operations (whether inserts, updates, and/or deletes), on all rows, on all models involved, had no errors. This is the property that ensures the save was successful.

  • insertResults ( array of objects ): An array of Nintex Apps InsertResult objects, which have the following properties:

    • id ( string ): The 18-digit Salesforce ID of the newly-inserted record
    • oldId ( string ): The temporary ID of the record before it was saved
    • success ( boolean ): True if the record was successfully inserted, false if there were errors, whether on the individual record, or, if the "Rollback entire save on any error" option was saved, if there was an error on some other record that was part of the save)
    • errors (): An array containing a Message object for each blocking connection error that occurred on this record, preventing it from being inserted
    • messages (): An array containing a Message object for any non-blocking info or warning messages that were applied to this row using skuid.utils.AddRowWarning(rowIndex,message)

  • updateResults ( array of objects ): An array of Nintex Apps UpdateResult objects, which have the following properties:

    • id ( string ): The 18-digit Salesforce ID of the record for which an update was attempted
    • success ( boolean ): True if the record was successfully updated, false if there were errors, whether on the individual record, or, if the "Rollback entire save on any error" option was saved, if there was an error on some other record that was part of the save)
    • errors (): An array containing a Message object for each blocking connection error that occurred on this record, preventing it from being updated
    • messages (): an array containing a Message object for any non-blocking info or warning messages that were applied to this row using skuid.utils.AddRowWarning(rowIndex,message)

  • deleteResults ( array of objects ): An array of Nintex Apps DeleteResult objects, which have the following properties:

    • id ( string ): The 18-digit Salesforce ID of the record for which a delete was attempted
    • success ( boolean ) True if the record was successfully deleted, false if there were errors, whether on the individual record, or, if the "Rollback entire save on any error" option was saved, if there was an error on some other record that was part of the save
    • errors (): An array containing a Message object for any blocking connection errors that occurred on this record while saving
skuid.events.models.saveHandled array of Message objects No

Published:

at the end of any call to model.save() or skuid.model.save([modelsArray]) call, regardless of whether the save call succeeded or failed

Data:

  • messages (): An array containing a Message object for any messages that were applied during the save

  • models ( object ): A JavaScript object containing the names of the Nintex Apps models as its keys and the actual skuid.model.Model objects as its values

  • initiatorId ( string ): The page-unique ID of the Ui Component, if any, that originally initiated the save. This is generally present, and is usually the ID of a skuid.ui.Editor, useful for preventing infinite loops.

    For example, your component is involved in two save operations: it causes a model to save, but it also wants to subscribe to the save event as a way of responding to save events triggered by a different Ui Component on the same model. In this instance, it is helpful to know whether it was your component, or a different component, which initiated the save operation.

  • totalsuccess ( boolean ): A Boolean that is true only if all save operations (whether inserts, updates, and/or deletes), on all rows, on all models involved, had no errors.

  • insertResults ( array of objects ): An array of Nintex Apps InsertResult objects, which have the following properties:

    • id ( string ): The 18-digit Salesforce ID of the newly-inserted record
    • oldId ( string ): The temporary ID of the record before it was saved
    • success ( boolean ) true if the record was successfully inserted, false if there were errors, whether on the individual record, or, if the "Rollback entire save on any error" option was saved, if there was an error on some other record that was part of the save
    • errors (): An array containing a Message object for each blocking connection errorthat occurred on this record, preventing it from being inserted
    • messages (): An array containing a Message object for any non-blocking info or warning messages that were applied to this row using skuid.utils.AddRowWarning(rowIndex,message)

  • updateResults ( array of objects ): An array of Nintex Apps UpdateResult objects, which have the following properties:

    • id ( string ): The 18-digit Salesforce ID of the record for which an update was attempted
    • success ( boolean ): True if the record was successfully updated, false if there were errors, whether on the individual record, or, if the "Rollback entire save on any error" option was saved, if there was an error on some other record that was part of the save
    • errors (): An array containing a Message object for each blocking connection error that occurred on this record, preventing it from being updated
    • messages (): An array containing a Message object for any non-blocking info or warning messages that were applied to this row using skuid.utils.AddRowWarning(rowIndex,message)

  • deleteResults ( array of objects ): An array of Nintex Apps DeleteResult objects, which have the following properties:

    • id ( string ): The 18-digit Salesforce ID of the record for which a delete was attempted
    • success ( boolean ): True if the record was successfully deleted, false if there were errors, whether on the individual record, or, if the "Rollback entire save on any error" option was saved, if there was an error on some other record that was part of the save
    • errors (): An array containing a Message object for any blocking connection errors that occurred on this record while saving
skuid.events.row.created string No

Published:

at the end of a call to model.createRow()

Data:

  • modelId (): The ID of the model where the new row was created
  • rowId (): The page-unique ID of the row that was just created.
  • row ( object ): The data row that was created, containing any default field values that may have been applied
  • initiatorId (): The page-unique ID of the Ui Component, if any, that originally called the createRow() method
skuid.events.row.updated string No

Published:

at the end of a call to model.updateRow() or model.updateRows() --- for calls to updateRows(), row.updated will be published separately for each row

Data:

  • modelId (): The ID of the model where the row was updated
  • rowId (): The ID of the row that was updated
  • row ( object ): The data row that was updated, containing any updated field values
  • updates ( object ): A JavaScript object containing, as keys, the API Names of the Fields that were updated, and as values, the new values that were applied to those fields on this row, e.g. { "Amount__c": 5000, "Stage__c": "Qualified" }
  • initiatorId (): The page-unique ID of the Ui Component, if any, that originally called the updateRow() method
skuid.events.row.deleted string No

Published:

at the end of a call to model.deleteRow()

Data:

  • modelId (): The ID of the model where the row was marked for deletion
  • rowId (): The page-unique ID of the row that was just marked for deletion
  • row ( object ): The data row that was marked for deletion
  • initiatorId (): The page-unique ID of the Ui Component, if any, that originally called the deleteRow() method
skuid.events.row.undeleted string No

Published:

at the end of a call to model.undeleteRow()

Data:

  • modelId (): The ID of the model where the row was un-marked for deletion
  • rowId (): The page-unique ID of the row that was just un-marked for deletion
  • row ( object ): The data row that was un-marked for deletion
  • initiatorId (): The page-unique ID of the Ui Component, if any, that originally called the undeleteRow() method

Conditions

In addition to being available as an initiating event for model actions within action flows, model condition changes and their respective JavaScript functions now fire JavaScript events. These events and their payloads contain useful data for JavaScript snippets and custom components.

When the setCondition() method—which both sets a value for a condition and then activates it for any future re-queries—is called, the condition.valueChanged event is published, which contains the following data as the event payload:

Copy 
{
  event: "condition.valueChanged",
  conditionName: <Condition Name>,
  modelId: <Model Id>,
  newValue: The new "value" property on the condition, unless it is a multi-value condition, then this would be the new "values" property
  oldValue: The old "value" property on the condition, unless it is a multi-value condition, then this would be the old "values" property
}

When the activateCondition() method—used to simply activate toggle style conditions—is called, the condition.activated event is published, which contains the following data as the event payload:

Copy 
{
  event: "condition.activated",
  conditionName: <Condition Name>,
  modelId: <Model Id>
}

When the deactivateCondition() method is called—such as when the Deactivate Filterable Conditions action occurs, the condition.deactivated event is published, which contains the following data as the event payload:

Copy 
{
  event: "condition.deactivated",
  conditionName: <Condition Name>,
  modelId: <Model Id>
}

Examples

Subscribing to a Nintex Apps Model event

One common use case for the Nintex Apps Publish / Subscribe API, with standard events, would be as a more generic alternative to using skuid.ui.Editor and skuid.ui.Field to listen for structured changes to particular Nintex Apps models and rows.

For instance, if you wanted to perform certain logic any time that rows were updated in a particular subset of Models, you could do it like this:

Copy 
skuid.events.subscribe('row.updated',function(updateResult){
   if ((updateResult.modelId === 'OpportunityData') && (updateResult.rowId===someRecordId)) {
       // Run my logic
   }
});

Or if you wanted to automatically requery a certain set of models whenever other models were saved, you could do this:

Copy 
skuid.events.subscribe('models.saved',function(saveResult){
   if (('NewOpportunity' in saveResult.models)&&(saveResult.totalsuccess)) {
       skuid.model.updateData([skuid.model.getModel('AllOpportunities')];
   }
});

To unsubscribe from the event, keep a reference to the subscription returned when you subscribed, and then call unsubscribe():

Copy 
var subscription = skuid.events.subscribe('row.updated', function() { ... });
skuid.events.unsubscribe(subscription);

Publishing / subscribing to a custom event

Another common use case for the Nintex Apps Events API is to publish and subscribe to custom events relevant to your application. For instance, you may have a custom visualization component that subscribes to the "acme.page.resize" event. Because your component subscribes to this custom event, this event can now be easily invoked by other areas of the application, either via JavaScript or via the Nintex Apps Action Framework's "Publish Event" action.

Example Component code that subscribes to the event:

Copy 
skuid.componentType.register('acme__chart',function(element,xmlDef,component){
    // Subscribe to a custom Page Resize event
    skuid.events.subscribe('acme.page.resize',function(config,eventDetails){
        if (eventDetails && eventDetails.direction==='vertical') {
            // Adjust for vertical resize
        }
        if (config && config.doSomething) {
            // Do something special
        }
    }
});

And then somewhere else in the application that performs "page resize" functionality would publish the event, causing the chart's subscription to be invoked:

Copy 
var config = {
    doSomething: true
};
var eventDetails = {
    direction: 'vertical'
};
skuid.events.publish('acme.page.resize',[config,eventDetails]);