6. Create the Expense Claim Currency SmartObject

In this step, you create the final data source for the Expense Claim application. This advanced data source uses the K2 Tutorial Currency REST Service - service instance created earlier. This data source has two functions: providing values for the currency code drop-down list and performing calculations that convert expense claim amounts to US dollars.

  1. From the K2 Application elements page, add a new SmartObject. Use the table below for configuring the general properties.
    Field Value Notes
    NameExpense Claim Currency 
    DescriptionCurrency look-up methods for expense claims.  
    Category (Leave default value unchanged.)  
    Type Advanced SmartObject You point this SmartObject to the REST service, service instance that you created earlier.
    1. From the K2 Application elements screen, click New and select SmartObject.
    2. On the GENERAL settings page, configure the new SmartObject using the table below as a guide. Click CREATE.
      Field Value Notes
      NameExpense Claim Currency  
      DescriptionCurrency look-up methods for expense claims.  
      Category (Leave default value unchanged.)  
      Type Advanced SmartObject You point this SmartObject to the REST service, service instance that you created earlier.
      Advanced SmartObject Properties
  2. Next, you add the first of two methods. The first method returns a list of currency codes that populates a drop-down list on the expense claim form.
    Add a method called ListCurrencies that points to the following service object method: K2 Tutorial Currency REST Service > Service Operations > ListCurrencies > ListCurrencies, then save the returned currency codes to a SmartObject property called CurrencyCode.
    1. Begin by selecting a method from the K2 Tutorial Currency REST Service - service instance. On the PROPERTIES & METHODS screen, click the Methods tab and click Add.
      Recall that you registered a new service instance of the REST earlier. Nintex K2 discovered the objects found in the REST service and returned the properties and methods. Because the REST service already has properties, you do not need to define them (which is why you are skipping over the Properties tab). In your application, you map the list method from this service instance.
    2. On the Add Method screen, select the following service object method:
      K2 Tutorial Currency REST Service > Service Operations > ListCurrencies > ListCurrencies, then click NEXT.
    3. Change the name of the method from 'ListCurrencies' to
      List Currencies
      and select the Default list method check box. Click NEXT to continue.
      ServiceObjects can have more than one list method. For example, an Active Directory ServiceObject might have a GetUsers list method that returns all user accounts. The ServiceObject might also have a method that returns all users in a specific group. By selecting the default list method option, Nintex K2 knows which list method to use throughout your application.
    4. You are now on the INPUTS & OUTPUTS screen. Double-click the String RETURN PROPERTY NAME. You create a property in your SmartObject that is mapped to this string return property.
    5. You are creating a new SmartObject property that displays the value from the returned string property. In the resulting dialog box, click the CREATE button to create a new property called
      CurrencyCode
      then click OK and OK again to return to the mapping screen.
    6. You should see the service method return property is now mapped to the new SmartObject property, CurrencyCode. Click NEXT, then FINISH to complete the wizard.
  3. Add a second method called Calculate USD Amount to the SmartObject that points to the service object method K2 Tutorial Currency REST Service > Objects Types> HistoricalConversion > HistoricalConversion, then configure the input parameters and return property as follows:
    1. You have added the first method to the SmartObject, which returns a list of currency codes. Next, you add a method that calculates the exchange rate amount for a given date, amount, and currency.
      Once again, click Add to add another method to the SmartObject.
    2. On the Add Method screen, select the following ServiceObject method: K2 Tutorial Currency REST Service > Objects Types> HistoricalConversion > HistoricalConversion, then click NEXT.
    3. Rename the method to
      Calculate USD Amount
      4. This method requires input parameters to perform the conversion calculation, then return a result. There are four parameters necessary for the conversion process:
      • Date - currency rates change from day-to-day.
      • FromCurrencyCode - the starting currency type, British pound for example.
      • Amount - the amount to be converted.
      • ToCurrencyCode - the ending currency type, US dollar for example.
      In this application, you hard-code the ToCurrencyCode value to USD so that calls to your SmartObject always convert to US dollars. To help you understand parameters a little more, let's go back to the data concept of ServiceObjects and service brokers. When you register a new service instance of a ServiceObject (REST, for example) the service broker for that service discovers the properties, methods, return properties, and parameters for that data source. Parameters are input values that methods need to return a value of some kind. In the image below (this is a screen shot from the SmartObject Service Tester utility), you see the Properties and Methods for the HistoricalConversion object. There is a HistoricalConversion method discovered and it returns a Decimal value. The HistoricalConversion method requires the four parameters that you are configuring now.
    4. On the bottom half of this window, click the Add button to add a new parameter called
      FromCurrencyCode
      that is a Text (type). Click OK.
    5. Add another (Decimal) parameter called
      Amount
      then click OK.
    6. Add another (Date/Time) parameter called
      Date
      then click OK.
      You should see your three input parameters listed at the bottom of the screen. Click NEXT.

      7. On the next screen, notice the four ServiceObject method input parameters. You map them to the three parameters that require values at runtime for the conversion to take place. The fourth parameter is the ToCurrencyCode parameter and you are going to hard-code that value so that it is always USD.

    7. Select the Date parameter, then click the Assign button.
    8. In the dialog box, select SmartObject method parameter from the Map to drop-down list, then Date in the Parameter drop-down list and click OK.
    9. Select the FromAmount web method parameter and use the same step to map it to the Amount SmartObject method parameter that you created earlier. Click OK.
    10. Repeat the step again and map the FromCurrencyCode web method parameter to the FromCurrencyCode SmartObject method parameter.
    11. Last, you hard-code the ToCurrencyCode property and Assign it to a Specific value. For the value, enter:
      USD.
      (For this tutorial, you always convert currencies back to US dollars, which is the static value you are entering in this step.) Click OK.

      12. Now, you are reversing the process a bit. Once the currency conversion is complete, the HistoricalConversion method returns the value to its Decimal property. (Notice the Decimal property in the Return Properties pane.) Like the ListCurrencies method, you create a new SmartObject property for the returned value in your Expense Claim Currency SmartObject. In a later step, you map the new property to a form field, that displays the converted value on your form.

    12. Select the Decimal return property on the bottom half of the screen and Assign it to a new SmartObject Property that you Create called:
      USD Amount
      then click OK and OK once again.
    13. Your mapping screen should look like the image below. Click NEXT, then FINISH to complete the method wizard.
    14. You should now have two methods for the advanced SmartObject. Click FINISH to complete the SmartObject configuration.
  4. Test the new SmartObject from the Management site by executing the ListCurrencies method and Calculate USD Amount (read) method.
    1. You should be on the K2 Application elements page. Confirm you can see the new Expense Claim Currency SmartObject.
      Test your new SmartObject from the Management site. Launch the Management site if it is not already open.
      If you are unsure of how to launch the Management site, see Accessing Sites.
    2. Expand the Categories node, then navigate to the Expense Claim Currency SmartObject. (Your menu may not be the same as the image below, depending on where you built your SharePoint list.) Click the Expense Claim Currency SmartObject to expose its properties and methods in the central pane. Scroll down to the Methods section, select the ListCurrencies method and click Execute.
      If you do not see the Expense Claim Currency SmartObject, right-click the Expense Claim List and select Refresh Menu.

    3. You don't need any filters for this method, so click Execute once again. Confirm you have results returned displaying currency codes. Click Done to exit the results screen.
    4. Now test the currency calculation method. Select the Calculate USD Amount method, then click the Execute button. This time, because it's a read method, you must provide input parameters. In this case, the starting currency type, date, and amount. Technically, the target currency type is also required, but remember you hard-coded it for US dollars, so you don't need to provide that input manually.
    5. For the FromCurrencyCode value, enter
      GBP
      then for the Amount, enter
      100
      and finally, for the Date, enter today's date and click Execute. Confirm you have a result returned. Click Done to exit the results screen.
Review

In this step, you created an advanced SmartObject using the REST service instance. You configured two methods. The first returns a list of currencies, which you use to populate a drop-down list. The second calculates the USD equivalent for a given currency and source amount, for a specific date. You use this method to convert amounts entered with a non-US country code. This makes it easier for you to submit travel expenses since you don't have to do the currency conversion by hand.

Remember, Nintex K2 can generate SmartObjects for you from a service instance or you can create SmartObjects from scratch, as you did in this step. This allows full control over the methods exposed and property names. This completes the data components for this application. In the next step, you begin working with views and forms.

Next Step: 7. Edit the New Expense Claim View