Using Web Services with External Data Sources

This topic describes external data and web service support, including associating scripts with the data, for new business objects.

This topic does not apply to existing business objects. To use the processes described here, you must create a new business object and apply the processes to that newly-created business object.

•About Working with External Data

•About Working with DSM as an External Data Source

•Prerequisites

•Creating an External Data Connection

•Troubleshooting

•Example: Creating an External Business Object to Access External Data Using Web Services

About Working with External Data

Many times, customers have data in systems outside of Service Manager, such as DSM or SalesForce.com, that needs to be integrated with Service Manager. Prior to Service Manager Release 2015.2, customers had to import that data; however, once the data was imported, it became stale. Also, the imported data could be very large and unnecessarily increase the size of the Service Manager database.

With this new process, you can have access to data in other systems without having to actually import the data into Service Manager. This access is accomplished by using web services.

With this process, you can use web services and scripts to create a mapping of the data from the other application to Service Manager. This allows you to pick and choose which data to integrate and what format to use and to use external data with different properties. From the script, you can make service calls to talk to the external application to get their data and bring it into Service Manager.

The data in the external application may be in a different format than the data in Service Manager, and there may be more fields that what Service Manager needs. The mapping does not have to be one-to-one. You can select the external data to import and configure the mapping. For example, the data in the external application may have 100 fields, but Service Manager only needs to work with 10 fields. Service Manager can import only those 10 fields and can map them to the associated fields in the business object in Service Manager.

About Working with DSM as an External Data Source

One of the most common external data sources that works with Service Manager is Desktop and Server Management (DSM). You can improve the integration between Service Manager and DSM by following the processes in this topic.

To drive a more useful integration with DSM, Service Manager needs to be able to view the data that is stored in DSM. To be effective, this should be done in such a way that changes made in DSM are automatically reflected in Service Manager. The way that Service Manager accesses DSM is through web services.

For more information about the new DSM integration, see Initially Configuring the New DSM Integration.

Prerequisites

We recommend that you have the following knowledge for working with this process:

•Familiarity with Service Manager and its database.

•Familiarity with the external application and its database.

•Programming skills and knowledge of JavaScript, for writing the scripts and using the web services.

Creating an External Data Connection

Follow these steps to work with an external data source:

1.Create an external business object.

Ensure that you check External and enter information in the External Object Synchronization section. See Creating a Business Object.

If you want the external business object to be a validation business object, when you create it, ensure that you click Pure Validation Object.

2.(Optional. Only if you created a validation business object.) Create a pick list that uses the external business object that you just created.

See Creating a Pick List. However, the constraints for the pick list must be all either AND or all OR. You cannot mix constraint types, nor can you use nested constraints.

Every time that you access the pick list, the application checks to see if it is a synchronized external business object.

•If it is a synchronized external business object, the application checks to see if the external data is available locally.
If there is no external data or if any of the external data is stale, the application triggers the script to get refreshed data to populate the pick list with. If the data exists and is not stale, the application does not trigger the script.

•If it is not a synchronized external business object, the application triggers the script to get the data to populate the pick list with.

3.Associate a script with the external business object. There can only be one script per business object use case. (A use case can be a form, list, report, workspace, etc.) This process is based on the information in Working with Web Service Script Integration.

Add a new external business object integration. See Adding an Outgoing External Business Object Integration for complete information.

As part of adding a new external business object integration, create a service reference. See Adding an Incoming Service Reference.

4.Create a top-level tab for this new external business object. See Defining Top Level Tabs.

5.You can optionally create a quick action to trigger the script. Use the Run Web Service quick action template to create the quick action. See Run Web Service Quick Action.

Troubleshooting

•Viewing the Logs

•Refreshing the Cache

Viewing the Logs

There is a new log type starting in Service Manager Release 2015.2 called Script. See Working with Logs for more information.

To view the information from the log on your monitor, add the following snippet to the bottom of your code:

console.log();

console.debug();

console.error();

You can also check the log at C:\Logs\AppServer.log.

Refreshing the Cache

You can also go to the Cache Management workspace, and in the Business objects that marked as external synchronized field, select the external business object. Click Invalidate synchronized data to mark all of the existing records as stale. This forces the application to go to the external application for the data the next time that you access the data.

Example: Creating an External Business Object to Access External Data Using Web Services

•Creating the Web Service Integration

•Creating a Service Request to Demo the Integration

Creating the Web Service Integration

The following is an example of using web services to allow a user to enter a country name and have the application return the country code.

1.Go to the Business Object workspace and create a new standalone business object. (See Creating a Stand-Alone Business Object for more information.)

For the business object name and display name, enter WS_Country.

Check External.

Check Synchronized, set the Refresh Interval parameter to 10, and set the Time To Live parameter to 60.

Check Pure validation object.

2.Go to the Fields tab. (See Creating a Field for more information.)

Add a new text field called ISOCode that is Unicode Text, variable, max 128, check Unique, and uncheck Nullable.

Add another text field called Name that is Unicode Text, variable, max 64, check Unique, and uncheck Nullable.

3.Go back to the Details tab.

In the External Primary Key field, select ISOCode_Unique.

Click Auto Generate UI to automatically create a new form associated with the WS_Country external business object.

4.Go to the Pick Lists tab.

Click Add new....

For the list name and display name, enter WS_Country.

Select WS_Country from the Get list data from field and select Name for the Display field, Value field, and Sort by field fields.

5.Go to the Roles and Permissions workspace.

Click Admin and then click the Top Level Tabs tab. Click Add New Tab and click Object Workspace.

Enter WS_Country in the Name field, select WS_Country in the Object field, and select WS_Country.Autogenerated in the Layout field.

6.Go to the Scheduled Jobs workspace.

Add a new hourly schedule.

Name it WS_Country and set a start time, end time, start date, end date, and set the Recur Every field to 1.

7.Go to the Web Service Connection (BETA) workspace.

Click New External BO Integration.

On the next page, select WS_Country for the External BO Name field.

On the next page, for the Service Reference field, select Add new.... For the Service Reference field, enter Country Info Service.

In the Service Address field, enter http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL.

Select the ListOfCountryNamesByCode method.

Paste the following into the Scripts field:

// web service call

console.info("Script starts: WS_Country - CountryInfoService - ListOfCountryNamesByCode");

var serviceCall = "CountryInfoService";

var serviceRef = "Country Info Service";

var serviceInstance = GetWebService(serviceRef, serviceCall);

var methodCall = "ListOfCountryNamesByCode";

var paramValues = [ null ];

var result = serviceInstance.InvokeMethod(methodCall, paramValues);

function GetCountries(isocode, name)

{

this.ISOCode = isocode;

this.Name = name;

}

var json = [];

for(i=0; i<result.length; i++)

{

json.push(new GetCountries(result[i].sISOCode,result[i].sName));

}

SynchronizeAllHeatData('WS_Country',['ISOCode'],json);

console.info("Script ends: WS_Country - CountryInfoService - ListOfCountryNamesByCode");

8.Click Next and for the Schedule List, select WS_Country.

9.Click Next and then click Publish & Run Now.

Creating a Service Request to Demo the Integration

1.Go to the Request Offering workspace and create a new request offering:

Select Demo Service for the service and enter WS_Country for the name. Choose any category.

Add a drop-down field called Country and a text field called ISOCode.

Edit the Country field and under Pick List: None, select the WS_Country pick list (validation list). Under Properties, set the Unique ID field to WS_CountryCombo.

Edit the ISOCode field and under Default Value, select Expression and for the Triggered by field, select WS_Country.

Click Next twice.

Click Add to add a new organizational unit. Select an org unit. Change the Status to Published.

2.Log in as a Self Service user. Go to the Service Catalog workspace.

3.Click the WS_Country request offering and make sure it opens.