Use a rule to evaluate information from a data action

You can use a data action as a call rule condition or action or both. Using a data action as a rule condition or action, a pre-call or wrap-up rule can evaluate response data from the Genesys Cloud Public API, Salesforce, Zendesk, or REST API endpoints. This procedure explains how to set up a rule that runs a data action, and then evaluates the information it returns.

  1. For all evaluation rules, see the instructions below in Setup and configure an evaluation rule.
  2. Do one of the following:
    • To use a data action as a condition, see the instructions below in Use a data action as a condition.
    • To use any other condition, follow the instructions in Add a call rule.
  3. Do one of the following:
    • To use a data action as an action, see the instructions below in Use a data action as an action.
    • To use any other action, follow the instructions in Configure rule actions.
Note: You can use data actions as both a condition and an action in the same rule. If you use a data action only as an action, you must still configure a condition for the rule.

  1. Click Admin.
  2. Under Outbound, click Rule Management.
  3. On the Call Rule Sets tab, click Create New.
  4. On the Create Call Rule Set page, type a name for this rule set in the Call Rule Set Name box.
  5. If your data action needs contact data, select a contact list from the Contact List box so that you can select its columns later. You do not need to select a queue.
  6. Click Save and Add Rules
    Note: If you are updating a set that already contains rules, click Add New Call Rule instead.
  7. On the Add Call Rule page, type a name in the Call Rule Name box.
  8. Select Pre-Call or Wrap-up from the Category box, based on whether you want your rule to evaluate before outbound dialer places calls, or after calls end.
  9. Configure the conditions and actions for this rule, then save the rule.

  1. Below Conditions, click inside the Type box. Select Data Action.
  2. To display a list of available data actions, click the Data Action box. Then select a data action from the list.
    You can input the following data action conditions for the individual categories:
    • Pre-call: Contact ID and all contact list columns
    • Wrap-up: agent wrap-up, call analysis result, Contact ID, and all contact list columns
    Notes:
    • If no existing data actions are suitable, create a new data action. See Create a custom action for integrations. To create a data action, you must know the data action’s input and output contracts, endpoint, and other parameters. Contracts define the format of data passed to the data action or returned by it. The endpoint is the address of the API call. For more information, see About integrations, About the Genesys Cloud data actions integration, and About custom actions for integrations.
    • The efficiency of data actions is important. If a data action makes an API call or conducts a database lookup that takes a long time to complete, it could slow down outbound dialing.
    • If the system displays, ‘The input contract on the data action must be of type object”, then the selected data action is not compatible with outbound. A compatible contract resembles this schema:
    • To view the input contract for a data action, select Actions from the Admin menu. To open a data action, select its name. Then, select its Input Contract tab. The data in the schema must define values as belonging to an object. See Create a custom action for integrations.
  3. To correlate campaign data with input values of the data action, use the controls below Map of Outbound Values to Data Action Inputs. This mapping tells the rule what information to pass to the data action before the data action runs. 
    Note: Agent Wrap-up and Call Analysis Result input fields can remain unpopulated for a running a data action condition. An Agent wrap-up does not appear for calls that do not reach an agent. Preview calls do not return a Call Analysis result. The call analysis returned as part of this string can sometimes be blank. This occurs when the media server was able to determine how to disposition the call without using audio analysis (SIP or ISDN disconnect signal, SIT, and other reasons).
    1. In the Outbound Value list, select an item of information to pass to the data action. Your selection of outbound values is based on the contact list selected.
    2. In the Data Action Input list, select which input value of the data action receives the outbound value. For example, you can map a phone number from the campaign to a data action’s Cell value.
      Tip: If the system displays a validation warning, then the data action is not configured as a HIPAA/Secure Data compliant data action. Reconfigure the data action and make it secure before using the data action in outbound. To reconfigure the action, click Admin. Under Integrations, click Actions. Click the data action name and then enable the HIPAA/Secure Data box.

      The inputs to a data action are based on its contracts. Contracts are JSON schema statements (specified when someone creates a data action) that define what data passes to a function or what the function returns.

    3. To map more outbound values to data action inputs, click the + below the last configured row. Repeat until you have mapped all inputs that the data action requires.

      Using this association between outbound values and data action inputs, your rule passes to the data action any data it needs. For example, a data action can use a column from the contact list to retrieve information from a CRM.

  4. Control whether the rule action is performed if the condition is met or not met.

    In some situations, you may want to invert the condition, so that the system performs its data action when the opposite of the condition is true. This inversion is accomplished by setting the Invert Condition switch to Yes. An inverted condition performs rule actions when the condition is not met.

    Do one of the following:
    • To perform a rule action when the condition is met, set Invert Condition = No. This setting is the default.

    • To perform a rule action when the condition is not met, set Invert Condition = Yes.

  5. Having defined inputs to the data action, the next step is to configure your rule to evaluate information returned by the data action. Use the Output Evaluations section to set up expressions that evaluate any return value in the data action’s Output contract.

    1. Select a return value from the Data Action Output box.

    2. Select an operator from the Comparator box.

      Currency evaluations

      A data action condition can evaluate currency values, but only if the output result has 2 or fewer decimal places.

      If a result has more than two decimal places, rules cannot evaluate it.

      Time evaluations

      String, Boolean, and numeric comparators are intuitive. You can compare date strings to relative times or to specific times. Both types of time comparators provide “Is Earlier Than” and “Is Later Than” comparators. The difference is whether the value is compared with an exact date and time, or relative to the current time, in the past or the future. A specific time value is set by configuring:

      But a relative time value is set by configuring a time offset:

    3. Type a value in the Value box. This value is compared with the value returned by the data action, using the selected comparator. For example, you can check to see if a postal code begins with the number 5:

      Note: String comparisons are case-sensitive.
  6. (Optional) To invert the comparison operator, enable the invert comparator box. For example, if you invert the “Begins With” comparator, the evaluation resolves true if the value does not begin with the specified value.
  7. (Optional) Set When there is no value for the data action output field, this evaluation resolves to True. If the output contains no data, you can decide whether the expression returns True or False. False is the default.
  8. (Optional) To evaluate another output value, click . Repeat steps 1-7 to configure the new evaluation condition.
    Note: Conditions join with the AND operator, so a call must meet all rule conditions for the overall rule to evaluate True.
  9. (Optional) If the data action returns no data, you can control whether the condition evaluates True or False by clicking the Data Not Found Resolution switch. False is the default, meaning that the condition returns False when the data action returns no data.
  10. Do one of the following:
    • To use a data action as an action, follow the instruction below in Use a data action as an action.
    • To use any other action, follow the instructions in Configure rule actions.

Note: A call rule data action execution times out after 20 seconds, which causes the record to be wrapped up with the code ININ-OUTBOUND-RULE-ERROR-SKIPPED. An ERROR level event log is also submitted, with the code DATA_ACTION_EXECUTION_FAILED.

Configuring a data action as a rule action is very similar to configuring it as a condition.

  1. After configuring a rule condition, below Actions, click inside the Type box. Select Data Action.
  2. To display a list of available data actions, click the Data Action box. Then select a data action from the list.
    You can input the following data action conditions for the individual categories:
    • Pre-call: Contact ID, and all contact list columns
    • Wrap-up: agent wrap-up, call analysis result, contact id, and all contact list columns
    Notes:
    • If no existing data actions are suitable, create a new data action. See Create a custom action for integrations. To create a data action, you must know the data action’s input and output contracts, endpoint, and other parameters. Contracts define the format of data passed to the data action or returned by it. The endpoint is the address of the API call. For more information, see About integrations, About the Genesys Cloud data actions integration, and About custom actions for integrations.
    • The efficiency of data actions is important. If a data action makes an API call or conducts a database lookup that takes a long time to complete, that could slow down outbound dialing.
    • If the system displays, “The input contract on the data action must be of type object”, then the selected data action is not compatible with Outbound. A compatible contract resembles this schema:
    • To view the input contract for a data action, select Actions from the Admin menu. To open a data action, select its name. Then select its Input Contract tab. The data in the schema must define values as belonging to an object. See Create a custom action for integrations.
  3. The Outbound Value and Data Action Input selections correlate campaign data with input values of the data action. This mapping tells the rule what information to pass to the data action before the data action runs. 
    Note: Agent Wrap-up and Call Analysis Result input fields can remain unpopulated for a running a data action as an action. An Agent wrap-up does not appear for calls that do not reach an agent. Preview calls do not return a Call Analysis result. The call analysis returned as part of this string can sometimes be blank. This occurs when the media server was able to determine how to disposition the call without using audio analysis (SIP or ISDN disconnect signal, SIT, and other reasons).
    1. Use the Outbound Value list to select an item of information to pass to the data action. Your selection of outbound values is based on the contact list selected.
    2. Use the Data Action Input list to select which input value of the data action receives the outbound value. For example, you can map a phone number from the campaign to a data action’s Cell value.
      Tip: If the system displays a validation warning, then the data action is not configured as a HIPAA/Secure Data compliant data action. Reconfigure the data action and make it secure before using the data action in outbound. To reconfigure the action, click Admin. Under Integrations, click Actions. Click the data action name and then enable the HIPAA/Secure Data box.

      The inputs to a data action are based on its contracts. Contracts are JSON schema statements (specified when someone creates a data action) that define what data passes to a function or what the function returns.

    3. To map more Outbound Values to Data Action Inputs, click the + below the last configured row. Repeat until you have mapped all inputs that the data action requires.

      Using this association between Outbound Values and Data Action Inputs, your rule passes to the data action any data it needs. For example, a data action can use a column from the contact list to retrieve information from a CRM.

  4. After you have configured the conditions and actions for this rule, click Save.

Note: A call rule data action execution times out after 20 seconds, which causes the record to be wrapped up with the code ININ-OUTBOUND-RULE-ERROR-SKIPPED. An ERROR level event log is also submitted, with the code DATA_ACTION_EXECUTION_FAILED.

Limitations on data types in contracts

When administrators create a custom action for integrations, they define input and output contracts. Some limitations on data actions you use with outbound rules include:

  • For both input and output contracts, the top-level type must be an object. An input contract cannot pass an array to a remote endpoint. An outbound contract cannot consume an array of response data unless the data action’s output contract uses a translation map to convert the array to an object.
  • Output contracts can allow complex objects or arrays, but outbound dialer does not permit use of those data types in a rule condition. The rule condition can only operate on Boolean, integer, number, and string data types.
  • If the endpoint returns a non-JSON response, you must provide a middleware service that transforms the response to JSON. The response to a data action must be a valid JSON. Otherwise, the data action fails.
  • Never try to flatten fields in a data action’s output schema. See Guidelines for actions used with outbound dialing rules.
  • The maximum number of data action rule conditions you can have on a single campaign is two.

Limitations of data actions as conditions or actions

When you use data actions as conditions or actions, be aware there are several limits that affect the speed of dialer operations. The data action service limits how many concurrent data actions can be run, as well as how many can be run over a course of a minute and hour.

When dialer operations detect a data action in use on the interaction to be dialed or the wrap-up to be processed, we check to see how many concurrent data actions are occurring and slow those respective operations to make sure not to hit the limits on the data action side.  Contacts may not be dialed as quickly as those without data actions. On the wrap-up side, we might delay processing the wrap-up for a short while (a few milliseconds to several seconds).

When using data actions as conditions or actions in an evaluation rule, keep in mind these limitations:

  • The maximum number of data actions used as conditions is two per rule, rule set, and running campaign.
  • The maximum number of data actions used as actions is ten per rule, rule set, and running campaign.
    Note: If you try to add more data actions as actions to a rule, rule set, or campaign than are allowed, the save fails. You see a message that a dialing error has occurred.