Corda 5 Developer Preview 2 is now available.

Running Your First CorDapp

The CSDE includes flows and tests for a very simple CorDapp, which you can run out of the box.

The code for the flow can be found in the src/main/kotlin.com.r3.developers.csdetemplate.MyFirstFlow.kt file. This is also the code described in the first flow section.

Starting the Corda Combined Worker

To run the flow, you must first start a local combined worker version of Corda. CSDE includes helper Gradle tasks to do this.

CSDE task to start the combined worker in IntelliJ
CSDE startCorda task

The startCorda task should complete relatively quickly with this message:

CSDE task to start the combined worker in IntelliJ completed
CSDE startCorda task completed

However, you must wait approximately one minute for Corda to finish its start-up routine. Currently, we do not have a liveness detector for Corda in the CSDE so we check liveness by manually hitting an endpoint.

Testing Liveness and Swagger

Corda exposes HTTP REST API endpoints for interacting with itself and the CorDapps running on it. It also exposes a Swagger interface which is described in the following sections.

Displaying the Swagger UI

To display the Swagger UI, use the following link:

https://localhost:8888/api/v1/swagger#/

If Corda has started, the Swagger UI displays:

Swagger UI showing Corda
Swagger UI showing Corda liveness

If Corda has not started yet, the page will not load. If the Swagger UI is already open whilst starting Corda, you must hit an endpoint to test liveness of Corda.

Authorizing Swagger

To access the Corda cluster, you must authorize Swagger:

  1. Click the green Authorize button.
    Button in Swagger UI to authorize access to the Corda cluster
    Swagger Authorize button
    The Available authorizations window is displayed.
  2. If necessary, click Logout.
  3. Enter the username and password. For the purposes of experimental development, the username for the combined worker is set to admin and the password is admin.
    Authorize authorizations window in Swagger UI to authorize access to the Corda cluster
    Swagger Authorize authorizations window
  4. Click Authorise and then Close.

Hitting Endpoints

Once authorised, you can start hitting endpoints. The easiest one to try is /cpi because it is the first one on the Swagger page and requires no arguments:

  1. Expand the GET /cpi row and click Try it out.
    Expanded GET /cpi with Try it out button
    Try it out button for GET /cpi
  2. Click the Execute button to hit the endpoint. If Corda has started you should see a response like this:
    Swagger showing a successful response to GET /cpi
    Swagger showing a successful response to GET /cpi
    As we have not uploaded any CPIs yet, the returned list of CPIs is empty. If Corda has not started yet, Swagger will return an error:
    Swagger showing an error response to GET /cpi
    Swagger showing an error response to GET /cpi
    If this occurs, you either have not started Corda, Corda has not finished starting, or something has gone wrong. If something has gone wrong, you should try again or reset the environment and start again.

Deploying a CorDapp

You can use the MyFirstFlow flow to build a CorDapp, without any further work:

  1. Click the deployCorda Gradle task:
    CSDE task to deploy a CorDapp in IntelliJ
    CSDE deployCorda task
    This task runs a series of Gradle tasks to:
    • Build the CPB
    • Create the GroupPolicy (Application Network definition)
    • Generate signing keys to sign the CPB and CPI
    • Build the CPI (combination of CPB and Group Policy)
    • Sign the CPI
    • Upload the CPI to Corda
    • Create and register the virtual nodes with the CPI You should now be able to start MyFirstFlow from the Swagger UI.

Starting Your First Flow

To run your first flow:

  1. Find the holdingidentityshorthash for the virtual node you want to trigger the flow on. You can do this by running the listVnodes Gradle task to display a list of the configured virtual nodes:

    Running the listVnodes gradle task
    The 12 digit hash is the holdingidentityshorthash that acts as the unique identifier for a virtual node.

  2. Expand the POST /flow/{holdingidentityshorthash} endpoint in the Flow Management API section in Swagger and click Try it out.

    Expanded POST /flow/{holdingidentityshorthash} with Try it out button
    Try it out button for POST /flow/{holdingidentityshorthash}

  3. Enter the hash and the requestBody and click Execute.

    Arguments for POST /flow/{holdingidentityshorthash}

requestBody code:

{
   "clientRequestId": "r1",
   "flowClassName": "com.r3.developers.csdetemplate.MyFirstFlow",
   "requestData": {
      "otherMember":"CN=Bob, OU=Test Dept, O=R3, L=London, C=GB"
   }
}
  • ClientRequestId is a unique identifier for the request to start a flow.

  • flowClassName is the fully qualified path to the flow class you want to run.

  • requestData is the set of arguments you pass to the flow.

    Swagger should display the following response:

    Successful response for POST /flow/{holdingidentityshorthash}

Note, if you forget to change the ClientRequestId on subsequent attempts to run the flow, the following error message is displayed:

Error response for POST /flow/{holdingidentityshorthash

Because the API is asynchronous, at this stage you only receive the confirmation START_REQESTED. There is no indication if the flow has been successful. To find out the status of the flow, you must check the flow status.

Checking the Flow Status

To check the flow status:

  1. Expand the GET /flow/{holdingidentityshorthash}/{clientrequestid} endpoint in Swagger and click Try it out.
  2. Enter the hash and the requestid used when starting the flow and click Execute.
    Arguments for GET /flow/{holdingidentityshorthash}/{clientrequestid}

    If the flow is successful, you will see the following response:
    Successful response for GET /flow/{holdingidentityshorthash}/{clientrequestid}
    You will learn more about the flowResult of “Hello Alice best wishes from Bob” in Your first flow.

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.