Methods of the Helper Object

To simplify the creation of scripts there is a helper object that is valid in the context of all the scripts. This auxiliary object is called "helper" in all scripts.

All functions listed here can throw exceptions, that react appropriately to error conditions. The administrator can decide in which function call he wants to catch the potential exceptions.

Working with forms

The following functions are suitable to work with forms in todo4teams.

TodoTaskExtendedMetaData addMetaData(long metaDataId)

This function can be appended to the forms of the current job. You may ie use  this feature If you want to automatically add a form to a mailbox on the arrival of emails.
The return value is the form attached to the ticket. Example:

var formular=helper.addMetaData(7);
TodoTaskExtendedMetaData addMetaDataByName(String metaDataName)

This is a "convenience" function that make a call using the above function. Previously it determines the ID to be used within the form name. If the name is not unique, the ID of the first identified form is taken.
The return value is the form attached to the ticket. Example:

var formular=helper.addMetaDataByName('Kundendaten');
void addValueForField(TodoTaskExtendedMetaData md, String name, Object value)

With this function the values can be set into a form. The first parameter md is the respective form. The second parameter is the name of the field and the third parameter is the value to be set.
This feature is e.g. useful when values have to be included automatically into a form from an pdf-form that was attached to an email.

TodoTaskExtendedMetaData[] getTaskMetaData()

Returns all the forms of the current ticket. Example:

var alleFormulare=helper.getTaskMetaData();

Changing the routing

The functions described in this section will provide the changing of the addressing of tickets in todo4teams. So you could, for example, change the addressing incoming mail or SMS depending on the time of day either team X or team Y.

void routeToGroup(long groupId)

This function can be used to address the current ticket to any team. The transfer parameter is the unique ID of the team. The ticket is sent as 'new' to the addressed team. A copy of the ticket with the current owner is stored in the database and is associated with the history of forwarded tickets. Example:

helper.routeToGroup(23);
void routeToGroupByName(String groupName)

A "convenience" function that performs  a call of the above mentioned function. It determines previously the ID that is used with the team name. If the name is not unique the ID of the first detected team is used. Example:

helper.routeToGroupByName('Software-Service');
void routeToUser(long userId)

This function allows the current ticket to be addressed firmly to a specific todo user. The transfer parameter is the unique ID of the user. The function should be used sparingly, since it contradicts the principle of the marketplace of todo4teams. Example:

helper.routeToUser(99);
void routeToUserByUsername(String userName)

A "convenience" function that performs  a call of the above mentioned function. It determines perviously the ID that is used with the user name. If the name is not unique the ID of the first detected user is used. Note that the username (that is, the logon ID) should be chosen - not the real name. Example:

helper.routeToUserByUsername('max.muster');
void setOwner(long userId)

This function allows the selection of the owner of a ticket. The transfer parameter is the unique ID of the owner. Example:

helper.setOwner(27);
void setOwnerByUsername(String userName)

A "convenience" function that performs  a call of the above mentioned function. It determines perviously the ID that is used with the user name. If the name is not unique the ID of the first detected user is used. Example:

helper.setOwnerByUsername('max.muster');

Changing of the target time

The following functions are used to change the target time of the current ticket.

void addSecondsToScheduledEndDate(int seconds)

With this function seconds are added to the target time. Example:

helper.addSecondsToScheduledEndDate(600);
void setDateForScheduledEndDate(int year, int month, int day, int hour, int minute, int second)

With this function the date and the time of day are determined and given as the transfer parameters to the target time for the current. Example

helper.setDateForSchedukedEndDate(2010,12,31,10,0,0);

Access to users and teams

TodoUser[] getUser()

Shows all registered users within your current instance of todo4teams. Example:

var users = helper.getUser();
var i;
for(i=0; i<users.length; i++){
 println(users[i].username);   
}
TodoWorkGroup[] getWorkGroups()

This function shows all registered teams within your current instance of todo4teams.

var groups = helper.getWorkGroups();

var i
for(i=0; i<groups.length; i++){
 println(groups[i].name);      
}

Working with attachments

With the following function of the attachments of a todo4teams ticket can be processed.

TodoAttachment[] getAttachments()

This function shows all attachments within your current ticket.

Example of finding a file attachment with the name Formular.pdf.:

for(ai=0;ai<helper.attachments.length;ai++){

var attachment = helper.attachments[ai];

println("Name: "+attachment.attachmentName);

if(attachment.attachmentName=="Formular.pdf"){

//...

}

}
void removeAllAttachments()

This function removes all attachments of the current ticket.

Example of removing all attachments from an incoming email:

helper.removeAllAttachments();
void removeAttachment(String attachmentname)

This function deletes all attachments named "attachmentname" of the current ticket.

Example of removing the file attachment named Formular.pdf:

helper.removeAttachments(„Formular.pdf“);

Working with strings

This function returns the estimated languageof the String „input“. Im E-Mail-Eingang wird zur vereinfachten Analyse der Sprache noch die Umgebungsvariable coretext bereitgestellt. Sie wird idealerweise verwendet um die Sprache einer E-Mail zu erkennen.

String getLanguage(String input)
Beispiel für Abfrage der Sprache einer eingehenden E-Mail. Die variable coretext ist mit dem Textinhalt der E-Mail belegt.
var lang = helper.getLanguage(coretext)
if(lang==“german“){
// …
} else ...
Object extractByRegExp(String input, String regExp, boolean multiMatch)

Extracts the list of hits from the string "input" using the regular expression "rexExp". The parameter multiMatch specifies whether it should evaluate all hits in depth.

In this example, an HTML file attachment is read in as a string and broken down using a regular expression. The HTML code contains a table in which the first column contains names and the second column contains values. The variables label and value take on the respective values ​​in the loop.

// ...

var content = new
java.lang.String(attachment.attachmentContent, "UTF-8");

var fields =
helper.extractByRegExp(content,

"<tr><td>(.+?)</td><td><b>(.+?)</b></td></tr>",

true);

for(j=0;j<fields.length;j++){

try{

     var label = fields[j][0];

     var value = fields[j][1];

// ...

}
String bytesToString(byte[] bytes, String charSetName)

This function creates a string from the byte sequence “bytes”. The “charSetName” parameter specifies the character set of the string to be created.
Beispiel: Umwandlung eines Byte-Arrays in einen String

Var s = helper.bytesToString(byteArray, „UTF-8“);

Working with PDF attachments

These functions can be used to edit PDF attachments in the current ticket. A helper class used here is the PdfFormField class. Describes the triple of field name, field value and field type for a field of a PDF form.

class PdfFormField {

String name;

String value;

String ftype;

}

PdfFormField[] getPdfFormFields(TodoAttachment pdfAttachment)

This function returns the list of all form fields for the passed PDF attachment.

Example: Reading the PDF form fields from a PDF file

for(ai=0;ai<helper.attachments.length;ai++){

var attachment = helper.attachments[ai];

println("Name: "+attachment.attachmentName);

if(attachment.attachmentName=="Formular.pdf"){

var fields = helper.getPdfFormFields(attachment);

}

}
void createFormFromPdfAttachment(TodoAttachment pdfAttachment, String formName)

Function for automatic form generation of forms. This can be used to automatically generate the form corresponding to a PDF form.

Example: Automatic generation of a form from a PDF form

for(ai=0;ai<helper.attachments.length;ai++){

var attachment = helper.attachments[ai];

println("Name: "+attachment.attachmentName);

if(attachment.attachmentName=="Formular.pdf"){

helper.createFormFromPdfAttachment(attachment);

}

}

Generate new jobs

available for
☑ SMS scripts
☑ Email scripts
☑ Start action
☑ End action

The function

long createTask(
int addressedGroupId,
String title,
String description,
int minutes,
int ownerId,
Map<Long, Map<String, Object>> forms,
List<ToDoAttachment> attachments)

enables the creation of new tickets within a script execution. The ID of the generated ticket is returned as a result.

In the following example, a ticket with an attached form and file attachment is sent to the group with ID 17.

var forms = new
 java.util.HashMap();

var values = new
 java.util.HashMap();

values.put(new
 java.lang.String("Name_t"), new
 java.lang.String("Bergener"));

values.put(new
 java.lang.String("Vorname_t"), new
 java.lang.String("Thomas"));

forms.put(new
 java.lang.Long(41), values);

var attachments = new
 java.util.ArrayList();

var att1 = new
 com.proxemo.todo.bom.ToDoAttachment();


att1.setAttachmentName("test1.txt");

att1.setAttachmentContent(new
 java.lang.String("some file content").getBytes());


attachments.add(att1);


var minutes = 20;

var toGroup = 17;

var owner = 0;

var id = helper.createTask(toGroup, "Create!","Just do it!", minutes, owner, forms,attachments);

Display messages

available for
☑ Send action
☑ Accept action
☑ Complete action
The functions in this section are used to display messages from a script. This is particularly useful for the completion scripts of forms. These scripts can be used to carry out consistency checks in todo4teams before a ticket is closed. If these fail, for example, this can be signaled using these functions.

void errorMessage(String message)

Example: Displaying an error message.

helper.errorMessage(„Es ist ein Fehler aufgetreten!“);
Back to Auxiliary Scripting Objects in todo4teams...

To simplify the creation of scripts there is a helper object that is valid in the context of all the scripts. This auxiliary object is called "helper" in all scripts.

All functions listed here can throw exceptions, that react appropriately to error conditions. The administrator can decide in which function call he wants to catch the potential exceptions.

Working with forms

The following functions are suitable to work with forms in todo4teams.

TodoTaskExtendedMetaData addMetaData(long metaDataId)

This function can be appended to the forms of the current job. You may ie use  this feature If you want to automatically add a form to a mailbox on the arrival of emails.
The return value is the form attached to the job. Example:

var formular=helper.addMetaData(7);
TodoTaskExtendedMetaData addMetaDataByName(String metaDataName)

This is a "convenience" function that make a call using the above function. Previously it determines the ID to be used within the form name. If the name is not unique, the ID of the first identified form is taken.
The return value is the form attached to the job. Example:

var formular=helper.addMetaDataByName('Kundendaten');
void addValueForField(TodoTaskExtendedMetaData md, String name, Object value)

With this function the values can be set into a form. The first parameter md is the respective form. The second parameter is the name of the field and the third parameter is the value to be set.
This feature is e.g. useful when values have to be included automatically into a form from an pdf-form that was attached to an email.

TodoTaskExtendedMetaData[] getTaskMetaData()

Returns all the forms of the current job. Example:

var alleFormulare=helper.getTaskMetaData();

Changing the routing

The functions described in this section will provide the changing of the addressing of jobs in todo4teams. So you could, for example, change the addressing incoming mail or SMS depending on the time of day either group X or group Y.

void routeToGroup(long groupId)

This function can be used to address the current job to any group or skill. The transfer parameter is the unique ID of the group. The job is sent as 'new' to the addressed group. A copy of the job with the current owner is stored in the database and is associated with the history of forwarded jobs. Example:

helper.routeToGroup(23);
void routeToGroupByName(String groupName)

A "convenience" function that performs  a call of the above mentioned function. It determines previously the ID that is used with the group name. If the name is not unique the ID of the first detected group is used. Example:

helper.routeToGroupByName('Software-Service');
void routeToUser(long userId)

This function allows the current job to be addressed firmly to a specific todo user. The transfer parameter is the unique ID of the user. The function should be used sparingly, since it contradicts the principle of the marketplace of todo4teams. Example:

helper.routeToUser(99);
void routeToUserByUsername(String userName)

A "convenience" function that performs  a call of the above mentioned function. It determines perviously the ID that is used with the user name. If the name is not unique the ID of the first detected user is used. Note that the username (that is, the logon ID) should be chosen - not the real name. Example:

helper.routeToUserByUsername('max.muster');
void setOwner(long userId)

This function allows the selection of the owner of a job. The transfer parameter is the unique ID of the owner. Example:

helper.setOwner(27);
void setOwnerByUsername(String userName)

A "convenience" function that performs  a call of the above mentioned function. It determines perviously the ID that is used with the user name. If the name is not unique the ID of the first detected user is used. Example:

helper.setOwnerByUsername('max.muster');

Changing of the target time

The following functions are used to change the target time of the current job.

void addSecondsToScheduledEndDate(int seconds)

With this function seconds are added to the target time. Example:

helper.addSecondsToScheduledEndDate(600);
void setDateForScheduledEndDate(int year, int month, int day, int hour, int minute, int second)

With this function the date and the time of day are determined and given as the transfer parameters to the target time for the current. Example

helper.setDateForSchedukedEndDate(2010,12,31,10,0,0);

Access to users and groups/skills

TodoUser[] getUser()

Shows all registered users within your current instance of todo4teams. Example:

var users = helper.getUser();
var i;
for(i=0; i<users.length; i++){
 println(users[i].username);   
}
TodoWorkGroup[] getWorkGroups()

This function shows all registered groups and skills within your current instance of todo4teams.

var groups = helper.getWorkGroups();

var i
for(i=0; i<groups.length; i++){
 println(groups[i].name);      
}

Working with attachments

With the following function of the attachments of a todo4teams job can be processed.

TodoAttachment[] getAttachments()

This function shows all attachments within your current job.

Example of finding a file attachment with the name Formular.pdf.:

for(ai=0;ai<helper.attachments.length;ai++){

var attachment = helper.attachments[ai];

println("Name: "+attachment.attachmentName);

if(attachment.attachmentName=="Formular.pdf"){

//...

}

}
void removeAllAttachments()

This function removes all attachments of the current Todo job.

Example of removing all attachments from an incoming email:

helper.removeAllAttachments();
void removeAttachment(String attachmentname)

This function deletes all attachments named "attachmentname" of the current Todo job.

Example of removing the file attachment named Formular.pdf:

helper.removeAttachments(„Formular.pdf“);

Working with strings

This function returns the presumed language based on the passed string "input". The environment variable coretext is also provided in the email inbox to simplify language analysis. It is ideally used to identify the language of an email.

String getLanguage(String input)
Example of querying the language of an incoming email. The variable coretext is filled with the text content of the email.
var lang = helper.getLanguage(coretext)
if(lang==“german“){
// …
} else ...
Object extractByRegExp(String input, String regExp, boolean multiMatch)

Extracts the list of hits from the string "input" using the regular expression "rexExp". The parameter multiMatch specifies whether it should evaluate all hits in depth.

In this example, an HTML file attachment is read in as a string and broken down using a regular expression. The HTML code contains a table in which the first column contains names and the second column contains values. The variables label and value take on the respective values ​​in the loop.

// ...

var content = new
java.lang.String(attachment.attachmentContent, "UTF-8");

var fields =
helper.extractByRegExp(content,

"<tr><td>(.+?)</td><td><b>(.+?)</b></td></tr>",

true);

for(j=0;j<fields.length;j++){

try{

     var label = fields[j][0];

     var value = fields[j][1];

// ...

}
String bytesToString(byte[] bytes, String charSetName)

This function creates a string from the byte sequence “bytes”. The “charSetName” parameter specifies the character set of the string to be created.

Example: Converting a byte array to a string

Var s = helper.bytesToString(byteArray, „UTF-8“);

Working with PDF attachments

These functions can be used to edit PDF attachments to the current ticket. A helper class used here is the PdfFormField class. Describes the triple of field name, field value and field type for a field of a PDF form.

class PdfFormField {

String name;

String value;

String ftype;

}

PdfFormField[] getPdfFormFields(TodoAttachment pdfAttachment)

This function returns the list of all form fields for the passed PDF attachment.

Example: Reading the PDF form fields from a PDF file

for(ai=0;ai<helper.attachments.length;ai++){

var attachment = helper.attachments[ai];

println("Name: "+attachment.attachmentName);

if(attachment.attachmentName=="Formular.pdf"){

var fields = helper.getPdfFormFields(attachment);

}

}
void createFormFromPdfAttachment(TodoAttachment pdfAttachment, String formName)

Funktion zur automatische Formulargenerierung von Todo-Formularen. Hiermit kann automatisch das zu einem PDF-Formular korrespondierende Todo-Formular erzeugt werden.

Beispiel: Automatische Erzeugung eines Todo-Formulars aus einem PDF-Formular

for(ai=0;ai<helper.attachments.length;ai++){

var attachment = helper.attachments[ai];

println("Name: "+attachment.attachmentName);

if(attachment.attachmentName=="Formular.pdf"){

helper.createFormFromPdfAttachment(attachment);

}

}

Generate new jobs

available for
☑ SMS scripts
☑ Email scripts
☑ Start action
☑ End action

The function

long createTask(
int addressedGroupId,
String title,
String description,
int minutes,
int ownerId,
Map<Long, Map<String, Object>> forms,
List<ToDoAttachment> attachments)

enables the creation of new tickets within a script execution. The ID of the generated ticket is returned as a result.

In the following example, a ticket with an attached form and file attachment is sent to the group with ID 17.

var forms = new
 java.util.HashMap();

var values = new
 java.util.HashMap();

values.put(new
 java.lang.String("Name_t"), new
 java.lang.String("Bergener"));

values.put(new
 java.lang.String("Vorname_t"), new
 java.lang.String("Thomas"));

forms.put(new
 java.lang.Long(41), values);

var attachments = new
 java.util.ArrayList();

var att1 = new
 com.proxemo.todo.bom.ToDoAttachment();


att1.setAttachmentName("test1.txt");

att1.setAttachmentContent(new
 java.lang.String("some file content").getBytes());


attachments.add(att1);


var minutes = 20;

var toGroup = 17;

var owner = 0;

var id = helper.createTask(toGroup, "Create!","Just do it!", minutes, owner, forms,attachments);

Display messages

available for
☑ Send action
☑ Accept action
☑ Complete action
The functions in this section are used to display messages from a script. This is particularly useful for the completion scripts of forms. These scripts can be used to run consistency checks in todo4teams before a ticket is closed. If these fail, this can be signaled using these functions.

void errorMessage(String message)

Example: Displaying an error message.

helper.errorMessage(„Es ist ein Fehler aufgetreten!“);
void warningMessage(String message)

Example: Displaying a warning

helper.warningMessage(„Sie haben keinen Adressaten angegeben!“);
void infoMessage(String message)

Displaying an informational message.

Example: Displaying a message

helper.infoMessage („Vielen Dank!“);

Status of execution

static boolean executionWasSuccessfull(String result)

This is a convenience function that provides information about whether a script was executed successfully.