---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# ProactiveTriggerAPI - Scoped

# ProactiveTriggerAPI - Scoped {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 5 minutes to read

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](https://www.servicenow.com/docs/access?context=proactive-triggers-landing-page&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US).

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](https://www.servicenow.com/docs/access?context=configuring-proactive-triggers&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US).

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)](https://servicenow-prod.fluidtopics.net/y4opgJirUbehQSKdold1WQ#ProTrig-createTrigger_S "Creates a server-side Proactive Triggers event.") 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](https://www.servicenow.com/docs/access?context=how-proactive-triggers-work&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US).  
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)](https://servicenow-prod.fluidtopics.net/y4opgJirUbehQSKdold1WQ#ProTrig-setUserId "Sets the user to whom to send the message generated by the associated Proactive Triggers event using the user ID."): Identifies the user by the sys_id of their associated User \[sys_users\] record.
* [ProactiveTriggerAPI - setUserName(String userName)](https://servicenow-prod.fluidtopics.net/y4opgJirUbehQSKdold1WQ#ProTrig-setUserName_S "Sets the user to whom to send the message generated by the associated Proactive Triggers event using the user name."): Identifies the user by their user name, such as "abel.tuter".
* [ProactiveTriggerAPI - setUserSessionId(String userId)](https://servicenow-prod.fluidtopics.net/y4opgJirUbehQSKdold1WQ#ProTrig-setUserSessionId_S "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."): Identifies the user by their current session sys_id.

Next, you should call the [ProactiveTriggerAPI - setTriggerRecord(String triggerRecord)](https://servicenow-prod.fluidtopics.net/y4opgJirUbehQSKdold1WQ#ProTrig-setTriggerRecord_S "Sets the trigger record on which to apply the Proactive Triggers' rules and actions.") method to specify the trigger record on which to apply the Proactive Triggers' rules and actions.

Finally, call the [ProactiveTriggerAPI - process()](https://servicenow-prod.fluidtopics.net/y4opgJirUbehQSKdold1WQ#ProTrig-process "Executes the specified Proactive Triggers API request.") 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) {#ariaid-title2}

Creates a server-side Proactive Triggers event.
{#ProTrig-createTrigger_S__table_kby_q4m_2xb__entry__3}

| Name | Type | Description |
|-|-|-|
| triggerTypeId | String | Unique ID of the trigger type to create. Located in the ID field of the Proactive Trigger Types \[sys_cs_ptrigger_trigger_type\] table. For example: `triggerTypeId = "sn_pt.ai_search_event"` |
[Table 1. Parameters]

{#ProTrig-createTrigger_S__table_kby_q4m_2xb} {#ProTrig-createTrigger_S__table_wx5_dkm_2xb__entry__2}

| Parameter | Description |
|-|-|
| None |   |
[Table 2. Returns]

{#ProTrig-createTrigger_S__table_wx5_dkm_2xb}  
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() {#ariaid-title3}

Executes the specified Proactive Triggers API request.
{#ProTrig-process__table_h25_rjb_fxb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 3. Parameters]

{#ProTrig-process__table_h25_rjb_fxb} {#ProTrig-process__table_i25_rjb_fxb__entry__2}

| Type | Description |
|-|-|
| sys_id | Sys_id of the Proactive Trigger Event record that was created. Located in the Proactive Event \[sys_cs_ptrigger_event\] table. Data type: String |
[Table 4. Returns]

{#ProTrig-process__table_i25_rjb_fxb}  
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) {#ariaid-title4}

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.
{#ProTrig-setTriggerRecord_S__table_qc1_m15_2xb__entry__3}

| 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 5. Parameters]

{#ProTrig-setTriggerRecord_S__table_qc1_m15_2xb} {#ProTrig-setTriggerRecord_S__table_rc1_m15_2xb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 6. Returns]

{#ProTrig-setTriggerRecord_S__table_rc1_m15_2xb}  
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) {#ariaid-title5}

Sets the user to whom to send the message generated by the associated Proactive Triggers event using the user ID.
{#ProTrig-setUserId__table_n3b_ssm_2xb__entry__3}

| Name | Type | Description |
|-|-|-|
| userId | String | Sys_id of the user to whom to send the associated Proactive Triggers message. Located in the User \[sys_user\] table or in the associated GlideRecord. |
[Table 7. Parameters]

{#ProTrig-setUserId__table_n3b_ssm_2xb} {#ProTrig-setUserId__table_o3b_ssm_2xb__entry__2}

| Parameter | Description |
|-|-|
| None |   |
[Table 8. Returns]

{#ProTrig-setUserId__table_o3b_ssm_2xb}  
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) {#ariaid-title6}

Sets the user to whom to send the message generated by the associated Proactive Triggers event using the user name.
{#ProTrig-setUserName_S__table_kby_q4m_2xb__entry__3}

| 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 9. Parameters]

{#ProTrig-setUserName_S__table_kby_q4m_2xb} {#ProTrig-setUserName_S__table_lby_q4m_2xb__entry__2}

| Parameter | Description |
|-|-|
| None |   |
[Table 10. Returns]

{#ProTrig-setUserName_S__table_lby_q4m_2xb}  
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) {#ariaid-title7}

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.
{#ProTrig-setUserSessionId_S__table_ngm_5vm_2xb__entry__3}

| 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 11. Parameters]

{#ProTrig-setUserSessionId_S__table_ngm_5vm_2xb} {#ProTrig-setUserSessionId_S__table_ogm_5vm_2xb__entry__2}

| Parameter | Description |
|-|-|
| None |   |
[Table 12. Returns]

{#ProTrig-setUserSessionId_S__table_ogm_5vm_2xb}  
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.
    }