Core Components of the ERP Connector

Article
05/05/2014

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The core components of the ERP Connector Solution Starter for Microsoft Office Project Server 2007 are the Connector, ConnectorService, and ConnectorTool assemblies. The Connector assembly contains the common functionality required to integrate between an ERP system and Project Server and to manage the plug-in components; the ConnectorService and ConnectorTool execute the ERP Connector.

This topic contains the following sections:

Connector Class Library
- Logging
- Loading and Saving Configuration Files
- Loading and Managing Plug-Ins
- Creating Web Service Proxies
- Authentication
- Managing and Synchronizing Entities
- Managing Requests
Connector Tool
Connector Service

For a diagram and information about the general architecture, see ERP Connector Architecture. For developer documentation of the classes, methods, properties, and events of the ERP Connector, see the ERPConnectorComponents.chm file in the Project 2007 SDK download. For class diagrams, see the class diagram.cd files in each project of the ERP Connector 2007 Visual Studio solution.

Connector Class Library

The Connector class library is the main part of the ERP Connector solution. It contains the primary logic and functionality of the complete solution and is extensible with plug-in components. The Connector class library (in the ERPConnector.Connector.dll assembly) includes two relatively independent but closely connected parts:

Base classes and structures:
- Extend ERP Connector by adding plug-ins.
- Execute the ERP Connector and plug-ins.
- Maintain and synchronize data with Project Server.
- Transmit request data exported from the mySAP™ ERP system to the plug-ins.
- Load and save user-level configuration files for the plug-ins.
- Log events from the application and plug-ins.
Derived classes:
- Create Web service proxies.
- Load and save configuration files.
- Provide a simple user interface to access protected sections of the application-level configuration, such as user name and password.
- Synchronize lookup tables and enterprise custom fields on Project Server with the plug-in configuration files and data in the XML requests from mySAP ERP.

For information about application-level configuration and user-level configuration of the Connector class, see Configuring the ERP Connector.

Logging

The Logger class writes messages from the Connector and plug-in components to event logs specified in the configuration files. Each message also has a message severity. If the severity is below that specified by the configuration file for the component, the Logger ignores the message. Otherwise, the Logger writes the message text and severity to the event log.

To ensure that the application can continue execution, the Logger does not throw an exception even if a logging error occurs or the logging fails.

Loading and Saving Configuration Files

The ERP Connector uses a custom configuration manager, which provides user-level and configuration application-level configuration files per type instead of only per executable. This makes it possible to separate the configuration of the Connector library, the plug-in libraries, and the execution tools. The configuration manager enables different components to have specific configuration settings.

The configuration manager extends the ConfigurationSection class in the System.Configuration namespace with a few fields. The default implementation of the System.Configuration classes handles most of the configuration file sections and properties.

Loading and Managing Plug-Ins

The Connector library includes a container class for managing plug-ins together with a base class for the ERP Connector plug-ins. A plug-in must be derived from the PlugInBase class to be properly detected, loaded, and invoked by the Connector. The PlugInBase class also provides useful functionality for the derived plug-ins and makes the implementation of plug-ins easier and faster.

Finding plug-ins. The PlugIns container class searches for assemblies in the same directory as the ERPConnector.Connector.dll assembly or in the plug-in directory specified in the shared Connector.config file. The PlugIns container then searches the assemblies for public types that are derived from PlugInBase. If a type such as SapHRPlugIn is instantiable (not abstract) and provides a public constructor with the correct signature, then the PlugIns container checks (in the user-level Connector.config file) whether the plug-in can be loaded, loads the plug-in, and adds it to the processing queue for incoming requests.

Priorities for loading and processing. All plug-ins have a loading and a processing priority. The loading priority specifies the order in which plug-ins are loaded; the processing priority specifies when they can receive an incoming request. The loading and processing priorities can be different. For example, the plug-in that is loaded first can be the last to receive a request. If two or more plug-ins have the same processing priority, they are invoked in the order of their loading. If two or more plug-ins have the same loading priority, the loading order depends on the assembly and type names.

Validating requests. A plug-in must provide an XSD schema for validating incoming requests. If a request validates against the schema, the plug-in must process the request. If a request does not validate against the schema, the plug-in ignores the request. If a plug-in detects that a request contains data that is not valid, it can end the processing of the request at any time and return an error code to the Connector. The validation schema is also used to specify which methods are accepted by a plug-in. For a description of how requests are handled, see Managing Requests.

Handling exceptions**.** In case of an error, a plug-in should throw an exception derived from the base ConnectorException class. If a plug-in throws any other exception, by default the Connector marks the plug-in as faulty and unloads it before the next request processing cycle. You can change the default behavior for unloading plug-ins by setting the Unload·Faulty·Plug-ins attribute to false in the shared Connector.config file.

Note
When you are developing a new plug-in, it can help prevent inconsistencies and cause fewer problems if you unload a plug-in on an unpredicted failure or ignore any following requests for the same plug-in.

Creating Web Service Proxies

Because the ERP Connector uses the Project Server Interface (PSI) to communicate with Project Server, it frequently needs different PSI Web service proxies to be created and configured. The WebServices container class handles authentication before any of the PSI proxies are requested. The WebServices container also creates and maintains all PSI proxies and disconnects from Project Server when the Web service proxies are to be used no longer.

Authentication

The Connector is able to authenticate itself on Project Server by using Windows authentication or Forms authentication. The Connector uses the authentication method and credentials specified in the user-level Connector.config file.

If the Connector is run from the ERP Connector Service and Windows authentication is specified, then the Connector uses the Windows account of the service to connect to Project Server. If Forms authentication is specified, then the ERP Connector uses the encrypted user name and password from the configuration files.

Managing and Synchronizing Entities

The ERP Connector provides the Entity and EntityContainer base classes to maintain different kinds of entities (projects, tasks, resources, custom fields, and lookup tables) and synchronize them with Project Server. The EntityContainer class provides methods to create new entities, to load entities from Project Server, and to synchronize entities with Project Server. The EntityContainer class also maps the GUID of an entity with its name. The Entity class stores the entity properties and provides the base logic for synchronization of the entity between the ERP Connector and Project Server.

Synchronization process**.** In the synchronization process, the EntityContainer uses two datasets. The source DataSet contains the data received from the server and the delta DataSet contains the data to be committed to the server. An entity received from the server has its source row attached to the synchronization process.

When an EntityContainer is created, the derived class must specify the synchronization master and synchronization modes. The synchronization master specifies whether the local container or Project Server should keep the entity property values if both sides have valid property values.

The synchronization mode specifies how the synchronization master and the synchronization slave should merge their data. Different combinations of settings can, for example, make an EntityContainer completely remove entities from the server, merge new entities with existing entities, or update only existing entities.

Implementing a custom entity**.** To implement a custom entity, derive a class from the Entity base class, and then extend the class with fields and properties that specify the data for one entity. The derived class should provide an overloaded constructor to create new entities from different sets of parameters.

The derived class should also override the virtual method used to update an entity from an equivalent reference entity with the same name or GUID. The update process copies custom properties from the reference entity.

You must also derive a class from the EntityContainer base class to create a container that can maintain a collection of the custom entities. The container class is responsible for communication and synchronization with Project Server.

The EntityContainer base class provides virtual methods that must be overridden to receive data from the server, generate new entities, fill a delta DataSet from the entities in the container, commit the delta DataSet, and update the entities on Project Server.

Synchronizing Enterprise Custom Fields and Lookup Tables

For examples of how to use the Entity and EntityContainer base classes, see the CustomField and CustomFields and the LookupTable and LookupTables derived classes in the Connector project in the ERP Connector 2007 Visual Studio solution. The derived classes manage enterprise custom fields and lookup tables required by the connector plug-ins.

When the plug-in is loaded, all of the custom fields and lookup tables it requires are added to the CustomFields and LookupTables containers, The containers synchronize with Project Server to create missing custom fields and lookup tables and to verify that existing custom fields and lookup tables have the proper data types and formats.

When a plug-in is executed, it can use the containers to resolve the names of custom fields and lookup tables and to create, update, or read custom fields for various entities.

Managing Requests

When ERP Connector detects an XML request file, it marks the file as hidden and loads the file as plain text into a Request object. The ERP Connector then hands the Request object to the PlugIns container, which tries to process the request by using all available plug-ins. The plug-ins process requests in the order specified by the processing priority.

To process the request, the PlugIns container invokes a plug-in and passes it the Request object. While the plug-in reads the request, it validates the request against the schema.

The XML request files have the following general format:

<Request>
   <Method>
       . . 
   </Method>
</Request>

In the ERP Connector sample implementation, the Method element is one of the following:

SapHRPlugIn recognizes ProcessHRDataSAP.
SapCOPlugIn recognizes ProjectCreateSAP.
SapFIPlugIn recognizes GetActualsSAP.

If validation fails before the Method element is read, then the plug-in either ignores the request or returns a failed state. The Method element only specifies the type of request. A plug-in is more efficient if it can validate the type of request early in the process.

If the plug-in accepts the request, it parses each element and converts the element into a RequestElement object. A request element can contain child elements grouped by name, or it can contain a value instead of child elements. The RequestElement class simplifies access to the data stored in request files. For example, to access the element value at the path Request/TestElement/Group/Subgroup/SomeKey, you can write the following code:

value = request[ "TestElement" ][ "Group" ][ "Subgroup" ][ "SomeKey" ];

If a plug-in successfully loads and validates a request, it passes the parsed request object tree to the OnProcess handler. The OnProcess handler can access and verify single request values, receive or commit data from the server, and do required computations. The handler returns a state (true or false) that indicates whether the request processing is successful.

Backing Up Requests

When a request is processed by all available plug-ins, the ERP Connector evaluates the return codes to decide what to do with the request file.

Leave in the drop folder. If all plug-ins ignore the request and the Leave·Ignored configuration setting is true, then the ERP Connector leaves the request file in the drop folder. If Leave·Ignored is false, the ERP Connector moves the request to the folder for rejected requests.

The Leave·Ignored setting can be useful when you are developing new functionality in a plug-in for multiple request file variations and you do not want the ERP Connector to always move unprocessed request files to the rejected folder.
Move to the accepted folder. If at least one plug-in accepts the request, the ERP Connector moves the request file to the folder for accepted requests.
Move to the rejected folder. If no plug-ins accept the request and at least one plug-in rejects the request, the ERP Connector moves the request file to the folder for rejected requests.

In all cases, the Hidden property of the request file is cleared to make the file visible.

If the configuration setting Check·Duplicates is true and the folder for accepted or rejected requests contains a file with the same name, the ERP Connector compares the content of both request files. If the content is the same, the ERP Connector creates a unique name by adding the current date and time to the backup file name.

If Check·Duplicates is false (the default), then the ERP Connector always adds the current date and time to the backup file name without checking whether there is a duplicate request. The Check·Duplicates setting can be useful when you are testing the ERP Connector with multiple request files and you do not want the connector to always create new backup files and change the file names.

For a reference of configuration settings, see Configuring the ERP Connector.

Connector Tool

ConnectorTool.exe is a command-line application that starts the ERP Connector. There are no configuration files for the Connector Tool; you specify options with command-line switches and arguments (Table 1).

Parsing Arguments

When the Connector Tool is executed, it copies all arguments into a key-value dictionary. The lower-case copy of an argument is the key and a case-sensitive copy of the same argument is the value. Each accepted argument is removed from the dictionary when the argument is processed.

Table 1. Command-line arguments for the Connector Tool

Switch or Argument	Description
/help or /?	Displays usage of the Connector Tool with a list of accepted arguments.
/setup	Runs the Connector Tool in setup mode instead of request processing mode. In setup mode, the Connector Tool shows a connection setup dialog box, saves setup values in the user-level Connector.config file, and then exits without processing any request files.
/service	The ERP Connector Service runs the ERP Connector in service mode. In service mode, the ERP Connector does not present any dialog boxes or error messages in a user interface, even if the Debug·Updates configuration flag is true.
"path" [. . .]	Specifies one or more directories to search for XML request files. A path argument can also be a path to a specific file. You should enclose each path in quotation marks to ensure that the Connector Tool does not interpret a path that contains a space as two paths.

Running ERP Connector

The Connector Tool must create an instance of the ERP Connector as a Connector object before it processes any request files or directories. If no request files or directories are specified, the Connector Tool calls the Connector.Process method with the current directory. If one or more path arguments are valid, the Connector Tool calls the Process method for each file or directory.

The Connector Tool also counts the number of errors that occur (as ConnectorException objects) when the Connector processes requests, and then returns the number as the error code on completion.

Connector Service

The ERP Connector Service is a Windows service application that watches a drop folder for incoming request files. If it detects a request file, then the Connector Service invokes ConnectorTool.exe /service "request directory path" to process the request. The ERP Connector itself enumerates, loads, processes, and backs up the request files.

Configuration settings for the Connector Service include ConnectorToolPath and RequestDirectory. For more information, see Configuring the ERP Connector.