Configuring 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.

After installing the ERP Connector Solution Starter for Microsoft Office Project Server 2007 on the Project Server computer, you must run the Connector Tool once to initialize all of the configuration files and to create the necessary lookup tables and custom fields on Project Server. To change the configuration settings, you edit the XML configuration files.

This topic includes the following sections:

Initializing ERP Connector
- Changing the Request Drop Folder
- Changing the Custom Field and Lookup Table Mappings
- Errors in Validating Lookup Tables
Configuration File Reference
- Application-Level Connector Configuration
- SapHRPlugIn Configuration
- SapCOPlugIn Configuration
- SapFIPlugIn Configuration

Note
The previous version of the ERP Connector, for Microsoft Office Project Server 2003, includes a Web page for making configuration settings. The administration Web page for the previous version cannot be used with ERP Connector 2007 because the configuration infrastructure, the Project Server enterprise custom fields and lookup tables, and Project Web Access architecture are all changed.

The 2007 version of ERP Connector is provided as a proof of concept for the new plug-in architecture and for using the Project Server Interface (PSI). It does not include an administration Web page. To use ERP Connector 2007 in a production environment, instead of manually editing the XML configuration files, you could create a Web Part Page and install a link in the Quick Launch in Project Web Access. For information about how to hide a link in the Quick Launch except for users who have a custom permission, see Walkthrough: Creating and Using Custom Project Server Permissions.

Initializing ERP Connector

When you run the Connector Tool for the first time, it loads the available plug-in components and reads the user configuration files for the names of lookup tables and custom fields used by each plug-in. The Connector Tool then creates the empty lookup tables and custom fields in Project Server and adds information about the plug-ins to the configuration files.

There are two groups of XML configuration files:

Application-level configuration. There is a Connector.config file in the following folders:

%AllUsersProfile%\Application Data\ErpConnector\Connector\<StrongKey>\<Version>\

%UserProfile%\Local Settings\Application Data\ErpConnector\Connector\<StrongKey>\<Version>\

The Connector.config file in the All Users profile is shared with all users who can run ERP Connector on the Project Server computer.
User-level configuration. The Connector.config file in the Local Settings folder is unique for each ERP Connector user. Following are the paths to the additional user-level configuration files for each plug-in:

%UserProfile%\Local Settings\Application Data\ErpConnector\SapCOPlugIn\<StrongKey>\<Version>\SapCOPlugIn.config

%UserProfile%\Local Settings\Application Data\ErpConnector\SapFIPlugIn\<StrongKey>\<Version>\SapFIPlugIn.config

%UserProfile%\Local Settings\Application Data\ErpConnector\SapHRPlugIn\<StrongKey>\<Version>\SapHRPlugIn.config

For an explanation of how the MMConnector merge module sets the path to the configuration files, see ERP Connector Setup Projects.

Procedure 1. To initialize the ERP Connector

On the Windows Start menu, click All Programs, click ERP Connector Solution Starter, and then click Connector Tool.

Alternately, because the Connector Tool is a console application, you can run the following commands in a Command Prompt window to save a record of the standard and error output.

cd C:\Program Files\ERP Connector Solution Starter\bin
ConnectorTool > initialize.txt 2>&1

If the Connector Tool has not been previously run and the ERP Connector is working correctly, the initialize.txt file contains the following output.

SAPMSP Info: - LookupTable successfully synchronized: 
    0 LookupValues created, 0 LookupValues updated, 
    0 LookupValues deleted and 0 LookupValues ignored.
SAPMSP Info: LookupTables successfully synchronized: 
    2 LookupTables created, 0 LookupTables updated, 
    0 LookupTables deleted and 0 LookupTables ignored.
SAPMSP Info: CustomFields successfully synchronized: 
    8 CustomFields created, 0 CustomFields updated, 
    0 CustomFields deleted and 0 CustomFields ignored.
ERP Connector accepted 0 requests from C:\Program Files\ERP Connector Solution Starter\bin.

On the Windows Start menu, click All Programs, click ERP Connector Solution Starter, and then click User-Level Configuration to open the folder that contains the user-level configuration files.
Check each of the configuration files to see the information they contain. To change the operation of ERP Connector, you need to edit the configuration files. For information about the XML elements in the configuration files, see Configuration File Reference.

Changing the Request Drop Folder

The ERP Connector 2007 Service executable file is in the [Program Files]\ERP Connector Solution Starter\bin folder. When you start the service, it reads the ConnectorService.exe.config file and loads the ConnectorToolPath and the RequestDirectory settings.

You can change the request drop folder for the ERP Connector Service in the ConnectorService.exe.config file or when you manually run the Connector Tool for testing.

Procedure 2. To change the request drop folder

Open the ConnectorService.exe.config file using Notepad or Microsoft Visual Studio.
Change the value of the RequestDirectory setting. The following is the default value:

C:\Program Files\ERP Connector Solution Starter\bin\ERP Requests Drop
Stop and restart the ERP Connector 2007 Service. To do this, on the Windows Start menu, click All Programs, click ERP Connector Solution Starter, and then click Stop Connector Service. After that completes, click Start Connector Service.
On the Windows Start menu, click All Programs, click ERP Connector Solution Starter, right-click Default ERP Requests Drop Folder, and then click Properties. Edit the Target value to match the RequestDirectory value in the ERP Connector Service configuration file.
On the Windows Start menu, click All Programs, click ERP Connector Solution Starter, right-click Connector Tool, and then click Properties. On the Shortcut tab, change the Start in value to be the same path you specified in Step 2 and Step 4.
To temporarily change the request drop folder when you run the Connector Tool in a Command Prompt window, use the command connectortool "<temporary path>". You should enclose the path in quotes, to avoid argument errors when the path contains spaces, for example:

connectortool "C:\ERP Connector Tests"

Note

The user-initialized Connector.config file specifies the accepted and rejected folders for XML request files; the default values are accepted and rejected. Therefore, if the previous Connector Tool command successfully processes the 0R_0M_0S.xml request file for SapHRPlugIn, the ERP Connector deletes the request file in C:\ERPConnectorTests and creates the folder and file C:\ERPConnectorTests\accepted\0R_0M_0S_YYMMDD_HHMMSS.xml. The accepted file name includes the date and time the request is processed.

Changing the Custom Field and Lookup Table Mappings

The configuration file for each ERP Connector plug-in specifies the lookup tables and custom fields that the plug-in uses. If they do not already exist, the ERP Connector creates the enterprise lookup tables and custom fields before their first use. If Project Server contains the lookup tables and custom fields specified in the configuration file, the ERP Connector checks them and takes no action.

Procedure 3. To change the custom field and lookup table mappings

Stop the ERP Connector 2007 Service. To do this, on the Windows Start menu, click All Programs, click ERP Connector Solution Starter, and then click Stop Connector Service.
On the Windows Start menu, click All Programs, click ERP Connector Solution Starter, and then click User-Level Configuration.

The folder that contains the four subfolders for the user-level configuration files opens in Windows Explorer. The subfolders are Connector, SapCOPlugIn, SapFIPlugIn, and SapHRPlugIn.
To change the mappings, for example, for SapHRPlugIn, open the successive subfolders in SapHRPlugIn, and then open the SapHRPlugIn.config file in a text editor such as Notepad.
Using the SapHRPlugIn Configuration section as a guide, decide what attributes you want to change in the Field Mappings element.
Check the Custom Fields and Lookup Tables page in Project Web Access to ensure that the custom field or lookup table name is not already in use. If the name exists but is not being used, ERP Connector can use the existing custom field or lookup table if it has the same field type.

For example, if you want to change the SAP Organisation Units lookup table name to ERP Organization Units, and there is already an unused ERP Organization Units lookup table of type Text, you can leave it there for ERP Connector to reconfigure. ERP Connector changes the code mask to five sequences of numbers, each with length = 8 and separator = ".".

Alternately, you can delete the unused lookup table and let ERP Connector create a new one.

Edit the plug-in configuration file, to change the names of lookup tables and custom fields.

Note
Suppose a custom field such as SAP Organisation Unit ID already exists and uses the lookup table SAP Organisation Units. If you change the name of the lookup table in the configuration file, ERP Connector does not change the custom field definition to use the new lookup table. You must use Project Web Access to edit the custom field so that it uses the new lookup table.

Run the Connector Tool to create the new lookup tables and custom fields.
In Project Web Access, refresh the Custom Fields and Lookup Tables page to verify that the new entities exist.
Restart the ERP Connector Service.

Errors in Validating Lookup Tables

When ERP Connector executes, it validates all lookup tables on Project Server. If you programmatically create simple or multiple-language lookup tables on a test Project Server system and then modify values or code masks, it is possible to create inconsistencies in the lookup tables. In that case, ERP Connector cannot validate the lookup tables and fails with a SOAP exception.

For example, the following error message from ConnectorTool.exe is formatted from the output in a Command Prompt window.

Failed to execute ERP Connector: Unable to commit LookupTables data to server: 
<errinfo>
  <dataset name="LookupTableDataSet">
    <table name="LookupTableTrees">
      <row="" LT_STRUCT_UID="17113e52-ecde-4f18-9bec-3aa56e02bc59">
        <error id="11050" name="LookupTableItemDoesNotFitMask" 
            uid="5823da9f-42f1-4abd-b4e2-bc8caaf4c490" />
      </row>
      <row="" LT_STRUCT_UID="70a90e6c-8675-4118-973c-9e3c462aacd7">
        <error id="11050" name="LookupTableItemDoesNotFitMask" 
            uid="412cdafa-3191-45bc-be4a-7d4dd28c75f4" />
      </row>
    </table>
  </dataset>
</errinfo>

System.Web.Services.Protocols.SoapException: ProjectServerError(s) 
LastError=LookupTableItemDoesNotFitMask 
Instructions: Pass this into PSClientError constructor to access all error information at 
Microsoft.Office.Project.Server.WebService.LookupTable.UpdateLookupTables(
    LookupTableDataSet ltds, Boolean validateOnly, 
    Boolean autoCheckIn, Int32 language)

The Connector project in the ERP Connector 2007 Visual Studio solution contains the code that works with lookup tables. To avoid modifying the lookup table code handlers for a test system, you can find the lookup table value from LT_STRUCT_UID or find the mask GUID, and fix the inconsistent values.

Procedure 4 shows how to find values in a LookupTableDataSet or LookupTableMultiLangDataSet that are causing problems.

Procedure 4. To find a lookup table value that causes an error

Stop the ERP Connector 2007 Service. To do this, on the Windows Start menu, click All Programs, click ERP Connector Solution Starter, and then click Stop Connector Service.
On the Windows Start menu, click All Programs, click ERP Connector Solution Starter, and then click Configure Server Connection. Or, run ConnectorTool.exe /setup.
In the ERP Connector 2007 Setup dialog box, select the Debug commitment of modifications to Project Server check box, click Test, and then click Save.

ERP Connector changes the Debug Updates attribute in the Connector.config file to true.
Run the Connector Tool from the ERP Connector Solution Starter menu or from the command line.

Before ERP Connector tries to commit a DataSet for a lookup table or custom field to Project Server, it shows a DebugView dialog box with the rows and columns of tables in the DataSet.

Figure 1. Using Debug View to examine DataSet values
Find the problem values or masks using GUIDs from the error output, and then fix problems by editing the lookup table with Project Web Access. Alternately, if the lookup table is unimportant, delete the lookup table that is causing a problem.
Run the Connector Tool again, and fix lookup table errors or delete lookup tables until the Connector Tool completes successfully.

Start the ERP Connector 2007 Service.

Note
The ERP Connector Service runs the Connector Tool in a state where ERP Connector does not show a user interface. You cannot debug datasets when the ERP Connector Service starts ERP Connector.

Configuration File Reference

This section lists the names, possible values, and default values of XML elements that you can change in each section of the configuration files and describes the purpose of each element. This section does not explain the overall format of the XML configuration files or list the elements that you should not change.

All configuration settings for ERP Connector plug-ins are on a user-level. Plug-in configuration files do not include application-level configuration.

Important
Do not change the names of elements or attributes in the configuration files, unless you also change the ERP Connector code that handles custom fields, lookup tables, and mappings. Change only the values of attributes.

Application-Level Connector Configuration

When ERP Connector starts, it reads two Connector.config files for application-level configuration. There is one Connector.config file shared by all users on the Project Server computer, and another Connector.config file in the settings folder for each user, as described in Initializing ERP Connector.

Shared Application Configuration

The shared Connector.config file contains only one configuration element, named Common·Application.

Table 1. Common·Application element

Attribute	Description	Possible values	Default value
Plug-In·Path	Relative or absolute path to a directory containing plug-ins for the ERP Connector.	Any valid relative or absolute path to a directory.	Empty string ("") indicates that the plug-in libraries are located in the same directory as ConnectorTool.exe.
Unload·Faulty·Plug-ins	Sepcifies whether the connector should unload plug-ins that throw an unexpected exception.	true, false	false

User-Level Application Configuration

Tables 2–6 explain the elements in a user-level Connector.config file.

Table 2. Authentication element

Element	Description
CipherValue	Encrypted combined value for the authentication method (Windows authentication or Forms authentication), and the user name and password for Forms authentication. To change the value, run ConnectorTool.exe /setup, or click Configure Server Connection on the ERP Connector Solution Starter menu.

Table 3. Common User element

Attribute	Description	Possible values	Default value
Server	URL of Project Web Access instance to use with ERP Connector.	Any valid Project Web Access URL.	http://ServerName/pwa
Language	Locale ID (LCID) of the language.	Any valid LCID supported by the specified Project Server.	1033
Debug·Updates	Specifies whether to use the DebugView dialog box for reviewing datasets before commiting them to Project Server.	true, false	false

The Logging element (Table 4) contains properties used for the ERP Connector event log. The configuration files for each plug-in also include a Logging element, so you can specify different log names and levels for each component. For example, the default log name in the Event Viewer is SAPMSP.

Note
In addition to the SAPMSP log, the Application log in the Event Viewer contains output from the ERP Connector 2007 Service.

When you run ConnectorTool.exe from a Command Prompt window, messages have the Name prefix.

Table 4. Logging element

Attribute	Description	Possible values	Default value
Name	Name of the event log in the Event Viewer, and prefix for messages from ConnectorTool.exe.	Any valid event log name.	SAPMSP
Level	Maximum severity of log messages to write. Messages lower than the specified severity are ignored.	None, Error, Warning, Info	Info

The Request Handling element (Table 5) controls how the ERP Connector processes XML request files.

Table 5. Request·Handling element

Attribute	Description	Possible values	Default value
Accepted·Requests·Folder	Relative path of the folder for accepted requests.	Any valid relative path.	accepted
Rejected·Requests·Folder	Relative path of the folder for rejected requests.	Any valid relative path.	rejected
Check·Duplicates	Specifies whether ERP Connector should check for existing request file backups before creating a new backup.	true, false	false
Backup·Always	Specifies whether ERP Connector should back up the processed request file, even if a command-line parameter specifies the file.	true, false	true
Leave·Ignored	If true, plug-ins leave request files that are not valid in the drop folder; if false, plug-ins copy request files that are not valid to the rejected requests folder.	true, false	false
Cancel·On·Error	Specifies whether to cancel processing a request at the first load (validation) error. Set true to help avoid complications from request files that are not valid.	true, false	false

The plug-in elements in the user-level Connector.config file, for example Plug-in·Microsoft.SolutionStarters.Project.Erp.SapHRPlugIn, specify only whether the plug-in is enabled. Each plug-in configuration file has additional configuration settings.

Table 6. Plug-in elements

Attribute	Description	Possible values	Default value
Enabled	Specifies whether the ERP Connector can load and execute the plug-in.	true, false	true

SapHRPlugIn Configuration

The SapHRPlugIn.config file enables each ERP Connector user to specify the names of enterprise custom fields and lookup tables for resource data imported from the mySAP™ Human Capital Management system. Tables 7–10 explain settings in the SapHRPlugIn.config file.

Table 7. Logging element for SapHRPlugIn.config

Attribute	Description	Possible values	Default value
Name	Name of the event log in the Event Viewer, and prefix for messages from the SapHRPlugIn.dll library.	Any valid event log name.	SAPMSP
Level	Maximum severity of log messages to write. Messages lower than the specified severity are ignored.	None, Error, Warning, Info	Info

The Defaults element (Table 8) specifies default work rates (cost per hour) for imported resources. If an imported resource has work rates set, ERP Connector ignores the defaults for that resource.

Table 8. Defaults element

Attribute	Description	Possible values	Default value
Standard·Rate	Standard cost per hour.	A positive decimal number.	40
Overtime·Rate	Overtime cost per hour.	A positive decimal number.	50
Clear·Mappings	Specifies whether the mapping between resources and organization units should be cleared, if the organization units are changed.	true, false	true
Use·SAP·Hierarchy	If true, extracts the organization unit hierarchy from the mySAP parent organization unit values. If false, extracts from the XML file structure.	true, false	false

The Activation·Control element (Table 9) specifies how the plug-in handles activating and deactivating resources on Project Server.

Table 9. Activation·Control element

Attribute	Description	Possible values	Default value
Activate·Resources	Specifies whether the plug-in can activate resources in the XML request, if the resources are deactivated on Project Server.	true, false	true
Deactivate·Resources	Specifies whether the plug-in can deactivate resources that are not in the XML request, if the resources are activated on Project Server.	true, false	true

The Field·Mappings element (Table 10) specifies the name of a lookup table and the names of enterprise custom fields for mapping mySAP resource data to Project Server.

Table 10. Field·Mappings element

Attribute	Description	Possible values	Default value
SAP·Resource·ID	Name of the enterprise custom field for mySAP Resource ID values.	Any valid custom field name.	SAP Resource ID
SAP·Organisation·Units	Name of the lookup table to store mySAP Organization Unit ID values.	Any valid lookup table name.	SAP Organisation Units
SAP·Organisation·Unit·ID	Name of the enterprise custom field for mySAP Organization Unit ID values.	Any valid custom field name.	SAP Organisation Unit ID
SAP·Manager·Flag	Name of the enterprise custom field for mySAP Manager Flag values.	Any valid custom field name.	SAP Manager Flag

SapCOPlugIn Configuration

The SapCOPlugIn.config file enables each ERP Connector user to specify the names of enterprise custom fields and lookup tables for project data imported from the mySAP Financials CO/PS subsystem. Tables 11–13 explain settings in the SapHCOPlugIn.config file.

Table 11. Logging element for SapCOPlugIn.config

Attribute	Description	Possible values	Default value
Name	Name of the event log in the Event Viewer, and prefix for messages from the SapCOPlugIn.dll library.	Any valid event log name.	SAPMSP
Level	Maximum severity of log messages to write. Messages lower than the specified severity are ignored.	None, Error, Warning, Info	Info

The Project·Field·Mappings element (Table 12) specifies the names of enterprise custom fields for mapping project data from mySAP to Project Server.

Table 12. Project·Field·Mappings element

Attribute	Description	Possible values	Default value
SAP·Project·ID	Name of the enterprise custom field for mySAP Project ID values.	Any valid custom field name.	SAP Project ID
SAP·Responsible·Number	Name of the enterprise custom field for mySAP Responsible Number values.	Any valid custom field name.	SAP Responsible Number
SAP·Plant·ID	Name of the enterprise custom field for mySAP Plant ID values.	Any valid custom field name.	SAP Plant ID

The Task·Field·Mappings element (Table 13) specifies the name of a lookup table and the names of enterprise custom fields for mapping task data from mySAP to Project Server.

Table 13. Task·Field·Mappings element

Attribute	Description	Possible values	Default value
Constrain·Start·Date	If true, constrains the start dates for new tasks, so that when you open the project with Project Professional, it does not change task start dates.	true, false	true
SAP·Orders	Name of the lookup table for mySAP Order ID values.	Any valid lookup table name.	SAP Orders
SAP·Order·ID	Name of the enterprise custom field for mySAP Order ID values.	Any valid custom field name.	SAP Order ID
SAP·WBS·Element·ID	Name of the enterprise custom field for mySAP WBS Element ID values.	Any valid custom field name.	SAP WBS Element ID"

SapFIPlugIn Configuration

The SapFIPlugIn.config file enables each ERP Connector user to specify the names of enterprise custom fields for data imported from the mySAP Financials FI subsystem and settings for exporting the actuals. Tables 14–16 explain settings in the SapHFIPlugIn.config file.

Table 14. Logging element for SapFIPlugIn.config

Attribute	Description	Possible values	Default value
Name	Name of the event log in the Event Viewer, and prefix for messages from the SapFIPlugIn.dll library.	Any valid event log name.	SAPMSP
Level	Maximum severity of log messages to write. Messages lower than the specified severity are ignored.	None, Error, Warning, Info	Info

The Defaults element (Table 15) specifies information for exporting actuals from Project Server to mySAP.

Table 15. Defaults element

Attribute	Description	Possible values	Default value
Actuals·Directory	Absolute or relative path of a directory for exporting actuals.	Any valid path to a writable directory on the Project Server computer.	actuals
Default·Units	Unit for the exported actuals, if no units are specified in the XML request file.	Days, Hours	Hours

The Field·Mappings element (Table 16) specifies the names of enterprise custom fields for mapping data imported from mySAP to Project Server.

Table 16. Field·Mappings element

Attribute	Description	Possible values	Default value
SAP·Resource·ID	Name of the enterprise custom field for mySAP Resource ID values.	Any valid custom field name.	SAP Resource ID
SAP·Order·ID	Name of the enterprise custom field for mySAP Order ID values.	Any valid custom field name.	SAP Order ID
SAP·Project·ID	Name of the enterprise custom field for mySAP Project ID values.	Any valid custom field name.	SAP Project ID