How to build a Service

With ManyWho, you can integrate your flows with cloud application platforms such as Salesforce, Box, or Twilio. You may also have various databases or other third-party applications, you’d like your apps to work with. We call these integrations: Services.


Creating a project

There is a Maven archetype available that will create a basic Service, along with some example actions, types and controller endpoints. Follow these instructions to install it inside IntelliJ:

  1. Create a new project of type Maven, ticking the Create from archetype box, then clicking the Add archetype button and supplying the following details.
    • GroupId:
    • ArtifactId: example-archetype
    • Version: 1.5.0
  2. On the next screen, give your Service a relevant group ID and artifact ID that follows the standard Java convention, e.g. (replacing your TLD, company name and the name of your Service).
  3. IntelliJ will now be running the Maven goal to create the project from the archetype. When it finishes, click Enable auto-import on the popup at the top right, and you should be good to go!

Adding the Grizzly configuration

Using the Grizzly server to run the service locally is the best option, as it’s pretty easy to debug inside IntelliJ. It’s fairly easy to set up, following these instructions:

  1. On the Run menu, choose Edit Configurations.
  2. Click the button at the top left, choose Application, and give it the name Run.
  3. Under Configuration > Main class, point to your Service’s Application class.
  4. Click OK, and your service should now run under Grizzly when you launch it by clicking the Debug button.

Creating a Describe

Every Service is required to implement a describe functionality. The /metadata endpoint of a Service informs ManyWho about the capabilities of the Service along with anything the Service provides (e.g. Types), the describe response can implement several properties:

Name Description
ProvidesDatabase Set to true if the Service supports loading and saving via requests sent from Load and Save elements in a flow.
ProvidesIdentity Set to true if the Service can be used as an identity provider for a flow i.e. allows a user to login using a third-party service like Google or Facebook.
ProvidesLogic Set to true if the Service supports actions that can be executed via Message elements in a flow, listening to items, providing notifications to a flow, or voting.


The Service describe response also has an Install property that allows you to provide custom Types back to ManyWho that are specific to your Service e.g. the JIRA Service provides an Issue Type that has various properties such as Name, Type, Assignee, etc.

By default any classes in your Service that extend AbstractType (from the Java SDK) will be automatically included in the describe response. You can manually add Types to the describe response install in case you need to provide dynamically generated Types as install time.

An example of building a describe response can be found here: How to Build a Service.

Creating an action

An action is a method that interacts with a Service that performs a task, like “Send an Email” or “Assign a Task to this user”.

Actions created using the Java SDK all extend the AbstractAction class and are automatically included in the Describe response when the Service installed in ManyWho. They can be added into a Service by creating a class like this:

Required fields

Field Description Example
URI Part Tells ManyWho the URI endpoint for the message action “tasks/assign”
Developer Name This is the name of the action that will be displayed in the Draw tool Assign Task
Developer Summary A short summary of what the action does that will be displayed in the Drawing tool Assign a task in Salesforce to a User
Service Inputs A collection of values that the action can be given, both optional and required See code above
Service Outputs A collection of values that the action sends back to ManyWho that can be used in the Flow afterwards (can be empty) See code above

Implementing the endpoint

As building a Service using the Java SDK uses the JAX-RS standard for building REST APIs, it’s super easy to add an endpoint for an action – all you need is a method in a controller that has the correct annotations.

Say we want to add an endpoint for the example action above, we will need:

  • A controller for the action’s “category” (e.g. TasksController)
  • A method in that controller for the action (e.g. assignTask)
    • It must be annotated with [email protected],[email protected],[email protected](“application/json”) [email protected](“application/json”) annotations
    • It must take a ServiceRequest object as the first parameter
    • It must return a ServiceResponse object
  • A way of interacting with the API (Services are a nice way of keeping code SOLID)

After installing a Service that provides an Action into a ManyWho tenant the Action can be executed by adding a Message element to a flow.

Creating a Type

Types created the Java SDK all extend the AbstractType class and are automatically included in the Describe response when the service is installed in ManyWho. A basic Type be added into a Service by creating a class like this:


Field Description Required?
Developer Name This is the name of the type that will be displayed in the Drawing tool. Make sure to change the NAME field, so the type can continue to be easily reference from other types and actions
Properties A collection of TypeElementProperty objects that define the properties for a type
Bindings A collection of TypeElementBinding objects that define the bindings to use a type in a Database load/save/delete

Debugging a Service

Debugging a Service locally against the ManyWho platform running in the cloud is extremely useful, as you won’t have to deploy your Service to use it. You can do this by using ngrok, which creates a tunnel between your local machine and the internet. After setting up ngrok you can debug your Service by installing it into your ManyWho tenant using the ngrok URL.

Errors and Exceptions

The Java SDK automatically transforms any Exceptions that are thrown into the format expected by ManyWho. The message value of the exception is what will be seen by users running the flow. All other properties will be available in the UI debugger.

Deploying to Heroku

If you created a Service from the example archetype (1.4.0 upwards), then your Service has built-in support for deploying to, and running on Heroku! An example Procfile is included in the root of your service, so a simple “git push heroku master” should get you up and running.

If your Service isn’t built using the example archetype then simply adding the following Procfile should work: