The Java APIs and libraries (STEP Client) discussed in this section are currently only available in STEP Enterprise Edition

Introduction

The STEP client exposes means to connect to the controller programmatically, access and use STEP services in a headless way via the class STEPClient. The Javadocs of each individual remote client is available at: https://www.exense.ch/static/javadoc-remote-client/ and examples are available in https://github.com/exense/step-enterprise-samples.

As a "headless" user (i.e assuming you're wanting to automate interactions with STEP, which are part your build pipeline, for instance) you will probably want to perform the following tasks programmatically:

  • upload and execute keywords
  • upload and execute plans
  • download existing plans
  • access execution metadata and execution results (report nodes)

All of these workflows are supported by STEP's java client. REST interactions also work and you can decide to build your automated workflows that way, but they are not the preferred way to do this, as REST signatures are subject to changes and they are not documented. Therefore, only limited support will be provided.

Plugin Services

When interactive with STEP in a headless way, we believe it is best to learn by example, which is why we've provided examples (see link at the beginning of the section) and put emphasis on the javadocs. However, certain services, such as the Event Broker, require deeper explanations. This is due to the fact that understanding certain subtleties in the implementation can make a big difference in how you'll want to use the service.

EventBroker

The EventBroker Service and API allow asynchronous communication to happen in step as well as synchronization between keywords, between plans and between keywords and plans. It is particularly useful in scenarios where a thread (or a "user") needs to wait for specific events before performing the next task.

These events can be created internally (from within a keyword or plan) using various types of clients (Java, REST, prepop Keywords and Artefacts). The service also exposes methods for testing the presence of an event, reading it's content, consuming it, etc.

Id's vs Groups

Events can be declared and targeted either through a unique identifier or a group & name combination. This is an important choice as it will impact the way you'll be using the API and how Events are managed. Here's the underlying reason behind each of these approaches:

Id-based declaration

Setting a unique identifier in the Id field of the Event object, as you could assume, will allow for the explicit manipulation of that event instance and only that event instance. This could be seen as the standard scenario in which the consumer of the event knows exactly what event they are waiting for and how to identify it.

It is important to note that the consumer has to be aware of the exact identifier ahead of time, or it will not be able to retrieve the event. Since the identifier is unique and is set dynamically, this is a strong constraint.

Group & Name declaration

Groups are designed to gather and store distinct, yet similar events. You can see this as a relaxed constraint on the identifier as consumers will be able to consumer any event from the group and no guarantee will be provided as to which Event instance specifically will be resolved. In other words, groups allow for the management of pools of events which share a common purpose.

Consumers only need to be aware of the Group identifier, which is a static string. In addition to the Group field, providers have the option to also set a name for the Event. The name field provides consumers with the ability to uniquely identify an event after it's been retrieved based it's Group.

In a Group & Name scenario, names can also be used indirectly as a unique identifier within the group, allowing for the logical grouping of events while maintaining a strong constraint on Event query resolution. This comes however at the cost of performance. Users themselves have to be aware of the trade-off between performance and ease of management and need to run their own tests to find out what fits their needs best.

Using the Java API

The STEPClient class provides access to a RemoteEventBrokerClient class, which exposes most of the broker's primitives.

Primitives

  • Put: upload an event to the broker
  • Peek: download a copy of the event, leaving the existing event untouched in the Broker
  • Consume: download and exhaust the event

Example

Initializing the client:

RemoteEventBrokerClient client = new StepClient("http://my-step-controller:8080", "admin", "init").getEventBrokerClient();

Creating, uploading, and consuming an event by Id:

Event sentEvent = new Event().setId("a_unique_id");client.putEvent(sentEvent);
client.peekEvent("a_unique_id");
Event readEvent = client.consumeEvent("a_unique_id");
System.out.println(readEvent);

Creating, uploading, and consuming an event by Group & Name:

Event sentEvent = new Event().setGroup("myGroup").setName("myEventName");
client.putEvent(sentEvent);
client.peekEventByGroupAndName("myGroup", "myEventName");
Event readEvent = client.consumeEventByGroupAndName("myGroup", "myEventName");
System.out.println(readEvent);

Closing the client:

client.close();

Artefacts and Keywords

Various artefacts and keywords have been pre-populated in step for convenience.

WaitForEvent artefact

Assuming some event of group "myGroup" and of name "myEventName"is sent by a third party EventBrokerClient, the following plan will wait for the event to be received and then store the content of the event in the variable "result":

Screen Shot 2018-07-11 at 16.58.11.png

WaitForEvent configuration:

Screen Shot 2018-07-11 at 16.58.27.png

Set configuration:

Screen Shot 2018-07-11 at 16.58.32.png

The same applies with the Id-based approach, i.e you just need to leave the Group & Name fileds empty and only set the Id.

Put, Peek & Get keywords

LocalFunction keywords have been pre-populated in step. This means they are available upon starting the controller for the first time. LocalFunction's are a specifal type of keyword which is executed directly in the controller. However, these keywords can also be manually deployed as regular Java keywords.

Schemas are also pre-configured for convenience. This means that the input key's (and the information about which are mandatory) will be displayed upon adding these keywords into your plan's tree:

1553599431865-548.png

These keywords can either target the local controller (for example, using "http://localhost:8080" as the ebcUrl) or a remote controller.

Put, Peek and Get respectively match the Put, Peek and Consume primitives.

EventBrokerMonitor

If you've purchased the Async package or are running the Premium Enterprise version of step, you'll be able to monitor in real time what's happening in the EventBroker by navigating to the EventBrokerMonitor view:

1553599712642-168.png

The Stats tab provides global statistics on the broker, such as the current amount of messages present in it and the high mark (or water mark), oldest & youngest events, etc.

The next two tabs provide users with the ability to browse and search for events, and organizes the query results either by Id or Group.

The last tab allows for easy testing as well as configuring the broker.

24/7 persistent monitoring

Persistent monitoring (via polling) can be achieved easily using a groovy-only plan which will be published in our community samples project on Github. The broker's activity is then logged via transactions in RTM and the complete history can be analyzed retro-actively:

1553599960765-255.png

Plan examples

Tags:
Created by Jerome Brongniart on 2019/03/11 13:43
     
Copyright © exense GmbH
v1.0