REST Service Definitions API
The Service Definition API provides a REST service for querying and modifying service definitions defined in Journey Manager in a secure and efficient manner.
Security
To access the Service Definition 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 Service Definitions API
'.
If the user is not a global administrator, only services belonging to the organizations assigned to the user will be accessible.
URL Endpoint
The REST service definitions URL endpoint is as follows:
``` https://Accessible Service Types
The REST Service Definitions service allows you to access service of the following service types:
- All services in ServiceDefinition.GROOVY_SERVICE_TYPES
- Job Controller
Service API
This section provides a description all the REST Service Definition API operations including:
- GET Service Definition List
- GET Service Definition
- GET Service Parameter List
- GET Service Parameter
- POST Create Service Definition
- POST Create Service Parameter
- PUT Update Service Definition
- PUT Update Service Parameter
- DELETE Service Definition
- DELETE Service Parameter
- POST Upload Service Archive
- POST Run Unit Test
GET Service Definition List
Return the list of service definitions ordered by service name and version number.
URL Format
GET https://<tm server>/manager/secure/rest/service-definitions/v1/
Request Parameters
The table below shows the set of request parameters can be used as additional search criteria.
If multiple parameters are specified, all of them are applied to the result set.
Parameter | Description |
---|---|
activeFlag | a boolean parameter that filters on the active flag (Values: true, false) |
clientName | if set, only services for the given organization (by name) will be returned |
id | a numeric parameter containing the service definition's database ID |
jobTemplateFlag | a boolean parameter that filters on the job template flag (Values: true, false) |
serviceName | the service name to match (note: the combination of service name and version number uniquely identifies a service) |
serviceType | the service type to match (see Accessible Service Types for the set of accessible types) |
unitTestEnabledFlag | a boolean parameter that filters on the unit test enabled flag (Values: true, false) |
versionNumber | a numeric value containing the version number to match (note: the combination of service name and version number uniquely identifies a service) |
URL Example
GET https://transact.maguire.com/manager/secure/rest/service-definitions/v1/?serviceType=Form%20Version%20Selector&activeFlag=true
200 Response
[
{
"id": 1226,
"serviceName": "A/B Testing Form Version Selector",
"versionNumber": 1,
"serviceType": "Form Version Selector",
"description": "A service that selects the form version to render at random from the list of form versions",
"serviceTypeDefaultFlag": false,
"activeFlag": true,
"jobTemplateFlag": false,
"unitTestEnabledFlag": false,
"classnameBeanname": "com.avoka.fc.core.service.form.RandomFormVersionSelectorService",
"createdAt": "Jun 13, 2014 10:20:15 AM",
"createdBy": "system",
"lastModifiedAt": "Mar 4, 2015 3:58:17 AM",
"lastModifiedBy": "medgar",
"serviceParameters": [
{
"id": 1931,
"name": "includedFormVersions",
"description": "A comma separated list of form version numbers to include in selection. Leave blank to use all versions.",
"type": "String",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "3.0, 2.0",
"createdAt": "Jun 13, 2014 10:20:15 AM",
"createdBy": "system",
"lastModifiedAt": "Mar 4, 2015 3:58:17 AM",
"lastModifiedBy": "medgar"
},
{
"id": 1932,
"name": "ignoreFormVersionRequestParameter",
"description": "Enable this parameter ignore the value of the 'tmFormVersion' request parameter.",
"type": "boolean",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "false",
"createdAt": "Jun 13, 2014 10:20:15 AM",
"createdBy": "system"
}
]
},
{
"id": 1206,
"serviceName": "Current Version Selector",
"versionNumber": 1,
"serviceType": "Form Version Selector",
"description": "This service returns the current form version, or (if specified) uses the request parameter 'tmFormVersion' to look up a specific version.",
"serviceTypeDefaultFlag": true,
"activeFlag": true,
"jobTemplateFlag": false,
"unitTestEnabledFlag": false,
"classnameBeanname": "com.avoka.fc.core.service.form.CurrentVersionSelectorService",
"createdAt": "Jun 11, 2014 3:13:31 PM",
"createdBy": "system",
"lastModifiedAt": "Feb 11, 2015 3:12:49 PM",
"lastModifiedBy": "someadmin",
"serviceParameters": [
{
"id": 1911,
"name": "ignoreFormVersionRequestParameter",
"description": "Enable this parameter to always use the current form version, regardless of the value of the 'tmFormVersion' request parameter.",
"type": "boolean",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "false",
"createdAt": "Jun 11, 2014 3:13:31 PM",
"createdBy": "system"
}
]
}
]
GET Service Definition
Return the service definition for the specified service id.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/<service ID>/
URL Example
GET https://transact.maguire.com/manager/secure/rest/service-definitions/v1/803/
200 Response
{
"id": 803,
"serviceName": "Random Tracking Number",
"versionNumber": 1,
"serviceType": "Tracking Number",
"description": "Create random form transaction tracking numbers.",
"serviceTypeDefaultFlag": true,
"activeFlag": true,
"jobTemplateFlag": false,
"unitTestEnabledFlag": false,
"classnameBeanname": "com.avoka.fc.core.service.form.RandomTrackingNumberService",
"createdAt": "Feb 27, 2014 5:14:18 PM",
"createdBy": "system",
"lastModifiedAt": "Aug 12, 2014 3:14:28 PM",
"lastModifiedBy": "someadmin",
"serviceParameters": [
{
"id": 1348,
"name": "numberLength",
"description": "The length of the tracking number.",
"type": "List",
"bindParameterFlag": true,
"unitTestFlag": false,
"listValues": "4:4|5:5|6:6|7:7|8:8",
"value": "6",
"createdAt": "Feb 27, 2014 5:14:18 PM",
"createdBy": "system"
},
{
"id": 1349,
"name": "characterValues",
"description": "The list of character values to generate the random tracking number from.",
"type": "String",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "ABCDEFGHJKLMNPQRSTVWXYZ23456789",
"createdAt": "Feb 27, 2014 5:14:18 PM",
"createdBy": "system",
"lastModifiedAt": "Aug 12, 2014 3:14:28 PM",
"lastModifiedBy": "someadmin"
}
]
}
GET Service Definition Parameter List
Returns all service parameters for the specified service definition, sorted by parameter name.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/<service ID>/serviceParameters
URL Example
GET https://transact.maguire.com/manager/secure/rest/service-definitions/v1/803/serviceParameters
200 Response
[
{
"id": 1349,
"name": "characterValues",
"description": "The list of character values to generate the random tracking number from.",
"type": "String",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "ABCDEFGHJKLMNPQRSTVWXYZ23456789",
"createdAt": "Feb 27, 2014 5:14:18 PM",
"createdBy": "system",
"lastModifiedAt": "Aug 12, 2014 3:14:28 PM",
"lastModifiedBy": "someadmin"
},
{
"id": 1348,
"name": "numberLength",
"description": "The length of the tracking number.",
"type": "List",
"bindParameterFlag": true,
"unitTestFlag": false,
"listValues": "4:4|5:5|6:6|7:7|8:8",
"value": "6",
"createdAt": "Feb 27, 2014 5:14:18 PM",
"createdBy": "system"
}
]
GET Service Definition Parameter
Return the service parameter for the specified service definition id and parameters id.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/<service ID>/serviceParameters/<service parameter ID>
URL Example
GET https://transact.maguire.com/manager/secure/rest/service-definitions/v1/803/serviceParameters/1348
200 Response
{
"id": 1348,
"name": "numberLength",
"description": "The length of the tracking number.",
"type": "List",
"bindParameterFlag": true,
"unitTestFlag": false,
"listValues": "4:4|5:5|6:6|7:7|8:8",
"value": "6",
"createdAt": "Feb 27, 2014 5:14:18 PM",
"createdBy": "system"
}
POST Create Service Definition
Post a JSON object describing a service definition to create a service definition.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/
POST Body Format
You must pass in a service definition value object containing the new values.
POST Example
POST https://transact.maguire.com/manager/secure/rest/service-definitions/v1/
{
"serviceName": "Random Tracking Number",
"versionNumber": 2,
"serviceType": "Tracking Number",
"description": "A new version of the random tracking number service",
"serviceTypeDefaultFlag": false,
"activeFlag": true,
"jobTemplateFlag": false,
"unitTestEnabledFlag": false,
"clientName": "Maguire",
"classnameBeanname": "com.avoka.fc.core.service.form.RandomTrackingNumberService",
"serviceParameters": [
{
"name": "numberLength",
"description": "The length of the tracking number.",
"type": "List",
"bindParameterFlag": true,
"unitTestFlag": false,
"listValues": "4:4|5:5|6:6|7:7|8:8",
"value": "6"
},
{
"name": "characterValues",
"description": "The list of character values to generate the random tracking number from.",
"type": "String",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "ABCDEFGHJKLMNPQRSTVWXYZ23456789"
}
]
}
200 Response
{
"id": 215,
"serviceName": "Random Tracking Number",
"versionNumber": 2,
"serviceType": "Tracking Number",
"description": "A new version of the random tracking number service",
"serviceTypeDefaultFlag": false,
"activeFlag": true,
"jobTemplateFlag": false,
"unitTestEnabledFlag": false,
"clientName": "Maguire",
"classnameBeanname": "com.avoka.fc.core.service.form.RandomTrackingNumberService",
"createdAt": "Sep 30, 2015 4:08:51 PM",
"createdBy": "someadmin",
"serviceParameters": [
{
"id": 950,
"name": "numberLength",
"description": "The length of the tracking number.",
"type": "List",
"bindParameterFlag": true,
"unitTestFlag": false,
"listValues": "4:4|5:5|6:6|7:7|8:8",
"value": "6",
"createdAt": "Sep 30, 2015 4:08:51 PM",
"createdBy": "someadmin"
},
{
"id": 949,
"name": "characterValues",
"description": "The list of character values to generate the random tracking number from.",
"type": "String",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "ABCDEFGHJKLMNPQRSTVWXYZ23456789",
"createdAt": "Sep 30, 2015 4:08:51 PM",
"createdBy": "someadmin"
}
]
}
POST Create Service Parameter
Post a JSON object describing a service parameter to create a service parameter for an existing service definition.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/<service ID>/serviceParameters
POST Body Format
You must pass in a service parameter value object containing the new values.
POST Example
POST https://transact.maguire.com/manager/secure/rest/service-definitions/v1/215/serviceParameters
{
"name": "myCustomParameter",
"description": "A new parameter that our service can use",
"type": "String",
"bindParameterFlag": false,
"unitTestFlag": false,
"value": "Default Value"
}
200 Response
{
"id": 953,
"name": "myCustomParameter",
"description": "A new parameter that our service can use",
"type": "String",
"bindParameterFlag": false,
"unitTestFlag": false,
"value": "Default Value",
"createdAt": "Oct 1, 2015 11:26:08 AM",
"createdBy": "someadmin"
}
PUT Update Service Definition
Put a JSON object describing an existing service definition to update its values.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/<service ID>
PUT Body Format
You must pass in a service definition value object containing the new values.
PUT Example
PUT https://transact.maguire.com/manager/secure/rest/service-definitions/v1/215
{
"serviceName": "My Random Tracking Number",
"versionNumber": 3,
"serviceType": "Tracking Number",
"description": "An updated version of the random tracking number service",
"serviceTypeDefaultFlag": false,
"activeFlag": true,
"serviceParameters": [
{
"name": "numberLength",
"description": "The length of the tracking number.",
"type": "List",
"bindParameterFlag": true,
"unitTestFlag": false,
"listValues": "4:4|5:5|6:6|7:7|8:8",
"value": "8"
},
{
"name": "characterValues",
"description": "The list of character values to generate the random tracking number from.",
"type": "String",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "AEIOU"
}
]
200 Response
{
"id": 215,
"serviceName": "My Random Tracking Number",
"versionNumber": 3,
"serviceType": "Tracking Number",
"description": "An updated version of the random tracking number service",
"serviceTypeDefaultFlag": false,
"activeFlag": true,
"jobTemplateFlag": false,
"unitTestEnabledFlag": false,
"clientName": "Maguire",
"classnameBeanname": "com.avoka.fc.core.service.form.RandomTrackingNumberService",
"createdAt": "Sep 30, 2015 4:08:51 PM",
"createdBy": "someadmin",
"lastModifiedAt": "Oct 1, 2015 10:27:19 AM",
"lastModifiedBy": "someadmin",
"serviceParameters": [
{
"id": 949,
"name": "characterValues",
"description": "The list of character values to generate the random tracking number from.",
"type": "String",
"bindParameterFlag": true,
"unitTestFlag": false,
"value": "AEIOU",
"createdAt": "Sep 30, 2015 4:08:51 PM",
"createdBy": "someadmin",
"lastModifiedAt": "Oct 1, 2015 10:27:19 AM",
"lastModifiedBy": "someadmin"
},
{
"id": 950,
"name": "numberLength",
"description": "The length of the tracking number.",
"type": "List",
"bindParameterFlag": true,
"unitTestFlag": false,
"listValues": "4:4|5:5|6:6|7:7|8:8",
"value": "8",
"createdAt": "Sep 30, 2015 4:08:51 PM",
"createdBy": "someadmin",
"lastModifiedAt": "Oct 1, 2015 10:27:19 AM",
"lastModifiedBy": "someadmin"
}
]
}
PUT Update Service Parameter
Put a JSON object describing a service parameter to update an existing service parameter.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/<service ID>/serviceParameters/<service parameter ID>
PUT Body Format
You must pass in a service parameter value object containing the new values.
PUT Example
PUT https://transact.maguire.com/manager/secure/rest/service-definitions/v1/215/serviceParameters/953
{
"name": "myCustomParameter2",
"description": "An updated parameter that our service can use",
"type": "String",
"bindParameterFlag": false,
"unitTestFlag": false,
"value": "Updated Value"
}
200 Response
{
"id": 953,
"name": "myCustomParameter2",
"description": "An updated parameter that our service can use",
"type": "String",
"bindParameterFlag": false,
"unitTestFlag": false,
"value": "Updated Value",
"createdAt": "Oct 1, 2015 11:26:08 AM",
"createdBy": "someadmin",
"lastModifiedAt": "Oct 1, 2015 11:35:22 AM",
"lastModifiedBy": "someadmin"
}
DELETE Service Definition
Irrevocably delete a service definition and all its parameters. USE THIS OPERATION WITH CAUTION.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/<service ID>
or
https://<tm server>/manager/secure/rest/service-definitions/v1/<service name>/<version number>
DELETE Examples
DELETE https://transact.maguire.com/manager/secure/rest/service-definitions/v1/215
and
DELETE https://transact.maguire.com/manager/secure/rest/service-definitions/v1/My Random Tracking Number/3
200 Response
The response will not contain any additional information. If the status code is 200, the service definition was deleted successfully.
DELETE Service Parameter
Irrevocably delete a service parameter. USE THIS OPERATION WITH CAUTION.
URL Format
https://<tm server>/manager/secure/rest/service-definitions/v1/<service ID>/serviceParameters/<service parameter ID>
DELETE Example
DELETE https://transact.maguire.com/manager/secure/rest/service-definitions/v1/215/serviceParameters/953
200 Response
The response will contain the updated service definition and the remaining parameters.
``` { "id": 215, "serviceName": "My Random Tracking Number", "versionNumber": 3, "serviceType": "Tracking Number", "description": "An updated version of the random tracking number service", "serviceTypeDefaultFlag": false, "activeFlag": true, "jobTemplateFlag": false, "unitTestEnabledFlag": false, "clientName": "Maguire", "classnameBeanname": "com.avoka.fc.core.service.form.RandomTrackingNumberService", "createdAt": "Sep 30, 2015 4:08:51 PM", "createdBy": "someadmin", "lastModifiedAt": "Oct 1, 2015 11:43:21 AM", "lastModifiedBy": "someadmin", "serviceParameters": [ { "id": 949, "name": "characterValues", "description": "The list of character values to generate the random tracking number from.", "type": "String", "bindParameterFlag": true, "unitTestFlag": false, "value": "AEIOU", "createdAt": "Sep 30, 2015 4:08:51 PM", "createdBy": "someadmin", "lastModifiedAt": "Oct 1, 2015 10:27:19 AM", "lastModifiedBy": "someadmin" }, { "id": 950, "name": "numberLength", "description": "The length of the tracking number.", "type": "List", "bindParameterFlag": true, "unitTestFlag": false, "listValues": "4:4|5:5|6:6|7:7|8:8", "value": "8", "createdAt": "Sep 30, 2015 4:08:51 PM", "createdBy": "someadmin", "lastModifiedAt": "Oct 1, 2015 10:27:19 AM", "lastModifiedBy": "someadmin" } ] } ```POST Upload Service Archive
Upload a Service Archive ZIP file into the Journey Manager server creating or updating any included service definitions.
Please note this will preserve any existing global default type Services and existing Service Connections. However any existing services of the same name will be updated with the provided service archive.
URL Format
POST https://<tm server>/manager/secure/rest/service-definitions/v1/upload-service-archive/
POST Body
The Multipart POST request parameters include:
-
archiveFile
- the service archive ZIP file (required) -
clientCode
- the Organization client code (optional), if not specified the current client will be used
Example
Please note POST example below is idealized to provide an illustration of multipart POST request.
POST <b>/manager/secure/rest/service-definitions/v1/upload-service-archive/</b> HTTP/1.1
Host: https://transact.maguire.com
Content-type: multipart/form-data, boundary=AaB03x
--AaB03x
content-disposition: form-data; name="archiveFile"; filename="service-archive-Groovy_Form_Security_Filter-2016-06-17.zip"
Content-Transfer-Encoding: binary
...
--AaB03x--
==========================
200 Response
{
"archiveName": "service-archive-Groovy_Form_Security_Filter-2016-06-17.zip",
"importMessage": "Imported Groovy Form Security Filter - v1 successfully.",
"importStatus": "Completed",
"importTime": "2016-06-17T16:47+1000"
}
POST Run Unit Test
Run the service's automated Unit Test.
URL Format
POST https://<tm server>/manager/secure/rest/service-definitions/v1/run-unit-test/
POST Body
The POST request parameters include:
-
serviceName
- the name of the service definition to run (required) -
versionNumber
- the service version number (optional), highly recommended to resolve correct version -
clientCode
- the Organization client code (optional), highly recommended to resolve correct Organization service
Example
This example below runs the unit test for the 'Hello World' version 1 service. The example the message body below formatted for easier reading.
Please ensure you specify Content-Type: application/x-www-form-urlencoded
POST <b>/manager/secure/rest/service-definitions/v1/run-unit-test/</b> HTTP/1.1
Host: https://transact.maguire.com
Content-Type: application/x-www-form-urlencoded
<b>serviceName</b>=Hello World&<b>versionNumber</b>=1&<b>clientCode</b>=maguire
200 Response
Below is a example response of a service unit test success.
{
"serviceName": "Hello World",
"versionNumber": 1,
"testStatus": "Success",
"message": "Test succeeded in 49 ms",
"logger": "21:24:21,034 INFO groovy result"
}
Below is a example response of a service unit test failure.
{
"serviceName": "Hello World",
"versionNumber": 1,
"testStatus": "Failure",
"message": "Test failed after 741 ms",
"errorCause": "java.lang.NullPointerException",
"errorLine": 19
}
Service Definition and Service Parameter JSON
The POST and PUT operations described above work with service definition and parameter JSON value objects. See the previous sections for a number of examples.
Service Definition
Attribute | Type | Description |
---|---|---|
activeFlag | Boolean | a flag describing whether the service is active and usable |
classnameBeanname | String | the Java class name/bean name of the class implementing the service |
clientName | String |
the name of the organization the service is associated with Note: This value cannot be changed once a service has been created. |
clientCode | String | the organization unique client code |
createdAt | Date |
the service creation date Note: This parameter is ignored during updates as Journey Manager maintains these attributes. |
createdBy | String |
the user who created the service Note: This parameter is ignored during updates as Journey Manager maintains these attributes. |
description | String | a description of the service that will be visible to administrators |
id | Long |
the database ID identifying the service Note: You should not need to set this in your POST and PUT calls. However, it is important to use the IDs returned by a GET call, as the service ID is used in URLs. However, do not use the ID across sessions as database IDs may change (e.g. because services may get recreated, or DB backups restored) |
jobTemplateFlag | Boolean | a flag describing whether the service contains a job template |
lastModifiedAt | Date |
the service last modified date Note: This parameter is ignored during updates as Journey Manager maintains these attributes. |
lastModifiedBy | String |
the user who last modified the service Note: This parameter is ignored during updates as Journey Manager maintains these attributes. |
serviceName | String |
the name identifying the service (required for new services) Note: Name and version number together uniquely identify a service. |
serviceParameters | List of Service Parameter | the list of service parameter value objects |
serviceType | String |
the service type, e.g. Dynamic Data Note: This value is required for new services but cannot be changed later. |
serviceTypeDefaultFlag | Boolean | a flag describing whether the service is the default service for its type |
tmMinVersion | String | specifies the minimum Journey Manager version required to support the service |
unitTestEnabledFlag | Boolean | a flag describing whether the service is set up for unit testing |
versionNumber | Integer |
the version number, e.g. 1 (required for new services) Note: Name and version number together uniquely identify a service. |
Service Parameter
Attribute | Type | Description |
---|---|---|
bindParameterFlag | Boolean |
a flag describing whether the service parameter name corresponds to a property on the service class and should be set automatically by Journey Manager Note: If you use this flag incorrectly, your service will not work. Ensure to turn this flag on if and only if the service class has a setter method corresponding to the parameter name. |
clearOnExportFlag | Boolean | a flag specifying whether the parameter value should be cleared when exported from a system to protect security credentials. |
createdAt | Date |
the service parameter creation date Note: This parameter is ignored during updates as Journey Manager maintains these attributes. |
createdBy | String |
the user who created the service parameter Note: This parameter is ignored during updates as Journey Manager maintains these attributes. |
description | String | a description of the service parameter that will be visible to administrators |
id | Long |
the database ID identifying the service parameter Note: You should not need to set this in your POST and PUT calls. However, it is important to use the IDs returned by a GET call, as the service parameter ID is used in URLs. However, do not use the ID across sessions as database IDs may change (e.g. because services may get recreated, or DB backups restored) |
lastModifiedAt | Date |
the service parameter last modified date Note: This parameter is ignored during updates as Journey Manager maintains these attributes. |
lastModifiedBy | String |
the user who last modified the service parameter Note: This parameter is ignored during updates as Journey Manager maintains these attributes. |
listValues | String |
for service parameters of type "List", this parameter contains the possible values that can be assigned to this parameter the format is pipe-separated with optional display names: value:displayName|anotherValue|thirdValue:thirdDisplayName example for a parameter controlling expiry: "0:Never|1:1 day|3:3 days|7:1 week|365:1 year" |
name | String |
the name identifying the service parameter (required) Note: Parameter names are unique within a service. |
readonlyFlag | Boolean | a flag specifying whether the service parameter is read only and cannot be modified in Journey Manager |
requiredFlag | Boolean | a flag specifying whether the service parameter must have a value before a service object can be created |
unitTestFlag | Boolean | a flag describing whether the service parameter is used for unit testing |
type | String |
the type of values that can be assigned to the service parameter This can be one of:
|
value | String |
the value assigned to the service parameter Note: The value must conform to the service parameter type. |