Spawn Scripts

Spawning a script allows you to run a script manually. It's also used to start a script from other scripts or external processes. You can also use it to test a script. When testing, it can be used together with script traces.

To test scripts, you can spawn:

To start scripts from other scripts or processes:

  • Use the SPAWN action in the calling script.
  • Using the POST /scripts/start An icon of a square with an arrow pointing from the center out to the upper right corner. API. This is the recommended solution to spawn a script from any external process.
  • Using the shortcut URL from the ACD Scripts page.

Script Parameters

Script parameters allow data to be passed into scripts. The data might come from other scripts, including system scripts, or from external sources such as CRMsClosed Third-party systems that manage such things as contacts, sales information, support details, and case histories. or APIs. It's passed into the scripts in pXvariables, p1 through pN, where N is the maximum number of parameters supported by the spawn method. You can specify the data to be passed into the script when you spawn a script using any of the options listed in the previous section.

If you want to change the names of the parameter variables, you can configure the Begin action in the spawned script with new names. When the script processes the BEGIN action, the pX variables are converted to the new names. If you don't specify new names, the variables retain the pX names.

When data is passed into a script, you can see it in a trace. Select the BEGIN action to see the parameter variables in the trace output variables list. If you've configured the BEGIN action with new variable names, select the action that comes after BEGIN in the script trace to see them.

Depending on the source of the values, you may see all the pX variables in the trace output or only the ones that hold values. Spawning from the ACD Scripts page passes in all pX variables. Those you didn't specify a value for hold an empty string. With other spawn methods, parameter variables are only present if they hold a value.

Custom parameters: 

  • Support a maximum of: 
    • 100 characters per value when spawned via the shortcut URL.
    • 32 KB per value when spawned using the SPAWN action.
    • 32 KB total for all parameters, including the pipe delimiters, when spawned by API.
  • Support variable substitution. Enter the variable name in curly brackets ( { } ).
  • Support different numbers of parameters depending on spawn method:
    • 1-9 parameters when spawning by URL or the ACD Scripts page.
    • 1-20 parameters when spawning by the SPAWN action or API.
  • Do not support dynamic data objects. Objects must be converted to a JSON string first.

Example

This example shows how custom parameters pass from the calling application or script into the child script. In this example, some of the variable names are changed in the BEGIN action, but not all of them, so you can see what happens in either case.

The following image shows that the IBVoice script has been spawned from the ACD Scripts page with the IBVoice ACD skillClosed Used to automate delivery of interactions based on agent skills, abilities, and knowledge and four custom parameter values: value1, value2, value3, and value4.

The Scripts page, showing the spawned script with four custom parameter values.

The next image shows the BEGIN action in the IBVoice script configured with new variable names in the first three lines of the Parameters property. The new names are newVar1, newVar2, and newVar3.

The properties of the BEGIN action, showing that three variables are configured in the Parameters property.

The next two images show the results of the spawn in the trace output. This image shows the Begin action, which contains the four script parameter values in the p1, p2, p3, and p4 variables.

The script trace showing the variables in the BEGIN action.

The final image shows the variables in the script after the BEGIN action finishes processing. You can see this by clicking the second action in the script; in this example, it's the HOURS action. The p1, p2, and p3 are no longer in the script. Their values have been assigned to newVar1, newVar2, and newVar3. The variables p4 - p9 are still in the script. p4 contains the value assigned to it on the Scripts page. The remaining pX variables were passed in as empty strings.

The script trace showing that the values of the first three pX vairables have been assigned to new variables.

Comparison of Studio Actions

There are three Studio actions that start a new script from the current script. However, there are some differences between them: 

  • Runscript: When  triggers another script, it doesn't return to the first script from the second script.
  • Runsub: When triggers a subscript, the script can return to the first script, as long as the subscript has a action. The action provides a value back to the action when the subscript is finished.
  • SPAWN: Starts a second script that runs in parallel to the first script. Spawned scripts cannot pass data back to the first script unless you include a action in the spawned script.

Spawn from Another Script Using the SPAWN Action

If you don't need to pass parameter values to the child script, all you need to do is add and configure the SPAWN action in the parent script. If you need to pass parameters, you need to make the following configurations:

  • Make the following changes in the parent script:
    • Place the SPAWN action at the point where you want to spawn the child script. Configure the Parameters property in the SPAWN action with any values you need to pass to the child script. Values are passed in variables p1 to p9.
    • Configure the other properties of the SPAWN action.

  • Make the following changes in the child script: 

    • Configure the Parameters property in the action to change the name of the custom parameter variables. If you do nothing, custom parameter values remain in the variables.
    • If you need to pass values back to the parent script or calling application, add and configure a action.

Spawn from the ACD Scripts Page

You can spawn a script from the Scripts page in the ACD application in CXone. When you use this method, all pX variables are passed into the spawned script. Variables with no specified value are passed in as empty strings.

  1. In CXone, click the app selector and select ACD.
  2. Under Contact Settings, click Scripts.
  3. Click a script from the list on the page.
  4. On the script's properties page, click the Spawn tab.

  5. Select an ACD Skill from the drop-down. The skill must:

    • Be active.
    • Match the script media type. For example, phone scripts must correlate with phone call skills. You can find the skill type on the Details tab of a skill. Scripts with the Generic type work with any active skill.
  6. To pass data into the script, enter the values in the Parameter fields. You can enter up to nine values.

  7. To spawn the script immediately without a script trace, click Spawn. The Spawn tab displays the message Script spawned. Contact ID: [number].

    The contact ID in the response is not confirmation that your script executed successfully. It only indicates that a spawn was triggered. The script could fail at any point after the contact ID is generated.

Spawn with an ACD Scripts Page Shortcut URL

The Show Shortcut option on the ACD Scripts page generates a URL that can be executed as a standard REST API GET request. This URL uses query string parameters to tell the platform how to spawn the script. Parameters and their values must be URL-encoded.

The following example shows a shortcut URL for a script called IBVoice:

https://home-[clusterName].nice-incontact.com/inContact/Manage/Scripts/Spawn.aspx?scriptName=IBVoice&bus_no=12334567&scriptId=172309310&skill_no=20967527&p1=ValOne&p2=ValTwo&p3=&p4=&p5=&Guid=abcdefgh-1not-real-2345-6789abcdefgh

The shortcut URL contains the following parameters:

Do not modify the GUID. Additionally, the GUID should be treated like a password. The GUID can never be reset.

  1. In CXone, click the app selector and select ACD.
  2. Under Contact Settings, click Scripts.
  3. Click a script from the list on the page.
  4. On the script's properties page, click the Spawn tab.

  5. Select an ACD Skill from the drop-down. The skill must:

    • Be active.
    • Match the script media type. For example, phone scripts must correlate with phone call skills. You can find the skill type on the Details tab of a skill. Scripts with the Generic type work with any active skill.
  6. To pass data into the script, enter the values in the Parameter fields. You can enter up to nine values.
  7. Click Show Shortcut.
  8. Right-click on the Shortcut to [Name of Script] link that appears in the information box on the Spawn tab, then select Copy link address. The name of the copy option may vary depending on the browser you use.
  9. Paste the copied URL into a web browser address bar and press Enter.

  10. The browser displays the following response message:

    Script spawned. Contact ID: [number]

    The contact ID in the response is not confirmation that your script executed successfully. It only indicates that spawn was triggered. The script could fail at any point after the contact ID is generated.

Spawn from the ACD Scripts Page with a Trace

You can spawn a script immediately and capture a trace in Studio. This is helpful if you're testing the script. If you've previously spawned the script and had it fail, spawning with a trace can help you determine where the problem is.

  1. In Studio, open the script you're spawning.
  2. Click Debug > Capture Script > Next Instance Only. To capture the script continuously, click Debug > Capture Script > Continuous.
  3. In CXone, click the app selector and select ACD.
  4. Under Contact Settings, click Scripts.
  5. Click a script from the list on the page.
  6. On the script's properties page, click the Spawn tab.
  7. Complete the fields on the Spawn tab.
  8. Execute the spawn: 
    • On the Spawn tab of the script in the ACDapplication, click Spawn.
    • Copy and paste the shortcut URL into a browser address bar and press Enter.
  9. Return to Studio and watch the trace output.
  10. If you specified parameter values, you can see them in the trace output. Click the BEGIN action in the trace output and locate the p1 through p9 variables. If you specified new names for the variables, click the second action in the script to see the change.

Spawn a Script by API

Use the POST /scripts/start An icon of a square with an arrow pointing from the center out to the upper right corner. API to spawn a script.

When using this API, it's important to note that: 

  • The following parameters are required: 
    • skillId: The value must be an integer when sending as JSON, but not if sending as query parameters. Skills must: 
        • Be active.
        • Match the script media type. For example, phone scripts must correlate with phone call skills. You can find the skill type on the Details tab of a skill. Scripts with the Generic type work with any active skill.

    • scriptId or scriptPath: Using scriptPath is recommended. The script ID changes every time changes to the script are saved, so it must be updated in the parameter.

  • You can include up to 20 parameters.
  • Parameters must be sent in a pipe-delimited list.
  • The API supports a maximum of 32 KB for all parameters, including the pipe delimiters.
  • Parameters cannot include pipe characters unless they are delimiters.
  • If sending the request as JSON, reserved characters must be properly escaped.
  • If sending the request by URL query parameters, the parameters must be URL-encoded.