Tools and automation - Batch exporting multiple files and scenes

Coherent Prysm can be part of continuous integration, testing, and automated building process of a project. The node script provided allows the user to batch the export of multiple FLA files without the need for manual interaction. Currently, this feature is only supported on Windows.

To batch export multiple FLA files:

1. Make sure the machine has Adobe Animate installed with the Coherent Prysm extension.
2. Make sure that you have enabled unsigned extensions debugging.
3. Execute npm install at least once in the batchExporter folder provided with the extension.
   • You can copy the batchExporter to a more convenient location.
4. Create a JSON config file with all the files you want to export.
   • You can use the SAMPLE_BATCH_EXPORT_CONFIG.json as reference.
5. Run the batchExport.js file with node and provide it with an --animate-path="<path> and a --config-path="<path>" e.g. ./node/node.exe ./batchExporter.js --animate-path="C:/Program Files/Adobe/Adobe Animate 2020/Animate.exe" --config-path="./config.json"
   • The --animate-path argument should lead to an Adobe Animate executable.
   • The --config-path argument should lead to a valid JSON configuration file.

Notes regarding the process

Messages from the batch exporter are written to stdout and stderr. The process can exit with a success or an error code.

If --animate-path or --config-path is omitted or invalid the batch exporter will exit with an error.

The batch exporter uses WebDriver to manipulate Adobe Animate. To do that it needs port 54323 to be free on your machine. If you want to change the default port you can check the Optional arguments section.

If publishing a document timeouts the currently opened document is closed and the batch exporter continues with the next file. The default publish timeout is 120000ms.

If an error happens while exporting a file, the procedure will recover by restarting Adobe Animate and WebDriver, and continue with the next file.

All relative paths from the config file and the command-line arguments will be resolved to the working directory of the batchExport.js script.

If the output directory of a document does not exist, it will be created by the batch exporter.

The batch exporter launches Adobe Animate and Coherent Prysm in silent mode, so warnings will be traced by the batch exporter only.

You can terminate the process gracefully with a "SIGINT" signal, which is emitted by default when you press Ctrl + C when running the process through a shell.

The process will emit its exit code when it is finished, so you can read that in combination with stdout and stderr to create an intricate build procedure.

Running the script in Admin mode should remove privilege problems.

Optional arguments

You can specify additional arguments that change the behavior of the batch exporter.

--colorize

• Colorizes the output by making the timestamp of stdout messages green and stderr messages red.

--webdriver-port="<port>"

• Changes the port which webdriver uses to connect to Adobe Animate.
• Acceptable values are in the range [1024, 65534]. The default port is 54323.

Please note that this will change the installed extension and break its certificate. To enable debugging of unsigned extensions you need to follow the steps here.

--publish-timeout="<milliseconds>"

• Changes the WebDriver publish timeout.
• We urge developers not to set a timeout less than the default 120000ms.

JSON configuration file

The JSON config file should always have a top-level "exports" array.

{
    "exports": []
}

All files that you want to export should be listed as objects in the exports array. The files will be exported from top to bottom as listed in the "exports" array.

"path"

A record should include at least a "path" key which has value the path to some Adobe Animate document.

{
    "exports": [
        {
            "path": "path/to/my/animate/document.fla"
        },
        {
            "path": "path/to/some/other/animate/document.xfl"
        }
    ]
}

If any of the records does not include a "path" key a warning will be traced and the record will be skipped.

"outputDir"

Optionally, you can include an "otputDir" key to a record, which will change the output directory of the document.

{
    "exports": [
        {
            "path": "path/to/my/animate/document.fla",
            "outputDir": "this/is/now/my/output/directory/"
        },
        {
            "path": "path/to/some/other/animate/document.xfl"
        }
    ]
}

If the provided output directory does not exist, it will be created.

Example usage of the script

The sampleRunner.js file contains code that executes the batch exporter, so you can use it as a reference.

// Do not use child_process.kill or process.kill as they might terminate the child abruptly.
// Call this script in admin mode to escape most errors with privilege.

const child_process = require('child_process');

// npm must be installed atleast once
console.log(child_process.execSync("npm install").toString());

// relative paths in the child process will be resolved by the CWD which is passed
const script = child_process.spawn("./User/Desktop/BatchExporter/thirdParty/node/node.exe", [
    './User/Desktop/BatchExporter/batchExport.js',
    '--webdriver-port="54323"',
    '--ignore-me',
    'ignore-me',
    'ignore me',
    '--animate-path="../Program Files/Adobe/Adobe Animate 2020/Animate.exe"',
    '--config-path="C:/Users/User/Desktop/BatchExporter/SAMPLE_BATCH_EXPORT_CONFIG.json"',
    '--colorize'
], { cwd: "C:/Users" });

script.stdout.on('data', (data) => {
    console.log(`STDOUT: ${data}`);
});

script.stderr.on('data', (data) => {
    console.log(`STDERR: ${data}`);
});

script.on('error', (err) => {
    console.log(`Error: ${err.toString()}`);
    process.exit(1);
});

script.on("close", (data) => {
    console.log(`Exitted: ${data}`);

    process.exit(data !== null ? data : 1);
});

process.on("SIGINT", () => {
    // Do not delete this handler. It stops the SIGINT signal from killing the child process instantly.
});

process.on("exit", (code) => {
    console.log("Parent exits with code", code);
});

Use cases and expected results

Use case	Result
I have not called npm install at least once	Exists with an error
I am not on Windows OS	Traces and exits with an error
I have not provided an --animate-path argument	Traces and exits with an error
The provided --animate-path does not exist	Traces and exits with an error
I have not provided a --config-path argument	Traces and exits with an error
The provided --config-path does not exist	Traces and exits with an error
I have provided a --webdriver-port argument in the [1024, 65534] range	The provided port is used to connect WebDriver to Animate's CEP
The provided --webdriver-port is not in the [1024, 65534] range	The port is ignored and the default one is used
I have provided a --publish-timeout argument	The timeout is used as WebDriver timeout on publish
The provided --publish-timeout is not a number	The timeout is ignored and the default one is used
I have provided a --colorize argument	The stdout and stderr timestamps are colored
I have provided an unknown argument	The provided argument is ignored
I don't have Prysm installed on my machine	Traces and exits with an error
The --config-path file can't be read	Traces and exits with an error
The --config-path file contains invalid JSON	Traces and exits with an error
The CEP debug file which changes the debug port can't be written	Traces and exits with an error
The CEP debug port is changed	Traces that the PlayerDebugMode registry needs to be set to 1
Running Adobe Animate processes fail to be killed	Traces and exits with an error
Animate's workspace fails to be prepared	Traces and exits with an error. Workspace is reverted to default state
Workspace fails to be restored after an error	Traces and exits with an error. Steps to revert manually are traced
The output window log file fails to be cleared	Export continues and a warning is traced
The backend log file fails to be cleared	Export continues and a warning is traced
Adobe Animate child process fails to be spawned	Workspace is reverted to default state. Traces and exits with an error
A critical error is hit after an instance of Adobe Animate is spawned	Adobe Animate instances are killed. Traces and exits with an error
Running Adobe Animate instances fail to be killed after an error	Traces and exits with an error. Traces to kill Adobe Animate manually
WebDriver fails to create and/or connect	Traces and exits with an error
A record does not contain a "path" variable	Export continues with next record and a warning is traced
Some "path" from the config file is not a fla or xfl file	Export continues with next record and a warning is traced
Some "path" from the config file does not exist	Export continues with next record and a warning is traced
Some "path" from the config file fails to be opened	Export continues with next record and a warning is traced
WebDriver timeouts when opening some "path" from the config file	Logs are traced. Export continues with the next record and a warning is traced. AA and WebDriver are restarted
Restarting Adobe Animate and WebDriver fails.	Traces and exits with an error
A record contains an "outputDir"	The current file is exported to the directory
Some "outputDir" does not exist	The directory is created. The current file is exported to the directory
Some "outputDir" does not exist and fails to be created	Export continues with next record and a warning is traced
Some "outputDir" is not a directory	Export continues with next record and a warning is traced
WebDriver timeouts when changing the output directory to some "outputDir"	Logs are traced. Export continues with the next record and a warning is traced. AA and WebDriver are restarted
No "outputDir" and the document output directory does not exist	The directory is created. The current file is exported to the directory
No "outputDir" and the output directory query fails	Export continues with current record and a warning is traced
No "outputDir" and the output directory query fails. Directory does not exist	Export continues with current record and a warning is traced. File is exported in the FLA directory
No "outputDir" and the document output directory fails to be created	Export continues with next record and a warning is traced
Some "path" from the config file timeouts when exporting	Logs are traced. Export continues with the next record and a warning is traced. AA and WebDriver are restarted
Some "path" from the config file crashes Adobe Animate	Logs are traced. Export continues with the next record and a warning is traced. AA and WebDriver are restarted
Some "path" is exported successfully	Output panel log traced. Export success traced
Some "path" fails to close in Adobe Animate	Export continues with next record and a warning is traced
All records are processed	Process exits with success code if all records exported successfully. Exits with an error otherwise
Adobe Animate is closed manually while the procedure is running	Dangerous. Depending on the state of the procedure exits with an error or continues with the next file
Some "path" timeouts on export	Logs are traced. Export continues with the next record and a warning is traced. AA and WebDriver are restarted
I don't have read or list directory permissions for the directory of --animate-path	Traces and exits with an error
I don't have read or list directory permissions for the directory of --config-path	Traces and exits with an error
I don't have read permissions for the --config-path file	Traces and exits with an error
I don't have read permissions for the --animate-path file	Traces and exits with an error
I don't have list directory permissions for the CoherentExporter extension folder	All files will be converted to AS3 in AA and will not be exported. Will complete export with error code
I don't have write permissions for the CoherentExporter extension folder	Traces and exits with an error
I don't have read permissions for the CoherentExporter extension folder	Traces and exits with an error
I don't have read permissions for the .debug file of the CoherentExporter extension	Debugging is disabled for our extension. WebDriver can't connect. Traces and exits with an error
I don't have write permissions for the .debug file of the CoherentExporter extension	Traces and exits with an error
I don't have write permissions for the workspace directory of Adobe Animate	Traces and exits with an error
I don't have full control permissions for the current.txt or Start.xml workspace file	Traces and exits with an error
I don't have full control permissions for the CoherentBatchExporerWorkspace.xml file	Traces and exits with an error
I don't have read/write permissions for the backend log file in %TEMP%	Warning about no backend log traced. Export continues
I don't have read/write permissions for the output panel log file in %TEMP%	Warning about no output log traced. Export continues. Can't check if document output dir exists
I don't have list directory permissions for the %TEMP% directory	Export will finish. No documents will be exported
I don't have read/write permissions for the %TEMP% directory	Adobe Animate alerts an error and crashes
I don't have read permissions for a record's "path"	Export continues with next record and a warning is traced
I don't have list directory privileges for the output dir of a record "path"	Export continues with next record and a warning is traced
I don't have read permissions for the directory of a record "path"	Export continues with next record and a warning is traced
I don't have write privileges for the output dir of a record "path"	Export continues with next record and a warning is traced
A record "path" is not a Coherent Prysm file	Export continues with next record and a warning is traced
I terminate the process with a "SIGINT" signal	Workspace is reverted. AA is killed. Process exits with an error
I terminate the process with a "SIGKILL" signal	Process exits with an error. State is undefined