Using Agent API to execute reports on a Neuron

Reports on the Neuron® exist in its Harmonized IoT Architecture, under a separate Data Source with ID Reports. An XMPP user with sufficient privileges can access these reports and execute them. A web client can use the Agent API, and its extension Agent Things API to do the same. This article outlines the steps to take to execute a report, using the Agent API:

1. The web client can use an Agent Account on any Neuron, provided the Neuron can connect to the Neuron hosting the report to be executed.

2. Login calling the Agent API AgentAPI.Account.Login() method. The web client will receive a token that it can use in subsequent requests. If you use the Javascript implementation provided, this is done automatically.

3. You can check the account has sufficient privileges by calling the AgentAPI.Things.Concentrator.GetAllDataSources() method after logging in. You need to specify the JID of the Neuron (as a client to its Parent Neuron). If access is granted, the Reports data source should be listed in the response. If not, check the following:

   • The Agent account must have presence subcription approved to Neuron JID that you provide. If such a presence subscription does not exist, a presence subscription request will be sent automatically, and a Forbidden error Account lacks an approved presence subscription. will be returned.

     To check presence subscriptions on the Neuron, go to the Roster page from the Administrative menu, and accept the request shown there.

     Example:

     

   • If the Agent account is on the same Neuron, the XMPP account must have sufficient privileges. To be able to view and administer the Reports data source, and any reports they contain, the user must have the Source.Reports.* privilege (or as a privilege regular expression: +Source\.Reports\..*). (Refine this privilege if a subset is required.).

   • If the Agent account is on another Neuron, a user account with the user name equal to the Bare JID of the Agent account needs to be created. This user account needs to be assigned a Role having the required privileges mentioned above.

4. You can call the AgentAPI.Things.Concentrator.GetRootNodes() and AgentAPI.Things.Concentrator.GetChildNodes() to browse available report folders and the reports they contain. You need to use the same JID argument as above, and set the Source ID argument to Reports. If you want to retrieve reports from a report folder, for instance, you need to call the AgentAPI.Things.Concentrator.GetChildNodes() resource, and also provide the ID of the reports folder node. If you want to get information about a particular node (or test if you have the correct Node ID), you can call the AgentAPI.Things.Concentrator.GetNode() resource.

5. By calling the AgentAPI.Things.Concentrator.GetNodeCommands() you receive a list of commands the account has access to. There are three types of commands: Simple, Parametrized and Query. Simple commands are just executed; they do not need parameters, and they do not return any information apart from if the execution succeeded or failed. A Parametrized command, requires the user to provide parameter values before it can be executed. Like Simple commands, they provide no detailed responses apart from executing successfully or not. A Query takes parameters for input, but also return a response (which may be long) asynchronously, as the query is being executed.

6. If you are going to execute a Parametrized command or query, you need to provide parameters. If you do not know what parameters are expected from the command, you can get a parameter form by calling the AgentAPI.Things.Concentrator.GetCommandParameters() method.

7. Depending on type of command, you then call the AgentAPI.Things.Concentrator.ExecuteSimpleCommand() method, if it is a Simple command, the AgentAPI.Things.Concentrator.ExecuteParametrizedCommand() method, if it is a Parametrized command, or the AgentAPI.Things.Concentrator.ExecuteQuery() method, if it is a Query.

Agent Reports API

The Agent API has an extension simplifying the execution of reports: The Agent Reports API. With some knowledge of where and how reports are accessed, it reduces access to reports to the following steps (some are the same as above, some are simplifications):

1. The web client can use an Agent Account on any Neuron, provided the Neuron can connect to the Neuron hosting the report to be executed.

2. Login calling the Agent API AgentAPI.Account.Login() method. The web client will receive a token that it can use in subsequent requests. If you use the Javascript implementation provided, this is done automatically.

3. To get a list of reports you have access to, call AgentAPI.Reports.GetReports(). It will return an array of the report identifiers you can view.

4. Get parameters for the report by calling AgentAPI.Reports.GetReportParameters(). You can edit or reduce this set of parameters (or provide your own parameter object if you know the parameters you need for the next step), for the next step.

5. You execute a report by calling AgentAPI.Reports.ExecuteReport() method. It collects all asynchronous responses, and returns a consolidated report result.

#agent, #agentapi, #api, #reports, #new, #features, #neuron