Ellipse 8 Hooks Framework

Hooks FrameworkCopyright 2016 ABB

All Rights Reserved

Confidential and Proprietary

Legal Disclaimer

The product described in this documentation may be connected to, and/or communicate information and data via, a networkinterface, which should be connected to a secure network. It is your sole responsibility to ensure a secure connection to thenetwork and to establish and maintain appropriate measures (such as but not limited to the installation of firewalls, applicationof authentication measures, encryption of data, installation of antivirus programs, etc.) to protect the product, the network,your systems, and the interface against any kind of security breach, unauthorised access, interference, intrusion, leakage,damage, or corruption or theft of data. We are not liable for damages or losses related to any such security breach,unauthorised access, interference, intrusion, leakage, damage, or corruption or theft of data.

ContentsHooks Framework 2

Introduction 3

About 4

Limitations 4

Installation Guide 5

Adding More Features (3rd Party Libraries) 5

Calling External Web Services 5

Hook Basics 6

Using Services 6

Query and Update the Database 6

Service Processing Hooks 7

Example Service Hooks 7

Example Service Hook (Cobol Service Ellipse Only) 9

MSO Screen Processing Hooks (Ellipse 8 specific) 11

Example Screen Hook 12

IntroductionThis document provides information relevant to the implementation of Hooks.

Use this to:

• Understand the Hooks framework.

• Develop custom Groovy scripts to run within the Hooks framework.

• Coding guidelines on usage of of Groovy scripts to run within the Hooks framework.The development of Groovy scripts to run within the Hooks framework is custom code, therefore:

• Automation of building and testing the Groovy scripts is not covered as that is specific to the development environment.

• Source code configuration and management of the Groovy scripts is also not covered as that is specific to thedevelopment environment.

• System Administration of the Groovy scripts is also not covered as that is specific to the scripts being implemented.

AboutFrom the introduction of the Java Infrastructure ABB Enterprise software products such as Ellipse 8 and CLLAS are delivered asa binary product that may not be modified. The Hooks framework is therefore provided as a mechanism to allow customers tobe able to customise the behaviour of ABB Enterprise software products to satisfy their unique business requirements.

The Hooks framework allow customers to perform customised processing of interactions between users and their software.Customers utilise this functionality by implementing a scripting technology that contains the required business logic to beperformed. The interactions that hooks can be added to are screen processing and service invocation. Scripts may beimplemented to modify requests and responses, raise errors and roll back database transactions. The business logic typicallyprocesses custom business rules, validation and update of data.

Customers can perform custom processing defined in a script before and after user interactions by utilising hooks. The Hookscripts are placed in a specific directory location so that Hooks framework can find and execute the scripts. The Hooksframework also holds the configuration that defines which service or screen the script is applicable to and whether the script isto be executed before or after the service or screen. Hooks are implemented using Spring Aspect Oriented Programming (AOP).This allows code that is independent of the underlying service or screen to be invoked before and/or after the service or serviceis invoked.

The ABB Enterprise Software JI supported technology for script is Groovy, a dynamic language for the Java Virtual Machine. Fordetails of Groovy, refer to the website http://groovy.codehaus.org/. A Groovy Hook script has full access to the underlyingimplementation technologies (in particular the Java Virtual Machine). It is envisaged that customers will be most interested inmanipulating the request and response of user interactions.

LimitationsJI software is delivered as a binary product that may not be modified. New releases and upgrades will contain changes made tothe product by ABB Enterprise Software that will not consider any custom processing implemented via the Hooks framework. Itwill be the responsibility of the customer then to ascertain the impact of a new ABB Enterprise Software JI release or upgrade tobe implemented on it's own custom processing. In addition, it will be responsibility of the customer to manage any customscripts implemented via the Hooks framework. This includes (but is not limited to) source code management, administration,development, support, disaster recovery, etc.

Installation GuideThe Hooks framework will look for Hook scripts according to a system property custom.root. Typically this will be the followingserver directory

/appliance/data/conf/git-repos/customer-software/hooks/src

The Hook scripts then can be either:

1. Physically located in the directory.

2. Logically located in the directory (the JI Software directory (for example Ellipse or CCLAS) is then linked to the actualdirectory where the files are physically located).

The decision then on where to physically locate Hook scripts is up to the Customer. Refer to your products Operations Guide forinformation on the storage of Hooks in a GIT repository (Recommended).

Adding More Features (3rd Party Libraries)To make use of additional java functionality contained in .jar files, you will have to download the 3rd party jar file(s) and putthese in the /${custom.root}/lib directory. By default this would be:

/mincom/data/conf/git-repos/customer-software/hooks/lib

The application server will need to be restarted for the new jar files to be picked up.

Calling External Web ServicesIn order for a groovy script to process as a web service client, the client jars for the web services to be accessed will need to begenerated and then imported into the groovy script. In order to generate the java client classes from an external web service,use Maven to generate classes and package into a jar.

The steps to do this (in Windows) are as follows:

1. Obtain the url that provides the wsdl for the external web service.

e.g. http://www.webservicex.net/globalweather.asmx?wsdl

2. Obtain a pom.xml file to be used by Maven to build and package client classes for the web service.

3. Edit the pom.xml file and make the following changes:

a. Update the <artifactId> attribute to provide the name of the jar file that Maven will create.

b. Update the <version> attribute to specify the version of the jar file that Maven will create.

c. Update the <wsdl> attribute to specify the wsdl of the service for which java client classes are to be generated.4. Open a command window.

5. Change directory to that which contains the pom.xml file.

6. Execute the mvn build process in the command window.

e.g. mvn package -Djava.net.prefer.IPv4Stack

7. The jar and client java classes will be generated into a directory called 'target' under the current directory.

8. The jar file generated (e.g. GlobalWeatherClient-0.0.1-SNAPSHOT.jar) should be copied to the JI application instance (egCLM, CLLAS or Ellipse) where the related groovy hooks script is to be installed.

When the groovy script is run in a JI application environment that jar will need to be on the build path for Groovy scripts(refer Adding More Features above).

Hook BasicsFor a comprehensive guide on writing groovy refer to http://groovy.codehaus.org/. The groovy language is beyond the scope ofthis document and it assumed the reader has some existing knowledge

Using ServicesUse the tools.service object to invoke service calls on existing services

// obtain the preferences servicesdef preferences = tools.service.get("Preferences")

// perform a search for 10 resultsPreferencesServiceResult [] searchResults = preferences.search(new PreferencesSearchParam(), 10)

// perform a readPreferencesDTO readDTO = new PreferencesDTO();readDTO.setPrefproperty(new PrefProperty("some.preference"));PreferencesServiceResult readResult = preferences.read(readDTO)

Query and Update the DatabaseUse the tools.edoi object to query and update the database

// Query the MSFPRF tableQuery query = new QueryImpl(MSFPRFRec.class);query.and(MSFPRFKey.prefProperty.like("s%"));query.setMaxResults(10);QueryResults queryResults = tools.edoi.search(query);

// Create a MSFPRF recordMSFPRFKey key = new MSFPRFKey("", "", "some.preference", "", "")MSFPRFRec rec = new MSFPRFRec(key);if (!tools.edoi.exists(rec.getPrimaryKey())) { tools.edoi.create(rec);}

Service Processing HooksService hooks are written against a particular service method eg. PreferencesService.Modify The hook will be executed when auser interacts with that service through the UI (any screen that calls that service) or a programmatic call to the service (webservice or batch process).

Service hooks provide the ability to:

• Add additional validation to a service

• Add additional processing (updates)

• override field values returned from the service

• Override field values sent to the service

• Return additional errors (and rollback all processing)

• Trigger additional processing when a field is updatedThe following functionality is not supported:

• Returning warnings

• Hooks that get recursively called. This is to prevent loops if your hooks calls a service that in turn executes your hookagain.

• Bypassing or replacing sections of standard business logic (the entire standard business logic can be overridden though)The hooks can utilise the libraries for service invocation, screen invocation and database interaction (EDOI).

The following methods are available:

• onPreExecute- This method is called when the particular service method is called. It allows additional validation to beperformed prior to the service logic being executed. Returning a non-null value from this function will bypass the standardbusiness logic. The value returned will be the return result of the service call.

• onPostExecute - This method is called after the standard service logic has been executed. This method is only executed ifthe standard business logic does not return an error or warning. This is the only method in which updates to the database(including via service calls) should occur. If an error is returned (an exception thrown) in this section, then the standardbusiness logic and hook logic updates will be rolled back (as if the error was part of the standard screen validation).

ImportantA hook for a service must conform to the following naming standard: <service name>_<method name>.groovy, forexample: Equipment_Service.groovy

Example Service HooksCheck some property and return an error before a service is executedimport com.mincom.ellipse.common.CoreErrorCodesimport com.mincom.ellipse.hook.hooks.CoreServiceHookimport com.mincom.ellipse.types.m1000.instances.PreferencesDTOimport com.mincom.ellipse.types.m1000.instances.PreferencesServiceResultimport com.mincom.ellipse.errors.Error;

class PreferencesService_create extends CoreServiceHook {

/** * Custom logic to be executed before the standard service logic * * Store current value, execute additional validation and override data to be passed to the standard service. * @param input the DTO passed from the caller * @return null if the standard service should be executed, non-null if the service has been overridden and the return value should be returned to the caller. */ @Override public Object onPreExecute(Object input) { log.info("Hooks onPreExecute")

PreferencesDTO dto = (PreferencesDTO)input; PreferencesServiceResult result = new PreferencesServiceResult(); if (dto.getPrefproperty().getAsEllipseValue().equals("return.error")) { result.addError(new Error("return an error")); return result; } return null; }

}

Do some additional processing after a service is executed

import com.mincom.ellipse.edoi.ejb.msfprf.MSFPRFKeyimport com.mincom.ellipse.edoi.ejb.msfprf.MSFPRFRec

import com.mincom.ellipse.hook.hooks.CoreServiceHookimport com.mincom.ellipse.types.m1000.instances.PreferencesDTO

class PreferencesService_read extends CoreServiceHook {

/** * Custom logic to be executed after the standard service logic * * The method won't be called if an error has already been returned from the main service logic or from the onPreExecute method. * Execute additional processing logic, trigger additional processes based on changes, override the data in the DTO to be returned to the caller. * * If an exception is thrown then all processing will be rolled back and the error returned to the caller. * * @param input the DTO passed from the caller * @param result the DTO to be returned to the caller * @return the DTO that will be returned to the caller. If null is returned then the * result input parameter will be returned to the caller but without any changes * made in during the method execution. */ @Override public Object onPostExecute(Object input, Object result) { PreferencesDTO dto = (PreferencesDTO)input; if (dto.getPrefproperty().getAsEllipseValue().equalsIgnoreCase("count.me")) { // Create a MSFPRF record MSFPRFKey key = new MSFPRFKey("", "", "times.read.count.me", "", "") MSFPRFRec rec = new MSFPRFRec(key); if (!tools.edoi.exists(rec.getPrimaryKey())) { rec.setPrefValue("1"); tools.edoi.create(rec); } else { rec = tools.edoi.get(key); int count = Integer.parseInt(rec.getPrefValue()); rec.setPrefValue("" + (++count)); tools.edoi.update(rec); } } return null; }}

Example Service Hook (Cobol Service Ellipse Only)import com.mincom.ellipse.attribute.Attributeimport com.mincom.ellipse.hook.hooks.ServiceHookimport com.mincom.enterpriseservice.ellipse.dependant.dto.WorkOrderDTOimport com.mincom.enterpriseservice.ellipse.location.LocationServiceModifyReplyDTOimport com.mincom.enterpriseservice.ellipse.location.LocationServiceModifyRequestDTOimport com.mincom.enterpriseservice.ellipse.location.LocationServiceReadReplyDTO;import com.mincom.enterpriseservice.ellipse.workorder.WorkOrderServiceModifyReplyDTOimport com.mincom.enterpriseservice.exception.*import com.mincom.enterpriseservice.ellipse.*

class LocationService_modify extends ServiceHook {

String hookVersion = "1"

// Use this variable to store a value before the standard service call is excuted. // It can be used in comparison after the standard service call to trigger processing. String oldValue = ""

/** * Custom logic to be executed before the standard service logic * * Store current value, execute additional validation and override data to be passed to the * standard service. * @param input the DTO passed from the caller * @return null if the standard service should be executed, non-null if the service has * been overridden and the return value should be returned to the caller. */ @Override public Object onPreExecute(Object input) { log.info("Hooks onPreExecute logging.version: ${hookVersion}")

LocationServiceModifyRequestDTO inputDTO = (LocationServiceModifyRequestDTO) input log.info("inputDTO: " + inputDTO)

// Get the current value of Town City so we can store it for later comparison to trigger // some processing if required. LocationServiceReadReplyDTO locationReadReply = tools.service.get("Location").read( { it.setLocation(inputDTO.getLocation()) }, false) oldValue = locationReadReply.getTownCity()

// Extra validation - return an error back to the caller. if (inputDTO.getTownCity() == null) { throw new EnterpriseServiceOperationException( new ErrorMessageDTO("9999", "townCity can not be EMPTY", "townCity", 0, 0)) }

List<Attribute> custAttribs = inputDTO.getCustomAttributes() custAttribs.each { Attribute customAttribute -> log.info ("Attribute Name = ${customAttribute.getName()}") log.info ("Attribute Value = ${customAttribute.getValue()}")

if (customAttribute.getName().equals(new String("tstString"))) { if (customAttribute.getValue().equals(new String("TEST"))) { throw new EnterpriseServiceOperationException( new ErrorMessageDTO( "9999", "TEST is invalid for Custom Attribute", "tstString", 0, 0)) } } } // Overwrite input fields that will be passed to the service if (inputDTO.getTownCity().equals(new String("BNE"))) { inputDTO.setTownCity("BRISBANE") }

return null }

/** * Custom logic to be executed after the standard service logic * * The method won't be called if an error has already been returned from the main service * logic or from the onPreExecute method. * Execute additional processing logic, trigger additional processes based on changes, * override the data in the DTO to be returned to the caller. *

* If an exception is thrown then all processing will be rolled back and the error returned * to the caller. * * @param input the DTO passed from the caller * @param result the DTO to be returned to the caller * @return the DTO that will be returned to the caller. If null is returned then the * result input parameter will be returned to the caller but without any changes * made in during the method execution. */ @Override public Object onPostExecute(Object input, Object result) {

LocationServiceModifyRequestDTO inputDTO = (LocationServiceModifyRequestDTO) input LocationServiceModifyReplyDTO responseDTO = (LocationServiceModifyReplyDTO) result log.info("inputDTO: " + inputDTO) log.info("responseDTO: " + responseDTO)

// Do additional processing. if (responseDTO.getLocationDescription().equals(new String ("WORKORDER"))) { WorkOrderDTO workOrder = new WorkOrderDTO(new String("00000134")) WorkOrderServiceModifyReplyDTO woModifyReply = tools.service.get("WorkOrder").modify( { it.districtCode = tools.commarea.District it.workOrder = workOrder it.workOrderDesc = "Tested from MSO Hooks" }, false) }

// Do some additional processing when a field has changed if (responseDTO.getTownCity().equals(oldValue)) { log.info("Town City has not Changed") } else { log.info("Town City has changed. We may want to trigger something to happen...") }

// Overwrite fields that will be returned if (responseDTO.getTownCity().equals(new String("SYD"))) { responseDTO.setTownCity("SYDNEY") }

List<Attribute> custAttribs = responseDTO.getCustomAttributes() custAttribs.each { Attribute customAttribute -> log.info ("Attribute Name = ${customAttribute.getName()}") log.info ("Attribute Value = ${customAttribute.getValue()}")

if (customAttribute.getName().equals(new String("tstString"))) { if (customAttribute.getValue().equals(new String("WORKORDER"))) { customAttribute.setValue("REDROKROW") } } }

return responseDTO }}

MSO Screen Processing Hooks (Ellipse 8 specific)MSO Screen hooks are written against a particular MSO screen eg. MSM010A. The hook will be executed when a user interactswith that screen through the Ellipse UI, or a programmatic call that interacts with that screen (ScreenService web service orEllipse batch process).

MSO Screen hooks provide the ability to:

• Add additional validation to a screen

• Add additional processing (updates) when a screen is submitted

• Set fields on a screen as read-only

• Set default field values on a screen or override field values returned to a screen

• Override field values submitted from a screen

• Return additional errors (and rollback all processing)

• Trigger additional processing when a field is updatedThe following functionality is not supported:

• Returning warnings to a screen

• Bypassing or replacing sections of standard business logic (the entire standard business logic can be overridden though)

• Redirecting to another screenThe hooks can utilise the Ellipse libraries for Ellipse service invocation, screen invocation and database interaction (EDOI).

The following methods are available:

• onDisplay - This method is called immediately prior to the screen displaying. It can be used to default values to thescreen and protect fields.

• onPreSubmit - This method is called when the screen is submitted. It allows additional validation to be performed prior tothe standard business logic being executed. Returning a non-null value from this function will bypass the standardbusiness logic and the returned GenericMsoRecord will be displayed to the user.

• onPostSubmit - This method is called after the standard business logic has been executed. This is the only method inwhich updates (including via service calls) should occur. Validation should not occur in this section, as it is not possible toroll back the transaction without throwing an exception and terminating the user's session.

• onScreenRequest - This method is called immediately prior to the screen displaying when the MSO has been requestedvia the menu/quicklaunch. It can be used to stop users from accessing a screen directly, while still allowing it to be usedin a flow from another MSO screen.

An example of the order that hooks will execute when a user submits on screen MSM200A is as follows:

MSM200A.onPreSubmit()

MSM200A.onPostSubmit()

MSM200B.onDisplay()

ImportantA hook for a screen must conform to the following naming standard: <screen name>.groovy, for example:MSM123A.groovy

Example Screen Hookimport com.mincom.ellipse.ejra.mso.GenericMsoRecordimport com.mincom.ellipse.ejra.mso.MsoErrorMessageimport com.mincom.ellipse.hook.hooks.MSOHookimport com.mincom.enterpriseservice.ellipse.dependant.dto.WorkOrderDTOimport com.mincom.enterpriseservice.ellipse.workorder.WorkOrderServiceModifyReplyDTOimport com.mincom.enterpriseservice.ellipse.workorder.WorkOrderServiceReadReplyDTOimport com.mincom.enterpriseservice.exception.EnterpriseServiceOperationException

public class MSM011A extends MSOHook {

String hookVersion = "1" final String CLOSED_WORKORDER_STATUS = "C"

// Use this variable to store a value before the standard service call is excuted. // It can be used in comparison after the standard service call to trigger processing. String oldValue = "" boolean standardSubmit = false

/** * Custom logic to be executed immediately before the screen displays * * Set values on the screen and protect fields. * If an exception is thrown from this method then the user's session will be aborted. * * @param screen which will be displayed * @return the screen object which will be displayed */ @Override public GenericMsoRecord onDisplay(GenericMsoRecord screen){ log.info("Hooks onDisplay logging.version: ${hookVersion}") log.info("GenericMsoRecord: " + screen)

// Override screen field value which will be displayed to the caller screen.getField("TABLE_TYPE1I").setValue("AH")

// Protect field (read-only) screen.getField("TABLE_TYPE1I").setIsProtected(true)

return screen }

/** * Custom logic to be executed before the standard screen logic is executed * * Do additional validation, override fields, capture field/s for later trigger processing * If an exception is thrown from this method then the user's session will be aborted. * * This method will be executed regardless of whether the user is doing a revert, submit or other action. * * @param screen the screen object which will be displayed * @return null to continue normal processing. * If a screen object is returned (non-null) it will be displayed and none of the standard MSO processing will occur. */ @Override public GenericMsoRecord onPreSubmit(GenericMsoRecord screen) { log.info("Hooks onPreSubmit logging.version: ${hookVersion}") log.info("GenericMsoRecord: " + screen)

// Only run this custom code if the Submit button was pressed (SUBMIT = 1 or 0) // However, a lookup (going into a field and using the lookup to go // to another screen) also sends a value of 1, so check all the values // of the screen attributes for a '?'. A lookup puts a '?' on the field. if ( ((screen.getNextAction() == 1) || (screen.getNextAction() == 0)) && !isQuestionMarkOnScreen(screen)) { standardSubmit = true log.info("Standard Submit. No question marks or reverting. Custom processing will be executed.")

// Override field that is passed to business logic screen.getField("TABLE_TYPE1I").setValue(tools.commarea.District)

// Do validation and return an error if required. The message will be returned and field selected. if (screen.getField("TABLE_CODE1I").getValue().trim().equals(new String("0000"))) { screen.setErrorMessage(new MsoErrorMessage("Invalid table code value", "9999", "Invalid table code value", MsoErrorMessage.ERR_TYPE_ERROR, MsoErrorMessage.ERR_SEVERITY_UNSPECIFIED))

screen.setCurrentCursorField(screen.getField("TABLE_CODE1I")) return screen }

// Store an old value for later use in 'onPostSubmit' try { if (screen.getField("TABLE_CODE1I").getValue().trim().equals(new String("1111"))) { WorkOrderDTO workOrder = new WorkOrderDTO(new String("00000054")) WorkOrderServiceReadReplyDTO woReadReply = tools.service.get("WorkOrder").read( { it.districtCode = tools.commarea.District it.workOrder = workOrder }, false)

if (woReadReply.getWorkOrderStatusM().equals(CLOSED_WORKORDER_STATUS)) { // Must catch any exceptions that could occur in the onPostSubmit processing otherwise // the user session will be aborted screen.setErrorMessage(new MsoErrorMessage("Work Order is closed", "9999", "Work Order is closed", MsoErrorMessage.ERR_TYPE_ERROR, MsoErrorMessage.ERR_SEVERITY_UNSPECIFIED)) screen.setCurrentCursorField(screen.getField("TABLE_CODE1I")) return screen }

oldValue = woReadReply.getEquipmentClass() } } catch (EnterpriseServiceOperationException e) { log.info("Unsuccessful Calling Service ${e.toString()}")

screen.setErrorMessage(new MsoErrorMessage(e.toString(), "9999", e.toString(), MsoErrorMessage.ERR_TYPE_ERROR, MsoErrorMessage.ERR_SEVERITY_UNSPECIFIED)) screen.setCurrentCursorField(screen.getField("TABLE_CODE1I")) return screen } } return null }

private boolean isQuestionMarkOnScreen (GenericMsoRecord screen) { String screenData = screen.getCurrentScreenDetails().getScreenFields().toString() return screenData.contains("?") }

/** * Custom logic to be executed before the screen displays * * Set values on the screen and protect fields. * If an exception is thrown from this method then the user's session will be aborted. * * This method will be executed regardless of whether the user is doing a revert, submit or other action. * It will be executed regardless of whether a warning or error is being returned to the user. * * @param screen the screen object which will be displayed * @return the screen to be displayed to the user */ @Override public GenericMsoRecord onPostSubmit(GenericMsoRecord input, GenericMsoRecord result) {

log.info("Hooks onPostSubmit logging.version: ${hookVersion}") log.info("Input GenericMsoRecord: " + input) log.info("Response GenericMsoRecord: " + result)

// if it was a lookup, revert, warning or error then don't do additional logic. if (!standardSubmit || (result.getMapname() != "MSM011B")) { return result } log.info("Standard Submit. No question marks or reverting. Custom processing will be executed.")

// Overwrite Value in the screen returned to the caller result.getField("TABLE_CODE2I").setValue("8888")

// onPostSubmit should not raise exceptions. // If there is an exception thrown, then the user connection will get aborted. // Any code that could potentially cause any exception should have validation in the pre submit method to avoid this // (preSubmit also shouldn't throw exceptions but has the option of returning an error to the caller). // Therefore in this particular example we need to check in the onPreSubmit that the work order 00000054 // exists (and should check if it can be modified). if (input.getField("TABLE_CODE1I").getValue().trim().equals(new String("2222"))) { WorkOrderDTO workOrder = new WorkOrderDTO(new String("00000054"))

WorkOrderServiceModifyReplyDTO woModifyReply = tools.service.get("WorkOrder").modify( { it.districtCode = tools.commarea.District it.workOrder = workOrder it.workOrderDesc = "Tested from MSO Hooks" }, false)

// Compare the equipment class with original value prior to the main standard service call (you wouldn't expect it to // change in this example since the MSO010 business logic won't touch this WO) String equipClass = woModifyReply.getEquipmentClass() if (equipClass.equals(oldValue)) { log.info("Same Equipment Class") } else { log.info("Different Equipment Class. Potentially trigger some additional processing...") } } return result }

/** * This hook is called when the screen is initially loaded (via quicklaunch or menu) * @param screen */ public void onScreenRequest(InitialMsoRecord screen) { // Set fields in 'screen' as protected or throw an exception }}