3. Create Service Instances for External Data Sources; Generate a SmartObject

In this step, you begin creating the data objects for your Expense Claim application. The first two data objects connect to external data sources. The first external data source is a SQL database we will use to look up Expense Categories, and the second data source is a REST service that we will use to work with currency conversion.

The first step when integrating with external systems such as SQL or REST services is to create a service instance. The service instance contains the connection configuration such as URL, server name, user name, password, and so forth. You will create a SQL Server service instance to connect to the SQL database, and a REST service, service instance to connect to the currency service.

Creating a service instance allows Nintex K2 to discover the objects (such as the properties and methods) that the data source contains. After you create a service instance, you can create a SmartObject from the service instance that allows Nintex K2 to interact with the data source through forms, workflows and rules.

Service Types, Brokers, Instances, and SmartObjects
Service types, service brokers, and service instances are the elements that allow Nintex K2 to interact with other systems, and which form the base layer for SmartObjects. The following is a brief overview of each concept:
  • Service Type: A service type is a pointer to a broker file for a specific system or data source. Examples include: SQL Server, SharePoint, CRM, and web services. Each service type has an underlying service broker associated with it.
    • Service Broker: A file that contains the logic needed to interact with a specific system. Each service type has its own requirements for interacting with the system. For example, what type of authorization will the system allow? What type of data is contained in the system?
  • Service Instance: A service instance is a single connection to a data source, and is based on the service type. The service instance uses the requirements defined by the broker to connect to the target data source. For example, you might have an instance of a SQL Server service type. The instance is specific to a single SQL database. If you have multiple databases, you need multiple instances. From the instances, you can then generate SmartObjects.

  • SmartObjects: The middle layer that allows interaction between an object (form, view, workflow) and the target data source. For example, you have a form bound to a SQL SmartObject. When you submit the form, the SmartObject creates a new record or it updates an existing record in the SQL table. The SmartObject connects Nintex K2 to the system via the service layer.

In a shared environment, you only need to create the service instance once. If the service instance already exists and you want to create your own, use a unique identifier of some kind. One example might be to add your name or initials to the service instance name.
Knowledge of Microsoft SQL Server is required as this scenario requires you to create a SQL database to integrate with the SQL server instance. Contact a member of your IT support team for help in creating the database in your environment, if necessary.
  1. Create a database to connect to. This database must be on the same server where your K2 database is hosted. This is to avoid setting additional security and permissions.
    1. For this example, you must create a SQL database called K2Learning. Alternatively, you can use the following SQL script to create the database. Ensure the K2 Service Account has db owner rights to the database.
    2. The database requires the following:
      Table Name
      TableExpenseCategory

      Column NameData TypeColumn Setting
      ColumnsExpenseCategoryIdint (Autonumber)Primary key
      ExpenseCategoryNamenvarchar(50) 
      ExpenseCategoryCodenchar(10) 
    3. Create the following entries in the database. If you used the SQL script, these entries already exist but you still have to assign rights to your K2 Service Account.
  2. Return to the Management site. Use the table settings below to configure a new Service Instance of the SQL Server Service, service type. This data source provides look-up values for the expense claim categories.
    Field NameSetting
    ADisplay NameK2 Tutorial Sample SQL Database
    BDescriptionThis is the service instance of the sample database used in the K2 Learning tutorial.
     Service TypeSQL Server Service (default)
    CAuthentication ModeImpersonate (Ensure Impersonate is selected)
    DOn Different SQL Serverfalse
    ECommand Timeout90
    FDatabaseK2Learning
    GServerLOCALHOST (Alternatively your SQL server name)
    HGenerate SmartObjects for this Service InstanceUNCHECKED
    1. In the Management menu, expand the Integration node, then click Service Types. You will see current service types displayed in the central pane. Scroll through the service types until you locate SQL Server Service. You can also use the search option instead of scrolling through the pages. (You may see more than one result returned.)
      Integration Menu
    2. Select SQL Server Service, then click the New Instance button in the toolbar.
    3. Use the table below to configure the service instance. There is an image below the table for reference as well. If a setting is not indicated in the table, assume the default value. Click OK when you have entered the configuration settings, and then click OK for the confirmation dialog. (It may take a few seconds for the confirmation dialog box to appear).
      Field NameSetting
      ADisplay NameK2 Tutorial Sample SQL Database
      BDescriptionThis is the service instance of the sample database used in the K2 Learning tutorial.
       Service TypeSQL Server Service (default)
      CAuthentication ModeImpersonate (Ensure Impersonate is selected)
      DOn Different SQL Serverfalse
      ECommand Timeout90
      FDatabaseK2Learning
      GServerLOCALHOST (Alternatively your SQL server name)
      HGenerate SmartObjects for this Service InstanceUNCHECKED
  3. Create a second service instance using the REST service type. Use the table settings below as a guide for the service instance configuration. This service provides two methods. The first method returns a list of currency codes (such as GBP, USD) for you to select when entering your expense claim line item. The second method performs a calculation that converts an amount entered to US Dollars. For example, if you enter a line item amount and select GBP as the currency code, the second method converts the amount and outputs it as USD.
    In a shared environment, you only need to create the service instance once. If the service instance already exists and you want to create your own, use a unique identifier of some kind. One example might be to add your initials to the service instance name.
    This REST service is for tutorial purposes only. Do not use this REST service for production implementations. Contact a member of your IT support team for help, if necessary.
     FieldValueNotes
    Service Instance
    A.Display NameK2 Tutorial Currency REST ServiceIf you are working in a shared environment, include your initials in the display name to make the name unique and easily identifiable to you.
    B.DescriptionThis is the service instance of the sample currency REST service used in the Expense Claim tutorial. 
    C.Service TypeREST
    Service Authentication
    D.Authentication ModeImpersonateThe Authentication Mode of the service instance should be set according to the authentication required by the endpoint. For example, if the endpoint supports static authentication then select the static authentication mode and provide a username and password.
    Service Keys
    There is only one service key value to set in this step (Descriptor Location).
    E.Descriptor Locationhttps://k2learning.azurewebsites.net/api/swagger.jsonThis is the location of the descriptor file. This must be a URL. The Authentication Mode used for the service instance is also used to access the Descriptor Location JSON file when that file is a URL. This file must be available at this location when the service instance is refreshed. Paths in the Swagger file must be unencoded. For more information about getting a Swagger file, see Resources for working with the REST Service Broker.
    1. Next you will add another service instance which points to the REST service used for currency conversion operations. Begin by opening a new browser window to verify you can connect to the following REST service:
      https://k2learning.azurewebsites.net/api/swagger/ui#/
      You should see a screen similar to the image below. This verifies that your firewall configuration is sufficient for connecting to this REST service.
      Test Connection EndPoints Web Service
    2. Returning to the Management site, expand the Integration node, then click Service Types. Scroll down to (or search for) the REST service type. Select REST, then click the New Instance button in the toolbar.
      Adding a New Service Instance
    3. Use the table below to configure the service instance. There is an image below the table to use as a reference as well. If a setting is not indicated in the table, assume the default value. Click OK when you have entered the configuration settings. Click OK for the confirmation dialog.
       FieldValueNotes
      Service Instance
      A.Display NameK2 Tutorial Currency REST ServiceIf you are working in a shared environment, include your initials in the display name to make the name unique and easily identifiable to you.
      B.DescriptionThis is the service instance of the sample currency REST service used in the Expense Claim tutorial. 
      C.Service TypeREST
      Service Authentication
      D.Authentication ModeImpersonateThe Authentication Mode of the service instance should be set according to the authentication required by the endpoint. For example, if the endpoint supports static authentication then select the static authentication mode and provide a username and password.
      Service Keys
      There is only one service key value to set in this step (Descriptor Location).
      E.Descriptor Locationhttps://k2learning.azurewebsites.net/api/swagger.jsonThis is the location of the descriptor file. This must be a URL. The Authentication Mode used for the service instance is also used to access the Descriptor Location JSON file when that file is a URL. This file must be available at this location when the service instance is refreshed. Paths in the Swagger file must be unencoded. For more information about getting a Swagger file, see Resources for working with the REST Service Broker.
      F.Generate SmartObjects for this Service InstanceUNCHECKEDYou will manually create a SmartObject in a later step.
      Endpoints Web Service Configuration
    4. Still in the Integration node, click Service Instances. Confirm the two new service instances appear in central pane, K2 Tutorial Sample SQL Database and K2 Tutorial Currency REST Service. You have completed the external data source connections.
      Expense Claim Service Instances
  4. Next, you will generate a SmartObject for the SQL database service instance. The SmartObject acts as the "bridge" for interaction between the SQL data source and artifacts (such as views, forms, workflows).
    Generate a SmartObject from the K2 Tutorial Sample SQL Database service instance. Select (only) the [Finance].[ExpenseCategory] table.
    Generate SmartObject
    1. Still in the Integration section, click Service Instances once again. Navigate to (or search for) the K2 Tutorial Sample SQL Database service instance in the central pane. Select the service instance, then click the Generate SmartObjects button in the toolbar.
      Generate SmartObjects from a Service Instance
    2. On the Generate SmartObjects screen, expand the Tables node. (If the Tables and/or Views nodes are already checked, uncheck them first. You do not want to create SmartObjects from all the tables and views, you will be selecting a single table from which to create the SmartObject.) CHECK the [Finance].[ExpenseCategory] table, then click OK.
      Generate SmartObject
  5. Next, you have two minor adjustments to make to the expense categories SmartObject you just generated. Because you generated the SmartObject from the service instance, Nintex K2 saved the SmartObject in a generic category, as the table name [Finance].[ExpenseCategory]. First, you will move the SmartObject to your Expense Claim > SmartObjects category, then you will rename the SmartObject so that it's easier to work with.
    Switch to the Categories menu, then edit the [Finance].[ExpenseCategory] SmartObject. Move the SmartObject to the Expense Claim > SmartObjects folder, then rename it to Expense Claim Categories.
    1. Still in the Management site, expand the Categories node. (You can collapse the Integration node if you need to.) Navigate to the [Finance].[ExpenseCategory] SmartObject. (SQL Server Service > K2 Tutorial Sample SQL Database > Tables)
      Categories Menu
    2. Select the SmartObject, then click the Design link in the central pane. After the Designer launches, click the Edit link in the central pane.
      Design or Edit SmartObject Link
      Edit the SmartObject
    3. Switch to the GENERAL tab. Rename the SmartObject
      Expense Claim Categories
      then move it to the K2 Learning > Expense Claim > SmartObjects category.
      Rename a SmartObject
    4. Click FINISH to save and exit the SmartObject. Close this browser window if you already have the Designer opened in another tab.
  6. Before moving on to the next tutorial topic, take a minute to test the categories SmartObject. You can easily test SmartObjects from within the Management site. This will confirm your SmartObject is ready for use in other artifacts. You will test the SmartObject by executing a list method that returns all the items from the data source.
    From the Management site, execute the Expense Claim Categories SmartObject's list method and confirm you see a list of categories returned. You may need to refresh the Categories node first to find the SmartObject in its new location. The SmartObject should be in the K2 Learning > Expense Claim > SmartObjects category.
    Categories Menu
    1. You can execute SmartObjects from within the Management site. Because you just renamed and moved the categories SmartObject, you need to refresh the Categories menu to see the changes. Right-click Categories, then select Refresh Menu.
      Refresh Menu
    2. Navigate to the Expense Claim Categories SmartObject. It should be in the K2 Learning > Expense Claim > SmartObjects folder.
      Categories Menu
    3. Select the Expense Claim Categories SmartObject. Notice the central pane displays the details for the SmartObject. The Properties section displays the properties (think columns in a table) and the Methods section displays the different ways you can interact with data from this SmartObject. This data source allows you to create, delete, list, read, and update its data content. Select the List method, then click Execute.
      SmartObject Details

      4. The Execute SmartObject Method screen opens. Here, you can apply filters before executing the method. In some cases, such as read methods, you must provide input parameters before executing the method. For example, you might provide the ID of a record you want returned. For this test, you just want to confirm the connection, so you don't need any filters.

    4. Click the Execute button in the lower right corner of the screen. You will see results displayed in the same screen, which confirms the connection. This data source provides the drop-down list values for the expense claim categories. Click Done to close the screen.
      SmartObject Execute Results
Review

In this step, you began creating the data sources for this application. The first two data sources are external, meaning they do not exist on your Nintex K2 server locally. To connect to external data sources, you begin by creating service instances of existing service types. (Service types do not have to be existing, you can in fact, create your own custom service types.) You configured connections to a SQL database and a REST Service. Once you have the service instance, you must generate or create a SmartObject. The SmartObject acts as the "bridge" between the data source, and the entities that consume the data (such as views, forms, and workflows). In this exercise, you auto-generated a SmartObject from a table found in the SQL database. In the next exercise, you will create a new SmartObject from scratch using the REST Service, service instance.

Next Step: 4. Create the Expense Claim Currency Code SmartObject