Perl scripts and external programs have much in common. External programs, .exe on Windows, runnable [+x] on Unix or Linux, will be executed by directly, using java.lang.Runtime.exec(). Perl scripts are distinguished by ".pl" extension and will be run using "perl scriptname.pl" command. includes a Perl interpreter with the standard installation.

Scripts take 2 command line arguments: names of the input and output files. Input and output files are in XML format. Note that the output file is precreated by but is empty.
Input file conforms to the following DTD: 

<!DOCTYPE input[
<!ELEMENT input project_name, old_state?,
linked_records, global_vars)>
<!ELEMENT project_name (#PCDATA) >
<!ELEMENT old_state (record) >
<!ELEMENT current_state (record) >
<!ELEMENT linked_records (record) *>
<!ELEMENT global_vars (variable) *>
<!ELEMENT record (field) +>
<!ELEMENT variable (value) >
<!ATTLIST record
table CDATA #REQUIRED
xml: id ID #REQUIRED>
<!ELEMENT field (value) >
<!ATTLIST field
name CDATA #REQUIRED
linked_refid IDREFS #IMPLIED>
<!ELEMENT value (#PCDATA) >
<!ATTLIST variable
name CDATA #REQUIRED>
]>
<?xml version="1.0" encoding="UTF-8"?>
<input>
  <project_name>Demo</project_name>
  <old_state>
    <record table="cases" xml:id="rec1">
      <field name="_118_f_user_login">
        <value>null</value>
      </field>
      <field name="internal_comments">
        <value>null</value>
      </field>
      <field name="f_from">
        <value>null</value>
      </field>
      <field name="bcc">
        <value>null</value>
      </field>
      <field name="publication_date">
        <value>31/12/1969 13:00:00</value>
      </field
      <field name="assign_date">
        <value>31/12/1969 13:00:00</value>
      </field>
      <field name="workflow_state">
        <value>null</value>
      </field>
      <field name="id">
        <value>8</value>
      </field>
      <field name="creator_full_name">
        <value>null</value>
      </field>
      <field name="_dao3_link3">
        <value>[0-14]</value>
      </field>
      <field name="_dao3_link0">
        <value>[]</value>
      </field>
      <field name="_link_art_column">
        <value></value>
      </field>
      <field name="attached_files">
        <value></value>
      </field>
      <field name="published">
        <value></value>
      </field>
      <field name="_649_f_fullname">
        <value>null</value>
      </field>
      <field name="parentid">
        <value>null</value>
      </field>
      <field name="date_">
        <value>null</value>
      </field>
      <field name="steps_to_duplicate">
        <value>Heres how to duplicate</value>
      </field>
      <field name="summary">
        <value>test of new fields</value>
      </field>
      <field name="attachments">
        <value>null</value>
      </field>
      <field name="owner">
        <value>14</value>
      </field>
      <field name="id0">
        <value>null</value>
      </field>
      <field name="owned_by" linked_refid="rec3">
        <value>admin</value>
      </field>
      <field name="_dao3_link">
        <value>[]</value>
      </field>
      <field name="full_name">
        <value>null</value>
      </field>
      <field name="email_type">
        <value>null</value>
      </field>
      <field name="message">
        <value>null</value>
      </field>
      <field name="telephone">
        <value>null</value>
      </field>
      <field name="_dao3_link1">
        <value>[]</value>
      </field>
      <field name="_dao3_link2">
        <value>[]</value>
      </field>
      <field name="company">
        <value>null</value>
      </field>
      <field name="solution">
        <value>null</value>
      </field>
      <field name="creator_email">
        <value>|HTML</value>
      </field>
      <field name="masterid">
        <value>null</value>
      </field>
      <field name="reply_to">
        <value>null</value>
      </field>
      <field name="standard_solution">
        <value>No</value>
      </field>
      <field name="priority">
        <value>Medium</value>
      </field>
      <field name="type">
        <value>Case.Bug Report</value>
      </field>
      <field name="cc">
        <value>null</value>
      </field>
      <field name="wfstate">
        <value></value>
      </field>
      <field name="_110_f_user_login">
         <value>null</value>
       </field>
       <field name="deleteable">
         <value></value>
       </field>
       <field name="creator">
         <value>14</value>
       </field>
       <field name="assignto">
         <value>null</value>
       </field>
       <field name="description">
         <value>Here we are</value>
       </field>
       <field name="creator_telephone">
         <value>null</value>
       </field>
       <field name="email">
         <value>|HTML</value>
       </field>
       <field name="_weighted_rating">
         <value>null</value>
       </field>
       <field name="subject">
         <value>null</value>
       </field>
       <field name="created_by">
         <value>null</value>
       </field>
       <field name="f_to">
         <value>null</value>
       </field>
       <field name="_649_f_contacts_cell_phone">
         <value>6503638270</value>
       </field>
     </record>
   </old_state>
   <current_state>
     <record table="cases" xml:id="rec2">
       <field name="_118_f_user_login">
         <value>null</value>
       </field>
       <field name="internal_comments">
         <value></value>
       </field>
       <field name="f_from">
         <value>null</value>
       </field>
       <field name="bcc">
         <value>null</value>
       </field>
       <field name="publication_date">
         <value>31/12/1969 13:00:00</value>
       </field>
       <field name="assign_date">
         <value>31/12/1969 13:00:00</value>
       </field>
       <field name="workflow_state">
         <value>null</value>
       </field>
       <field name="id">
         <value>8</value>
       </field>
       <field name="creator_full_name">
         <value></value>
       </field>
       <field name="_dao3_link3">
         <value>[0-14]</value>
       </field>
       <field name="_dao3_link0">
         <value>[]</value>
       </field>
       <field name="_link_art_column">
         <value></value>
       </field>
       <field name="attached_files">
         <value></value>
       </field>
       <field name="published">
         <value></value>
       </field>
       <field name="_649_f_fullname">
         <value>null</value>
       </field>
       <field name="parentid">
         <value>null</value>
       </field>
       <field name="date_">
         <value>null</value>
       </field>
       <field name="steps_to_duplicate">
         <value>Heres how to duplicate</value>
       </field>
       <field name="summary">
         <value>test of new fields</value>
       </field>
       <field name="attachments">
         <value>null</value>
       </field>
       <field name="owner">
         <value>14</value>
       </field>
       <field name="id0">
         <value>null</value>
       </field>
       <field name="owned_by" linked_refid="rec3">
         <value>admin</value>
       </field>
       <field name="_dao3_link">
         <value>[]</value>
       </field>
       <field name="full_name">
         <value>null</value>
       </field>
       <field name="email_type">
         <value>null</value>
       </field>
       <field name="message">
         <value>null</value>
       </field>
       <field name="telephone">
         <value></value>
       </field>
       <field name="_dao3_link1">
         <value>[]</value>
       </field>
       <field name="_dao3_link2">
         <value>[]</value>
       </field>
       <field name="company">
         <value></value>
       </field>
       <field name="solution">
         <value></value>
       </field>
       <field name="creator_email">
         <value>|HTML</value>
       </field>
       <field name="masterid">
         <value>null</value>
       </field>
       <field name="reply_to">
         <value>null</value>
       </field>
       <field name="standard_solution">
         <value>No</value>
       </field>
       <field name="priority">
         <value>Medium</value>
       </field>
       <field name="type">
         <value>Case.Bug Report</value>
       </field>
       <field name="cc">
         <value>null</value>
       </field>
       <field name="wfstate">
         <value>Closed</value>
       </field>
       <field name="_110_f_user_login">
         <value>null</value>
       </field>
       <field name="deleteable">
         <value></value>
       </field>
       <field name="creator">
         <value>14</value>
       </field>
       <field name="assignto">
         <value>null</value>
       </field>
       <field name="description">
         <value>Here we are</value>
       </field>
       <field name="creator_telephone">
         <value></value>
       </field>
       <field name="email">
         <value>|HTML</value>
       </field>
       <field name="_weighted_rating">
         <value>null</value>
       </field>
       <field name="subject">
         <value>null</value>
       </field>
       <field name="created_by">
         <value>null</value>
       </field>
       <field name="f_to">
         <value>null</value>
       </field>
       <field name="_649_f_contacts_cell_phone">
         <value>6503638270</value>
       </field>
     </record>
   </current_state>
   <linked_records>
     <record table="contacts" xml:id="rec3">
       <field name="_appendtext_ref_key_created_by">
         <value></value>
       </field>
       <field name="_appendtext_ref_key_city">
         <value></value>
       </field>
       <field name="stop_work">
         <value>21:03:36</value>
       </field>
       <field name="lead_owner">
         <value>null</value>
       </field>
       <field name="_appendtext_ref_key_last_name">
         <value></value>
       </field>
       <field name="fullname">
         <value>Admin Default Admin</value>
       </field>
       <field name="_dao3_link0">
         <value>[]</value>
       </field>
       <field name="_link_art_column">
         <value></value>
       </field>
       <field name="attached_files">
         <value></value>
       </field>
       <field name="parentid">
         <value>null</value>
       </field>
       <field name="made_sale?">
         <value></value>
       </field>
       <field name="probability_of_sale_within_1_month">
         <value>0.0</value>
       </field>
       <field name="_login">
         <value>admin</value>
       </field>
       <field name="time_zone">
         <value></value>
       </field>
       <field name="_appendtext_ref_key_first_name">
         <value></value>
       </field>
       <field name="attachments">
         <value>null</value>
       </field>
       <field name="_106_sw_description">
         <value>Staff</value>
       </field>
       <field name="probability_of_sale_within_3_months">
         <value>0.0</value>
       </field>
       <field name="_100_sw_systemteamid">
         <value>0</value>
       </field>
       <field name="id0">
         <value>null</value>
       </field>
       <field name="nextcontact">
         <value>null</value>
       </field>
       <field name="amount_of_sale">
         <value>0.0</value>
       </field>
       <field name="factors_that_helped_sale">
         <value></value>
       </field>
       <field name="state">
         <value></value>
       </field>
       <field name="_appendtext_ref_key_additional_comments">
         <value></value>
       </field>
       <field name="_105_sw_description">
         <value>&lt;dao_line 1&gt;Staff&lt;/dao_line&gt;&lt;dao_line 7&gt;All&lt;/dao_line&gt;</value>
       </field>
       <field name="email_type">
         <value>null</value>
       </field>
       <field name="message">
         <value>null</value>
       </field>
       <field name="telephone">
         <value>null</value>
       </field>
       <field name="rating">
         <value></value>
       </field>
       <field name="_appendtext_ref_key_id0">
         <value></value>
       </field>
       <field name="close_date">
         <value>08/07/2003</value>
       </field>
       <field name="reply_to">
         <value>null</value>
       </field>
       <field name="_appendtext_ref_key_subject">
         <value></value>
       </field>
       <field name="_101_sw_systemgroupid">
         <value>0</value>
       </field>
       <field name="_appendtext_ref_key_other_decision_makers">
         <value></value>
       </field>
       <field name="_appendtext_ref_key_email_type">
         <value></value>
       </field>
       <field name="city">
         <value>unknown</value>
       </field>
       <field name="website_url">
         <value></value>
       </field>
       <field name="_appendtext_ref_key__231_f_company_company_name">
         <value></value>
       </field>
       <field name="picture">
         <value></value>
       </field>
       <field name="last_name">
         <value>Default Admin</value>
       </field>
       <field name="lead_source">
         <value></value>
       </field>
       <field name="actions_taken">
         <value></value>
       </field>
       <field name="creator">
         <value>14</value>
       </field>
       <field name="country">
         <value>Unknown Country</value>
       </field>
       <field name="cell_phone">
         <value>null</value>
       </field>
       <field name="start_work">
         <value>21:03:36</value>
       </field>
       <field name="f_to">
         <value>null</value>
       </field>
       <field name="f_from">
         <value>null</value>
       </field>
       <field name="bcc">
         <value>null</value>
       </field>
       <field name="_appendtext_ref_key_owned_by">
         <value></value>
       </field>
       <field name="fax">
         <value>null</value>
       </field>
       <field name="id">
         <value>14</value>
       </field>
       <field name="_231_f_company_company_name">
         <value>null</value>
       </field>
       <field name="_dao3_link3">
         <value>[]</value>
       </field>
       <field name="instant_messaging_nickname">
         <value>null</value>
       </field>
       <field name="_appendtext_ref_key__login">
         <value></value>
       </field>
       <field name="date_">
         <value>null</value>
       </field>
       <field name="first_name">
         <value>Admin</value>
       </field>
       <field name="zip_code">
         <value>12345</value>
       </field>
       <field name="_appendtext_ref_key_title">
         <value></value>
       </field>
       <field name="pager">
         <value>|HTML</value>
       </field>
       <field name="additional_comments">
         <value></value>
       </field>
       <field name="owner">
         <value>14</value>
       </field>
       <field name="_appendtext_ref_key_comments">
         <value></value>
       </field>
       <field name="_appendtext_ref_key_instant_messaging_nickname">
         <value></value>
       </field>
       <field name="_appendtext_ref_key_street_address">
         <value></value>
       </field>
       <field name="other_decision_makers">
         <value></value>
       </field>
       <field name="_appendtext_ref_key_date_">
         <value></value>
       </field>
       <field name="_dao3_link">
         <value>[0-6]</value>
       </field>
       <field name="owned_by">
         <value>null</value>
       </field>
       <field name="history">
         <value>Actor: admin Date: Thu Mar 31 15:09:15 MSD 2005 Description: Record
 added; initial values:</value>
       </field>
       <field name="_groupid">
         <value>14</value>
       </field>
       <field name="comments">
         <value>null</value>
       </field>
       <field name="title">
         <value>Admin</value>
       </field>
       <field name="_appendtext_ref_key__235_f_user_login">
         <value></value>
       </field>
       <field name="_dao3_link2">
         <value>[0-1]</value>
       </field>
       <field name="_dao3_link1">
         <value>[0-1, 0-7]</value>
       </field>
       <field name="home_phone">
         <value>null</value>
       </field>
       <field name="masterid">
         <value>null</value>
       </field>
       <field name="_235_f_user_login">
         <value>null</value>
       </field>
       <field name="password">
         <value>******</value>
       </field>
       <field name="_dao3_link5">
         <value>[]</value>
       </field>
       <field name="_104_sw_description">
         <value>&lt;dao_line 6&gt;admin&lt;/dao_line&gt;</value>
       </field>
       <field name="type">
         <value>Contact.User.Employee</value>
       </field>
       <field name="street_address">
         <value>unknown</value>
       </field>
       <field name="cc">
         <value>null</value>
       </field>
       <field name="factors_that_hurt_sale">
         <value></value>
       </field>
       <field name="deleteable">
         <value></value>
       </field>
       <field name="_dao3_link4">
         <value>[]</value>
       </field>
       <field name="email">
         <value>junk@example.com|HTML</value>
       </field>
       <field name="subject">
         <value>null</value>
       </field>
       <field name="_appendtext_ref_key_message">
         <value></value>
       </field>
       <field name="wfstate">
         <value></value>
       </field>
       <field name="stage">
         <value></value>
       </field>
       <field name="created_by">
         <value>null</value>
       </field>
     </record>
   </linked_records>
   <global_vars>
     <variable name="my_Close_Date">
       <value>2003-07-08 21:19:06.0</value>
     </variable>
     <variable name="my_Created_By">
       <value></value>
     </variable>
     <variable name="my_Fax">
       <value></value>
     </variable>
     <variable name="my_Stop_Work">
       <value>00:03:36</value>
     </variable>
     <variable name="my_Group_Name">
       <value>&lt;dao_line 1&gt;Staff&lt;/dao_line&gt;&lt;dao_line 7&gt;All&lt;/dao_line&gt;</value>
     </variable>
     <variable name="my_Start_Work">
       <value>00:03:36</value>
     </variable>
     <variable name="my_Last_Name">
       <value>Default Admin</value>
     </variable>
     <variable name="my_Actions_Taken">
       <value></value>
     </variable>
     <variable name="my_groups">
       <value>admin</value>
     </variable>
     <variable name="my_From">
       <value></value>
     </variable>
     <variable name="my_Lead_Source">
       <value></value>
     </variable>
     <variable name="my_Zip_Code">
       <value>12345</value>
     </variable>
     <variable name="my_deleteable">
       <value></value>
     </variable>
     <variable name="my_Object_type">
       <value>employees</value>
     </variable>
     <variable name="my_Pager">
       <value>|HTML</value>
     </variable>
     <variable name="my_Owned_By">
       <value></value>
     </variable>
     <variable name="my_Additional_Comments">
       <value></value>
     </variable>
     <variable name="my_Factors_that_hurt_sale">
       <value></value>
     </variable>
     <variable name="my_Message">
       <value></value>
     </variable>
     <variable name="my_primarygroup_id">
       <value>14</value>
     </variable>
     <variable name="my_CC">
       <value></value>
     </variable>
     <variable name="my_First_Name">
       <value>Admin</value>
     </variable>
     <variable name="my_primarygroup_description">
       <value></value>
     </variable>
     <variable name="my_primarygroup_dn">
       <value></value>
     </variable>
     <variable name="my_Made_Sale?">
       <value></value>
     </variable>
     <variable name="my_Description">
       <value>&lt;dao_line 6&gt;admin&lt;/dao_line&gt;</value>
     </variable>
     <variable name="my_Amount_of_sale">
       <value>0.0</value>
     </variable>
     <variable name="my_Date">
       <value></value>
     </variable>
     <variable name="my_Team_Name">
       <value>Staff</value>
     </variable>
     <variable name="my_Website_URL">
       <value></value>
     </variable>
     <variable name="my_Lead_Owner">
       <value></value>
     </variable>
     <variable name="my_Other_Decision_makers">
       <value></value>
     </variable>
     <variable name="my_primarygroup_name">
       <value>admin</value>
     </variable>
     <variable name="my_MasterID">
       <value></value>
     </variable>
     <variable name="my_Login">
       <value>admin</value>
     </variable>
     <variable name="my_Workflow_State">
       <value></value>
     </variable>
     <variable name="my_Title">
       <value>Admin</value>
     </variable>
     <variable name="my_Email">
       <value>junk@<ew:productsite><span class="product1">enterprisewizard.com</span><span class="product2">saaswizard.com</span></ew:productsite>|HTML</value>
     </variable>
     <variable name="my_Home_Phone">
       <value></value>
     </variable>
     <variable name="my_Rating">
       <value></value>
     </variable>
     <variable name="my_dn">
       <value></value>
     </variable>
     <variable name="my_Probability_of_sale_within_1_month">
       <value>0.0</value>
     </variable>
     <variable name="my_Internal_group_ID">
       <value>14</value>
     </variable>
     <variable name="my_Attachments">
       <value></value>
     </variable>
     <variable name="my_Cell_Phone">
       <value></value>
     </variable>
     <variable name="my_teams">
       <value>all,staff</value>
     </variable>
     <variable name="my_Time_Zone">
       <value></value>
     </variable>
     <variable name="my_Full_name">
       <value>Admin Default Admin</value>
     </variable>
     <variable name="my_login">
       <value>admin</value>
     </variable>
     <variable name="my_PK_of_owner">
       <value>14</value>
     </variable>
     <variable name="my_Subject">
       <value></value>
     </variable>
     <variable name="my_Street_Address">
       <value>unknown</value>
     </variable>
     <variable name="my_City">
       <value>unknown</value>
     </variable>
     <variable name="my_Instant_Messaging_Nickname">
       <value></value>
     </variable>
     <variable name="my_Telephone">
       <value></value>
     </variable>
     <variable name="my_PK_of_creator">
       <value>14</value>
     </variable>
     <variable name="my_ID">
       <value></value>
     </variable>
     <variable name="my_name">
       <value>admin</value>
     </variable>
     <variable name="my_Factors_that_helped_sale">
       <value></value>
     </variable>
     <variable name="my_To">
       <value></value>
     </variable>
     <variable name="my_Lead_Creator">
       <value></value>
     </variable>
     <variable name="NULL">
       <value>NULL</value>
     </variable>
     <variable name="my_Reply_To">
       <value></value>
     </variable>
     <variable name="my_Company_Name">
       <value></value>
     </variable>
     <variable name="my_linked_field_Link_Column_Label">
       <value>0</value>
     </variable>
     <variable name="my_description">
       <value></value>
     </variable>
     <variable name="my_State">
       <value></value>
     </variable>
     <variable name="my_Stage">
       <value></value>
     </variable>
     <variable name="my_Country">
       <value>Unknown Country</value>
     </variable>
     <variable name="my_ParentID">
       <value></value>
     </variable>
     <variable name="my_Probability_of_sale_within_3_months">
       <value>0.0</value>
     </variable>
     <variable name="my_Email_Type">
       <value></value>
     </variable>
     <variable name="my_BCC">
       <value></value>
     </variable>
     <variable name="my_Next_Contact">
       <value></value>
     </variable>
     <variable name="my_Comments">
       <value></value>
     </variable>
   </global_vars>
 </input>

For Perl scripts there are interface modules for interaction with provided; see full description below.

Output file example: 

<?xml version= "1.0" encoding="UTF-8" ?>
<!DOCTYPE output[
<!ELEMENT output (exitAction?, debug?, message?, redirect?, report?,
record?) >
<!ELEMENT exitAction (#PCDATA) >
<!ELEMENT debug (#PCDATA) >
<!ELEMENT message (#PCDATA) >
<!ELEMENT redirect (#PCDATA) >
<!ELEMENT report (#PCDATA) >
<!ELEMENT record (field) +>
<!ELEMENT field (value) >
<!ATTLIST field
name CDATA #REQUIRED>
<!ELEMENT value (#PCDATA) >
]>
<output>
<exitAction>AcceptChanges</exitAction>
<debug> Something to be sent to the server logs</debug>
<message> Script accepts your data</message>
<report> Some report for the history fuctionality</report>
<record>
<field name= "assigned_to" >
<value> Umbra</value>
</field>
<field name= "summary" >
<value> some summary here</value>
</field>
</record>
</output> 

This file describes the script result, with assigned_to field value set to "Umbra", summary set to "some summary here", changes accepted to be put to database, and "Script accepts your data" message is shown to user.

Both files always use UTF-8 encoding. Input file uses xml: id; see http://www.w3.org/TR/2004/WD-xml-id-20041109/ for assistance with referring to the linked records. Things like project and table names and values from user record are not translated into the user's language. When converting user record into XML format uses so-called Stringifiers from com.supportwizard.util.stringify package.

In short, for every column type there exists a stringifier that can translate the internal data representation into String and vice-versa. For instance, if there is a Choice 'priority' column that contains 'Medium' value, it's internal representation is Medium's ID and choices stringifier will convert this ID into 'Medium' string for scripts, - then some script can change 'Medium' into 'High' and stringifier will convert it back into 'High's ID. This implies that values produced by scripts must be understandable by stringifiers. See the appendix for full stringifiers info.

All of the output file fields are optional, except for <redirect> that must be present if exit code is 2 or 3; see below. If there 's no <record>, then it is considered to be unmodified. <debug> only sends it's content to system log. <report> provides data for a report that will appear in the history tab. <message> and <redirect> are covered below.

The main thing that expects from a script is its return (exit) code. There are 4 possible values:

It is also possible to use <exitAction> to override the exit codes. Recognized values are:

If exitAction is present, it overrides the "Raw" exit code. For instance if <exitAction>is set to AcceptChanges and exit code is 1, changes will be accepted.

Scripts must reside in the scripts directory. By default it is .installation.dir}/data/\${kb.name}/scripts. When creating script action, user should specify the script filename as action name, like "myScript.pl", for example.

Related articles