How To: Create a SmartObject to connect to a web service

You can use the Endpoints WebService and an advanced SmartObject to connect to a SOAP/WSDL web service. For example, you have a web service that provides currency conversion functions, and you want to create a SmartObject to list the types of currency, and calculate the exchange value from one currency type to another.

Testing the currency conversion method of the currency web service.

Scenario

In this scenario we use a sample web service that provides currency conversion functions to list accepted currency types, as well as converting currencies based on the exchange rate for a given date. You create an advanced SmartObject to expose those functions. Eventually, you might use a SmartObject like this in a travel expense claim applications, but for the purposes of this example we will just create the SmartObject.

Steps

First, create a new Endpoints WebService to connect to the currency web service. Then you create a SmartObject for the properties and methods needed for the expense claim application. You configure a method to list the currency types, and then a method that converts currency amounts into US Dollars. Finally, you test both SmartObject methods using the SmartObject execute options in K2 Management.

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Create an advanced SmartObject in K2 Designer.

1. In K2 Management create a new Endpoints WebService instance that connects to the currency web service. 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). The second method performs a calculation that converts an amount entered to US Dollars. For example, if you enter an amount and select GBP as the currency code, the second method converts the amount and outputs it as US Dollars.
   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 web service is for tutorial purposes only. Do not use this web service for production implementations. The web service used by this application runs on Azure. This web service should be accessible through port 80 and unless your organization has strict firewall policies in place, it should be available for use anywhere. If you need to host the web service internally, you can download the source code for the web service from the following location: http://help.k2.com/files/8554. Contact a member of your application development team for help, if necessary.

   	Field	Value	Notes
   Service Instance
   1.	Display Name	K2 Tutorial Currency Web Service	If you are working in a shared environment, include your initials in the display name to make the name unique and easily identifiable to you.
   2.	Description	This is the service instance for the sample currency web service used in the Expense Claim tutorial.
   3.	Service Type	Endpoints WebService
   Service Authentication
   4.	Authentication Mode	ServiceAccount	You will use the credentials of the K2 service account to connect to the target web service. When using the service account authentication mode, the service account must have the necessary permissions to interact with the data source. Be aware of this when registering a new service instance in your own environment.
   Service Keys There is only one service key value to set in this step (WebService URL).
   5.	WebService URL	http://k2learning.azurewebsites.net/ExchangeRates.asmx	This is the URL of the target web service you will connect to.
   6.	Generate SmartObjects for this Service Instance	UNCHECKED	You will manually create a SmartObject in a later step.

Create an advanced SmartObject with methods to list the currency types and convert the currency value to US Dollars

In the next steps you create the Expense Claim Currency Code advanced SmartObject. By creating a SmartObject from scratch, you can create your own methods and properties and tailor them specifically to your application. You create two methods based on service objects from the K2 Tutorial Currency Web Service service instance. They are as follows:

• List Currencies: This method returns a list of predefined currency codes. (You can use this method in an expense claim form where the form user needs to select the currency of the reported expense.)
• Calculate USD Amount: This method performs a calculation that converts an amount for a given currency on a specific date to US Dollars, using the applicable exchange rate for that date. (You can use this method on a form to auto-calculate the equivalent US Dollar amount for an expense entered in another currency.)

2. Create an advanced SmartObject in K2 Designer.
   1. In K2 Designer click create SmartObject.
      
   2. Configure the properties for the new SmartObject using the table below as a guide.
      

      Field	Value	Notes
      Name	Expense Claim Currency Codes
      Description	This SmartObject provides currency look-up methods for expense claims.
      Category	Select a category for the new SmartObject. In this scenario the category is Denallix.
      Type	Advanced SmartObject	You will point this SmartObject to the web service service instance that you created earlier.
      Workflow Use (if shown)	(Not Checked)	This is a legacy setting and is not needed for this application. You may or may not see this setting, depending on your version of K2.

      
      
   3. Click Create.
3. Add a new method called List Currencies that points to the following service object method: K2 Tutorial Currency Web Service > ExchangeRates Objects > ListCurrencies() > List. Bind the returned string property to a new SmartObject property called Currency Codes.
   1. Select the Methods tab, then click Add.
      
   2. Expand the K2 Tutorial Currency Web Service and navigate to ExchangeRate Objects > ListCurrencies() and select List.
      
   3. Click Next.
   4. Change the method name to List Currencies and activate the Default list method check box.
      
      Service Objects can have more than one list method. For example, an Active Directory Service Object might have a GetUsers list method that returns all user accounts, and the Service Object 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.
   5. Click Next.
   6. Double-click the String property in the lower half of the page. The "string" return property is the property in the data source that contains the currency codes.
      
   7. Click Create.
      
   8. Specify Currency Codes as the property name. This creates the SmartObject property that receives currency codes from the web service.
      
   9. Click OK, and OK again to complete the method.
4. Configure a currency conversion method to convert currency values to US Dollar amounts. The currency web service provides a function to convert currencies using currency type, amount, and date inputs. This method performs a calculation behind-the-scenes. For example, when you enter an amount in GBP (UK pounds) it will call this method to convert the amount to USD for the given date.
   1. Click the Add button to add another method to the SmartObject.
      
   2. Expand the K2 Tutorial Currency Web Service and navigate to ExchangeRates Objects > HistoricalConversion().
   3. Click Read.
      
   4. Click Next.
   5. Rename the method to Calculate USD Amount.
      
      
      This method requires input parameters to perform the conversion calculation, then returns 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).

      For this method 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 (Endpoints WebService, for example) the service broker for that web 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.

   6. On the bottom half of this screen, click Add.
   7. Specify FromCurrencyCode] as the Parameter name, and leave the Parameter type as Text.
      
   8. Click OK.
   9. Add another parameter named FromAmount of type Decimal. Click OK.
      
   10. Add another parameter named Date of type Date/Time. Click OK.
       .
   11. 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 will be hard coded to USD. Click Next.
       
   12. In the Add Method page you see the four ServiceObject method input parameters. These are the parameters discovered in the K2 Tutorial Currency Web Service object. Map the three parameters that require values at runtime for the conversion to take place. The fourth parameter is the ToCurrencyCode parameter and you hard-code that value so that it is always US Dollars.
   13. Select the Date parameter, then click Assign.
       
   14. 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.
       
   15. 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.
       
   16. Repeat the same procedure to map the FromCurrencyCode method parameter to the FromCurrencyCode SmartObject method parameter.
       
   17. Select ToCurrencyCode, then Assign it to a Specific value. Specify USD as the value.
       
   18. Once the currency conversion is complete, the HistoricalConversion method returns a Decimal value. Like you did with the List Currencies method, you create a new SmartObject property for the returned value in your Expense Claims Currency Codes SmartObject.
   19. 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.
       
   20. Click Next, then Finish to complete the method wizard.
       
   21. You should now have two methods for the advanced SmartObject. Click Finish to complete the SmartObject configuration.
       
5. Test the List Currencies method using K2 Management.
   1. In K2 Management, navigate to Categories > Denallix and select the Expense Claim Currency Codes SmartObject.
      
   2. Select the List Currencies method and click Execute.
      
   3. You don't need any input values, so click Execute.
   4. The SmartObject returns a list of currency codes from the web service.
      
6. Test the Calculate USD amount method in K2 Management, providing inputs for currency type, amount, and date.
   1. Select the Calculate USD amount method and click Execute.
   2. Specify GBP (UK Pounds) as the FromCurrencyCode, 100 as the FromAmount, and specify today's date as the Date. (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.) Click Execute.
      
   3. The web service takes the inputs and returns the amount converted into US Dollars.
      

Review

You created an Endpoints WebService instance to connect to a sample currency web service. Then you created a SmartObject that uses the properties and methods exposed by the web service. You configured the Currencies List method, and then the Amount in US Dollars conversion method. Finally, you tested both SmartObject methods using the SmartObject Execute options in K2 Management.