Help

Page tree

EWget Module

EWget::load($fileName)

Loads the input file into internal data structures, you will be calling it like this:

Example

my ($input_fname, $output_fname) =@ARGV;
EWget::load($input_fname);

Comments

This is the first thing you must do before any further calls to EWget functions. This call is the same for all scripts.

 

EWget::getValue($recordName, $fieldname)

Returns the value for the field of the record.

Example

 To retrieve the current value of the 'status' field: 

EWget::getValue('current_state', 'status') 
EWget::getValue('old_state', 'status')

Retrieves the old value of the 'status' field, i.e its value prior to any changes made by the user:

Comments

This is the core method for accessing field values, but see also EWget::record($path), it is a more elegant method for retrieving the fields of the 'current_state' record.

EWget::getGlobalVariable($variableName)

Returns the value of the specified variable. For example:

Example

 The following function retrieves the value of the "my_first_name" field in the contact entry of the user who caused the script to run. 

printf "my_name= '% s' \n", EWget::getGlobalVariable('my_first_name'); 

Comments

Global variables contain KB-wide settings along with user-specific settings, they are also used in saved searches and formulas.

EWget::getLinkedValue($recordName, ...)

Returns value of a field from a linked record.

Parameters:

  • name of base record
  • name of field from base record
  • index of linked record (always=0 at present, because as noted in the getLinkedRecordsNamesList description, only "single" value linked fields are currently exported to scripts)
  • name of field of linked record

Example

 To find the value of the "email" field of the employee responsible for the given case: 

my $responsible_person_email=
EWget::getLinkedValue("current_state", "assigned_to", 0,
"email");

Comments

This is the core method for accessing the data in linked records.

EWget::record($path)

Returns the value of a field in a record.

This function provides a "compact" navigation through the record data for the "current_state" record.

Path format: fieldname [.reffieldname[#index]]

Example

 "email" - returns the value of current_state.email

"email.username" - returns the value of the "username" field for the first referenced record from current_state.email

So: 

EWget::record(email.username)

is equal to 

EWget::getLinkedValue("current_state",
"email", 0, "username");

Comments

As the above example shows, EWget::record() is not really necessary, but it is certainly convenient.

EWget::getCallInitiator()

Returns a string that indicates the action that caused the script to be called.

The value returned is one of:

WEB_WORKFLOW-A workflow action, typically initiated by a user changing the Workflow State in the GUI.

WEB_BUSINESS_RULE-A business rule that is triggered by a change to a record

TIMER_BUSINESS_RULE-A business rule that runs automatically at specified intervals

EMAIL-Inbound email

API-An action triggered by the Web Services API

Comments

This function is useful when you have a single script that responds differently, depending upon the cause of the event. For example, if a ticket is updated via email and meets some special criteria, you might send a confirmation email if the update was performed through email, and provide a message in the GUI if the update was performed using the web interface.

EWget debug functions:

The following functions are mostly used for debugging scripts.

EWget::getGlobalVariablesNamesList()

Returns a sorted array of global variables names.

Example

 Names of all available variables

printf "all vars: %s\n", join(',', EWget::getGlobalVariablesNamesList());

Comments

You will usually know what global variables you want to use in your scripts, so this function is mostly for debugging purposes and to find out what variables are available.

EWget::getFieldsNamesList($recordName)

Returns list of field names for record by record's name.

Example

Obtain dump of all the fields' names for "current_state" record 

printf "fields names: '%s' \n",
join (',', EWget::getFieldsNamesList("current_state")); 

Comments

This function is mostly used for debugging since you will usually know what field names you are interested in before writing the script.

EWget::getRecordsNamesList()

Returns an array with the names of all the records provided to the script.

The following code dumps all the records names from the input file passed to the script. 

printf "record names: '%s' \n",
join(',', EWget::getRecordsNamesList());

Comments

This function is mostly used for debugging purposes. There always will be a record named "current_state" and possibly one named "old_state" (if the current record is being modified, rather than created). There may also be records that were linked to the current record.

These are named "recXXX", where XXX is an incremental number starting from 1.

EWget::getLinkedRecordsNamesList($recordName, $fieldName)

Returns sorted list of names of records linked via a "linked" field.

Comments

This function is mostly used for debugging because you will probably know the names of the records that you want to access before writing the script.

Only the linked records where the link does not allow multiple values are passed to scripts, so this function will return an array of 0 or 1 entry in a form of "recXXX" string.

EWget::getTableNameForRecord($recordName)

Returns the name of the table that a record belongs to. If $recordName is omitted, it returns the value of the "current_record". For example: 

printf "table for current record: '%
s' \n", EWget::getTableNameForRecord(); 
printf "table for rec3: '% s' \n"
, EWget::getTableNameForRecord('rec3');

In most cases you will already know what tables your records are from, but in case of the linked field type "single field from multiple tables" this function will allow you to determine what table the associated record is from and handle it appropriately.