Fluent API REST Service

   Fluent APIThis topic is related to Fluent API. |   Platform Developer |  v21.05 This feature was introduced in v21.05.

As you know, Journey Manager comes with an extensive set of private Fluent API enabling you to implement various complex business requirements. All you need to do is to just write a Groovy scrip that calls a few API and run it within your service. And it all works. However, what happens when you want to invoke the same Fluent API outside Manager. Now, we have a solution for you!

The 21.05 release of Journey Manager has introduced a new service (com.avoka.fc.admin.service.FluentApiService.java) which exposes some of Manager's Fluent API via RESTREST or RESTful API design (Representational State Transfer) is designed to take advantage of existing protocols. While REST can be used over nearly any protocol, it usually takes advantage of HTTP when used for Web APIs. end points. This service is simple to understand and use and yet it provides you with ability to invoke rich in functionality Fluent API.

Note

This is the Beta release of the Fluent API REST service, which implements only a limited number of Fluent API. We may need to update or even change some service functionality or implementation depending on REST performance, usability, and your feedback.

Now, you are probably curious to find out how it all works. Well, it's rather simple. The Fluent API REST service is included in the new Transact Manager WAR module, along with other REST services, so if you've installed or upgraded Journey Manager to the 21.05 release, you can start using the Fluent API REST service. The new service architecture is illustrated in the diagram below:

Requests

You interaction with the Fluent API REST service starts by sending a REST request. Each Fluent API class and every of its methods (operations) form a single endpoint, which you call by sending a request to a URL in the following format:

https://{SERVER}/manager/secure/rest/fluentapi/{CLASSNAME}/{OPERATION}

Where:

  • SERVER is your Manager server instance
  • CLASSNAME is a case-insensitive name of Fluent API class, for example, txnupdater for the TxnUpdater class
  • OPERATION is a case-insensitive name of a final method (oreration) to be called on this API, for example, update
Note

We have chosen the combination of class names and methods to simplify the learning curve for developers, who are already familiar with our Fluent API.

You have to provide a body payload for an operation in a JSONJSON (JavaScript Object Notation) is a syntax for storing and exchanging data and is used in Maestro to store forms. If a Form Builder wants to transfer their form to another system, they can do so by using the Download JSON file button. format, where each set method has its own entry in the JSON payload. The Fluent API REST server processes the request and sends back a response including a response code and a payload, depending on an operation.

Let's illustrate it with a simple example. Suppose, you want to update a transaction delivery status from a Groovy script. For that, you use the TxnUpdater class, as shown below.

import com.avoka.tm.svc.*
import com.avoka.tm.vo.*
 
new TxnUpdater(txn)
    .setId​(733)
    .setDeliveryStatus(Txn.DELIVERY_READY)
    .update()

You can achieve the same result by executing this POST request with a payload:

POST https://{SERVER}/manager/secure/rest/fluentapi/txnupdater/update
Content-Type:application/json
Accept:application/json
{
    "setId" : "733",
    "setDeliveryStatus" : "Ready"
}

Let's examine the REST POST method:

  • txnupdater is the TxnUpdater class
  • update is the last method to be called on the instance of TxnUpdater class, which is the update () method
  • setId sets a transaction ID to be updated, which is the setId() method
  • setDeliveryStatus sets the Ready status of a transaction, which is the setDeliveryStatus() method

You can see the REST method basically mimics the Fluent API call, which makes developer's life much easier.

Responses

Each Fluent API REST request has a corresponding response including an HTTP code and data in a JSON format or an error message. We've simplified and minimized the number of responses, so it's easy to use the service.

The Fluent API REST service returns the following HTTP response codes:

HTTP Code Description

200 OK

This code is returned when a Fluent API REST call is successful.

400 Bad Request

This code is returned when a Fluent API REST call fails due to bad input. The error message in the response includes an error log ID so you can find more details about the error in the error log.

404 Not Found

This code is returned when a Fluent API REST call fails trying to update or access objects that don't match provided ID. The error message in the response includes an error log ID so you can find more details about the error in the error log.

Security

Manager has a new REST Fluent API core permission which you must assign to roles of users who will invoke the Fluent API REST service. The Administrator role has this permission set by default. We recommend creating a dedicated user with this permission.

Class Names

This release of Manager has the following CLASSNAMEs implemented:

CLASSNAME Usage Example
ActionResultBuilder  
DeliveryTxnBuilder  
Emailer  
GroupQuery  
JobActionQuery  
JobBuilder  
JobQuery  
JobStepQuery  
JobUpdater  
PaymentLogQuery  
PropertyQuery
https://localhost/manager/secure/rest/fluentapi/propertyquery/getValue

{
  "setName" : "733",
  "setTxn" : "{\r\n    \"id\": 439,\r\n    \"attachmentsStatus\": null,\r\n    \"orgId\": 7,\r\n    \"clientCode\": \"dccu\",\r\n    \"orgName\": \"dccu\",\r\n    \"deliveryStatus\": \"Not Ready\",\r\n    \"deliveryChannel\": null,\r\n    \"deliveryMaxAttempts\": null,\r\n    \"deliveryMessage\": null,\r\n    \"deliveryMethod\": null,\r\n    \"deliveryProcessAttempts\": null,\r\n    \"emailAddress\": null,\r\n    \"emailVerificationStatus\": null,\r\n    \"formId\": 54,\r\n    \"formCode\": \"originationform\",\r\n    \"formName\": \"Origination Form\",\r\n    \"formStatus\": \"Completed\",\r\n    \"formType\": \"Maestro Form\",\r\n    \"groupNames\": [],\r\n    \"paymentStatus\": null,\r\n    \"paymentTotal\": null,\r\n    \"jobId\": 21,\r\n    \"jobActionId\": 75,\r\n    \"jobRefNumber\": \"VZTSF33\",\r\n    \"spaceId\": 8,\r\n    \"spaceName\": \"Work Space\",\r\n    \"receiptNumber\": \"VZTSF33\",\r\n    \"receiptStatus\": \"Completed\",\r\n    \"saveChallengeHash\": null,\r\n    \"saveChallengeFailures\": null,\r\n    \"saveChallengeLastFailure\": null,\r\n    \"saveChallengeTimeout\": null,\r\n    \"timeCreated\": \"24 Apr. 2019, 9:42 am\",\r\n    \"timeAbandoned\": null,\r\n    \"timeAbandonmentScheduled\": null,\r\n    \"timeUserLastModified\": \"24 Apr. 2019, 9:42 am\",\r\n    \"timeSubmitted\": \"24 Apr. 2019, 9:42 am\",\r\n    \"timeCompleted\": \"24 Apr. 2019, 9:43 am\",\r\n    \"timeDelivered\": null,\r\n    \"timeProcessUpdated\": null,\r\n    \"timePurgeDataScheduled\": null,\r\n    \"timePurgeDataActual\": null,\r\n    \"timePurgeRecordScheduled\": null,\r\n    \"timeRequested\": \"24 Apr. 2019, 9:42 am\",\r\n    \"timeSubmissionExpiry\": null,\r\n    \"timeTaskExpiry\": null,\r\n    \"timeTaskScheduled\": null,\r\n    \"timeTxnExpiry\": null,\r\n    \"dataDeleted\": false,\r\n    \"submitKey\": \"f788f5d7eb69d5e42dd8250dab4239c1\",\r\n    \"trackingCode\": \"VZTSF33\",\r\n    \"transRefNumber\": null,\r\n    \"userLoginName\": null,\r\n    \"userSaved\": false,\r\n    \"externalUserId\": null,\r\n    \"paymentGatewayTimestamp\": null,\r\n    \"paymentGatewayReceiptNo\": null,\r\n    \"paymentGatewayTxnNo\": null,\r\n    \"processStatus\": null,\r\n    \"formVersionId\": 71,\r\n    \"formVersionNumber\": \"1.0-develop\",\r\n    \"txnScore\": null,\r\n    \"userAgent\": \"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/73.0.3683.103 Safari\/537.36\",\r\n    \"userAgentDeviceType\": \"Desktop\",\r\n    \"formAbandonmentType\": null,\r\n    \"formUrl\": null,\r\n    \"receiptUrl\": \"https:\/\/localhost\/workspace\/servlet\/FormReceipt.pdf?submitKey=f788f5d7eb69d5e42dd8250dab4239c1\",\r\n    \"checkpoints\": null,\r\n    \"formDataMap\": {},\r\n    \"propertyMap\": {},\r\n    \"milestones\": [],\r\n    \"formXml\": \"\",\r\n    \"receiptPdf\": null,\r\n    \"fileAttachList\": [],\r\n    \"deliveryFuncs\": [],\r\n    \"comments\": [],\r\n    \"commentList\": []\r\n}"
}
PropertyBuilder  
RefDataSvc  
RefDataQuery  
RoleQuery  
SpaceQuery  
SvcConnQuery  
SvcDefQuery  
SvcConnUpdater  
TrackingCodeBuilder  
TxnBuilder  
TxnUpdater  
TxnHistoryQuery  
TxnQuery

Query by ID

https://localhost/manager/secure/rest/fluentapi/txnquery/firstValue

{
  "setId" : "733"
}
UserQuery  
UserBuilder
https://localhost/manager/secure/rest/fluentapi/userbuilder/create

{
    "setEmail" : "person@temenos.com",
    "setUserType" : "Local",
    "setLoginName" : "loginName",
    "setPassword" : "pAs3W0rd!@#"
}
UserEmailer
https://localhost/manager/secure/rest/fluentapi/useremailer/sendEmail

{
    "setLoginName" : "loginName",
    "setSpaceName" : "Work Space",
    "setType" : "WELCOME"
}

Next, learn about Fluent Groovy Services vs Groovy Services.