6. Create the Expense Claim Currency SmartObject

In this step, you will create the final data source for the Expense Claim application. This advanced data source uses the K2 Tutorial Currency Web Service - service instance created earlier. This data source provides 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 Advanced SmartObject with the following configuration:
    Field Value Notes
    NameExpense Claim Currency  
    DescriptionCurrency look-up methods for expense claims.  
    Category (Leave default value unchanged.)  
    Type Advanced SmartObject You will point this SmartObject to the web service, service instance that you created earlier.
    Workflow Use (Not checked) You are using the new Workflow Designer and not the legacy.
    1. From the K2 Application elements screen, click New and select SmartObject.
    2. On the GENERAL settings page, configure the properties for 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 will point this SmartObject to the web service, service instance that you created earlier.
      Workflow Use(Not Checked)You are using the new Workflow Designer and not the legacy.
      Advanced SmartObject Properties
  2. Now, you will add the first of two methods. The first method returns a list of currency codes that populate 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 Web Service > ExchangeRates Objects > ListCurrencies() > List, then save the returned currency codes to a SmartObject property called CurrencyCode.
    1. On the PROPERTIES & METHODS screen, click the Methods tab, then click Add. You will select a method from the K2 Tutorial Currency Web Service, service instance.
      Recall that you registered a new service instance of the Endpoints WebService earlier. K2 discovered the objects found in the web service and returned the properties and methods. Because the web 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 will map one of the methods that K2 discovered for the web service.
    2. On the Add Method screen, navigate to the following service object method:
      K2 Tutorial Currency Web Service > ExchangeRates Objects > ListCurrencies() > List, then click NEXT.
    3. Change the name of the method from 'List' to
      ListCurrencies
      then select the Default list method checkbox. 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, 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 will 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 Web Service > ExchangeRates Objects > HistoricalConversion() > Read, 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 will add a method which 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, navigate to the ServiceObject method:
      K2 Tutorial Currency Web Service > ExchangeRates Objects > HistoricalConversion() > Read, 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 will hard-code the ToCurrencyCode value 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 (Endpoints WebService, for example) the service broker for that web service will discover 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 (this is a screen shot from the SmartObject Service Tester utility), you see the Properties and Methods. There is one Read method discovered and it returns a Decimal value. The Read 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 of type Text called
      FromCurrencyCode
      then click OK.
    5. Add another Parameter of type Decimal called
      Amount
      then click OK.
    6. Add another Parameter of type Date/Time 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 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.

    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 menu, then click OK.
    9. Select the FromAmount web method parameter and use the same procedure to map it to the Amount SmartObject method parameter that you created earlier. Click OK.
    10. Repeat the same procedure to map the FromCurrencyCode web method parameter to the FromCurrencyCode SmartObject method parameter.
    11. Last, you will hard-code the ToCurrencyCode property and 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.

      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 will create a new SmartObject property for the returned value in your Expense Claim Currency SmartObject. In a later step, you will map the new property to a form field, which will in turn, displays the converted value on your form.

    12. Select the Decimal return property on the bottom half of this screen and Assign it to a new SmartObject Property that you will 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 K2 Management site: List 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. If you wish, you can test the new SmartObject as described in the next few (optional) steps.
      (Optional Step) You can test your new SmartObjects from the K2 Management site. Launch the K2 Management site if it is not already open.
      If you are unsure of how to launch the K2 Management site, see Accessing K2 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, then 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, then 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 Endpoints WebService - service instance. You configured two methods. The first returns a list of currencies, which you will 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 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.

Remember, K2 can generate SmartObjects for you from a service instance and 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
Expense Claim Application