SmartObject Terminology and Architecture

SmartObjects are the middle layer between data providers and data consumers. Consider the diagram in the image below. On the left, we have some providers of data, where the data lives. This is represented in blue. Data providers could be a SQL server table, Active Directory, a SharePoint list, web services, or a number of other technologies. On the right (represented in green), we have some consumers of that data. Data consumers could be forms, workflows, reports or custom code that use K2 APIs to interact with SmartObjects.

SmartObjects exist between providers and consumers. SmartObjects are essentially an abstraction layer that makes it possible to integrate with many different systems as if they were logical business objects, without having to know where the data comes from, or how to integrate with the particular system in question.

Basic architecture and terminology of SmartObjects

SmartObjects

A SmartObject is the logical business object or entity that consuming elements like reports, forms and workflows use to ultimately interact with some provider. A SmartObject is made up of properties and methods that come from one or more service objects. The SmartObject itself is actually nothing more than a definition that tells K2 which service object to use when populating the SmartObject with data or executing a method. You can associate a SmartObject with a single service object: for example the “Customer” and “Account” SmartObjects in the diagram. Each of these SmartObjects links to respective “Customers” and “Accounts” service objects. The “Customers” and “Accounts” service objects, in turn, point to tables in the “Finance” SQL database. This is a fairly straightforward “mapping” of a data entity in a provider (a table in a SQL database) that ultimately maps directly to an equivalent SmartObject. The consuming element does not need to know anything about the SQL database or how to interact with a SQL database, instead it just calls the SmartObject and K2 takes care of the rest.

You can also associate SmartObjects with multiple service objects when you combine properties and methods from different service objects; these are known as composite (Advanced) SmartObjects. In the diagram, we created an “Employee” SmartObject. This SmartObject points to the “AAD User” service object and the “Employees” service object, each of which retrieves data from a different provider. By combining the data from different systems, we created a logical business object called “Employee” which may be very useful to our business, since it contains all the data about an employee in one object, regardless of where that data actually comes from. Again, the consuming elements do not need to know anything about the underlying systems or how the data is combined: all they know is that there is an “Employee” object that contains all the data that makes up an employee in our organization, regardless of where that data resides.

Service Objects

A service object is a representation of the properties and methods for an entity in a particular provider. Consider the “Customers” SQL table in the diagram. This SQL database table has several columns (name, contact person, website and so on) and methods (select, update, delete and so on). K2 uses a service object to represent the database table’s properties and methods in a way that can be understood and used by SmartObjects. When you register a service instance for a particular provider, K2 queries the target system and then generates service objects for that system based on the entities it can discover. Optionally, you can also tell K2 to generate SmartObjects for each service object, but you can always create a SmartObject manually later and point it to a service object as well.

You can also use a 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 using the same underlying service objects and service instances. In this example, perhaps the business wants to create a “User” SmartObject that is used to modify user accounts in Azure Active Directory, and another “Employee” SmartObject that is used to read data from a SQL database and Azure Active Directory.

Service Instance

A service instance is a configured instance of a particular service type. Essentially, this is where K2 stores the configuration information necessary to reach a particular system, such as a server name, web service address or database name. This configuration is defined and stored in the service instance configuration, and also includes security settings (in other words, what security credentials should K2 use to connect to the service), connection settings (for example, the name of the SQL server and the database that the service instance should connect to) and other configuration settings that may be required by the provider. The configuration settings are usually different depending on what type of system you are trying to connect to: a SQL database has different connection settings than a web service, for example. In the diagram, notice that there are two service instances in the SQL service type block. Each service instance has been configured to point to a different SQL database, but they both use the same SQL service broker to communicate with the target databases. In the diagram there is also a service instance of the AAD service broker, which has been configured to point to the Denallix365 domain. A service instance is always associated with a particular service type. Think of it this way: the service type tells K2 which adapter/broker to use when connecting to a provider, and the service instance tells K2 how to connect to the provider. The service broker does all the actual work of interacting with the provider.

If any schema/definition/structural changes are made to the underlying provider, you must manually refresh the service instance to discover the changes so that K2 can generate or update the service objects that represent the entities in the target system.

Service Type

Service Types are essentially "connectors" or "adapters" that allow K2 to interact with some underlying system and eventually expose that system as SmartObjects. A Service Type is used to allow K2 to integrate with a particular technology, while Service Instances are configured instances of a Service Type that connect to specific occurrences of that technology. Service Instances are essentially configured instances for a particular service type that point to s specific occurrence of a technology, 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 will be configured to interact with your HR database while another Service Instance of the SQL Server Service Type will be configured to interact with your Finance database. You must configure Service Instances before developers and designers will be able to create SmartObjects for that particular data store.

A service type is just an entry in a database for a specific service broker. Before K2 can use a service broker to interact with some provider, the service broker must be registered with K2 as a service type. K2 administrators can then create service instances for the service type and configure the service instance with the necessary settings to connect to a particular system. A service type is bound to a service broker in a one-to-one relationship. Usually, a K2 environment will contain many different service types, and each service type is usually associated with a particular provider technology. In the diagram, 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. Of course, your K2 environment will have many more service types, see the topic Service Types for more information.

Service Broker

A service broker is the “adapter” or “connector” that performs the actual work of connecting to some provider, executing the methods and doing the translation between the service object “language” and the “language” that the provider understands. In the diagram, we are using the SQL service broker to communicate with the SQL databases. The same service broker is used by both the “Finance Database” and the “HR Database” service instances because the mechanism to interact with a SQL database is the same, regardless of the actual data in that database. However, if we want to interact with another system (like Azure Active Directory), K2 will 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. Under the covers, service brokers are .dll files that reside in the file system of a K2 server.

Providers

A provider is just the source of the data, for example the database, web service, API or whatever else is providing the data that we want to expose as a SmartObject. It is important to note that the data always lives in a provider: SmartObjects does not actually store any data. Whenever you interact with a SmartObject, K2 will use the service object>service instance>service type>service broker mechanisms to retrieve data from the provider on-demand. This ensures that data is always consistent and you are always interacting with the latest version of the data.