Stardust/Knowledge Base/API/A first Look at the Stardust API
This article gives you a first taste of Stardust API. In this context, the Stardust API is also referred to as Stardust services. The aim of this article is to explain the process of gaining an access to Stardust services and give an overview of available services. We assume that you have already installed the Stardust modeler and have Stardust runtime environment setup with a simple process model deployed in it. If you haven't done this, please follow the tutorials in the Stardust online documentation.
Once you have Stardust up and running with some process model or models deployed in it, you can start interacting with it via its exposed API. Normally, you will access the Stardust services (API) via various different ways like as local Spring services, Spring remoting, or over WS API depending on your deployment setup.
Establishing Connection with Runtime Environment
You will use the appropriate service factory to authenticate and establish connection with Stardust runtime environment. We will see in detail how we use different service factories in a separate article. Assuming you authenticate and establish connection with Stardust runtime, you can get a reference to Stardust services via this initialized service factory.
You can initialize the service factory as simple as this:
ServiceFactory sf = ServiceFactoryLocator.get(user, pwd, properties);
The ServiceFactory caches the authenticated Stardust services for the user. For use in a production environment it is important that the clients cache the ServiceFactory per user. Not caching the ServiceFactory means that a new login will be performed for every interaction with the engine.
Once you have initialized service factory, you can get access to the services offered by Stardust. The reminder of this section gives overview of core services and some of their operations.
The Workflow Service provides all functionality for workflow operations in an Stardust runtime environment.
- starting and aborting process instances,
- activating, completing, suspending and aborting activities,
- binding and unbinding event handlers,
- delegating activities, and
- accessing workflow data.
For example, you can get the workflow service from service factory and execute the startProcess() like this;
WorkflowService wfs = sf.getWorkflowService(); workflowService.startProcess("LeaveApplicationProcess", inputData, true);
Where, the parameters are
param1: process ID of the process which you want to start,
param2: input data required to the process in the form of java.util.Map<String, ?>, and
param3: flag to indicate if process should execute synchronously or asynchronously
This service provides administration services for the Stardust runtime environment. An administration service always operates against an audit trail database. The administration service requires that the user performing tasks (in this case, the user used to initialize the service factory) has been assigned to the predefined role Administrator.
The functionality of this service includes the following tasks:
- manage the workflow models (deploy, modify or delete)
- recover the runtime environment or single workflow objects
- terminate running process instances
- manage the life cycle of daemons
The User Service provides functionality for operating on Stardust runtime users.
The operations include:
- creating, modifying and invalidating users, and
- accessing user data.
The Query Service provides services querying the Stardust runtime environment. A Query service always operates against an audit trail database.
The functionality includes the following tasks:
- retrieve or counts elements in the audit trail (users, process instance, activity instances or log events)
- retrieve deployed models from the audit trails
- retrieve participants from the models