ACTICO Platform - Execution Server...• Standard web service interfaces (REST/SOAP, JSON/XML) • Simultaneous hosting of multiple model versions • Deployments and roll-backs without

ACTICO Platform - Execution Server

User Guide

Version 9.0.0

www.actico.com

User Guide: Version 9.0.0

User Guide

Copyright © ACTICO GmbH iii

Table of Contents

1. About this document ........................................................................................................ 1

1.1. Audience ........................................................................................................................... 1

1.2. Content ............................................................................................................................. 1

1.3. Conventions ...................................................................................................................... 1

2. Introduction ........................................................................................................................ 2

2.1. Feature Overview .............................................................................................................. 2

3. System Overview, Links and Authentication ............................................................... 3

3.1. System Overview Diagram ................................................................................................. 3

3.2. Model Hub ........................................................................................................................ 3

3.3. Web Service Client ............................................................................................................ 3

4. Concepts and Background .............................................................................................. 4

4.1. Rule Execution .................................................................................................................. 4

4.2. Execution Trace ................................................................................................................ 4

4.3. Clustering ......................................................................................................................... 5

4.4. XML Representation of Data Types ................................................................................... 54.4.1. Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54.4.2. Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.4.3. Lists and Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.4.4. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.4.5. Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5. Calling a Web Service ....................................................................................................... 9

5.1. REST ................................................................................................................................. 95.1.1. Request Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.1.2. Reponse Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

5.2. SOAP ............................................................................................................................... 115.2.1. Rule Model to WSDL Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.2.2. Request Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.2.3. Response Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 1. About this document

Copyright © ACTICO GmbH 1

Chapter 1. About this documentThis document describes the usage of ACTICO Execution Server.

1.1. Audience

This document is intended for

• Users

• System Administrators

1.2. Content

This document considers the following topics

• Installation of Execution Server

• Usage of Execution Server

1.3. Conventions

The following text conventions are used in this document:

Table 1.1. Conventions

Convention Meaning

boldface Used for elements, labels and terms from the userinterface.

monospace Used for filenames or URLs.

Chapter 2. Introduction


Chapter 2. IntroductionACTICO Execution Server is responsible for the execution of models via standard web service interfaces.

It embedds the ACTICO Engine, the core component for model execution.

2.1. Feature Overview

Main features are:

• High-performance model execution

• Standard web service interfaces (REST/SOAP, JSON/XML)

• Simultaneous hosting of multiple model versions

• Deployments and roll-backs without downtime

• Traceability of individual model executions

• Horizontal & vertical scalability

• Security

Chapter 3. System Overview, Links and Authentication


Chapter 3. System Overview, Links and Authentication

3.1. System Overview Diagram

The following diagram shows Execution Server and the involved systems:

3.2. Model Hub

The URL to connect Execution Server to Model Hub is: http://localhost:8080/. (URL might vary dependingon Model Hub configuration)

See Model Hub user guide how to create credentials for the Execution Server to authenticate against ModelHub.

3.3. Web Service Client

Any Web Service client can be used to execute models via REST or SOAP.

The Base URL to connect to Execution Server is http://localhost:9090/engine/v1/executions. (BaseURL might vary depending on Model Hub configuration)

No authentication is required.

http://localhost:8080/

http://localhost:9090/engine/v1/executions

Chapter 4. Concepts and Background


Chapter 4. Concepts and BackgroundThe Execution Server itself has no user interface. Instead, it is controlled via an environment located in ModelHub. The Execution Server is designed to fetch all deployments available in the environment it is connected to.All these deployments are available for execution as long as they are resolved.

The sources of a release have be encoded in UTF-8 in order to be executed by the ExecutionServer.

Whenever there are deployment changes, the Execution Server automatically updates its internal runtimemodules. Thus, as soon as a release is deployed to the environment it is ready for execution.

For further information about environments, releases and deployments see the Model Hub UserGuide.

4.1. Rule Execution

For the rule execution, the engine requires the following information:

1. The module id.

2. The version.

3. The project id.

4. The path to the rule within the model.

The version can consists of a stream name and a release number (e.g. stream-1.0) or only of a stream name(e.g. stream-1). In case of only a stream name given, the release number of the active deployment is taken forexecution.

For legacy version, e.g. 1.2.3 or 1.2.3-SNAPSHOT or 1.2.3.RELEASE, everything before the first dot istreated as the stream name and everything after is the release number. Thus in these examplecases the stream name would be 1.

The execution of a rule can be called via a web service or java api. See Chapter 5, Calling a Web Service forfurther information.

4.2. Execution Trace

For every rule execution trace data is collected and returned with the execution result:

1. Correlation Id: External id allowing to correlate rule executions with a custom identifier.

2. Request Id: Id of the request. If, within the requested model, another model is internally called, theresulting request will get the same request id. By using this id, internal executions calls can be groupedtogether to one logical execution call.

3. Error Id: In case of an error, the error id can be used to fetch error details.

4. Model Name: Name of the model that has been executed.

5. Model Path: Model related path to the executed rule.

6. Version: The executed version, e.g. stream-1.0.

7. Stream: The executed stream name, e.g. stream-1.



8. Module Id: The id of the executed module.

9. Model Project Id: The id of the executed model project.

10. Model Project Type: The type of the executed model project. RULES, DMN, MACHINE_LEARNING, EXTENSIONor BIRT.

11. Deployment Resolution Id: The dependency resolution id of the executed deployment.

12. Duration Millis: Duration of the rule execution in milliseconds.

13. Execution Timestamp: Timestamp of the execution start in UTC.

The amount of trace data returned with the result can be defined when calling a rule execution.For further reading see chapter Chapter 5, Calling a Web Service.

4.3. Clustering

Multiple Execution Server can be connected to the same environment.

4.4. XML Representation of Data Types

4.4.1. Simple Types

Data types which stem from an imported XSD do not follow the rules described in this chapterand are represented as defined in the original XSD.

Simple types are mapped to the following XML schema types:

ACTICO Rules data type XML schema type

String xsd:string

Integer xsd:integer

Float xsd:decimal

Boolean xsd:boolean

Date xsd:date

Time xsd:time

Timestamp xsd:dateTime

If values are to be explicitly set as empty (represented in Java by the keyword null), this can beachieved by setting the xsi:nil attribute. For this to work, the request must also import the namespacexmlns:xsi="http://www.w3.org/2001/XMLSchema-instance".

Example:

<myDate xsi:nil="true" />

Please note that using the xsi:nil attribute only works for datatypes which support this. Forexample it is useless to specify this, when the datatype is a primitive Java type like int, becauseby definition they always have a value.

String



String values are simply specified as text (without quotes). For example, this XML fragment specifies a stringvalue "Peter" for a data element name.

Example:

<name>Peter</name>

Integer

Integer values are specified as numbers. For example, this XML fragment specifies 199 as the integer value for adata element seat_no.

Example:

<seat_no>199</seat_no>

Float

Float values are specified as numbers using a point as decimal separator. For example, this XML fragmentspecifies float values for different data elements. Please see an XML schema documentation for a moredetailed format description of xsd:decimal.

Examples:

<price>7.45</price><rate>-.4453</rate>

Boolean

Boolean values are specified as the word true or false. The XML type is xsd:boolean.

Examples:

<student>true</student><coupon>false</coupon>

Date

Date values are specified with this format: YYYY-MM-DD, four digits for the year, two digits for the month, twodigits for the day, all separated by dashes (-). Please see an XML schema documentation for a more detailedformat description of xsd:date.

Example:

<show_date>2008-08-22</show_date>

Time

Time values are specified with this format: hh:mm:ss, two digits for hour, minutes and seconds, separatedby colons (:). No part may be omitted. Please see an XML schema documentation for a more detailed formatdescription of xsd:time.

Example:

<alarm>15:47:23</alarm>

Timestamp

Timestamp values are specified according to the XML schema type xsd:dateTime. The format is YYYY-MMDDThh:mm:ss, which is a date and a time separated by the letter T. No part may be omitted. Please see anXML schema documentation for a more detailed format description of xsd:dateTime.

Example:



<startTimestamp>2009-05-30T09:30:10</startTimestamp>

4.4.2. Structures

Values for structures in a request or a response are simply represented by elements for each attribute. Forexample, the following XML fragment represents the value of a data element named customer with twoattributes name and address. Address itself has an attribute named zip.

Example:

<customer> <name>John Doe</name> <address> <zip>12345</zip> </address></customer>

4.4.3. Lists and Sets

Lists and sets in a request or a response are represented by a sequence of element tags, each specifying onevalue in the list or set.

For example, this is a list (or set) of Strings:

<names> <element>John Doe</element> <element>Peter Pan</element> <element>Captain Hook</element></names>

And this is a list (or set) of customers, where each customer has the attributes name and address:

<customers> <element> <name>John Doe</name> <address> <zip>12345</zip> </address> </element> <element> <name>Peter Pan</name> <address> <zip>99999</zip> </address> </element> <element> <name>Captain Hook</name> <address> <zip>99996</zip> </address> </element></customers>

4.4.4. Maps

Maps are represented by a sequence of entry tags, each having two elements named key and value. Forexample, this is a String → Customer mapping with two entries:



<customerMap> <entry> <key>8847-736-90</key> <value> <name>John Doe</name> <address> <zip>12345</zip> </address> </value> </entry> <entry> <key>2234-993-77</key> <value> <name>Peter Pan</name> <address> <zip>99999</zip> </address> </value> </entry></customerMap>

4.4.5. Enumerations

A value for an enumeration is specified simply by stating the desired literal. The following example specifiesthe value GOLD for a enumeration data element named bonus_card:

<bonus_card>GOLD</bonus_card>

Chapter 5. Calling a Web Service


Chapter 5. Calling a Web ServiceExecution Server provides endpoints to be called via a Webservice

5.1. REST

The Execution Server REST Webservice is accessible under the endpoint:

engine/v1/executions

Case Method Value Media Type

Execute Rule POST module/version/name/model-path

XML/JSON Object

Read WADL GET module/version/name/model-name.wadl

XML Object

Example Request to execute rule Movie Ticke Pricing/Pricing located in module "mtp" with version "stream-1.0"and project "Movie Ticket Pricing":

POST http://localhost:9090/engine/v1/executions/mtp/stream-1.0/Movie%20ticket%20Pricing/Movie%20Ticket%20Pricing/Pricing

with payload (JSON or XML)

{ "student" : false, "show_date" : "2037-08-03T16:24:41Z", "seat_no" : 1, "coupon" : false, "bonus_card" : "SILVER", "auditorium_no" : 1}

<pric:input xmlns:pric="http://www.visual-rules.com/vrpath/Movie%20Ticket%20Pricing%20Maven/Pricing/"> <pric:show_date>2037-08-03T16:24:41Z</pric:show_date> <pric:coupon>false</pric:coupon> <pric:auditorium_no>1</pric:auditorium_no> <pric:seat_no>1</pric:seat_no> <pric:student>false</pric:student>  <pric:bonus_card>SILVER</pric:bonus_card></pric:input>

if a rule has only one input parameter, the JSON payload consists only of the value, e.g. for aboolean input

false

5.1.1. Request Parameters

For every request a set of optional parameters can be set:

1. statistics: Define if and how detailed a stastic about the rule execution should be written.

a. SWITCHED_OFF: No information about the execution is collected. This is the default value.

b. QUIET: Collect information about start end end time of execution.

c. LOW: Count created request and visits of rule elements.



d. MEDIUM: Measure the time spent in a rule element.

e. HIGH: Determine minimum and maximum time spent in a rule element during all requests.

2. returnTrace: Amount of trace data returned in the execution response.

a. DEFAULT: Returns version, model name, model path, request id, and correlationId (if defined).

b. ALL: Returns all trace data.

c. NONE: Return no trace data at all.

3. correlationId: Set a custom correlation id for the request.

4. requestId: Set the request id for the request. If not specified, the Engine will assign a id. If a modelinternally calls another model, the resulting request will get the same request id. Using this id internalexecutions calls can be grouped together to one logical execution call.

For more information about the execution trace see chapter ??.

5.1.2. Reponse Format

The REST response format may be of type JSON or XML.

{ "trace": { "version": "stream-1.0", "modelName": "Movie Ticket Pricing", "modelPath": "Pricing", "requestId": "c1547f84-e732-499e-80a6-4d5cb08263c1" }, "output": { "price": 7, "bonus_points": 15, "student_discount_granted": false, "weekend_surcharge_added": false, "special_seating": true, "general_seating": false, "coupon_discount_granted": false }}

<execution> <trace> <requestId>b743b10b-1c65-43b4-87f6-4ae83a72e1de</requestId> <modelName>Movie Ticket Pricing</modelName> <modelPath>Pricing</modelPath> <version>stream-1.0</version> </trace> <output xmlns="http://www.visual-rules.com/vrpath/Movie Ticket Pricing/Pricing/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <price>7</price> <bonus_points>15</bonus_points> <student_discount_granted>false</student_discount_granted> <weekend_surcharge_added>false</weekend_surcharge_added> <special_seating>true</special_seating> <general_seating>false</general_seating> <coupon_discount_granted>false</coupon_discount_granted> </output></execution>

Both responses the trace element and the output element. The trace element contains data about the ruleexecution. . The output element contains the actual rule output. Additionally in contrast to JSON, the XMLrepresentation has a root element called execution.



If request parameter returnTrace is set to NONE, the trace element is not returned.

5.2. SOAP

The Execution Server SOAP Webservice is accesible under the endpoint:

engine/soap/v1

Case Method Value Media Type

Execute Rule POST module/version/name/model-name

XML Object

Read WSDL GET module/version/name/model-name.wsdl

XML Object

Example request to read the WSDL for the model Movie Ticket Pricing located in module "mtp" with version"stream-1.0" and project "Movie Ticket Pricing":

GET http://localhost:9090/engine/soap/v1/mtp/stream-1.0/Movie%20ticket%20Pricing/Movie%20Ticket%20Pricing.wsdl

5.2.1. Rule Model to WSDL Mapping

When a rule model is release, the WSDL is created using the following procedure:

1. The WSDL contains one service called <model>Service.

2. Each XML schema file contains the definitions of data types that are on that level in the rule model. Rulepackages, containing imported custom XML type definitions, reuse original XSD resources.

The WSDL file imports several XML schema files. The XML schema files are created like this:

1. There is one XML schema file for each level in the rule model, i.e. one for the rule model itself, one foreach rule package and one for each rule (flow rule or decision table) that was marked to be exported tothe rule service.

2. Each XML schema file contains the definitions of data types that are on that level in the rule model.

3. The namespace URI of each XML schema is derived from the rule package names, i.e. you will find the samehierarchy of rule packages and rules represented in the XML schema namespaces.

4. The XML schema files for exported rules also contain the definitions of the message formats for inputand output data elements. In other words, these schemas describe the interface of the rule, including thenames and types of all input/output data elements.

5.2.2. Request Format

The outermost element of the SOAP request is called Envelope, which contains the header and body elements.In the body the rule request is configured via the VRRequest element.



<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pric="http://www.visual-rules.com/vrpath/Movie%20Ticket%20Pricing/Pricing/" xmlns:vis="http://www.visual-rules.com"> <soapenv:Header/> <soapenv:Body> <pric:VRRequest>  <vis:target>  <vis:version>?</vis:version>  <vis:provider>?</vis:provider> </vis:target>  <vis:configuration>  <vis:requestId>?</vis:requestId>  <vis:correleationId>?</vis:correleationId>  <vis:activeConfigurationName>?</vis:activeConfigurationName>  <vis:sessionStatistics> <vis:level>?</vis:level> </vis:sessionStatistics> </vis:configuration> <pric:input> <pric:show_date>?</pric:show_date> <pric:coupon>?</pric:coupon> <pric:auditorium_no>?</pric:auditorium_no> <pric:seat_no>?</pric:seat_no> <pric:student>?</pric:student>  <pric:bonus_card>?</pric:bonus_card> </pric:input> </pric:VRRequest> </soapenv:Body></soapenv:Envelope>

The target element is optional. It can be used the sepcify a specific version that should be executed. If thetarget element is not present the active version of the deployment will be executed.

Similar to the target element the configuration element is also optional. It holds values which are used toconfigure the execution of the rule service.

The values that can be specified in the configuration element are the same as the parameters ofthe REST rule execution.

Finally, the input element specifies the values of the input data elements for the rule.

5.2.3. Response Format

The response format for SOAP request has the same layout as the REST XML response. It contains the twoelements output and trace. Only the root element is called VRResponse istead of execution.



<vrresponse:VRResponse xmlns:vrresponse="http://www.actico.com/rules" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:vr="http://www.visual-rules.com"> <vrresponse:output> <vrresponse:price>7</vrresponse:price> <vrresponse:bonus_points>15</vrresponse:bonus_points> <vrresponse:student_discount_granted>false</vrresponse:student_discount_granted> <vrresponse:weekend_surcharge_added>false</vrresponse:weekend_surcharge_added> <vrresponse:special_seating>true</vrresponse:special_seating> <vrresponse:general_seating>false</vrresponse:general_seating> <vrresponse:coupon_discount_granted>false</vrresponse:coupon_discount_granted> </vrresponse:output> <vr:trace> <vr:modelName>Movie Ticket Pricing</vr:ruleModel> <vr:modelPath>Pricing</vr:rulePath> <vr:version>stream-1.0</vr:version> <vr:requestId>19fd85f2-07ad-485f-9542-9feee543e496</vr:requestId> <vr:activeConfigurationName>Default</vr:activeConfigurationName> </vr:trace></vrresponse:VRResponse>

The trace element only present if the returnTrace parameter is set to DEFAULT or ALL.

Documents

ACTICO Platform - Execution Server...• Standard web service interfaces (REST/SOAP, JSON/XML) • Simultaneous hosting of multiple model versions • Deployments and roll-backs without