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

Refactored KyC process: Service Collaboration

From build 2025-04-12, the KyC process to authenticate Identity Applications has been refactored to allow multiple Identity Authenticator services to collaborate to approve or reject an application. Apart from updates to the Neuron® itself, it also affects Identity Authenticator service packages, library nugets, and the Agent API, the focus of this article.

There are mainly two resources that have been updated:

• The ReadyForApproval resource, now requires use of cryptographic key and signature to be called. The reason for this is that the call, which triggers the automated KyC process, can generate an attachment being added to the identity application, documenting which services have validated which parameters. For this to be permitted, the caller must provice the cryptographic key to use, for signing the attachment. The new call takes more arguments than the previous version, so any software making use of this resource must be updated as well.

• While refactoring the ReadyForApproval resource, the AddIdAttachment resource was updated to include the LegalId argument in the request signature. The call does not take any more arguments, so software using the JavaScript implementation do not need to be updated, as the request signature is calculated by the JavaScript library. But if software implements a custom HTTP REST interface, such software must be updated to reflect this new request signature calculation.

Other important changes related to KyC has also been performed. Now, the Neuron® and associated KyC-services support IDs that are defined using FULLNAME instead of FIRST, MIDDLE and LAST name property fields. If a FULLNAME is provided, and a contract references FIRST, MIDDLE and LAST, they will be extracted using the expected canonical approach. Likewise, if an ID is created using FIRST, MIDDLE and LAST, and a contract references FULLNAME, it will be constructed by joining FIRST, MIDDLE and LAST with a single space character as delimiter.

#new, #features, #api, #agentapi, #kyc

Using a proxy server with Agent API & Quick Login API

From build 2025-02-05, a new mode is available for integrating Quick Login API and Agent API when using a proxy to access the Neuron®. The web page may reside on an external server, and it wants to integrate with both Quick Login API and Agent API on a Neuron® different from the web server. In this case, the web-client only or backend modes are not sufficient, as they cannot integrate the two APIs seamlessly. Session mode is not available either, since the HTTP session held by the client, is between the client and the web server, not the Neuron®.

A new mode is now availble: A Session-proxy mode. allows the client to create a Session ID implicitly, by adding a agentApiTimeout property in the initial request made to the Neuron® from the proxy. The Neuron® will implicitly call the QuickLoginServiceId(Request,Timeout) function, and return the Service ID in the response to the proxy.

Note: The proxy needs to enable cookies in its communication with the Neuron®, to maintain the session correctly. The proxy will need to call the Agent API over the same session, to be able to access the Quick Login done in this mode.

For more information, see the Quick Login API reference documentation.

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

Agent API Javascript NPM package

Currently, there is no package on the public npm package registry, but you can still add the package as a dependency in your package.json. You just add

“agent-api”: “https/github.com/Trust-Anchor-Group/AgentApiJavascript.gitnpm-package”

to your dependencies. Though, note that this might require that you have the newest version of the AgentApi on your neuron (which may require the newest neuron version). This is because the repo is designed for the latest version, which means that it might be different since the AgentApi is ever evolving. And at last, there currently is only one version, which if it is updated, and you later install your dependencies, the package might have changed. So if you for some reason do not plan to update the neuron or your code, it might be better to copy the code in the package. For those curious, there is currently not a package for the typescript version.

In The Code

if you use ES6 import syntax just use : `js import AgentAPI from "agent-api" AgentApi.Legal.CreateContract()

or if you use CommonJs: `js const AgentAPI = require("agent-api") AgentApi.Legal.CreateContract()

The Github Repository

As you may see, the package is located in the npm-package branch on the AgentApiJavascript repository on Github. If you notice that the main branch have got some important commits that the npm-package does not, please consider rebasing the npm-package branch to the main branch. If you are not sure how to rebase, consider learning more about it, absolutely use something like Sourcetree to check that you did it right, and if you are worried, make a backup of the repo.

#javascript, #npm, #package, #agentapi

Agent API C# implementation

A C# implementation of the Agent API is now publicly available both on Github and as a NuGet Package

The implementation provides generated models and simplifies the process of making requests to the Agent API for .NET applications

Instructions and documentation can be found on the Github page. Also feel free to open any issues on the Github page

#c#, #.net, #agent, #api, #agentapi