Starting flows

Use this guide to allow flows to be invoked using HTTP-RPC.

As part of the Corda 5 Developer Preview, you can start flows using the FlowStarterRPCOps interface and add annotation to expose them via the HTTP server.

Use the startFlow method

The startFlow method uses the endpoint: https://[baseUrl]/startflow and requires RpcStartFlowRequest as a body parameter. Here’s an example:

@HttpRpcResource(
        name = "FlowStarterRPCOps",
        description = "FlowStarterRPCOps",
        path = "flowstarter"
)
interface FlowStarterRPCOps :  RPCOps {
    @HttpRpcPOST
    fun startFlow(
            @HttpRpcRequestBodyParameter(
                    description = "httpRpcFlowRequest",
                    required = true
            )
            rpcStartFlowRequest: RpcStartFlowRequest): RpcStartFlowResponse
}

When implemented, the startFlow method:

  1. Looks up the specified flow.
  2. Checks if the user has permission to start the flow.
  3. Instantiates the flow via the constructor that takes an RpcStartFlowRequestParameters parameter and executes it.
  4. Returns an RpcStartFlowResponse.

Add RpcStartFlowRequest as an input to startFlow

To allow flows to be invoked using HTTP-RPC, you need to add RpcStartFlowRequest to the startFlow method with this structure:

data class RpcStartFlowRequest(
        val flowName: String,
        val clientId: String,
        val parameters: RpcStartFlowRequestParameters
)

Once the flow is discovered by its full name (package name and class name), it is instantiated with the RpcStartFlowRequestParameters parameter. The flow’s developer needs to deserialize this parameter and initialize the flow class.

data class RpcStartFlowRequestParameters(val parametersInJson: String)

Expected output from RpcStartFlowResponse

startFlow extracts and returns relevant information from FlowStateMachineHandle (once it’s available). You should see a response that contains a unique identifier for a single state machine run and the client id.

data class RpcStartFlowResponse (
        val stateMachineRunId: StateMachineRunId,
        val clientId: String?)

Manage user permissions

To start a flow via HTTP-RPC, a user needs:

  1. Permission to invoke the startFlow method InvokeRpc:net.corda.client.rpc.flow.FlowStarterRPCOps#startFlow.
  2. Permission to execute the flow(s) that the user wants to start. For example startflow.net.corda.finance.flows.ExampleFlowClass.

Here is an example of a node.conf section that allows the user demouser to execute the flow MessageStateIssue via HTTP-RPC:

security {
   authService {
       dataSource {
           type=INMEMORY
           users=[
                 {
                     password=test
                     permissions=["InvokeRpc:net.corda.client.rpc.flow.FlowStarterRPCOps#startFlow",
"startflow.net.corda.httprpcdemo.workflows.MessageStateIssue"
                     ]
                     user=demouser
                 }
           ]
       }
   }
}

startFlow example in the HTTP-RPC demo

The README.md file of the HTTP-RPC demo sample contains instructions on how to build and run the HTTP-RPC demo. Once it is up and running, you can execute MessageStateIssue via HTTP-RPC by passing in this body parameter to the startflow endpoint:

{
  "rpcStartFlowRequest": {
    "clientId": "id",
    "flowName": "net.corda.httprpcdemo.workflows.MessageStateIssue",
    "parameters": {
      "parametersInJson": "{\"message\":\"hello\"}"
    }
  }
}

Was this page helpful?

Thanks for your feedback!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

We're sorry this page wasn't helpful. Let us know how we can make it better!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Create an issue

Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.