Using profile scripts

Most workflow solution projects include at least one profile script, which, after being assigned to a profile using the Device Policy Editor, can be executed from a printer or software client. A profile script may have any file name other than the names reserved for auto-configure scripts, and each profile script file should contain a main() function.

All LDD objects are available for use in profile scripts, and profile scripts can access library scripts.

The script file TestMFP.js in the TestMFP example template is an example of a profile script.

Library scripts, which can be accessed only by other scripts, can be used to contain common functionality, such as functions for database access, logging, and progress monitoring. Each function in a library script should use objects and methods appropriate only for scripts that will call it. For example, a library script called by a scheduled script should not use prompt objects or any scan methods.

The script file library.js in the TestSNS example template is an example of a library script.

Adding a library script to a solution

A library script does not require a specific file name. To begin adding a library script, add a blank script in the scripts\ folder.

To define the script as a library script, a specific structure is used:

• Begin the library section of the script with an empty library() function.

• Use the format library.prototype.<functionName> = function(<arguments>) for function headers.

• Create a new library object. This must be done as the last line of the script.

The following example shows the basic structure of a library script:

function library()
{
}
…
library.prototype.myFunction = function(myArgument1,myArgument2)
{
  …
}
…
new library();

Accessing the functions of a library script

To access the functions of a library script from another script, create an object reference to the library script using the context.callTask() method. The functions in the library script are then available as members of the new object.

The first argument in the callTask() method is always taskInfo.solutionName. The second argument is the script file name with no extension. For example, if the previous library script is named “mylibrary.js,” the following line creates an object reference to that library:

var myLib = context.callTask(taskInfo.solutionName, "mylibrary");

The included functions can then be accessed as follows:

myLib.myFunction(arg1,arg2)

If you have detailed knowledge of the LDD system where a solution is deployed, then you can write an auto-configure script that can:

• Create a device group.

• Add printers to a device group.

• Deploy the solution to a device group.

• Configure home screens.

• Discover devices.

• Perform a policy update.

• Set the server online.

Several events can trigger auto-configure scripts. The following script names determine the events that trigger the scripts:

• configureNewSolution.js—The script is triggered when a solution is installed on the LDD system.

• configureNewSolutionServer.js—The script is triggered when a solution is added to each LDD server in the LDD system.

• configureUpgradeSolution.js—The script is triggered after an existing solution is upgraded in the LDD system.

• configureUpgradeSolutionServer.js—The script is triggered after a solution is upgraded on each server in the LDD system.

• configureRemoveSolution.js—The script is triggered when a solution is removed from the LDD system.

• configureRemoveSolutionServer.js—The script is triggered when a solution is removed from each server in the LDD system.

• configureSolutionRestart.js—The script is triggered when a solution is installed or upgraded, or a server is restarted, in which case it is run for each solution.

To add an auto-configure script to a workflow solution, create a script using the selected name in the scripts\ folder of the workflow solution project.

Using auto-configure methods

All methods used for auto-configure are members of the caller object, which is detailed in the Lexmark Document Distributor Script Reference. These methods can also be used in a scheduled script in which the caller object is assigned as follows:

var caller = context.getObject("autoconfigUtilities")

For an example of an auto-configure script that uses several of the available methods, see the configureNewSolution.js file in the TestMFP template in the Eclipse software. Also, the simplelog.js file in the scheduled\ folder of the TestMFP template contains the preceding var statement and uses auto-configure methods.

Configuring the home screen with auto-configure

The method caller.setWelcomeScreen(groupName, solutionName, fileName) configures the home screen for the specified solution in the specified group. The specified XML file, located in the “src\solution\welcomescreen\” folder, provides a description of the layout of the home screen.

The description of a home screen for an individual device class is specified using the element <welcomescreen model="class">, where class is one of the following:

• etask—For e-Task MFPs

• sfp_etask—For e-Task SFPs

• etask2—For e-Task 2 MFPs

• etask2+—For e-Task 2+ MFPs

• sfp_etask2—For e-Task 2 SFPs

• etask3—For e-Task 3 MFPs

• sfp_etask3—For SFP e-Task 3 SFPs

• etask4—For e-Task 4 MFPs

• etask4(4.3)—For e-Task 4 MFPs with a 4.3-inch screen

• sfp_etask4(7)—For e-Task 4 SFPs with a 7-inch screen

• sfp_etask4—For e-Task 4 SFPs with a 7-inch screen

• etask5—For e-Task 5 MFPs

• sfp_etask5—For e-Task 5 SFPs

• x642—For X642 printers

• T656—For T656 printers (SFP with a touch screen)

The layout is specified as an integer in the contents of the <buttonLayout> element. The settings apply as shown in the following table.

Buttons for the home screen are contained within a <buttons> element. Each button is defined using the <button> element, which contains the following child elements to define the properties of a button:

• <action>—Specifies the action associated with the button. Values available for each device class are shown in the following table. To leave a space on the home screen, do not include this element. If Placeholder is specified for the action, then do not specify any other properties for the button.

• <displayText>—The custom display text for the button.

• <displayIcon>—The custom icon for the button.

• <profileName>—The profile to assign to the button when <action> contains Single Profile, Copy + Profile, Fax + Profile, or Email + Profile.

• <shortcut>—The shortcut number assigned to the button when <action> contains Shortcut.

Determine the placement of each button by the order in which the buttons are defined.

• MFPs and SFPs with touch screens—The first button specified is the button nearest to the upper-left corner of the home screen in the specified layout. The order of the buttons progresses from left to right, and then from top to bottom by rows. If subsequent pages are present, then each page begins after all buttons have been specified on the previous page. To leave a blank space in the specified layout, define the button using the <button> element. Do not include the <action> element or any other properties of the button.

• SFPs without touch screens—The buttons appear as menu items in the order in which they are defined.

The following sample XML file specifies a home screen for e-Task 2 devices:

<?xml version="1.0" encoding="UTF-8"?>
<welcomescreen model="etask2">
   <buttonLayout>5</buttonLayout>
   <buttons>
      <!-- Buttons in page 1 -->
      <!-- A layout of 5 buttons is used, but only positions
           2 and 3 on the first page contain buttons -->
      <button/>
      <button>
         <action>Copy</action>
      </button>
      <button/>
      <button>
         <action>Fax</action>
         <displayText>My Fax</displayText>
      </button>
      <button/>
         
      <!-- Buttons in page 2 (page 2 starts after specifying all
           5 buttons on the first page) -->
      <!-- Place a profile button in position 5, using empty
           buttons for the first 4 -->
      <button/>
      <button/>
      <button/>
      <button/>
      <button>
         <action>Single Profile</action>
         <profileName>TestMFP</profileName>
         <displayText>Test MFP</displayText>
         <displayIcon>images\\testmfp_up.gif</displayIcon>
      </button>
   </buttons>
 </welcomescreen>

An example file for the home screen on each device class can be found in the “\src\solution\welcomescreen” folder of the TestMFP example template.

You can use forms merge scripts to perform advanced management of forms merge operations or modify forms merge data and output documents. Using a forms merge script, you can:

• Send merged documents to multiple destinations, including e-mail messages, printers, network shares, FTP locations, or destinations provided by custom components included with the solution.

• Retrieve and modify input data.

• Create and insert new data pages.

• Retrieve the number and description of the port used to submit the job.

• Retrieve the name of the formset associated with the job.

• Retrieve global solution settings.

• Start another merge within the current merge.

The following scripting elements are unique to forms merge scripts:

• mergeContext top-level object—This provides fields and methods for forms merge jobs.

• DataPage object—This is a page of input data.

• FormSetManageClass object—This is used to manage the formset, allowing you to add, delete, and update formsets through the methods specified in this class.

• MergeClass object—This is used to merge data with a formset.

The script file TestMergeScript.js in the TestMergeScript example template is an example of a forms merge script.

Scripting for different stages of a forms merge

Forms merge scripts use callbacks to define functions that are activated at various stages of a forms merge job. The main() function in the script contains any actions executed when the job is first submitted, as well as assignments of callback functions. You only need to define and assign callback functions for the stages where scripted actions are necessary.

Assign callback functions to the following fields of the mergeContext top-level object at the end of the main() function (or, when using exception handling, at the end of the try block within the function):

A forms merge script with all callback functions defined is structured as follows:

function main()
{
   try
   {
      //Actions to take when job is first submitted
      …
      //Assignment of callback functions
      mergeContext.renderDataPage = myRenderDataPageFunction;
      mergeContext.endDoc = myEndDocFunction;
      mergeContext.endDataSet = myEndDataSetFunction;
      mergeContext.endData = myEndDataFunction;
      mergeContext.endJob = myEndJobFunction;
   }
   catch(e)
   {
      //Logging and other exception handling
      …
      throw e;
   }
}

function myRenderDataPageFunction(page)
{
   try
   {
      //Actions to take after each page of data
      //is read from the input data
      …
   }
   catch(e)
   {
      //Logging and other exception handling
      …
      throw e;
   }
}

function myEndDocFunction(fileName)
{
   try
   {
      //Actions to take after input from a single form is completed
      //and the resulting PDF is rendered
      …
   }
   catch(e)
   {
      //Logging and other exception handling
      …
      throw e;
   }
}

function myEndDataSetFunction(fileName)
{
   try
   {
      //Actions to take after input from a single form is completed
      //and the resulting dataset is generated
      …
   }
   catch(e)
   {
      //Logging and other exception handling
      …
      throw e;
   }
}

function myEndDataFunction()
{
   try
   {
      //Actions to take after all input data is read
      …
   }
   catch(e)
   {
      //Logging and other exception handling
      …
      throw e;
   }
}

function myEndJobFunction(files)
{
   try
   {
      //Actions to take after all PDFs included
      //in the job have been rendered
      …
   }
   catch(e)
   {
      //Logging and other exception handling
      …
      throw e;
   }
}

Using the PrintClass service with forms merge scripts

As in all scripts, you can use the PrintClass service to send a document to a printer.

Two fields are particularly important when using PrintClass in a forms merge script:

• nativeSpooling—Normally, the destination printer is identified by its IP address, but input data for a forms merge may contain the name of the output queue. Set this field to true, to identify the printer by queue name instead of by IP address.

• optionMode—This field should always be set to PrintClass.OPTION_MODE_IGNORE to make sure print settings from the form are used instead of settings that may be defined using PrintClass.

Printing forms on printers with forms cards

If you have printers with forms cards, you can choose to print forms using a dataset, an XML list of key-value pairs that represent input data. Most of the information about the final output form is stored on the forms card, and only the dataset is sent to the printer. Because less data is transferred over the network, use of datasets may provide better performance with limited network bandwidth.

To use a dataset, define mergeContext.endDataSet in main(), and then use the function assigned to the field to send the dataset to the printer.

Using scheduled scripts

Scheduled scripts can be created to assist with system maintenance. Since scheduled scripts are launched by the LDD system itself rather than a printer or software client, they cannot use objects that require user intervention, such as prompt objects and scan methods.

You can use auto-configure methods for making changes to the LDD system in scheduled scripts if the caller object is assigned as follows:

var caller = context.getObject("autoconfigUtilities")

You can also access an Additional Options field that an administrator can populate with free-form text when scheduling the task in LMC. You should provide the LDD administrator with documentation on any values that the script expects in the field. Scripts access the value supplied by the administrator using the field taskInfo.additionalOptions.

To create a scheduled script, create a new script in the src\scripts\scheduled\ folder.

For more information about adding scheduled scripts in LMC, see the Lexmark Document Distributor Administrator's Guide.

Examples of scheduled scripts can be found in the TestMFP and TestSNS example templates.