Connector for Web Services

Connector for Web Services

The Web Services Connector allows you to connect to various systems with an exposed Web Services interface. The Connector and default projects are available from Microsoft Download Center.

The Web Services connector is used as a platform for the following systems:

• SAP ECC 5.0 and SAP ECC 6.0
• Oracle PeopleSoft 9.1
• Oracle eBusiness 12.1

For additional information about these systems, please refer to the TechNet documentation for each system. This article documents the Web Services Connector as a platform and common functionality.

Summary

• Web Services based on SOAP

• Configured through Web Services Configuration Tool

• Full Import, Delta Import
• Add, Delete, Replace (Update)
• Set Password, Change Password
• Test parameters

• Configured through Web Services Configuration Tool

Interface with connected data source

The Web Service connector integrates identities through Web Service operations with Forefront Identity Manager (FIM) 2010. The connector requires the Web Service Project file to connect with the correct data source. This project can either be downloaded fromMicrosoft Download Center or can be created by using the Web Service Configuration Tool.

When FIM Synchronization Service invokes the Web Service connector, it loads its configured project file (.wsconfigfile). This file helps it to recognize the data source’s Endpoint that should be used to establish a connection and the workflow to execute in order to implement a FIM operation. To execute the configured workflows, the web service connector is leverages the .NET 4 Workflow Foundation run time engine.

Permissions in connected data source

The permissions needed are different depending on data source. Please refer to respective TechNet document for further information.

Connector update history

Requirements, before you begin, and installation

Prerequisites for Web Service Connector

Following applications should be present on your system before you start installing the WebService Connector.

1. For the Web Service Connector:

• FIM Synchronization Service
• FIM2010 Update 2, FIM2010 R2, or later.
• .NET 4.0 Framework

1. For Web Service Configuration Tool

• NET 4.0 Framework

To be able to create a Web Service Connector the configuration files (.wsconfig) must be present in the extensions folder.

Installation of the Web Service Connector

The Connector and default projects are available from Microsoft Download Center.

Web ServiceConnector MSI: This MSI exposes two features:

• Web ServiceConnector Runtime which will install the core Connector, its dependencies and the packaged Connector.
• Web Service Configuration Tool that will install the Web Service Configuration Tool.

The configuration tool can be installed without having the Synchronization Service installed. This allows configuration on a separate computer.

Default Projects

Additional default projects are shipped with the Web Services Connector. These are available as self-extract EXE files. You may download web service Connector project as appropriate to your requirement.

After the installation is complete the different components with their binaries are installed at below folder location on your system.

Additional Permissions

Project file can be saved and opened from any location (with the appropriate access privileges of its executor); however, only project files that are saved to Synchronization Service\Extensionfolder will be able to get selected in the Web Service connector wizard accessed through FIM Sync UI.

The user running the Web Service Configuration tool will require the following privileges:

•Read/Write permissions to the Synchronization Service Extension folder.

•Read access to the registry key HKLM\System\CurrentControlSet\Services\ FIMSynchronizationService\Parameters

Configuration of Web Service Connector

Create Management Agent

Connectivity

On the Connectivity screen, select the Web Service Connector projectto be used. Provide the Host and Port.

Global Parameters

Use the login credential procured from Web Service Admin for connecting to the Host. You must select the following

:

• If the location of data source observs Daylight Saving and the data source is configured to automatically adjust to daylight saving settings then you must check the box for Data Source is configured to automatically adjust clock for Daylight Saving Time.
• If you want to trigger the test connection workflow from this connector then you must check the check box for Test Connection.

Note: Oracle EBS default project is missing the “Data Source Server time zone” and “Data Source Server date format” parameters. Therefore, in Full Import workflow the last import time is not preserved, due to which delta import functionality will not work as expected.

Object Types

Select the object type(s) you want to work with. The supported object types will be different depending on the connected system.

Attributes

Check all the mandatory attributes for the selected objects and the attributes you need to work with.

Follow the installer instructions to complete the process.

Web Services Configuration Tool

Creating a new Project in Web Service Configuration Tool

The Web Service Configuration Tool allows you to create a new .wsconfig project as well as use the downloaded project template / default project from Microsoft Download Center.

These are the high level steps to create a new Web Service project. Detailed steps can be found in the next section.

1. Open Web Service Configuration Tool. It opens a blank project.
2. Go to File menu and click New (Figure a).Or you can click on the shortcut just below the File menu (Figure b).

Figure a Figure b

1. Click on Discovery and then click Add. This control allows discovering the exposed web service. For detailed steps, see Discovering Web Services.

Here, you must provide the new web service name and WSDL path which will retrieve the exposed services, end-points and operations.

1. Next step is to define the connector space schema, which is achieved by creating the Object Type and defining the attributes. Click Object Types in left pane and click Add.

Enter a valid Object Type name and click OK. For detailed steps, seeConnector Space Schema Configuration.

1. When the object has been created, default blank workflows are created corresponding to Synchronization Service actions.

1. Next step is to configure the workflows for your object type. The Web Service Configuration Tool facilitates you to create four different workflows:

• Import: To import data from data source.
• Full Import
• Delta Import
• Export: To export data to data source
• Add
• Delete
• Replace
• Password: To perform password management for the user (object type)
• Set password
• Change Password
• Test Connection: To configure workflow which when invoked checks if the connection is successfully established with the data source.

For more details see, Workflows in Web Services Configuration Tool.

1. Click on the workflow that you want to configure. Go to the bottom section of central workflow designer and declare the variables. Arguments are already defined and Imports are already specified and are specific to the activities. Below is an example of declared variables. Set the properties in the right hand pane.

1. The toolbox in right pane holds all the custom workflow specific activities (See the reference information section for more information) that you require for configuration. Assign the values to the variables that you are going to use for your logic.

1. Save this project at the location: %FIM_INSTALL_FOLDER%\Synchronization Service\Extensions. It will be saved as .wsconfig file.

Discovering Web Services

Discovery is the process of accessing a Web service through a WSDL (Web Services Description

Language) and retrieve its services, endpoints and operations it provides. Services, endpoints and operations are used by the Web Service Connector to access the data-source and synchronize identities with Forefront Identity Manager (FIM).

Discover a new service

Follow below steps to perform a new discovery.

1. Open Web Service Configuration Tool and Click on Discovery in the left hand side tree.
2. Click Add. Below screen is displayed. You should provide the new service name, the WSDL path and the namespace:

Click Next. Specify the authentication type and use the credentials to continue.

1. The WSDL path is accessed to retrieve the service information and the list of exposed functions is displayed.

If the WSDL path entered is incorrect then the Web Configuration Tool fails to retrieve the service information and throws following error.

1. Once the discovery is performed, then it lists the endpoint and the operations that are discovered.

Click Finish.

When Finish button is pressed, compilation is performed. Compilation is a process of compiling the data contract assembly, which may be a time consuming operation. User will be informed about compilation errors if there will be any.

After the discovery is performed, the tool displays the below screen.

You can also edit or remove the discovery by clicking on Edit and Remove buttons on the screen respectively.

1. The discovery contents that include Endpoints, Operations and Operations arguments may be referenced by workflows. Any change (Edit / Remove) in discovery should be done carefully in order not to harm the existing workflows. It is recommended to check the workflows after discovery changes to confirm no errors were caused by the change.
2. You cannot discover two Endpoints with the same name in the same project.
3. For SAP specific *.wsconfig project, while updating Employee records we must lock (Enqueue) them before doing any modification and unlock (Dequeue) then after changes. All these operations must perform in same session and to make it possible we must enable cookies in our WS call. By default it is OFF. Please find below the following steps to allow cookies in our WS call :-
4. Change the wsconfig project file extension to *.zip and extract it to a folder.
5. Open cfg.config and look for allowCookies="false". Change it to true
6. Zip again the complete folder and rename it with file extension *.wsconfig.
7. You are ready.

Connector Space Schema Configuration

The schema configuration includes the listing the Object Types and Attributes for a specific implementation. You can define the object types and the defining attributes for your project in Web Service Configuration Tool.

Create/Edit Object Type

Follow below steps to create an object type:

1. Open Web Services Configuration Tool and Click Object Types in left hand tree.

Click Add and provide unique name for the new object.

The object name can include following:

• Characters a-z, A-Z, 0-9, hyphen (-), colon (:) and underscore (_).
• The first character of an object type name cannot be a hyphen (-).
• The object type name cannot contain two or more consecutive hyphens (--).

1. Click OK. The new Object Type is created.

Since, workflows reference object types and attributes, they are recommended to be defined only after the schema configuration is complete.

Create/Edit Attributes

The next step after creating an object type is to define attributes for the Object Type. Follow below steps for creating attributes:

1. Select the Object Type for which you want to define the attributes. Click Add. It shows the Attributedialogue.

The attribute name can include following:

• Characters a-z, A-Z,0-9,hyphen (-), colon (:) and underscore (_).
• The first character of an attribute name cannot be a hyphen (-).
• The attribute name cannot contain two or more consecutive hyphens (--).

1. You can edit or remove attribute, by selecting; the attribute and then clicking Edit or Remove respectively.
2. You must configure at least one attribute as an Anchor attribute. If no anchor attribute is defined then you will encounter errors while configuring a web service connector.

You may specify, if you want it to be multi-valued and whether it should behave as an anchor. Click OK. The new attribute is created.

After the schema configuration is complete, you can continue with the configuration of Workflows in your project.

1. If you have changed the schema through the web service configuration tool , you should also validate that workflows are not including errors in a case where they have referenced to object type / attributes you have changed.
2. If you have changed the schema through the web service configuration tool and saved it to an active web service connector that is referencing this project, then you must refresh the schema for the Connector in the FIM Synchronization Service UI.

Workflows in Web Service Configuration Tool

Workflow files are a series of activities that are used by the Web Services Connector at run time in order to implement an appropriate FIM operation. The tool allows you to configure four types of workflows:

• Import
• Export
• Password
• Test Connection

The operation flow configuration is an interface to configure the above workflows through a series of system and custom workflow activities:

Import Workflow

This operation includes two types of workflows: Full Import and Delta Import.

Export Workflow

Export workflow involves the exporting of data from FIM to connected directory. It supports three types of operations: Add, Delete and Replace. You can configure them as per your requirement.

Password Workflow

This operation allows configuring the workflows associated with user passwords. There are two types:

• Set password: This operation is setting a user’s password on the data source.
• Change password: This operation is changing a user’s password on the data source only after his existing password has been successfully confirmed.

Test Connection

Test connection workflow allows you to configure a workflow to check if the connection with data source server is successfully established.

The test connection workflow is run when the Test Connection checkbox is selected and you select “Next >”.

Password Management

The Web Service Configuration Tool enables you to manage the password for the users (object type) by defining a workflow. The password for an employee can be managed through the user corresponding to the employee.

You can perform two operations under password management:

Set Password:

In this case, the user can set a new password for his account. It does not require the old password to proceed.

Change Password:

In this case, user may want to change the password or he is prompted to change password after a specified time. For this operation to happen, both old and new passwords are mandatory.

Troubleshooting

By default, Web Service Connector logging is disabled. In order to turn ON logging, you should perform following operation:

1. Open file FIM_INSTALL_DIR\Synchronization Service\Extensions\Logging.xml
2. Goto the “LoggingLevel” section and change the value to 2 or 3.

1. The different logging values represent the following:

1. Value 2 – High logging – High important events (e.g. Exceptions) are logged.
2. Value 3 – Verbose logging – All the activities performed are logged.
3. Any other value than the above represents logging disabled.

1. Save the changes.

Log file is written to folder: FIM_INSTALL_DIR\Synchronization Service\Extensions

Log file name: WebServiceConnector.log

Log File size restriction:

By default, maximum log file size is restricted to 10 MB. If it is exceeded a new log file is created and the old log file is renamed to LogFileName.Index.log. After the first rotation the next 3 rotations of web service connector log file will result in following log files at the extension folder:

WebServiceConnector.log – current log

WebServiceConnector.1.log – first history log file

WebServiceConnector.2.log – second history log file

WebServiceConnector.3.log – third history log file

1. It is highly recommended to exclude the log file name from your Antivirus scanner to avoid the Antivirus scanner from engaging the file at the same time it is being accessed by the connector or by the web service configuration tool.
2. Log Level configuration is sampled by the Web Service configuration tool at the time of its first execution. Any changes made to Log Level configuration at the time the tool is running will require the restart of the Web Service configuration tool in order to take effect.

Performance Testing