Skip to main contentCarbon Design System

Endpoint script

You can write Maximo Integration Framework (MIF) endpoint handlers using automation scripts. For example, you might want to write a handler for sending emails, which is something that is not there in Maximo. To write a handler for sending emails:

  1. Use the Add/Modify handlers action from the endpoint application to add a new handler. You can name it “SCRIPT” and you can set the class name to be com.ibm.tivoli.maximo.script.ScriptRouterHandler. Note: This handler is there from Maximo 7.6.1.2 onwards.
  2. Create a new endpoint for that handler Endpoints app.
  3. Set the handler to be SCRIPT.
  4. Set the “script” property to the name of the script that you are going to write. For example, you can name the script “emailme”. You have now created a script named “emailme”.

The following table shows the implicit variables specific to these endpoint scripts.

VariablePurpose
requestDataByte[] data for endpoints.
requestDataSString data for endpoints. If the byte[] cannot be converted to String - this variable is not set.
responseDataThis is an OUT implicit variable. The endpoint script code can set it to store the response from the actual endpoint call. This can be set as a String or a byte[].

All endpoint metaData content is set as variables to the script. This means that in case of Publish Channel endpoints, all JMS/Kafka messages headers are set as variables in the script. Variables like destination would be available and set to the external system name for that endpoint script.

It is possible to write the following simple code:

from psdi.server import MXServer
from java.lang import String
MXServer.getMXServer().sendEMail( to,from,subject, String(requestData))

You can define the from and to as literal variables in the script and then set the email addresses there. You can also define another literal variable called “subject” to define a static subject for the email like “Email from Maximo”. You can make it more dynamic and fancy by getting the to email from the data, and set other properties.

The following example shows how to write a custom web service handler that uses WS-Security UserNameToken, which is not supported in MIF WebService Handler. The following script code leverages the JAXWSClient utility to set WS-Security UserNameToken.

from org.jdom import Element
from org.jdom import Namespace
from psdi.iface.webservices import JAXWSClient
from java.util import HashMap
from java.util import ArrayList
from psdi.iface.util import XMLUtils
from javax.xml.namespace import QName
ns = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"

The code leverages the jdom library that ships with Maximo Manage to create the security header. The script code hard codes the username and password, but they can be set as script literal variables. This is also applicable with the URLs to invoke, in this case, /meaweb/services/SYSTEM, and other input parameters to the cl.invoke(..) call. The code shows how to add the soap headers as well as HTTP headers as an example.

HTTP Handler Exit

HTTP handler provides an exit that can be leveraged to intercept and modify the request and response. The HTTPEXIT property of the handler endpoint can be set to a value like script:{script name} to register a scripted exit for the HTTP endpoint. A script will support the following set of callback functions.

Script Http Handler Exit methodsPurpose
urlProps(req)Used for adding query params to a configured URL. The req object is implemented by psdi.iface.router. ScriptHTTPReq. Use the req.addUrlProp(propname,propvalue) API to set the URL query parameters.
getUrl(req)Used for setting the URL for HTTP call. Use the req.setUrl(url) API to set the new URL.
headerProps(req)Used for setting request headers for the HTTP call. Use the req.addHeader(propname,propvalue) API to set the HTTP request headers.
processResponse(resp)Used for processing HTTP response. The resp object is implemented by psdi.iface.router.ScriptHTTPResp. Use the ‘resp.setError(java.util.Exception)’ API to mark the response for Error and the Error message. You can use the resp.getData() to get the response data and analyze that in the script.

ScriptHTTPReq details

ScriptHTTPReq methodsPurpose
getData()Used to get byte[] data that has been passed to the endpoint.
getSData()Used to get String data that has been passed to the endpoint.
getMetaData()Used for getting the metadata java.util.Map object that was passed in to the endpoint. This contains some of the jms/kafka message headers.
getEndPointName())Used for getting the endpoint name (string).
setURL(String url)Sets the URL to be called. This overrides the URL, if that is set in the endpoint configuration
getURL()Returns the URL (string) to be invoked.
addHeader(String name, String value)Adds an HTTP header/value pair to the request.
getHeaderProps()Gets the HTTP header/value java.util.Map for the request.
addUrlProp(String name, String value)Adds an HTTP URL query param/value pair to the request.
getUrlProps()Gets the HTTP query param/value java.util.Map for the request.
addFormProp(String name, String value)Adds an HTTP form param/value pair to the request.
getFormProps()Gets the HTTP form param/value java.util.Map for the request.

ScriptHTTPResp details

ScriptHTTPResp methodsPurpose
getData()Gets byte[] data response.
getMetaData()Gets the metadata java.util.Map object that was passed in to the endpoint. This contains some of the jms/kafka message headers.
getEndPointName()Gets the endpoint name (string).
geResponseMsg()Returns the response status message from the HTTP call
getResponseCode()Returns the HTTP response code.
setError(Exception e)Sets the error ( java.lang.Exception instance) by analyzing the HTTP response.

One common use case that we face from customers being needing to do a custom authentication before invoking the target URL. One way to do that would be to attempt that authentication call in the headerProps(req) call back as that will provide the script oppertunity to set that custom authentication header (say was fetched from the authentication call) to the request. A sample code is shown below. Note that the script would invoke the token api to set the generated token to the request header of the request for the target url.

from psdi.iface.mic import MicUtil
def headerProps(req):
authTokenUri = "http://sometokenurl/token"
apikey = MicUtil.getProperty("mxe.customservice.apikey")
headers = "apikey:"+apikey
tokenJson = req.httpgetasjson(authTokenUri,None,headers,None)
token = tokenJson.get("authtoken")

Web service handler exit

Similar to HTTP Handler, Web Service handler also provides an exit that can be leveraged to intercept and modify the SOAP request and response. The WSEXIT property of the handler endpoint can be set to a value like script:{script name} to register a scripted exit for the web service endpoint. The following callback functions are supported by a script.

Script web service handler exit methodsPurpose
responseOk(resp)Analyzes a good response from the external web service. The resp object is implemented by the psdi.iface.router.ScriptSOAPResp object. This can be leveraged to either do some processing with the response or set an error.
responseError(resp)Analyzes and takes action, if needed, for an error response from the external web service. The resp object is implemented by the psdi.iface.router.ScriptSOAPResp object.
setupHeaders(req)Uses request soap headers for the soap call. The req object is implemented by the psdi.iface.router.ScriptSOAPReq object.

ScriptSOAPReq details

ScriptSOAPReq methodsPurpose
getData()Gets byte[] data that has been passed to the endpoint.
getMetaData()Gets the metadata java.util.Map object that was passed in to the endpoint. This contains some of the jms/kafka message headers.
getEndPointName())Gets the endpoint name (string).
setURL(String url)Sets the URL to be called. This override the URL if that is set in the endpoint configuration
getURL()Returns the URL (string) to be invoked.
addHeader(String ns, String name, String value)Adds soap header/value pair to the request. ns specifies the namespace for the header element. The following example shows the usage.
getHeaderProps()Gets the soap header/value Map<QName,List<String>> for the request.

ScriptSOAPResp details

ScriptSOAPResp methodsPurpose
getData()UGets byte[] data response.
getMetaData()Gets the metadata java.util.Map object that was passed in to the endpoint. This contains some of the jms/kafka message headers.
getEndPointName)Gets the endpoint name (string).
setError(Exception e)Sets the error ( java.lang.Exception instance) by analyzing the soap response.

The following sample code shows how a WS Security header can be set using the setupHeaders.

from org.jdom import Element
from org.jdom import Namespace
from java.util import HashMap
from java.util import ArrayList
from psdi.iface.util import XMLUtils
from javax.xml.namespace import QName
def setupHeaders(req):

JMS Handler Exit

Customers often need to write an outbound integration message to an external queue. They can leverage the JMSHandler for this purpose. Customers can create an endpoint for this. The endpoint allows an exit to customize the JMS message properties as well as process the response, whether it is success or error. Like other endpoint exits, this is an interface type script.

Script JMS handler exit methodsPurpose
msgProps(req)Allows developers to set JMS message properties. The req object is of type psdi.iface.router.ScriptJMSReq
responseError(resp)Allows developers to process error response from the external JMS provider. The resp object is implemented by the psdi.iface.router.ScriptJMSResp object.
responseOk(resp)Allows developers to process success response from JMS provider. The resp object is implemented by the psdi.iface.router.ScriptJMSResp object.

ScriptJMSReq details

ScriptJMSReq methodsPurpose
getData()Gets byte[] data that has been passed to the endpoint.
getMetaData()Gets the metadata java.util.Map object that was passed in to the endpoint. This contains some of the jms/kafka message headers.
getEndPointName())Gets the endpoint name (string).
setURL(String url)Sets the URL to be called. This override the URL if that is set in the endpoint configuration
getURL()Returns the URL (string) to be invoked.
addProperty(String prop, String value)Adds jms message property/value pair to the request.
getMessageProperties()Gets the jms message property/value Map<String,String> for the request.

ScriptJMSResp details

ScriptJMSResp methodsPurpose
getData()Gets byte[] data that has been passed to the endpoint.
getMetaData()Gets the metadata java.util.Map object that was passed in to the endpoint. This contains some of the jms/kafka message headers.
getEndPointName())Gets the endpoint name (string).
getError()Gets the error ( java.lang.Exception instance) form jms response.

The following sample script demonstrates this.

def msgProps(ctx):
ctx.addProperty("maxendpoint",ctx.getEndPointName())