ProactiveTriggerAPI - Scoped

The ProactiveTriggerAPI enables you to create server-side triggers that send context-specific messages to a specified user.

This API uses rules and related actions based on those rules to send messages to a user. These rules and actions are context-specific and are based on real-time data gathered as the user navigates across portal pages. For additional information, see Proactive Triggers.

Before using this API, the trigger types, rules, and actions must be configured on your instance. For information on how to configure Proactive Triggers, see Configuring Proactive Triggers.

Using this API you can send messages to a specific user or to a user in a specific session.

For example, in the case where a customer adds items to their cart, you can have a Proactive Triggers event within a business rule that sends a reminder to the user to complete check-out after a specified amount of time.

Similarly, if a user performs an AI Search from a Service Portal and no results are returned, you can have logic in a business rule that creates a Proactive Triggers that sends alternate offerings to the user through the proactive pop over message web-client.

When calling the ProactiveTriggerAPI, there's a specific sequence in which you should call the methods. This API runs in the sn_pt namespace.

First, you should call the ProactiveTriggerAPI - createTrigger(String triggerTypeId) method to specify the type of trigger that you want to create. This call is required. For the list of available trigger types, see How Proactive Triggers work.

Next, you should call one of the methods that identifies the user to whom the messages should be sent. You can do this by calling one of the following methods:

• ProactiveTriggerAPI - setUserId(String userId): Identifies the user by the sys_id of their associated User [sys_users] record.
• ProactiveTriggerAPI - setUserName(String userName): Identifies the user by their user name, such as "abel.tuter".
• ProactiveTriggerAPI - setUserSessionId(String userId): Identifies the user by their current session sys_id.

Next, you should call the ProactiveTriggerAPI - setTriggerRecord(String triggerRecord) method to specify the trigger record on which to apply the Proactive Triggers' rules and actions.

Finally, call the ProactiveTriggerAPI - process() method to execute the call chain. Both the setTriggerRecord() and process() method calls are required.

For example:

var eventSysId = sn_pt.ProactiveTriggerAPI.createTrigger(triggerTypeId)
  .setUserName(userName).setTriggerRecord(userId).process();

ProactiveTriggerAPI - createTrigger(String triggerTypeId)

Creates a server-side Proactive Triggers event.

Table 1. Parameters

Name	Type	Description
triggerTypeId	String	Unique ID of the trigger type to create. For example: triggerTypeId = "sn_pt.ai_search_event" Table: ID field of the Proactive Trigger Types [sys_cs_ptrigger_trigger_type] table.

Table 2. Returns

Parameter	Description
None

The following business rule shows how to call the createTrigger() method inside a business rule.

try {
  var triggerTypeId = "sn_pt.ai_search_event";
  var userId = current.getValue("user");

  var eventSysId = sn_pt.ProactiveTriggerAPI.createTrigger(triggerTypeId)
       .setUserId(userId).setTriggerRecord(current).process();

  // Returns the Proactive Trigger Event record's sys_id
  gs.info("Proactive Trigger Event Sys Id:"+ eventSysId);

} catch (e) {
    gs.info("error:"+e); // Log the error.
}

ProactiveTriggerAPI - process()

Executes the specified Proactive Triggers API request.

Table 3. Parameters

Name	Type	Description
None

Table 4. Returns

Type	Description
sys_id	Sys_id of the Proactive Trigger Event record that was created. Data type: String Table: Proactive Event [sys_cs_ptrigger_event]

The following business rule shows how to call the process() method to execute the specified Proactive Triggers API request.

try {
  var triggerTypeId = "sn_pt.ai_search_event";
  var userId = current.getValue("user");

  var eventSysId = sn_pt.ProactiveTriggerAPI.createTrigger(triggerTypeId)
       .setUserId(userId).setTriggerRecord(current).process();

  // Returns the Proactive Trigger Event record's sys_id
  gs.info("Proactive Trigger Event Sys Id:"+ eventSysId);

} catch (e) {
    gs.info("error:"+e); // Log the error.
}

ProactiveTriggerAPI - setTriggerRecord(String triggerRecord)

Sets the trigger record on which to apply the Proactive Triggers' rules and actions.

These rules and actions are defined in the associated trigger type record, located in the Proactive Trigger Types [sys_cs_ptrigger_trigger_type] table.

Table 5. Parameters

Name	Type	Description
triggerRecord	String or GlideRecord	Sys_id or GlideRecord of the trigger record on which to apply the associated Proactive Triggers' rules and actions. The trigger record is located in the table specified in the trigger_table field of the trigger type record that was specified in the createTrigger() method call. For example, if your createTrigger() call specified the AI Search Event trigger type, then the trigger table is the Search Event [sys_search_event] table. Note: This table is typically the same as the table that caused the business rule to execute. If it isn't the same, you will need to add this sys_id to the GlideRecord so you can pass it into this method.

Table 6. Returns

Type	Description
None

The following business rule shows how to call the setTriggerRecord() method.

try {
  var triggerTypeId = "sn_pt.ai_search_event";
  var userId = current.getValue("user");

  var eventSysId = sn_pt.ProactiveTriggerAPI.createTrigger(triggerTypeId)
       .setUserId(userId).setTriggerRecord(current).process();

  // Returns the Proactive Trigger Event record's sys_id
  gs.info("Proactive Trigger Event Sys Id:"+ eventSysId);

} catch (e) {
    gs.info("error:"+e); // Log the error.
}

ProactiveTriggerAPI - setUserId(String userId)

Sets the user to whom to send the message generated by the associated Proactive Triggers event using the user ID.

Table 7. Parameters

Name	Type	Description
userId	String	Sys_id of the user to whom to send the associated Proactive Triggers message. Table: User [sys_user] table or in the associated GlideRecord.

Table 8. Returns

Parameter	Description
None

The following code example shows how to call the setUserId() method using the value in the user field of the current GlideRecord.

try {
  var triggerTypeId = "sn_pt.ai_search_event";
  var userId = current.getValue("user");

  var eventSysId = sn_pt.ProactiveTriggerAPI.createTrigger(triggerTypeId)
       .setUserId(userId).setTriggerRecord(current).process();

  // Returns the Proactive Trigger Event record's sys_id
  gs.info("Proactive Trigger Event Sys Id:"+ eventSysId);

} catch (e) {
    gs.info("error:"+e); // Log the error.
}

ProactiveTriggerAPI - setUserName(String userName)

Sets the user to whom to send the message generated by the associated Proactive Triggers event using the user name.

Table 9. Parameters

Name	Type	Description
userName	String	Name of the user to whom to send the proactive message. This name must correlate to the User ID field in the User [sys_user] table, such as "abel.tuter".

Table 10. Returns

Parameter	Description
None

The following business rule shows how to call the setUserName() method using the value in the sys_created_by field of the current GlideRecord.

try {
  var triggerTypeId = "sn_pt.ai_search_event";

  // User name of the user to whom to send the proactive message.
  var userName = current.getValue("sys_created_by");

  var eventSysId = sn_pt.ProactiveTriggerAPI.createTrigger(triggerTypeId)
       .setUserName(userName).setTriggerRecord(current).process();

  // Returns the Proactive Trigger Event record's sys_id
  gs.info("Proactive Trigger Event Sys Id:"+ eventSysId);

} catch (e) {
    gs.info("error:"+e); // Log the error.
}

ProactiveTriggerAPI - setUserSessionId(String userId)

Sets the user session ID on the associated Proactive Triggers event. When using this method, the Proactive message is only sent to the specific user associated with a specific session.

Table 11. Parameters

Name	Type	Description
userSessionId	String	Sys_id of the current session of the user to whom the Proactive Triggers message should be sent. Note: Not all tables contain a session ID. Before using this endpoint, ensure that the table that you're referencing contains a valid session ID. If not, the latest available session ID is used which may cause erroneous results.

Table 12. Returns

Parameter	Description
None

The following business rule shows how to call the setUserSessionId() method using the value in the session field of the current GlideRecord.

try {
  var triggerTypeId = "sn_pt.ai_search_event";
  var sessionId = current.getValue("session");

  var eventSysId = sn_pt.ProactiveTriggerAPI.createTrigger(triggerTypeId)
       .setUserSessionId(sessionId).setTriggerRecord(current).process();

  // Returns the Proactive Trigger Event record's sys_id
  gs.info("Proactive Trigger Event Sys Id:"+ eventSysId);

} catch (e) {
    gs.info("error:"+e); // Log the error.
}