Pony ID

This guide will walk you through using the User Tasks Bridge in a complete local development setup.

You will do the following:

• Spin up a local LittleHorse + User Tasks Bridge environment using Docker
• Define a UserTaskDef for approving an IT rental
• Register supporting TaskDefs for handling the workflow
• Create a WfSpec that includes a human approval step
• Use the User Tasks Bridge Console to view and complete assigned tasks

Setup

Our quickstart uses Java. However, you can use the User Tasks Bridge in any of the four supported languages (Java, Go, Python, C#).

tip

For examples of how to use User Tasks with other languages, check out the User Tasks Concepts page of the LittleHorse Kernel documentation.

Your system needs:

• Java 11 or greater
• Docker configured with at least 4GB of RAM
• Homebrew

Start the Docker Image

For development purposes, we ship a docker image ghcr.io/littlehorse-enterprises/lh-user-tasks-bridge-backend/lh-user-tasks-bridge-standalone that has a complete Pony ID installation. Let's start the image:

docker run --pull always --name lh-user-tasks-bridge-standalone --rm -d \
  -p 8080:8080 \
  -p 8888:8888 \
  -p 8089:8089 \
  -p 3000:3000 \
  -p 2023:2023 \
  -p 9092:9092 \
  ghcr.io/littlehorse-enterprises/lh-user-tasks-bridge-backend/lh-user-tasks-bridge-standalone:latest

The standalone Pony ID image contains a complete Pony ID installation and all of its dependencies for local development, all running on localhost:

Component	Port	Protocol
LittleHorse Server	2024	GRPC
LittleHorse Dashboard	8080	http / web
Keycloak Admin Console	8888	http / web
User Tasks Bridge	8889	http / rest
Pony ID Console	3000	http / web
Apache Kafka	9092	Apache Kafka Protocol

Users and Credentials

For convenience, the docker image has a setup script which configures the Keycloak, which is what we use as an implementation of an OIDC-compatible identity provider. The script creates a master realm and configures three users in Keycloak:

User	Pass	Realm	Email Address
my-user	1234	default	someemailaddress@somedomain.com
my-admin-user	1234	default	someotheremailaddress@somedomain.com
admin	admin	master	N/A

The docker image takes about a minute to start up (it has quite a few things inside it!), but once it's ready, go ahead and log into the Pony ID Console:

1. Open http://localhost:3000 in your browser.
2. Click Sign In and use the credentials for my-admin-user.

Other Dependencies

You'll need our lhctl command line client:

brew install littlehorse-enterprises/lh/lhctl

Next, you'll also need to clone our lh-examples repository on GitHub:

git clone https://github.com/littlehorse-enterprises/lh-examples

# Move into the Pony ID Quickstart directory
cd lh-examples/quickstart/pony-id

Running the Quickstart

The quickstart workflow we will use today models a classic "IT Request Approval" flow.

Register the WfSpec

To register the WfSpec, all you have to do is run the application:

./gradlew run

This will register the WfSpec, UserTaskDef, and TaskDefs, and it will also start the Task Workers that will be used in the workflow. You can check out the workflow in the LittleHorse Dashboard:

IT Request WfSpec

info

If you're curious about this step works, read the code!

• ITOrderWorkflow.java defines the WfSpec logic.
• OrderTasks.java include two dummy task workers.
• Main.java, which registers all of the metadata and starts the Task Workers.

Run the WfRun

Let's run the workflow! Obi-Wan wants a new lightsaber:

lhctl run it-request item laptop employee obi-wan

In the LittleHorse Dashboard, you'll see the WfRun waiting for the UserTaskNode as follows:

IT Request WfRun Waiting for User Task

Execute the UserTaskRun

Go back over to the Pony ID Console and log in as my-admin-user. You'll see the UserTaskDef:

The UTB Console

When you click on the UserTaskDef, you can see the UserTaskRun from our workflow that we just ran. Note that it is assigned to my-user with the email address someemailaddress@somedomain.com.

The UserTaskDef Overview Page

Since you're logged in as an Admin User, you can complete UserTaskRuns that are assigned to other users. Go ahead and click on Complete, fill out the information, and then head over to the LittleHorse Dashboard to check out your WfRun. It should be completed!

Next Steps

If you've made it this far, join us on Slack and give us a star on GitHub!

To explore further, here are some ideas in order of increasing difficulty:

Create More Users

If you log in to the Pony ID console as my-admin-user, you can create additional users and specify their credentials. Try doing that, and then:

• Using the same WfSpec, try assigning the UserTaskRun from the Pony ID console (while logged in as my-admin-user) to your new users.
  • Then, in an incognito window, log in as the new user and execute the UserTaskRun.
• Try editing the WfSpec in ITOrderWorkflow.java to assign it to different users!

Create Groups

The my-admin-user can create Groups in the Pony ID console. Next, add some users (or just my-user) to one of the groups you create.

Finally, edit the WfSpec to assign the UserTaskRun to a group instead of a user.

Here's a hint:

UserTaskOutput result = wf.assignUserTask("approve-it-rental", "my-user", "my-group");
wf.releaseToGroupOnDeadline(result, 60); // 60-seconds

If you're really feeling adventurous, try creating a reminder task!

Build Your Own Frontend

Pony ID exposes a backend (the User Tasks Bridge) that has a well-documented API. We ship a JavaScript API Client for the User Tasks Bridge which can be embedded into your own frontend applications, allowing your users to execute User Tasks without logging into a different screen.

Try it out!