Categories: DEVELOPER GUIDE API ENTERPRISE

step client API

Introduction

The step client exposes means to connect to the controller programmatically, access and use step services in a headless way. It also allows to execute locally step controller functionalities like building and running a plan.

Resources: The Javadocs of the step client is available here: step.client.StepClient and examples can be found on github.

The most common cases for a “headless” user is to integrate the automation activities covered with step to a build pipeline for instance and be able to cover 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 API and more.

Services description

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 below is a description of the services provided by the API:

By instantiating a StepClient, you will have access to most step functionalities through diverse accessors as described below:

Functionality Description Ref example
Create a step Client Create a client connecting to a physical controller or able to execute (limited) functions locally see the method controllerClientDemo in StepClientDemo
ControllerServicesClient Manage remotely a controller (i.e. shutdown gracefully) see remoteControllerManagementDemo in demo
RemoteEventBrokerClient The event API is detailed here
RemoteExecutionManager Access and manage step controller executions example runAnExistingPlan in demo
FunctionExecutionService Execute a given Keyword see functionManagerDemo in demo
FunctionManager Interact with step Keywords (ex: create a new keyword) see uploadDemoKeyword in Demo
PlanBuilders Offer two means of creating plans either programmatically or by parsing a plan defined in plain text see remotePlanRunnerDemo in demo
PlanRepository Access and manage the controller plan’s repository (ex: save a new plan) see controllerClientDemo in demo
PlanRunners Execute step plans and get its results see remotePlanRunnerDemo in demo and below sample for local runs of plan
RemoteAccessors Give access to step elements through following 3 accessors:
  • RemoteFunctionAccessor: to retrieve and operates keywords
  • RemotePlanAccessor: allows to browse the plans
  • RemoteExecutionAccessor: get access to executions (active ones, by id, name…
  • RemoteParameterAccessor: get access to parameters
 Javadoc of RemoteAccessors
RemoteResourceManager Manage step resources (ex: upload a new jar file) see uploadDemoKeyword in Demo
StagingRepositoryClient Execution on a controller in an isolated context see isolatedExecutionDemo in demo

Examples

As mentioned earlier, you will find most details directly in the javadoc and in provided demo on github.

Below are additional examples that you might not found on github yet.

Local plan runner

The example provided on github illustrates how to runs plan on a remote controller, below is an example for a local execution:

LocalPlanRunner runner = new LocalPlanRunner(LocalRunnerTestLibrary.class);
Map<String, String> properties = new HashMap<>();
properties.put("prop1", "MyProp1");

Echo echo = new Echo();
echo.setText(new DynamicValue<>("prop1", ""));
Plan plan = PlanBuilder.create().startBlock(new Sequence()).add(echo).endBlock().build();

runner = new LocalPlanRunner(properties, LocalRunnerTestLibrary.class);
runner.run(plan).visitReportNodes(node->{
  if(node instanceof EchoReportNode) {
    Assert.assertEquals("MyProp1",((EchoReportNode) node).getEcho());
  }
});

Search executions

Search executions with different type of criteria.

		//Search executions active within the given interval
		List<Execution> executions = new ArrayList<>();
		HashMap<String, String> criteria = new HashMap<>();
		criteria.put("attributes.name", "myNameCriteria");
		//search order 1 is ascending and -1 descending
		boolean searchEndedTestOnly = true;// to search only executions ended within that interval
		executionAccessor.findInInterval(criteria,new Date(startTimeInterval),new Date(endTimeInterval),searchEndedTestOnly,new SearchOrder("startTime",1))
				.forEach(e -> executions.add(e));

		//Search executions running within the given interval (i.e starting and ending in that interval)
		executions.clear();
		executionAccessor.findByCritera(criteria, new Date(startTimeInterval), new Date(endTimeInterval),new SearchOrder("endTime", 1))
				.forEach(e -> executions.add(e));

See Also