Service variable
Information on most of the implicit variables can be found at: Core Components & Manage Documentation. One of the most common ones you will utilize is the service variable.
“Service” variable
The service object is an implicit object available in all the scripts. For
most of the script points it is called service. The
MIF Object Structure scripts do not directly refer to this variable as service. Instead they
refer to it as `ctx’, which is an extended version of the “service” object, in callback method input parameter.
The service object helps us simplify some common tasks from an automation
script. For example, tasks like throwing an error or adding a warning or invoking workflows,
MIF invoke channels, logging, HTTP calls and so on become much easier leveraging the service var. It is the easier and better way to use the service variable. For example, if you want to throw real
time errors, rather than setting the errorkey and errorgrp variables, you should just use the
service.error(grp,key) or service.error(grp,key,params) APIs to achieve that. It is also leveraged to
invoke library scripts. There are also example on
how to invoke a MIF Invoke Channel to integrate to some rest APIs using the
service.invokeChannel(channelname) API.
The ‘service’ object supports the following built-in functions:
The first few are for json handling:
| Function | Request | Response | Description |
|---|---|---|---|
| jsonToString | com.ibm.json.java.JSONObject | String | Used for converting a json object to string. |
| jsonarrayToString | com.ibm.json.java.JSONArray | String | Used for converting a json array to string. |
| tojsonarray | String | com.ibm.json.java.JSONArray | Converts a string to a JSON array. |
| tojsonobject | String | com.ibm.json.java.JSONObject | Converts a string to a JSON object. |
The next ones are classic UI interactions:
| Function | Request | Response | Description |
|---|---|---|---|
| closeDialog | NA | void | Closes a classic UI dialog when the script is executed in context of an action launch point. A sample invocation would be service.closeDialog() |
| openURL | String (url to open), boolean (whether to open in a new window) | void | opens a url specified in the input string parameter. A sample invocation would be service.openURL("weather.com", False) |
The next ones are for HTTP calls and MIF endpoint invocations:
| Function | Request | Response | Description |
|---|---|---|---|
| httpget | String | String | Invokes HTTP GET on the specified URL (input string parameter) and returns the response as a String. Do not use this if the GET response type would be anything but a string or null. A sample usage would be respData = service.httpget("some url") |
| httppost | String (url), String (POST data) | String | Invokes HTTP POST on the specified URL (input string parameter) with POST data as a string and returns the response as a String. Do not use this if the POST response type would be anything but a string or null. |
| httpget | String (url),String (user),String (password) | String | Invokes HTTP GET on the specified URL (input string parameter) for BASIC auth user and password. Returns the response as a String. Do not use this if the GET response type would be anything but a string or null. |
| httppost | String (url),String (user),String (password), String (POST data) | String | Invokes HTTP POST on the specified URL (input string parameter) for BASIC auth user and password with POST data as a string and returns the response as a String. Do not use this if the POST response type would be anything but a string or null. |
| httppostasjson | String (url),String (user),String (password), com.ibm.json.java.JSONArtifact (POST Data) | com.ibm.json.java.JSONArtifact | Invokes HTTP POST on the specified URL (input string parameter) for BASIC auth user and password with POST data as a byte[]. Returns the response as a json. Do not use this if the response type would be anything but a json or null. |
| httppostasbytes | String (url),String (user),String (password), byte[] (POST data) | byte[] | Invokes HTTP POST on the specified URL (input string parameter) for BASIC auth user and password with POST data as a byte[] and returns the response as a byte[] or null. |
| httpgetasjson | String (url),String (user),String (headers), String (password) | com.ibm.json.java.JSONArtifact | Invokes HTTP GET on the specified URL (input string parameter) for BASIC auth user and password. The format for headers being header1:val1,header2:val2. Returns the response as a json. Do not use this if the response type would be anything but a json or null. |
| httpgetasbytes | String (url),String (user),String (password) | byte[] | Invokes HTTP GET on the specified URL (input string parameter) for BASIC auth user and password. Returns the response as a String. Do not use this if the GET response type would be anything but a string or null. |
| invokeEndpoint | String (endpoint),Map<String,String> (metadata),String (data) | String | Invokes any MIF endpoint with the given name and metadata and String data. The response is a String |
| invokeEndpoint | String (endpoint),Map<String,String> (metadata),byte[] (data) | byte[] | Invokes any MIF endpoint with the given name and metadata and byte[] data. The response is a byte[] |
| invokeChannel | String (channel name) | void | Invokes a MIF Invokechannel with the given name. This leverages the mbo in context of the script and that mbo is used as the channel MBO. |
| raiseSkipTransaction | NA | void | Throws the MXException with group “iface” and key “SKIP_TRANSACTION”. Leveraged by MIF framework to skip processing certain inbound and outbound messages. |
The next few functions are for logging.These functions should be used for real time logging leveraging the logger for this script:
| Function | Request | Response | Description |
|---|---|---|---|
| log | String (log message) | void | logs the message at DEBUG or INFO based on the setting on that script. A sample usage would look like service.log("setting the replacementcost..") |
| log_debug | String (logMsg) | void | script logger logging at DEBUG |
| log_debug | String (logMsg), Throwable (error) | void | script logger logging at DEBUG |
| log_info | String (logMsg) | void | script logger logging at INFO |
| log_info | String (logMsg), Throwable (error) | void | script logger logging at INFO |
| log_warn | String (logMsg) | void | script logger logging at WARN |
| log_warn | String (logMsg), Throwable (error) | void | script logger logging at WARN |
| log_error | String (logMsg) | void | script logger logging at ERROR |
| log_error | String (logMsg), Throwable (error) | void | script logger logging at ERROR |
| log_fatal | String (logMsg) | void | script logger logging at FATAL |
| log_fatal | String (logMsg), Throwable (error) | void | script logger logging at FATAL |
Real time Errors and warnings:
| Function | Request | Response | Description |
|---|---|---|---|
| error | String (group), String (key) | void | Throws MXException with the error group and key (input parameters). |
| error | String (group), String (key), String[] (params) | void | Throws MXException with the error group and key and params(input parameters) |
| setWarning | String (group), String (key), String[] (params) | void | Sets warning to the mboset in context mbo.getThisMboSet(). This is leveraged by REST APIs and classic UI framework to show warnings. |
Next few are for Yes, No, Cancel (YNC) interactions.
This is just to introduce the utility functions available in service for enabling YNC cutomizations using scripting.
| Function | Request | Response | Description |
|---|---|---|---|
| yncerror | String (group), String (key) | void | Throws MXApplicationYesNoCancelException with the error group and key (input parameters). |
| yncerror | String (group), String (key), String[] (params) | void | Throws MXApplicationYesNoCancelException with the error group and key and params(input parameters) |
| yncuserinput | String (group), String (key), String[] (params) | int | Provides the script code the input option (yes/no/cencel etc) chosen by the end user. This would be leveraged by the script code to provide business logic for the specific input. |
The next few are for library scripts:
| Function | Request | Response | Description |
|---|---|---|---|
| invokeScript | String (script name), Map<String,String> context | void | Invokes a script with the given name and passes in the context specified in input. |
| invokeScript | String (script name) | Map<String,Object> | Invokes a script with the given name. Returns the context of the invoked script as a java Map object |
| invokeScript | String (script name), String (function name), Object[] (function arguments) | Object | Invokes a function inside the target script with the specified arguments. The call returns the response of the function call (if any) as an object |