4. Create the Expense Claim Currency Code SmartObject

In this step, you will create the Expense Claim Currency Code SmartObject from scratch. In the last topic, you auto-generated the Expense Claim Categories SmartObject from its service instance, which automatically created a SmartObject with all the available methods and properties for the targeted service object. However, by creating a SmartObject from scratch, you can create your own methods and properties and tailor them specifically to your application. In this step, you will create two methods based on service objects from the K2 Tutorial Currency REST Service, service instance. They are as follows:

  • List Currencies: This method returns a list of currency codes which you will use later on in a currency code drop-down list control on the Expense Claim Form. Users can select a code as they enter their line items. This allows users to enter expense claims that occurred in other countries.
  • Calculate USD Amount: This method performs a mathematical calculation that converts all line item amounts to US dollars. You will use this later on to auto-calculate the equivalent US dollar amount for an expense entered in another currency.
  1. First, return to the K2 Designer. Add a new SmartObject to the SmartObjects category. Use the table below for the SmartObject settings. If a setting is not specified in the table, assume the default value.
    Field Value Notes
    NameExpense Claim Currency Codes  
    DescriptionThis SmartObject provides currency code look-up methods for expense claims.  
    Category Leave this as-is
    (K2 Learning\Expense Claim\SmartObjects)    		  
    Type Advanced SmartObject You will point this SmartObject to the REST service, service instance that you created earlier.
    1. Return to the K2 Designer site. (It should already be a tab in your browser.) Navigate to your Expense Claim categories. Right-click the SmartObjects category, then select New SmartObject.
      New SmartObject
    2. In the GENERAL tab, configure the properties for the new SmartObject using the table below as a guide. Click CREATE.
      Field Value Notes
      NameExpense Claim Currency Codes  
      DescriptionThis SmartObject provides currency look-up methods for expense claims.  
      Category Leave this as-is
      (K2 Learning\Expense Claim\SmartObjects)      		  
      Type Advanced SmartObject You will point this SmartObject to the REST service, service instance that you created earlier.
      SmartObject General Settings for Currency Codes
  2. First, you will add and configure the method that returns a list of currency codes. You will apply this method to a drop-down list on the Expense Claim form in a later step.
    Add a new method called List Currencies that points to the following service object method: K2 Tutorial Currency REST Service > Service Operations > ListCurrencies > ListCurrencies. Bind the returned string property to a new SmartObject property called Currency Codes.
    1. In the PROPERTIES & METHODS tab, click the Methods tab, then click Add. You will select a method from the K2 Tutorial Currency REST Service, service instance.
      Recall that you registered a new service instance of the REST Service. 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). For the Expense Claim application, you will map one of the methods that was discovered for the service.
      Add New SmartObject Method
    2. On the Add Method screen, select the following service object method:
      K2 Tutorial Currency REST Service > Service Operations > ListCurrencies > ListCurrencies, then click NEXT.
      Add Service Object Method
    3. Change the name of the method from 'ListCurrencies' to
      List Currencies
      then 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.
      Rename SmartObject Method
    4. You are now on the INPUTS & OUTPUTS screen. Double-click the String RETURN PROPERTY NAME. You will create a new property in the SmartObject that is bound to this string return property. The new property is what you will use in your drop-down list for returning currency codes. (The "string" return property is the property in the data source that contains the currency codes.)
      Return Properties
    5. In the dialog box that opens, click the CREATE button to create a new property called
      Currency Codes
      then click OK and OK again to return to the mapping screen.
      Create New Property
    6. You should see the service method return property is now bound to the new SmartObject property, Currency Codes. Click NEXT, then FINISH to complete the wizard.
      Bound Return Property
  3. Now, you will add the second method. This method performs a mathematical calculation behind-the-scenes. It automatically converts all expense claim line items to US dollars. For example, if the user enters a line item in GBP (UK pounds), we will call this method to convert the amount to USD. This way, all line items are of the same currency and can be accurately totaled. It also provides a convenience to your users who don't have to do the calculation themselves.
    Add another method called Calculate USD Amount to the SmartObject that points to the service object method K2 Tutorial Currency REST Service > Objects Types> HistoricalConversion > HistoricalConversion. Configure the input parameters and return property as follows:
    Completed SmartObject Properties
    1. Because your users have the option to enter expense claim line items in another country's currency, you need a way to convert that amount to US dollars. You want all the line items to be US dollars that can be summed for a final total amount. In this step, you will add a method which calculates the USD exchange rate for a given date, amount and currency code.
      Once again, click the Add button to add another method to the SmartObject.
    2. On the Select a ServiceObject method screen, select the following ServiceObject method:
      K2 Tutorial Currency REST Service > Object Types > HistoricalConversion > HistoricalConversion, then click NEXT.
      Select ServiceObject Method
    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 - the date that the expense was incurred (because currency rates change from day to day).
      • FromCurrencyCode - the starting currency type (GBP for British pound for example).
      • FromAmount - the amount to be converted.
      • ToCurrencyCode - the ending currency type (USD, for example).
      In this application, you will hard-code the ToCurrencyCode parameter to USD so that any call to your SmartObject always converts 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 Service, for example) the service broker for that REST 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. Take, for example, the HistoricalConversion ServiceObject. In the image below, you see the Properties and Methods. There is a HistoricalConversion method discovered and it returns a Decimal value. The HistoricalConversion method requires the four parameters that you are configuring now.
      Parameters for a ServiceObject
    4. On the bottom half of this screen, click the Add button to add a new parameter of type Text called
      FromCurrencyCode
      then click OK.
      Adding a Parameter
    5. Add another parameter of type Decimal called
      FromAmount
      then click OK.
      Adding a Parameter
    6. Add another parameter of type Date/Time called
      Date
      then click OK.
      Adding a Parameter
    7. You should see your three input parameters listed at the bottom of the screen. You don't need to add a parameter for "ToCurrencyCode" because that value is hard coded. (The user won't be inputting this value.) Click NEXT.
      Input Parameters

      8. On the next screen, notice the four ServiceObject method input parameters. These are the parameters discovered in the ServiceObject. You will map 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.

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

      13. Once the currency conversion is complete, the HistoricalConversion method will return a Decimal value. Like the List Currencies method, you will create a new SmartObject property for the returned value in your Expense Claim Currency Codes SmartObject. In a later step, you will map the new property to a form field, which will in turn, display the converted value on your form.

    13. Select the Decimal return property on the bottom half of the screen, then click Assign. Create a new SmartObject property called
      USD Amount
      then click OK and OK once again.
      Create New SmartObject Property
    14. Your INPUTS & OUTPUTS screen should look like the image below. Click NEXT, then FINISH to complete the method wizard.
      Complete SmartObject Properties
    15. You should now have two methods for the advanced SmartObject. Click FINISH to complete the SmartObject configuration.
      Completed Currency Methods
  4. Before moving on to the next tutorial topic, take a minute to test the SmartObject from the Management site. (Categories > K2 Learning > Expense Claim > SmartObjects > Expense Claim Currency Codes) This validates your method configurations are correct, plus gives you a glimpse into how the calculate method takes the parameter values, then calculates the return amount (USD Amount).
    1. To test the two new methods, return to the Management site. (It should be a tab in your browser. If not, launch it from the start menu, short cut, or from a URL provided by your Nintex K2 administrator.)
    2. Expand the Categories node, then navigate to the Expense Claim Currency Codes SmartObject. (K2 Learning > Expense Claim > SmartObjects)
      Expense Claim Categories
    3. Click the Expense Claim Currency Codes SmartObject to expose the properties and methods in the central pane. Scroll down to the Methods section, select the List Currencies method, then click Execute.
      Execute Method
    4. You don't need any filters for this method, so click Execute once again. Confirm you have results returned displaying currency codes. These are the values you will use for the currency code drop-down list on the Expense Claim form. Click Done to exit the results screen.
      Execute List Method
    5. Now test the currency calculation method. Select the Calculate USD Amount method, then click the Execute button. This time, you must provide the input parameters you just configured, so that the calculation can be executed and return the result. You must provide values for the FromCurrencyCode, FromAmount and Date parameters. (Technically, the ToCurrencyCode parameter is also required, but recall that you hard-coded it for US dollars, so you don't need to provide that input manually.)
    6. For the FromCurrencyCode value, enter
      GBP
      then for the FromAmount, enter
      100
      and finally, for the Date, enter today's date. Click Execute. Confirm you have a result returned. Click Done to exit the results screen.
      Execute Calculate Method
Review

In this step, you created an advanced SmartObject from scratch, that connects to a REST service to work with currency data. You configured two methods. The first returns a list of currency codes, which you will use to populate a drop-down list. The second calculates the US dollars equivalent for a given currency and source amount, for a specific date. You will use this method to convert amounts entered with a non-US country code. This makes it easier for your users to submit travel expenses since they don't have to do the currency conversion by hand. It also allows for easy calculation of total expense claim amounts.

Remember, Nintex K2 can generate SmartObjects for you from a service instance. You can also create SmartObjects from scratch, as you did in this step. Creating a SmartObject from scratch allows you full control over the properties and methods for that SmartObject.

Next Step: 5. Create the Expense Claim Header SmartObject