REST Groovy Service Invoke v2
The REST Groovy Service Invoke API provides support for call arbitary Groovy Services from external systems. This service endpoint can be used to perform operation such as uploading reference data for use in dynamic data or form prefill services.
Security
To enable Groovy Services to be invoked via REST API the service parameter 'REST Invoke Enabled' service parameter must be enabled.
By default the service parameter is false, and it must be explicitly enabled.
To access the Groovy Service Invoke REST endpoint the caller needs to be authenticated using HTTP Basic Authentication. The authenticated user will need an user account on the Journey Manager server and this account will need to be active and have access to the Management Console module.
To be authorized to call the service the user account will also need the Management Console permission 'REST Groovy Service Invoke'.
If the user is not a global administrator, only services belonging to the organizations assigned to the user will be accessible.
The endpoint supports HTTP GET and POST operations, including file upload MULTI-PART POST requests.
URL Endpoint
The REST service definitions URL endpoint is as follows:
``` https://Service API
This section provides a description all the REST Groovy Service Invoke operations including:
GET Groovy Service List
Retrieve the list of available services of type 'Groovy Service' sorted by service name and version.
URL Format
GET https://<tm server>/manager/secure/rest/groovy-service-invoke/v2/
URL Example
GET https://transact.maguire.com/manager/secure/rest/groovy-service-invoke/v2/
200 Response
[
{
"serviceName": "Bulk User Loader",
"versionNumber": 1,
"clientCode": "maguire",
"url": "http://localhost:9080/manager/secure/rest/groovy-service-invoke/v2/maguire/bulk-user-loader/v1/"
},
{
"serviceName": "Product Catalog Loader",
"versionNumber": 1,
"clientCode": "maguire",
"url": "http://localhost:9080/manager/secure/rest/groovy-service-invoke/v2/maguire/product-catalog-loader/v1/"
},
{
"serviceName": "Q1 Accounts Loader",
"versionNumber": 1,
"clientCode": "maguire",
"url": "http://localhost:9080/manager/secure/rest/groovy-service-invoke/v2/maguire/q1-accounts-loader/v1/"
},
{
"serviceName": "User Profile Updater",
"versionNumber": 1,
"clientCode": "maguire",
"url": "http://localhost:9080/manager/secure/rest/groovy-service-invoke/v2/maguire/user-profile-updater/v1/"
}
]
POST Invoke Groovy Service
Invoke the specified service and return the results of the Groovy Service invocation. All Groovy Service invocations are recorded in the Groovy Service Log.
Please Note: all groovy service invocations must be performed using a HTTP POST or a multi-part POST operation. This follows the REST architectural pattern of not performing state changes when making HTTP GET requests.
URL Format
The service name is normalized to avoid any URL encoding issues. Please use the service URL values provided in the GET Service List operation.
POST https://<tm server>/manager/secure/rest/groovy-service-invoke/v2/<normalized client code>/<normalized service name>/<version number>/
URL Example
POST https://transact.maguire.com/manager/secure/rest/groovy-service-invoke/v2/maguire/product-catalog-loader/v1/
POST Body
Any request parameters should be URL form encoded in the request body. Do Not add request parameters to the POST URL as they will not be resolved.
Binary files can be uploaded to the services using Multipart Post. This is particularly
useful for loading reference data, such as Excel or CSV data.
Any uploaded files will be made available as Apache Commons FileUpload FileItem objects.
200 Response
The response content is that returned by the invoked Groovy Service, for example:
Product Catalog Loaded
Reference Data Example
The example Groovy Service below is loading product catalog CSV file into a client property named 'Product Catalog' belonging to the 'Maguire' Organization.
Fluent Groovy Script
The REST client makes multi-part post request with the CSV file uploaded with the request parameter
name 'products'. The script gets the request parameters.products FileItem object. The FileItem's byte data
is then convered into text using the UTF-8 charset.
With the products CSV data, the script then loads it into the database using PropertyBuilder. This service
will create or update any existing property value with the same name.
import com.avoka.core.groovy.GroovyLogger as logger
import com.avoka.tm.svc.*
import com.avoka.tm.vo.*
import javax.servlet.http.*
import org.apache.commons.fileupload.FileItem
class FluentGroovyService {
/*
* Perform a groovy service invocation
*
* return: the result object
*/
Object invoke(SvcDef svcDef, HttpServletRequest request, User user, Map params) {
// Get the products file upload file item
FileItem fileItem = (FileItem) params.products
logger.info "loading file: " + fileItem.name
// Convert the fileItem binary data to CSV text
String productsCSV = new String(fileItem.get(), "UTF-8")
// Create or update the Organizations "Product Catalog" property
new PropertyBuilder()
.setName("Product Catalog")
.setValue(productsCSV)
.setClientCode(svcDef.clientCode)
.build()
String msg = "Imported '" + fileItem.name + "' file into 'Product Catalog' organization property"
logger.info msg
return msg
}
}
200 Response
When the script executes it returns the following response.
Imported 'product-catalog-q1.csv' file into 'Product Catalog' client property