Agents and Services

iModel agents and services are apps that have no interactive user interface. They are generally deployed on servers, often in the cloud using containers (e.g. Docker) and managed using a cloud orchestration framework (e.g. Kubernetes.) Agents and services are always hosted by NodeJs.

Agents and services are backend code. Their main concern is to access and process the content of iModels. They use briefcases to access iModels.

Agents and services are written in TypeScript/JavaScript and depend on the @bentley/imodeljs-backend package. They may also depend on common packages such as imodeljs-common, bentleyjs-core, or geometry-core. They frequently also use third-party JavaScript packages, as well as the services built into nodejs.

Agents and Services use logging to enable users to monitor their operations and to help with diagnosing problems.

iModel Agents

An iModel Agent is a program that performs an unattended action upon being invoked by an event from iModelHub.

As an example, consider an iModel.js Agent that receives notifications from iModelHub for every ChangeSet to a specific iModel. The Agent could inspect every changeset using the ChangeSummaryManager API to ensure all changes to its iModel are in compliance with company standards. A separate instance of the Agent would be deployed for each iModel of interest.

iModel Services

An iModel Service is a program that responds to requests from other apps. A service runs on a server and waits for requests. A service may receive requests from Web Apps (frontend or backend) or from other services.

A true service is a stand-alone program that is never bundled with the clients that use it. An app-specific backend is a special kind of service that is logically part of an app and is often bundled with it. This distinction is important for portability reasons.

An example of a service is a program that serves out spatial tiles that it extracts from a specified area of an iModel upon request.

An iModel service or app backend exposes an interface that clients can use to make requests. An iModel service interface is an RpcInterface. A service always configures its interfaces using a Web RPC configuration. Client code must be written in TypeScript and must use an RpcInterface to access the operations in an iModel service.

Interactive Apps

An interactive app obtains information from an iModel and presents that information in a user interface. It has a frontend and a backend, which communication through RpcInterfaces. An iModel.js-based interactive app can be configured to run as a Web app, a desktop app, or a mobile app.

Configurations

Web Apps

When configured as a Web app, the frontend will run in a Web browser and the backend will run on a server. The frontend's assets (HTML pages and js files) will be served out by a server (generally different from the backend). The frontend and backend will use a Web configuration for all RpcInterfaces. See the diagram of a Web app for an overview. Also see app tailoring.

Architecture

App Backend

An app can use a pre-existing or general-purpose service as its backend. For example, a family of viewing apps can use a general-purpose service that handles requests for data from a given iModel.

An app may require data-access operations that are specific to and intrinsically part of the app. One reason is performance. An analysis that must make many related queries on iModel content, perhaps based on knowledge of a domain schema, to produce a single, combined result should be done close to the data. Another reason for app-specific backends is the backends-for-frontends pattern. App-specific backends are easy to write using RpcInterfaces and are encouraged.

App-specific backends are written in TypeScript/JavaScript and depend on @bentley/imodeljs-backend. A backend may also depend on common packages such as imodeljs-common, bentleyjs-core, or geometry-core. See backend portability.

App Frontend

The UI-specific part of an app is called the frontend. The frontend should be concerned only with display and user interaction.

The frontend must be written in TypeScript or JavaScript. The frontend should use Web technologies only, including HTML, CSS, and JavaScript. The frontend can use any Web app framework, such as React or Angular.

The frontend makes requests on backend services to access iModel content. The frontend uses RpcInterfaces to communicate with the app's backend(s) and other services. The frontend should depend on @bentley/imodeljs-frontend. The frontend may also depend on common packages such as imodeljs-common, bentleyjs-core, or geometry-core. It may also depend on Web-specific packages. Both the UI and functionality of the app frontend can be tailored to best fit each desired configuration and target platform.