An exciting new feature of version 3 of opscotch is the capability of listening for and responding to HTTP requests using workflows - essentially turning opscotch into an application server. As security is always a top priority, HTTP serving is strictly controlled in several ways.

How does this work?

Firstly, workflows cannot simply respond to any arbitrary HTTP request - workflows can ONLY listen for HTTP requests on HTTP listeners specified in the bootstrap using the allowHttpServerAccess property. Since the bootstrap cannot be changed remotely, the HTTP listeners available to opscotch workflows are limited to those defined by the administrator who installs opscotch.

HTTP listeners in the allowHttpServerAccess property must include at a minimum: an id and a port. When opscotch starts, it will attempt to listen on the specified port. Requests to opscotch on that port at this point will return a 404.

Bootstrap:

{
    ...
    "allowHttpServerAccess" : [
        {
            "id" : "myHttpServer",
            "port" : 12345
        }
    ],
    ...
}

How to respond to a request

On the step that you want to attach to the HTTP listener, add an http trigger and a resultsProcessor. The trigger requires at a minimum: the bootstrap server to bind to and the path regex to listen for.

Workflow:

{
    ...
    "workflows" : [
        {
            ...
            "steps" : [
                {
                    ...
                    "trigger" : {
                        "http" : {
                            "server" : "myHttpServer",
                            "path" : "/api/.*"
                        }
                    },
                    "resultsProcessor" : {
                        "processors" : [
                            {
                                "script" : "console.log(context.getMessageBodyAsString());"
                            },
                            {
                                "script" : "context.setMessage('I am here for you');"
                            }
                        ]
                    }
                    ...
                }
            ]
            ...
        }
    ]
    ...
}

In this example, when the workflow is loaded, the step binds to the myHttpServer server and requests to receive requests that match the path regex (additionally, you can specify the HTTP method to listen for on the trigger). The resultsProcessor is the most suitable processor to handle requests, and in this example, the body passed to the step is a JSON representation of the request, like so:

{
    "uri" : "",
    "method" : "",
    "path" : "",
    "query" : "",
    "body" : ""
}

The context.setMessage(...) function will set the response for the HTTP request.

With this example, when HTTP requests are made to port 12345 with the URI path starting with "/api/", opscotch will reply with I am here for you.

An important note: the HTTP listener is available to any step in the workflow, and multiple steps can bind to the same listener. You will need to be careful that there is some difference in the binding criteria; otherwise, the last bound HTTP trigger will receive the request. Additionally, if two regex patterns match the same request, the longest regex wins the request. For example, if one step listens for /api/.* and another step listens for /api/records/.*, both match the path, but the longest one will win the request, i.e., /api/records/.*.

Furthermore, to change the response status code in the workflow, set a status_code property on the context, i.e.:

context.setProperty("status_code", "400");