Deployment Guide. Cartagena as. Cartagena ERP Integration 3.0 for Microsoft Dynamics CRM. Knut Eivind Handeland

Transcription

1 Cartagena as Deployment Guide Cartagena ERP Integration 3.0 for Microsoft Dynamics CRM Knut Eivind Handeland 5. februar

2 Contents Overview... 3 CRM Input adapter... 3 CRM output adapter... 3 ERP input adapter... 3 ERP output adapter... 3 Integration service... 3 Before you begin... 4 Requirements... 4 User accounts... 4 Installation Importing the CRM Solution... 5 Activating the License Running database scripts... 6 Upgrade from version Create Integration database... 6 Creating triggers in the Visma Global database... 6 Granting user access Registering the Windows service Configuring the system... 7 Modifying Config files... 7 Setting up metadata in CRM... 8 Import ERP Table and ERP Field metadata Mappings Capabilities One-to-many mapping Entity Mapping Example Field mapping Special configurations for Picklists and Lookups (including owner and status) Supported data type mappings februar

3 Overview Integration Service CRM Output Output ERP Input Input Integration database The integration consists of the following components CRM Input adapter This component listens to changes sends messages from CRM to the integration engine. The adapter uses the ModifiedOn field of the synchronized entities to determine which records that have been created or changed since last check. Every time the adapter checks for changes, the time is saved in a corresponding record in the Integrator entity. The CRM Input adapter is hosted inside the Integration windows service. CRM output adapter This component is responsible for saving data to CRM, and is hosted within the windows service. ERP input adapter The ERP Input adapter checks for changes in the ERP system and transmits them to the integration service. For Visma Global the adapter is implemented as triggers on the database tables. The trigger creates a raw XML based on the modified data in the table and saves it in the VismaMessage of the integration database. A stored procedure that is part of the deployment package is used to create the triggers. The integration service picks up the messages in the VismaMessage table and converts them to a general format for further processing. ERP output adapter This component saves data to the ERP system using the ERP system API. Integration service This is the heart of the system. The integration service is responsible for the following tasks: Storing and queuing messages Converting messages from the source system to a general format Validating messages Applying mappings to messages 5. februar

4 Converting messages to destination format Error handling All messages are stored in the integration database. When messages are completed successfully, they remain in the database for later tracking and statistics. Before you begin It is recommended to install the integration service on the same server as the ERP system is installed. If you choose to install it on a different server, you must also install the ERP Client so the integration has access to the ERP API. When the ERP Server is upgraded, the client on the integration server must also be upgraded. Failing to do that might cause the integration service to stop unexpectedly. Therefore it is recommended to install the integration on the same server as the ERP system. Requirements.NET Framework 4.0 must be installed on the server where the integration Windows service will run. In addition, the following software versions are required. Windows server 2003 or later (both 32-bit and 64-bit are supported) Microsoft SQL Server 2005 or later. Microsoft Dynamics CRM 2011 or later Visma Global (any version) User accounts You will need one domain user account which the integration engine will run. The account will need the following permissions: Create/Update as well as append/append to of all entities that will be synchronized in CRM, plus all the custom entities that are part of the Integration solution. Create/Update of all entities that will be synchronized in the ERP system. Run as service on the computer where the integration service installed. dbowner on the Integration database. All these items are described in more detail below. Installation Installation consists of the following steps: 1. Importing the CRM Solution 2. Running database scripts 3. Registering the Windows service 4. Configuring the system 5. Create mappings 5. februar

5 1. Importing the CRM Solution Import the solutions included in the installation folder into your CRM organization. Import the Solution CartagenaERPIntegration_SharedData_1_0_0_0_managed.zip first, then CartagenaERPIntegration_X_X_XX_Managed.zip. 1. Select the Settings role 2. In the Customization group, select Solutions 3. Click the Import button 4. Import the solution Follow the wizard to complete the import. Activating the License The Windows Service requires an activated license to run. The license file is an XML file that is stored as a CRM Web Resource that is part of the Cartagena Erp Integration solution. You should have received a license for your organization by . To update license file, follow these steps: 1. Open the Cartagena Erp Integration solution. 2. Paste the License XLM you have received by to the License Key section. 3. Click the Save button. 4. When you see a save confirmation text above the Save button, close the form. 5. Click Publish All Customiztions on the solutions toolbar. 5. februar

6 2. Running database scripts Upgrade from version 2 This step is only necessary if you are upgrading the integration from version 2. Skip this step if you are deploying a new installation. Disabling old triggers: select 'disable trigger ' + T.name + ' on ' + S.name + '.' + O.name from sys.triggers T inner join sys.objects O on T.parent_id = O.object_id inner join sys.schemas S on O.schema_id = S.schema_id where T.is_disabled = 0 select 'drop trigger ' + S.name + '.' + T.name from sys.triggers T inner join sys.objects O on T.parent_id = O.object_id inner join sys.schemas S on O.schema_id = S.schema_id where T.is_disabled = 0 Create Integration database Run the script FullScript.sql located in the \Scrips folder using SQL Management Studio. This script will create a database named IntegrationSerice. You must at least have the dbcreator role in your SQL Server in order to execute this script. Creating triggers in the Visma Global database Run the script VismaTriggerScript.sql on the Visma database(s) you want to integrate with your Microsoft Dynamics CRM deployment. This script will create a stored procedure in the Visma database that will simplify creating the triggers that will notify the integration service of changes in the Visma database. After the stored procedure is created, run the below command on each Visma table that you want to synchronize. dbo.p_create_trigger 'Schema', 'Table', <UserNo>, 'Primary key (optional)' The following list describes each parameter Schema: The database schema used in your Visma database Table: Name of the table you want to synchronize <UserNo>: The Id of the user account that the integration service will use to access your Visma Global organization. This number can be retrieved by the Visma UI or the following command: select UserNo from <Schema name>.logonuser where Name = '<User Name>' Where <User Name> is the name of the Windows user that will access Visma Global Primary Key: Name of the primary key of the table you want to synchronize. The procedure will try to determine this value, but if it fails you can specify it with this parameter. Granting user access Visma client user needs write access in the Integration db USE [IntegrationService] 5. februar

7 GO CREATE USER [Your ERP Login] FOR LOGIN [Your ERP Login] GO USE [IntegrationService] GO EXEC sp_addrolemember N'db_datawriter', N' Your ERP Login' GO Integration service account need full access to the integration db. 3. Registering the Windows service 1. Create a folder named "Cartagena ERP Integration for MSCRM" in the "C:\Program Files (x86)" folder. 2. Copy the files from the Service sub folder in the installation package to the newly created folder. 3. Open a command window as an administrator. 4. Execute the file Register.bat. The Windows service is now registered on the server. Do not start the service before you have completed the setup procedure described in Configuring the system and Mappings. Open the Services MMC applet. Identify the Cartagena ERP Integration for Microsoft CRM service. Change the following properties: Set the execution account to the account you have created according to the description above. Set startup type to Automatic (Delayed). 4. Configuring the system Modifying Config files Copy the three config files from the Config folder of the installation package to the folder that you created for the Windows Service in the previous step. You must modify two config files in the folder. Crm.config: This file contains information for how to connect to the CRM organization. Setting.config: This file contains information for how to connect to the Integration database. This file contains a standard ODBC Connection String. To build a connection string you can create an empty file on your desktop with the extension *.udl. When you double-click this file, Windows will open a dialog so you can specify the connection. On clicking OK the connection string will be saved to the file as plain text so you can open it in Notepad. You can obtain your CRM Organization Unique name in CRM by selecting the Settings role, choose Customizations click Developer Recourses. 5. februar

8 Setting up metadata in CRM For the integration service to work properly, the following metadata must be set up in your CRM organization: At least one ERP System Adapter Containers for CRM and for each ERP System At least one Entity Mapping with child Field Mappings All these entities are available in the Settings section after you have imported the solution and refreshed your browser. Name: A descriptive name of the connected Visma client/organization License Code: BAPI key used to access the Visma API. Can be retrieved via View License info in the Visma Global application. ERP Organization: This is the name of the Visma Company, as displayed in the Visma Logon dialog (without the numeric prefix). Schema name: Database schema name used for the Visma company. Two adapter containers must be set up for CRM and for each ERP System; one for input and one for output. Name and Binary are updated automatically for you when you select Container and Integrated System. 5. februar

9 You must have at least four Adapter Containers for the system to work, Input/Output for MSCRM, and Input/Output for your Integrated System / ERP System. Import ERP Table and ERP Field metadata ERP Table and ERP Field are two entities that are created in CRM when you import the Integration solution. These entities holds metadata about tables and fields in the ERP System. By storing this information in CRM, setting up mappings becomes easier and less exposed for configuration errors. The installation packages comes with two metadata files: ERP Tables.xml ERP Fields.xml These files can be directly imported through the following procedure: 1. Click Import on the Ribbon menu. 2. Select ERP Tables.xml and click next 3. Click next to confirm uploading of the file 4. Select Default (Automatic Mapping) in the Select Data Map step, and click next. 5. Select ERP Talbe as CRM Record type 5. februar

10 6. The Import wizard will automatically suggest mappings based on their names. Verify that the suggestion is correct and click next. 7. Complete the wizard to import the records. The last step of the wizard will display a link so you can monitor the import job. You can also find this information in the Data Management section in CRM. When you have imported the ERP Tables.xml file, repeat the above steps for the ERP Fields.xml file. 5. februar

11 5. Mappings Capabilities With mappings, you can set up the system to synchronize data in CRM with one or more ERP organizations/companies. You can also choose whether to synchronize accounts on a one-to-one basis or a one-to-many basis. For example, a CRM account may be synchronized with both a customer and a supplier in the ERP system. Mappings has a filtering capability, so you can define a subset of records for synchronization, or applying different sets of mappings to different records of the same entity. One-to-many mapping With one-to-one mapping, one Account synchronizes with one Customer or one Supplier in the ERP System. With one-to-many mapping an accounts may synchronize with multiple customers and suppliers in one or more ERP organizations. To accomplish this an additional entity is needed. One-to-one mapping CRM Entity (Primary entity) ERP Entity One-to-many mapping CRM Associated entity CRM Primary entity ERP Entity The entity in the middle is called Primary entity because this entity will store the Primary Key of the ERP entity. This field will be the shared key between the two systems. In the example of Account to Customer mapping, Account will be Associated entity, and we need to insert a Ledger entity in between. The ledger entity is imported as part of the Integration solution. You can choose whether to use this functionality or not. (Please note that the schema name of the Ledger entity is ctg_accountsyncunit). A similar entity exists for Contacts (ctg_contactsyncunit). Account Ledger Customer 5. februar

12 Entity Mapping Below all important fields of Entity Mapping are described. Name. Type a descriptive name of the mapping. ERP System/org. Select to which ERP system/organization/company this mapping will apply. Description. Here you can insert notes for you own use. Primary Entity. The primary entity for the mapping in CRM. This is a mandatory field. The Select button below will assist you in picking the correct entity name. ERP Table. Select the ERP table you want to map to the Primary entity from CRM. You must choose from the list of imported ERP Tables. This is a mandatory field. Note: You can add additional records to the ERP Table entity, but you must make sure that your data matches the ERP SDK specification. Any errors in the metadata will make the messages for this mapping fail. ERP Link Field. This is the field of the CRM Primary Entity that holds the Primary Key of the ERP Table. When you have selected an ERP Table, the primary key shows below. This will help you determine the corresponding field in CRM. 5. februar

13 ERP Primary Key. This field shows the primary key of the above ERP Table. This field is updated automatically and is read-only. ERP Pk Prefix. The Visma Output adapter uses a custom generator for creating new primary keys. This generator always uses the lowest available number. You can use field to enforce a prefix to the generated keys, or to specify that all records created from CRM will have a key greater than the number you specify. Customers and Suppliers have their own number intervals in Visma. You can use this field to force all customers created with this mapping have 3 or 400 as prefix. The generator will then assign numbers until the end of the prefix interval, and then continue on the next interval. If the limit of Customer/Supplier interval, no new keys are available and an error will occur. Associated Entity. If you wish to use one-to-many mapping this field is for the associated entity. The Select button below will assist you in picking the correct entity name. Fail on Error. This field specifies what will happen if a field validation error occurs. If one field in a message is rejected by the destination system and this field is set to Yes, then the whole message will fail. For example, if the product selected for an Order line Item does not exist in the ERP System, the whole order is rejected. For customers you may want to set this value to No. If a customer group specified for an Account does not exist in ERP, you probably still want the updated phone number to save. CRM Filter. CRM filters are useful in the following situations: If you don t want to synchronize all records of an entity. For example, you may not want to synchronize Accounts that are marked as prospects. When you need multiple mappings for a single CRM entity. For example, you need this if you are setting up mappings for Account to Customer and Account to Supplier. The lookup field saves a fetch XML definition of you CRM filter. When you use CRM Filters it is recommended to also set up defaults in Field Mapping to support the filter. Please consult the next section for more information. ERP Filter. ERP Filters are less common than CRM filters, but are needed in the following situations: When you don t want to synchronize all records from a table. For example, some companies uses Supplier ledger to track transactions against employees, and do not want to expose this information in CRM. When you need multiple mappings for a single ERP Table. For example, if you need different mappings for different types of customers. The filter is saved in a proprietary XML format on the Entity Mapping record, but a graphic tool is proved to assist you in setting up the filter. You can toggle between graphic and XML mode. When you use ERP Filters it is recommended to also set up defaults in Field Mapping to support the filter. Please consult the next section for more information. 5. februar

14 Example Below is an example of a one-to-many entity mapping between Account and Customer. The CRM Filter in this example is defined as Relationshiptype (of AccountSyncUnit) Equals Customer. Field mapping Field mappings are children of Entity Mapping. Each field is described below. Name. Name of the Field mapping. This field is filled in automatically based on CRM and ERP fields and is read-only. Line Item No. This optional field specifies in which order each message field will be saved to the destination record. This is very important in some cases, for example: When updating a PostCode field in Visma Global, the Visma business engine will automatically look up the corresponging PostOffice field from the PostOffice table 5. februar

15 and save it to the PostOffice field of your destination record. If the PostOffice field is written before the PostCode field, your data may be overwritten. For Orders, no data is accepted before a valid customer number is inserted. Please note that Field Mappings with no Line Item No will be processed first (in random order). Description. Here you can insert notes for you own use. Entity. This field is only available if the parent Entity Mapping is saved with an Associated entity for use with one-to-many mapping. The field specifies whether the CRM field exists in the Primary Entity or the Associated Entity. Entity Mapping. The parent Entity Mapping. Type. Specifies if the Field Mapping is a mapping (synchronize data between two fields) or a default for one of the fields. A default applies only when a new record is created in the destination system. Use the Direction field to specify if the default applies to CRM or ERP. Defaults are useful for supporting Entity Mapping filters. For example, when Accounts are mapped to both Customers and Supplier, the Relationhiptype field (of either Account or Ledger) usually specifies which mapping to use. When new customers are created in Visma, we must set the Relationshiptype field in CRM when creating the new Account (or Ledger). If we don t set this field, the newly created record in CRM won t be recognized by any of the CRM Filters and updates to the CRM record won t result in an integration message to ERP. You can also use Defaults in other scenarios where you want to set a value when a record is created, but not synchronize it later. Direction. Specifies if data goes in both directions, from CRM to ERP or vice versa. CRM Field. The CRM field to synchronize. ERP Field. The ERP field to synchronize. Default Value. If Type is set to Default, select the default value here. If the default is for CRM and the CRM Field datatype is Picklist or Lookup, a button will show below this field. Click the button to display a list of available values. Special configurations for Picklists and Lookups (including owner and status) When the data type of the CRM Field is either Picklist or Lookup, additional configuration is needed. Since the corresponding ERP value isn t stored in the CRM Field itself but in a related CRM entity, we must supply information so the integration engine is able to find this data. When you select a CRM field that has a data type of either Picklist, Lookup, Owner or status, the Mapping Configuration displays. 5. februar

16 For Picklist fields, the Mapping Configiurations shows like the below example. All the valid choices from CRM are automatically filled in. All you need to do is to add the matching ERP values. 1. Click on the line in the grid. The above fields are filled in. 2. Edit the the ERP value. 3. Click the Update button. You can also view and edit the value mapping in XML format. This is especially useful if you have a very long list of value pairs. In this case, you can edit or generate your XML somewhere else and paste it to the Mapping Configuration. For statuscode (Satus Reason) fields, the grid will have three columns. The reason for this is that CRM saves statecode and statuscode in one operation. Please note that adding statecode (Status) as CRM Field is not supported. To synchronize statecode, add mapping for statuscode. 5. februar

17 For Lookup fields, the Mapping Configuration looks different. The Reference entity field specifies which entity the lookup field is linked to. Reference field is name of the field where we find the corresponding ERP value. In the above example, CustomerId is mapped to CustomerNo for SalesOrders. CustomerId is in this case related to Account. AccountNumber is the field where we find the ERP Customer number. It is also possible to set up more advanced configuration using XML. This is described in the appendix. 5. februar

18 Supported data type mappings Visma Data Type Variable Length Text Number Small Number Floating Point Number Decimal Number Memo Time and Date Time Date CRM Data Type SQL Data Type Varchar(N) int smallint float decimal(28, 6) Text Datetime datetime datetime Single Line of Text nvarchar(n) Yes 1) Yes 2) No No No No No No No Option Set int No Depends 3) No No No No No No No Two Options bit No Depends 3) Yes No No No No No No Whole Number int No Yes Trucates Trucates Trucates No Trucates Trucates Trucates Floating Point Number float No Trucates No Yes Yes No Trucates Trucates Trucates Decimal Number decimal(23, 10) No Trucates No Yes Yes No Trucates Trucates Trucates Currency money No Trucates No Yes Yes No Trucates Trucates Trucates Multiple Lines of Text nvarchar(max) Yes 1) No No No No No No No No Date and Time datetime No Trucates No Trucates Trucates No Yes Yes Yes Lookup uniqueidentifier No Depends 3) Depends No No No No No No Owner uniqueidentifier No Depends 3) No No No No No No No Status int No Depends 3) Depends 3) No No No No No No Status Reason int No Depends 3) Depends 3) No No No No No No Primary Key uniqueidentifier Yes No No No No No No No No Color Codes Will always work, fully supported, but may trunctate data when types are not equal Will generate an error and / or is unsupported Will work when certain conditions are true, but may still trunctate data Footnotes 1. If field lenght is different, the integration engine will only compare the first MIN(CRM, ERP) characters. 2. For certain fields, this combination is recommended. For example ERP Id's in the CRM system should always be stored as text since this type also support ID's of other types, such as GUID. 3. Requires separate Mapping Configuration 5. februar

19 5. februar