QUICKSTART

MarkLogic State Conductor - Quick Start Guide

The State Conductor requires ml-gradle as its build and deployment tool. If you're adding the State Conductor to an existing ml-gradle project, begin by adding the required dependencies. Otherwise, you must first create a new ml-gradle project by following this guide.

Add the State Conductor dependencies

The State Conductor is distributed as an mlBundle for ml-gradle projects. Within you project's build.gradle file, make the following changes:

Add the following as a repository

maven {
  url {"https://dl.bintray.com/aclavio/maven"}
}

Add the mlBundle as a dependency

mlBundle "com.marklogic:marklogic-state-conductor:1.0.0"

Create State Machine definitions

Next you must define one or more state machine's to process your data. By default, state machines are loaded into you project's content database under a folder named state-machine. Within your project's src/main directory, create a ml-data directory if one does not already exist. Then within that folder, create a state-machine sub-directory; This is where you should place any state machines you create. Utilizing this folder will also ensure state machine definitions will be deployed with the correct collections and permissions.

Create one or more state machines using the supported syntax. Your state machine definitions should be saved using a .asl.json extension. Your state machines's states can be composed using the built-in action modules, and/or custom action and condition modules. See the state-conductor-examples project for examples.

Create Action Modules

States with a type of "Task" utilize action modules to process data. Action modules are server-side-javascript which implement a specific function signature. Custom action modules should be saved along with other code under a sub-directory of the project's ml-modules directory. By convention it is recommended to use the following folder structure: ml-modules/root/ext/state-conductor/${state-machine-name}/actions.

The State Conductor mlBundle ships with several included action modules.

Create Condition Modules

States with a type of "Choice" utilize one or more condition modules to analyze data. Custom condition modules are server-side-javascript which implement a specific function signature. Custom condition modules should be saved along with other code under a sub-directory of the project's ml-modules directory. By convention it is recommended to use the following folder structure: ml-modules/root/ext/state-conductor/${state-machine-name}/conditions.

Deploy

The State Conductor is deployed using standard ml-gradle commands. Custom code is deployed alongside project code, and state machine definitions are deployed with project data.

To deploy everything:

./gradlew mlDeploy

To just deploy custom modules:

./gradlew mlLoadModules

To just deploy state machine definitions:

./gradlew mlLoadData

Start the Driver

The State Conductor uses a "driver" application to coordinate the flow of data through the installed state machines. We recommend utilizing the Data Services Driver for ease of use.

Download the driver's jar file from the release page, and save it to a local directory. Create a configuration file in that directory named application.properties with the following properties:

mlHost=localhost
mlPort=8888
username=admin
password=######

Adjust for your environment as needed. The hostname and port should be that of your MarkLogic application's primary app-server.

Start the driver:

java -jar state-conductor-dataservices-1.0.0.jar --config application.properties

Add Data

The final step is to add data to test your state machines. The data can be inserted into MarkLogic via any means (QConsole, Rest, Client API, etc). Be sure the data matches the "context" of one or more of the installed state machines. Now your up and running with the State Conductor!

Next Steps

Review the State Conductor Wiki