PowerTools Documentation: Index | DSP life cycle (dAPI.py methods)


Table of contents


dAPI.py contains the methods for managing life cycle of an instance of a deployable These methods are called by the powertools installer to manage life cycle of the tool. The file finally gets installed in '/usr/lib/ensim/deployables/TOOLNAME-VERSION/lib/dAPI.py' from where it is loaded whenever required.

To manage the life cycle of a deployable the dAPI.py should contain definition of following 6 methods.

These methods in turn call methods from the deployables lib. (DL) to carry out necessary actions. For more information of the DL methods please refer to the deployables lib. API reference (deployables_lib.api)].

1 install

  • Manages installation
def install( site, site_conf, instance_conf, msgs )
The install method defines a list of actions necessary for the installation and passes the list to do_install_actions method of the DL. The list of permitted actions can be checked from the do_install_actions (deployables_lib.api/public/deployables_lib-module.html#do_install_actions) reference. This function is called in the context of CONTEXT_INSTALL
The 'do_install_actions' executes the actions sequentially as in list 'action'. The arguments to the functions are passed using 'args_dict' argument of the call to 'do_install_actions'.
An example of call the 'do_install_actions' method can be -
import deployables_lib as dl                                                                                                                          
dl.load_msgs_module("DSP_SHORTNAME-DSP_VERSION", symtab = globals())
def install( site, site_conf, instance_conf, msgs )
   actions = ['resolve_location', 'check_disk_quota', 'check_pass', 'check_install_loc_owner', ]
   args_dict = {}
   dl.do_install_actions(site, site_conf, instance_conf, msgs, globals(), actions, args_dict)
   if msgs.get_severity() != msgs.ERROR :
      #  Do Further Actions
NOTE
  1. The above example passes an empty args dictionary and forces the 'do_install_actions' method to derive argument values from the 'site_configuration'.
  2. The above example passes the 'globals()' (current symbol table) as it contains errors/warning already imported objects(line 2).
  3. An unsuccessful call to 'do_install_actions' would set the 'severity' object as 'ERROR', which means the installation needs to be aborted.
  4. An example of passing arguments using 'args_dict' can be given as -
args_dict = {'archive_unpack': {'dir_moves':dir_moves, 'file_mods':file_mods},
             'handle_security_mode': {'files': secure_files},
             'exec_php_script': {'script': 'setup/index.php', 'args': {'go_next': '1',                                                                                                                               
             'next_page' : 'write',                                                                                                                          
             'editPassword[0]' : instance_conf['instance_pass1'],                                                                                                                          
             'editPassword[1]' : instance_conf['instance_pass1'],                                                                                                                           
             'GALLERY_PHP_VALUE_OK' : '1',                                                                                                                          
             'data' : local_config},
             'failure_re' : '.*There are errors'},
             'access_url' : {'user' : 'admin'}
             }
NOTE
It is always advisable to call the do.install_actions twice (with different action list). This is because actions can be easily categorized into 2 different groups - ones which check availability of features on the installation box or do some ground work for installation (e.g check_quota, probe_db etc.) and others which preforms installation actions (e.g unpack_archive , exec_php_script etc.). The do_install action executes the actions sequentially but doesn't stop on any error until the actions list is exhausted. And then it checks on critical errors and rolls back installation if needed.
Hence it is advisable to pass the actions list in two steps. First passing the list of 'feature checking' functions and then the 'installation' ones.

2 reconfigure

reconfigure(context, site, site_conf, old_site_conf, instance_conf, old_instance_conf, msgs)
  • Manages reconfiguration. reconfigure methods defines the course of action for
    • reconfigure (CONTEXT_RECONFIGURE) while SA changes the parameters of installed DSP and
    • site edit (CONTEXT_SITE_EDIT) when the site is edited.
def reconfigure(context, site, site_conf, old_site_conf, instance_conf, old_instance_conf, msgs)
The reconfigure method defines a list of actions necessary for the installation and passes the list to 'do_reconfigure_actions' method of the DL. The list of permitted actions can be checked from the do_reconfigure_actions reference.
This function is invoked whenever context = CONTEXT_SITE_EDIT or CONTEXT_RECONFIGURE. The 'do_reconfigure_actions' functions takes care of the context while calling the actions/functions.

3 remove

remove(site, site_conf, instance_conf, msgs)
  • Manages DSP removal
The remove method is called when the DSP instance is been removed.
It is not necessary to provide the remove method but if provided this method can used to clean up install location and mysql database (if any) used by the powertool which is not done otherwise.
This functionality can be achived by
  1. dl.install_loc_cleanup
  2. dl.db_drop
Typical code:
def remove(site, site_conf, instance_conf, msgs):
   dl.install_loc_cleanup(site, site_conf, instance_conf, dir_moves,
                          file_mods = file_mods)

4 upgrade

upgrade(site, site_conf, instance_conf, old_instance_conf, msgs)
  • Manages DSP upgradation
The upgrade method defines a list of actions necessary for the DSP upgradation and passes the list to 'do_upgrade_actions' method of the DL. The list of permitted actions can be checked from the do_upgrade_actions reference. This function is invoked whenever context = CONTEXT_UPGRADE. The 'do_upgrade_actions' functions takes care of the context while calling the actions/functions.

5 get_instance_configuration

  • Creates and populates the instance configuration. Function declaration is required in dAPI.
get_instance_configuration(context, site, site_conf, instance_conf, old_instance_conf, locale, msgs)
This function must contain call to at least following two functions -
  1. dl.dsp_create_instance
  2. dl.dsp_fill_instance
Call to 'dsp_create_instance' creates and returns an instance of (dictionary representing) dsp.xml configuration, which is also passed on to 'dsp_fill_instance'. The call to these two functions can be followed by calls to some deployable specific functions e.g dl.enable_patches
A typical declaration of this function can be as follows -
def get_instance_configuration(context, site, site_conf, 
     new_instance_conf, old_instance_conf, locale, msgs):
   dsp_instance  =  dl.dsp_create_instance(new_instance_conf['short name'], \
      new_instance_conf['version'])                                                                                                                                
   dl.dsp_fill_instance(context, dsp_instance, site, site_conf, new_instance_conf, \
    old_instance_conf, ['username', 'url_net', 'url_path', 'domain_to_path']
   dl.enable_patches(dsp_instance, instance_patches)
   return dsp_instance