SmartObject terminology and architecture

Microsoft Azure Active Directory is now Microsoft Entra ID

SmartObjects are reusable objects that provide a standard way to integrate with number of third-party systems and technologies, including querying and updating data stored in another system. SmartObjects hide the integration details and complexities of various systems to make it simpler for designers and developers to interact with data from Line-Of-Business (LOB) systems, without needing to know or provide those details when they need to query or update data.

It is important to keep in mind that the SmartObject layer does not replicate LOB data, but rather provides a way to abstract data from LOB systems in a more logical and business-focused manner. With SmartObjects, the LOB systems remain in control of their data and how data are queried and updated, and the SmartObjects become the mechanism through which that data is used in forms, workflows, reports, and code. Applications that use SmartObjects call methods which are then executed by the server based on how the service instance is configured to connect to the LOB system. Most SmartObjects are used to query and update information in LOB systems. At the service instance level, you configure how authentication and authorization works to the LOB systems, ensuring that only authorized users can query and update data.

Looking at the architecture diagram below, you can see that SmartObjects are a middle layer between data providers (on the left, in blue) and data consumers (on the right, in green). In the image below, data comes from data providers such as a SQL server table, Active Directory, a SharePoint list, web services, or other technologies. Data is used by consumers, such as forms, workflows, reports, and custom code. SmartObjects exist between data providers and consumers, and are an abstraction layer that makes it possible to integrate with many different systems as if they were logical business objects. Designers to not have to know where the data comes from or how to integrate with the particular LOB to use that third-party system in solutions.

This topic explains the various terms and components you may encounter when working with SmartObjects. You can refer back to the diagram to understand where that component fits into the bigger picture.

Architecture and terminology of SmartObjects

A SmartObject is the logical business object used in reports, forms, and workflows to interact with data. A SmartObject is made up of properties and methods, and those properties and methods are associated with one or more service objects. The SmartObject itself is a definition that the product uses to know which service object to 'call' when executing a method. You can associate a SmartObject with a single service object, such as the Customer and Account SmartObjects in the diagram. These SmartObjects link to Customers and Accounts service objects, and the service objects are based on tables in the Finance database. This is a straightforward mapping of a data object in a provider (a table in a SQL database) that maps to a SmartObject. The consuming application does not need to know anything about the SQL database or how to interact with it. Instead, it calls a SmartObject method and uses the properties without needing additional detail.

You can create basic SmartObjects where the data is stored the K2 database as opposed to a line of business system. These are called SmartBox SmartObjects. When you initially create a SmartObject, it will be set to Basic mode and the product will take care of creating the underlying storage tables for you. See SmartBox for more information.

Advanced SmartObjects allow you more control over the methods when creating or editing a SmartObject definition. You would typically create an Advanced SmartObject when you want to integrate with a third-party system, if you want to combine data from different systems to create a composite SmartObject, or if you want to edit the properties or methods of a auto-generated SmartObject. See Advanced SmartObjects for more information.

Composite SmartObjects, a special type of advanced SmartObject, are SmartObjects that use multiple service objects to combine properties and methods from different LOBs. For more information see composite SmartObjects.

The SmartBox service type is used for basic SmartObjects. SmartBox is a product-managed SQL schema in the K2 database used for storing SmartObject data when there is no existing LOB system to provide data you need in your solutions. SmartObjects you create using the Designer typically use the SmartBox provider, unless you change the SmartObject to use data from another service by switching to advanced mode and mapping the SmartObject's properties and methods to Service Objects. See SmartBox for more information.

A service object represents the properties and methods of an entity from a data provider. Consider the Customers SQL table in the diagram above which contains several columns (such as Name, Contact Person, and Website) and methods (such as Select, Update, and Delete). The product uses a service object to represent the table’s properties and methods in a way that can be understood and used by SmartObjects. When you register a service instance, the product queries the target system and generates service objects based on the entities it discovers. For example, the SQL service type generates SmartObjects for tables, views, and stored procedures. You can optionally auto-generate SmartObjects for each service object, however you can create a SmartObject manually at a later time or by designing an advanced SmartObject.

You can use the same service object in multiple SmartObjects. In the diagram, notice that the AAD User service object is used in two different SmartObjects. This makes it possible to create different SmartObjects that expose different data, but still use the same underlying service instances and objects. In this example, perhaps you need a User SmartObject to modify user accounts in Azure Active Directory and an Employee SmartObject to read specific data from Azure Active Directory as well as a SQL database.

A service instance is a configured instance of a service type containing the configuration information necessary to connect to an LOB system, such as a server name, web service address, or database name. This configuration information is stored in the service instance and includes security settings (such as the security credentials to connect to the service), connection settings (such as the name of the SQL server database), and other configuration settings required to connect to the provider. The configuration settings are different depending on the LOB system you are connecting to. For example, a SQL database requires different connection settings than a web service. In the diagram above, there are two service instances of the SQL service type. Each service instance is configured to point to a different SQL database, but they both use the same SQL service type to communicate with the databases. There is also a service instance of the AAD service broker, configured to connect to the Denallix365 domain. A service instance is always associated with a particular service type. The service type describes how to connect to a provider technology, and the service instance contains information about connecting to a particular system of that technology. The service type does the actual work of connecting to the provider and querying and updating data.

If your make any schema, definition, or structural changes to the data provider, you must manually refresh the service instance to generate or update the service objects that represent the new or changed entities in the LOB system.

Service types are connectors/adapters that allow the product to interact with some underlying system and expose objects in that system as SmartObjects. A service type allows the product to integrate with a technology, while Service Instances of a service type to connect to specific instances of that system. Service instances are configured instances for a particular service type that point to an actual system, and you can have multiple service instances for the same service type that are configured to connect to different systems. For example, one instance of the SQL Server service type is configured to connect to your HR database while another service instance is configured to connect to your Finance database. You must configure service instances before developers and designers are able to create or use SmartObjects for that particular data store.

Behind the scenes, a service type is an entry in a K2 database that points to a specific service broker .dll. A service type is bound to a service broker in a one-to-one relationship. In the diagram above, there is a service type that understands how to interact with SQL databases, and another service type that understands how to interact with Azure Active Directory. Your environment will have many different service types. See Service Types for more information, and for information about LOB system version support, please see the Product Compatibility, Integration and Support matrix.

A service broker is an assembly (.dll) that performs the actual work of connecting to a provider, executing the methods, and doing the translation between the service object language and the language of the data provider. Similar to the service type and sometimes used interchangeably, the broker contains code and logic necessary to discover objects and communicate with the data provider. In the diagram above, the SQL service broker communicates with the SQL databases. The same service broker is used by the HR and Finance service instances because the mechanism to interact with a SQL database is the same, regardless of the data in a particular database. However, if you need to interact with another system, such as Azure Active Directory, you need to use a different service broker because the language and syntax to interact with an Azure AD system is different than interacting with a SQL database.

A provider is the LOB system that represents the source of the data, for example the database, web service, API or whatever else is providing the data that you want to expose as a SmartObject. It is important to note that the data always lives in the data provider. SmartObjects do not store any data, nor is data stored or cached in any other layer. Whenever you interact with a SmartObject, the product uses the service object > service instance > service type > service broker mechanisms to retrieve or update provider data on-demand. This ensures that data is always consistent, and you are always interacting with the latest version of the data.