Agent Management Client for Java¶

Introduction¶

The Agent Management Java client allows you to onboard, offboard, update and delete agents. It provides connectivity functions to enable communication with Insights Hub.

Further implementation of the AgentManagement SDK library has been shown in a sample project that you can download and test in local or on Insights Hub application. Please refer to this repository: industrial-iot-java-sdk-examples

See Agent Management for more information about the service.

Hint

In the IoT context, assets are referred to as entity and aspects as propertyset. The following code samples switch between these terms depending on the used APIs.
Placeholders in the following samples are indicated by angular brackets < >.

Agent Operations¶

The Agents client lists, creates, updates, reads and deletes agents.

Client name: AgentOperationsClient

Basic Agent Management¶

Create an Agent¶

// Construct the AgentOperationsClient object
AgentOperationsClient agents_client = AgentOperationsClient.builder()
                                        .mindsphereCredentials(<credentials>)
                                        .restClientConfig(<config>)
                                        .build();

AgentInput agent = null;
try {
  agent = agents_client.agentsPost(<agent_input>);
}catch (MindsphereException e) {
  // Exception handling
}

List all Agents¶

Get all agents for the given filter input.

// Construct the AgentOperationsClient object as shown above
PagedAgent agents_list = null;

try {
  agents_list = agents_client.agentsGet(<filter>, <size>, <page>, <sort>);
} catch (MindsphereException e) {
  // Exception handling
}

Get an Agent by ID¶

// Construct the AgentOperationsClient object as shown above
Agent agent = null;

try {
  agent = agents_client.agentsIdGet(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

Update an Agent¶

// Construct the AgentOperationsClient object as shown above
Agent agent = null;

try {
  agent = agents_client.agentsIdPut(<agent_id>, <agent_update>, <ifMatch>);
} catch (MindsphereException e) {
  // Exception handling
}

Delete an Agent¶

// Construct the AgentOperationsClient object as shown above
try {
  agents_client.agentsIdDelete(<agent_id>, <ifMatch>);
} catch (MindsphereException e) {
  // Exception handling
}

Get an Agent's Online Status¶

// Construct the AgentOperationsClient object as shown above
// Construct the AgentOperationsClient object as shown above
OnlineStatus online_status = null;

try {
  online_status = agents_client.agentsIdStatusGet(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

Agent Data Source Configuration Operations¶

The Data Source Configuration client gets, creates and updates the data source configuration.

Client name: DataSourceConfigurationOperationsClient

Get the Data Source Configuration¶

Get the data source configuration for an agent with the given ID.

// Construct the DataSourceConfigurationOperationsClient object
DataSourceConfigurationOperationsClient data_source_configuration_client = DataSourceConfigurationOperationsClient.builder()
                                      .mindsphereCredentials(<credentials>)
                                      .restClientConfig(<config>)
                                      .build();

DataSourceConfiguration data_source_configuration = null;
try {
  data_source_configuration = data_source_configuration_client.agentsIdDataSourceConfigurationGet(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

Create the Data Source Configuration¶

Create the data source configuration for an agent with the given ID.

// Construct the DataSourceConfigurationOperationsClient object as shown above
//Create a DataSource object
DataSource data_sources_item = new DataSource();
data_sources_item.setName(<name>);
data_sources_item.setDescription(<description>);
data_sources_item.setDataPoints(<data_points>) {
data_sources_item.customData(<custom_data>) {

//Create a DataSourceConfigurationInput object
DataSourceConfigurationInput configuration = new DataSourceConfigurationInput();
configuration.setConfigurationId(<configuration_id>);
configuration.addDataSourcesItem(data_sources_item);

DataSourceConfiguration data_source_configuration = null;

try {
  data_source_configuration = data_source_configuration_client.agentsIdDataSourceConfigurationPut(<agent_id>, configuration);
} catch (MindsphereException e) {
  // Exception handling
}

Update the Data Source Configuration¶

Update the data source configuration for an agent with the given ID.

// Construct the DataSourceConfigurationOperationsClient object as shown above
DataSourceConfiguration data_source_configuration = null;

try {
  data_source_configuration = data_source_configuration_client.agentsIdDataSourceConfigurationPut(<agent_id>, <configuration>, <ifMatch>);
} catch (MindsphereException e) {
  // Exception handling
}

Agent Boarding Operations¶

The Boarding client is used to offboard an agent and to get the boarding configuration and the boarding status.

Client name: BoardingOperationsClient

Get the Boarding Configuration¶

Get the boarding configuration of an agent with the given ID.

// Construct the BoardingOperationsClient object
BoardingOperationsClient boarding_client = BoardingOperationsClient.builder()
                                      .mindsphereCredentials(<credentials>)
                                      .restClientConfig(<config>)
                                      .build();

ModelConfiguration boarding_configuration = null;
try {
  model_configuration = boarding_client.agentsIdBoardingConfigurationGet(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

Offboard an Agent¶

Offboard an agent with the given ID.

// Construct the BoardingOperationsClient object as shown above
OnboardingStatus onboarding_status = null;

try {
  onboarding_status = boarding_client.agentsIdBoardingOffboardPost(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

Get the Boarding Status¶

Get the boarding status of an agent with the given ID.

// Construct the BoardingOperationsClient object as shown above
OnboardingStatus onboarding_status = null;

try {
  onboarding_status = boarding_client.agentsIdBoardingStatusGet(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

Agent Registration Operations¶

The Registration client can register an agent and update agent information.

Client name: RegistrationOperationsClient

Register an Agent¶

Register an agent.

// Construct the RegistrationOperationsClient object
RegistrationOperationsClient registration_client = RegistrationOperationsClient.builder()
                                      .mindsphereCredentials(<credentials>)
                                      .restClientConfig(<config>)
                                      .build();

ClientIdentifier client_identifier = null;
try {
  client_identifier = registration_client.onBoardAgent(<initial_access_token>, <keys>);
} catch (MindsphereException e) {
  /

Note

The initialAccessToken string can be obtained via boardingClient.getBoardingConfiguration(agentId).

Register an Agent with SHARED_SECRET Security Profile¶

// Construct the RegistrationClient object
ClientIdentifier client_identifier = null;
try {
  client_identifier = registration_client.onBoardAgentWithSharedSecretProfile(<initial_access_token>);
} catch (MindsphereException e) {
  /

Agent Token Operations¶

The Token client is used to get the access token and the key information of OAuth server.

Client name: TokenOperationsClient

Fetch an Access Token¶

Fetch an access token.

// Construct the TokenOperationsClient object
TokenOperationsClient access_token_client = TokenOperationsClient.builder()
                                      .mindsphereCredentials(<credentials>)
                                      .restClientConfig(<config>)
                                      .build();

AccessToken access_token = null;
try {
  access_token = access_token_client.oauthTokenPost(<grant_type>, <client_assertion_type>, <client_assertion>);
} catch (MindsphereException e) {
  // Exception handling
}

Provide Key Information of OAuth Server¶

Provide key information of OAuth server.

// Construct the TokenOperationsClient object as shown above
TokenKey token_key = null;
try {
  token_key = access_token_client.oauthTokenKeyGet(<ifNoneMatch>);
} catch (MindsphereException e) {
  // Exception handling
}