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:

• From Studio using the trace option.

• From the ACD Scripts page. 

To start scripts from other scripts or processes:

• Use the SPAWN action in the calling script.
• Using the POST /scripts/start 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 CRMs 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 variables 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 preceding 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 after the 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.

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 skill Used to automate delivery of interactions based on agent skills, abilities, and knowledge and four custom parameter values, value1, value2, value3, and value4.

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 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 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.

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 Runscript triggers another script, it doesn't return to the first script from the second script.
• RunsubRunsub: When Runsub triggers a subscript, the script can return to the first script, as long as the subscript has a Return action. The Return action provides a value back to the Runsub action when the subscript is finished.
• SPAWNSPAWN: 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 SIGNAL 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:

• 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 BEGIN action to change the name of the custom parameter variables. If you do nothing, custom parameter values remain in the pX variables.
  • If you need to pass values back to the parent script or calling application, add and configure a SIGNALactionaction.

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.

1. 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.
2. To pass data into the script, enter the values in the Parameter fields. You can enter up to nine values.

3. 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:

• The script name
• The business unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment number
• The script ID
• The ACD skill Used to automate delivery of interactions based on agent skills, abilities, and knowledge number of the skill specified on the ACD Scripts page
• All custom parameter values specified on the ACD Scripts page
• A GUID—a 128-bit text string generated as a unique identifier for information on a computer or network

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.

1. 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.
2. To pass data into the script, enter the values in the Parameter fields. You can enter up to nine values.
3. Click Show Shortcut.
4. 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.
5. Paste the copied URL into a web browser address bar and press Enter.

6. 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.
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.
3. Complete the fields on the Spawn tab.
4. 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.
5. Return to Studio and watch the trace output.
6. 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 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.