First and most importantly, Illustrator runs multiple instances of its ExtendScript engine, In order to access powerscripts your will need to add the following to the beginning of your script.

This will

• Get the filename of the script that's running
• Send a message via PlugPlugExternalObject to PowerScripts to run the script
• The program will exit
• PowerScripts will get the message, and then load and execute your code in the same instance of EntendScript. Giving your program access to the internal functions.

//
   
// If  _powerScriptCommand is undefined then send message  
// to PowerScripts to run this script and exit.

if(typeof _powerScriptCommand === 'undefined'){
	// get this filename
	var thisFilename = $.fileName;

	// escape shashes and '
	thisFilename = thisFilename.replace(/\\/g, '\\\\').replace(/\'/g, '\\\'')

	// Send JSON string with command "evalFile"
	var lib = new ExternalObject( "lib:PlugPlugExternalObject");
	var eventObj = new CSXSEvent();
	eventObj.type = "nz.co.o2creative.events.lwAction";	
	eventObj.data = '{"action": "evalFile", "data": {"filename": "' + thisFilename + '"}}';
	eventObj.dispatch(); 

	// exit
	return; 
}

//

Once your script is loaded in the same instance as PowerScripts, you can then run commands using the functions below, All actions are asynchronous

These built-in functions allow you to send commands and actions to powerScripts

• Commands allow to you load powerScripts, get information, and apply settings, in additional some PowerScirpts will have custom commands
• Actions are specific to each PowerScripts

Runs a set of one or more actions on a PowerSciprts,

Parameters

• {string} scriptID - UUID for the individual PowerScript
• {string|array} actions
• {data} savedSetting
• {function} callback

Description Actions are predefined in each PowerScript. To get a list of actions see [getActions] below

Callback return value

{object}

Send an indivudual command to PowerScripts .

Parameters

• {string} scriptID - UUID for the individual PowerScript
• {string} command
• {data} data
• {function} callback

Callback return value

{object}

Run multiple commands.

Parameters

• {array) commands - An array objects { scriptID, “###”, command: “[load]”, data: {} }
• {function} callback
• {boolean|optional} stopOnFail - If false, all commands will excuete, if true it will stop and callback on first failure

Callback return value

    // Success
     {
        success: true,
        results: []   // an array of results - see default command list below for return values for each command
     }
     
     // on Failure
     {
            success: false,
            step: index,  // index where the command fialed
            error: 'Failed at command 2",   // Error message
            failedCommand: {},  // the failed command object
            results: []   // an array of results - see default command list below for return values for each command
     }

Support for the standardJSON.parse and JSON.stringify are included

Because your script will run in a different instance, you will not be able to run a debugging session to step through errors. Here are some functions to help with debugging.

Display an alert box and gives you a detailed output of the message, If the message is an object or an array it will show its member and properties.

Parameters

• {any} message
• {string} title - Title
• {isError} display an error icon if asDialogue != true
• {asDialogue} Displays a scriptUI dialogue so you can copy the message

Description

Object and arrays will be correctly displayed

To display a console in a new dialogue while your code is running use _console.log(object). You do not need to call console.show() first as calling console,log() will automatically display the console.

For a compact view use JSON.stringify, i.e. console.log( JSON.stringify(var) );

• _console.show()
• _console.hide()
• _console.clear()
• _console.format(any, nolabel, noCr, maxLevel )
  • Same as log below but returns a string rather than outputs to log window
• _console.log(any, nolabel, noCr, maxLevel)
  • any - a message or any variable
  • maxLevel - max delth for nested objects/array, default is 5
  • noLabel - if true hides the labels such as (Array:6)
  • noCr - if true no carriage return

Below is a list of default commands, which are denoted by the square brackets.

Individual PowerScripts can extend these and have more commands, so check the documentation for each PowerScript to see if additional commands are available.

When the (not required) call _powerScriptCommand with an empty string or null

Gets a list of enabled and installed PowerScripts

Parameters

• scriptID: (not required)
• data: (not required)

Callback Return value

   object {
         success: true,
         data: [  
            {
                name: "",  
                uuid:"",
                group: ""
            },
            ......
          ] 
         }

Loads the script specified in scriptID

Parameters

• scriptID: UUID of the script to load
• data (not required)

Callback Return value

  object {success: true/false}

Gets the values of the controls in the current PowerScript panel

Parameters

• scriptID: (not required)
• data: (not required)

Callback Return value

  object {
      uuid: "",  // string containing the UUID of the loaded PowerScript
      values: [   // array of values 
             name: "",  // string containing the name of the control
             type: "" ,    // string containing the control type
             value: ??   // Value of the control, will varry depending on the type of control
         ]
      }

Sets the values of the controls in the current PowerScript panel

Set values should be in the same format as you retrieve from getValues, it is therefore recommended to call the command [getValues] and copy the format . Note that is the control does not exist it will be ignored

Data can be in a supplied range of formats where obj = {name: “”, type: “”, value: ?}

• Simple array of value objects [{obj},{obj},{obj},{obj} …]
• Object with a value property {values: [{obj},{obj},{obj},{obj} …] }
• Object with a value property and optional forceUpdate property {values: [{obj},{obj},{obj},{obj} … ], forceUpdate:true} (*see note below)
• preset data (can be obtained from exporting a setting from Powerscripts) {name: 'settings name', uuid:'###', scriptID: '###', values: [{obj},{obj},{obj},{obj} … ]}

* Some controls are preset to not automatically update their values when using setValues, such as tables that automatically load and save data from the hard drive. You can use forceUpdate to change these controls, but be aware that this might also permanently save the new table data to the hard drive. Use forceUpdate with caution.

Parameters

• scriptID: (not required)
• data: values objects

Callback Return value

   object {success: true/false}

Returns a list of saved settings for the currently loaded PowerScirpt. see using saved settings

Parameters

• scriptID: (not required)
• data: (not required)

Callback Return value

   object {
         success: true,
         data: ["name", "name", "name" ] // array of saved setting names
         }

Loads a user saved setting by name. see using saved settings

Parameters

• scriptID: (not required)
• data: object {name: “saved setting name”}

Callback Return value

   object {success: true/false}  //Retruns false if the name is not found

LoReloads the default settings for the loaded PowerScript (As if it was first loaded)

Parameters

• scriptID: (not required)
• data: (not required)

Callback Return value

   object {
         success: bool,      // false: no script loaded 
         ready:  bool,    // script loaded and ready to run commands
         alreadyLoaded:  // true if script was already loaded (will always return false as its was reloaded) 
     }

Actions are specific to each individual PowerScripts. They are like commands but can also be used for Hot Keys and Quick Keys. So using actions can achieve the same functionality as Hot Keys and Quick Keys. Use the _powerScriptActions function to run an action.

Parameters

• scriptID: (not required)
• data: (not required)

Callback Return value

   object {
         success: true,
         data: [  // array of action 
            {
                id: "",  // String containing the ID for the action - you will need this
                scriptid:"", // String contains a special scriptID, used internally
                type: "",  // the type of action which is "run" , "event" , "click",
                placeholder:"", // Used for HotKeys/Quick Keys inputs, describes the data that is expected
                label: "" // Used for HotKeys/Quick Keys, a label/description for the preset
            },
            ......
          ] 
         }

Run the current PowerScript. Check the documentation for each PowerScript to see what run arguments are required.

Parameters

• scriptID: UUID of the script
• data: { scriptID: “”, args: { … }, noUpdateIDs: […] }
  • {string|optional} scriptID: scriptID or blank for the default script
  • {object} args: Aditional arguments to send the scirpt
  • {array[{string}]} noUpdateIDs - List of controls ID not to update, use to override with args

Callback Return value

  
   object {
         success: true,  // Always true as the command ran, but see data as script may fail
         data: ????  // Will vary depending on the script
    }

//

// Dimensions Script
var scriptID = '2765bf7d-9500-4eb4-8e10-36f12e42eeac'; 

_powerScriptCommands(
	[
		{
			scriptID:scriptID,	
			action: '[load]',
			data: {}
		},
		{
			scriptID:scriptID,
			action: '[loadSavedSetting]',
			data: {name: '10 percent'}
		},
		{
			scriptID:scriptID,
			action: '[run]',
			data: {args:{'create': 'top', _alwaysrun:true}}
		},
		{
			scriptID:scriptID,
			action: '[run]',
			data: {args:{'createxxx': 'left', _alwaysrun:true}}
		},
		{
			scriptID:'08939b67-ff69-4d8d-b340-fed9227e2d07',
			action: '[load]'
		},
	],
	function onCompleted(result){
		if(result.success){
			alert('Successful');
		} else {
			_console.log(result);
			alert(result.error);
		}
	},
	true // stop on failure
);

//

//

_powerScriptCommand('', '[getSavedSettings]',{}, function onCompleted(result){
	_console.log(result);
});

//

Result

{
   success: true (bool),
   data: ["100 percent inch+mm", "floorplans", "100% red lines", "10 percent"] (Array:4),
} (object)

//

_powerScriptCommand('', '[getValues]',{}, function onCompleted(result){
	_console.log(result);
});

//

Result

{
   success: true (bool),
   data: {
      uuid: "8024ee3e-6bf0-495d-a04c-0d7236405e70" (String:36),
      values: [
         {
            name: "_accordions" (String:11),
            type: "accordions" (String:10),
            value: {} (object EMPTY),
         } (object),
         {
            name: "markStyle" (String:9),
            type: "select" (String:6),
            value: "0" (String:1),
         } (object),
         {
            name: "length" (String:6),
            type: "unitnumber" (String:10),
            value: "3 mm" (String:4),
         } (object),
         {
            name: "offset" (String:6),
            type: "unitnumber" (String:10),
            value: "3 mm" (String:4),
         } (object),
         {
            name: "bleed" (String:5),
            type: "unitnumber" (String:10),
            value: "3 mm" (String:4),
         } (object),
         ....