Typical API applications indicated by the dark coloured arrows

Transcription

1 API Data Integration for webcrm /EM/TS Typical API applications indicated by the dark coloured arrows Important: The use of the API should primarily be event driven. For example, only when some user action requires data, the API will be called. If this is not possible, a scheduled/loop connect to the API can be initiated every 4 to 8 hours never every second or minute. Download of large amounts of data must take place based on incremental downloads. After an initial download, only items updated since the last download should be downloaded. If these guidelines are not followed, the API access may be closed. page 1

2 Introduction Important: The use of the API should primarily be event driven. For example, only when some user action requires data, the API will be called. If this is not possible, a scheduled/loop connect to the API can be initiated every 4 to 8 hours never every second/minute. Download of large amounts of data must take place based on incremental downloads. After an initial download, only items updated since the last download should be downloaded. If these guidelines are not followed, the API access may be closed. Introduction: The API is a web service (SOAP) with a number of methods for 2-way integration and synchronization of data with webcrm. From the Configuration/Integration/API menu in your webcrm system you can download more information including a Getting started document for programmers with some guidelines on how to communicate with the API. Data entities can be created and updated. Deleting of records is not supported by the API (except for linked data and quotation lines). Instead create a custom field in webcrm and use the API to update this field with something like API delete. Then use a Mass delete overview in webcrm to delete records. In webcrm Organisation is the parent entity for Persons, Opportunities, Deliveries, Activities, Events and Products. Each data entity has a number and an associated entity Type (text) which is used by the API methods. page 2

3 Overview 1 Organisations 2 Persons 3 Activities 4 Products 5 Opportunities 6 Deliveries 9 Users (limited methods and fields) 10 Events (meetings) 19 Relations 0 Linked data (has no data entity number) The entities may be disabled and terminology may differ depending on the customer s settings for the specific webcrm system. Notes: webcrm has a special option for so-called multi-opportunities where one opportunity links to many Organisations. Multi-opportunities are not supported by the API. The optional Delivery phases in webcrm are not supported by the API. Help and support: The API is available at no extra cost to webcrm customers. Any help and support (except concerning documented errors) will be charged for at the current hourly rate for consultancy. webcrm is not able to give support regarding client specific programming issues. page 3

4 Enabling the API service Access the API from this URL: The API service must be enabled in the webcrm system. Enable the API from the menu: Configuration/Integration/API The dbn Code - used by the authentication method - is determined by the webcrm system and is unique for each webcrm system. Make sure to enter name and of the technical person to receive technical notes and updates regarding the API User ID (= User name) and Password - used by the authentication method - must be minimum 10 and maximum 30 characters. Only the entities enabled and the read/write mode in the setting will be supported by the API. Terminology may differ from the below screenshot depending on the customer s settings. page 4

5 Documentation and test Details of properties and methods can be found here: This URL provides a way to test the API methods interactively from your browser: 1) Select a service method with the dropdown. 2) Enter method arguments. 3) Click "Generate Request" to generate SOAP request message. 4) Review and correct/modify the SOAP request message if necessary. For example remove empty value pairs. 5) Click "Send Request" to submit the SOAP request message to the API. 6) View the SOAP response in the textbox. The "Ticket GUID" textbox right under the argument textboxes is filled automatically after Authenticate method submitted. You may also enter the GUID yourself. page 5

6 Data formats A webcrm system can be configured in many ways, and data entities may have a different number of fields and the fields may represent different types of data. In order to reflect this in the API service webcrm entities are represented with a collection of key-value pairs. Every key-value pair in the collection describes one field of a webcrm data entity. The field value can be interpreted based on field metadata returned with ReturnAllFieldDescription() method. The most significant properties of metadata are DatabaseFieldKey and DisplayType (see the following pages) DatabaseFieldKey is used as a key for key-value pair, while DisplayType specifies the format for the value. The value of key-value pair is a string (native "s:string" SOAP type) and its formatting and validation logic mainly depends on the corresponding DisplayType (see following pages). The DisplayType formatting for key-pair collection is applied for these methods: Read data: ReadFromWebcrmByDates and ReadFromWebcrmById. Write data: WriteToWebcrm and WriteCollectionToWebcrm. And for the formatting of search values for these methods: Search value: SearchOrganisation, SearchPerson, SearchOpportunity, quicksearch. Generic SOAP data formatting Data formats in all other context than the above mentioned use standard SOAP conventions. For example a date/time value passed as a limiting parameter for the ReadFromWebcrmByDates method will use this format: YYYY-MM-DDTHH:MM:SS (example: T12:45:00) Note: Date/Time values in the format of the standard SOAP conventions are always represented in webcrm as time zone: GMT+1 hour. The SOAP message must convert these characters: '&' = '&' '<' = '<' '>' = '>' newline ( CR LF ) in memo type fields must be converted to \r\n page 6

7 Please note, that Entity Type must be passed to the API as text (not a number) Entity Number Entity Type 1 Organisations 2 Persons 3 Activities 4 Products 5 Opportunities 6 Deliveries 10 Events 19 Relations Reading field data will be presented in field-id order defined by webcrm and described by the field-id and field SortOrder. When writing/updating a field data the databasefieldkey must be included for identifying the field. Retrieve all databasefieldkeys by the method ReturnAllFieldDesc. Example of part of response from method ReturnAllFieldDesc - <FieldMetadata> <Index>2</Index> <DatabaseFieldKey>1_Name</DatabaseFieldKey> <FieldDescription>Name</FieldDescription> <SortOrder>11010</SortOrder> <ItemNumber>1</ItemNumber> <DisplayType>T</DisplayType> <FieldSize>50</FieldSize> <DropDownItems /> </FieldMetadata> - <FieldMetadata> <Index>3</Index> <DatabaseFieldKey>1_Division_name</DatabaseFieldKey> <FieldDescription>Division_name</FieldDescription> <SortOrder>11020</SortOrder> <ItemNumber>1</ItemNumber> <DisplayType>T</DisplayType> <FieldSize>50</FieldSize> <DropDownItems /> </FieldMetadata> - <FieldMetadata> page 7

8 The DisplayType in the above example indicates how the data field is displayed in the webcrm system and also the string format used in value-pairs and for values in search methods. DisplayType can have the following values: DisplayType Displayed as in webcrm Actual data type C Checkbox Text Yes or No Cust Custom field (see next page) Text D Dropdown text data value = displayed text Text DI Dropdown integer value for displayed text Integer DT Date + Time Real DTGMT Date + Time stored at GMT+1 offset Real DAT Date for a custom field String HM Duration in minutes Integer I Integer Integer IS Unique record Id Integer LOGA Activity log in html format Text - Note LOGP Opportunity/Delivery log in html format Text - Note M Memo Text - Note PI Record id for person record (relation) Integer R Real Real SD Dropdown text data value <> displayed text Text SDI Dropdown integer data value for displayed text Integer T Text Text UI Record ID for user (relation) Integer Period. is used for numbers as decimal separator DT or DTGMT type: Format = YYYY-MM-DDTHH:MM:SS example: T12:45:00 DA type: Format = YYYYMMDD TM type: Format = HH:MM DAT type: The date format depends on the setting in the webcrm menu: Configuration/Integration/API page 8

9 Custom fields in webcrm Custom fields in webcrm can be enabled/disabled and defined by the customer for a number for display types such at integer, string, checkbox, date, dropdown list etc. The actual use of each custom field cannot be determined from the API. Look in the webcrm system to see how each custom field is used. In the webcrm system custom fields are managed from the Configuration/Custom fields menu. Here the custom field display type and the number (1-15) for the custom fields can be found. The data base field name for a general custom field is xx_customn xx depends on the data entity type and N can be from 1 to 15. Additionally there is custom field of type Memo: The field name is xx_memo The actual value of N can be seen as indicated below by the red ellipse. Note: The number may be different from the display order in the drop down. Internally in webcrm all custom fields are stored as text (string). Format of strings for custom fields of display type other than plain text: Dates: The date format for custom fields depends on the setting in the webcrm menu: Configuration/Integration/API Integers: Always 12 characters with preceding zeros. For example: Checkbox: Yes or No Drop down lists: A string with the selected option text. newline ( CR LF ) in memo type fields must be converted to \r\n page 9

10 Custom field of type Multi select list: Each option for a Multi select list is defined as a description associated with a number in the range 1 to 99. Example for a multi select custom field definition in as shown in this box --> Note that the numbers are not necessarily in sequence. In webcrm the options will be displayed in the order, they are listed in the custom field configuration regardless of the numbers associated with each option. 01:Green 02:Yellow 03:Blue 04:Red 20:White 70:Black 45:Red-Yellow 46:Blue-Green 90:Transparent The string value for the custom field is one number (1-99) for each selected option (maximum 50 selected options). Each number is separated by semicolon. Example: If Yellow, Red, Black and Blue-Green options are selected, then value of the custom data field is returned as: 02;04;70;46 When searching a multi select list where the stored value is 02;04;70;46 then these search values will return as a match: ;04 04;70 70;46 02;04;70 04;70;46 02;04;70;46 These search values will not return a match: 03 02;03 02;04;46 02;04;46;70 02;04;46 page 10

11 Owner and responsible For the data entities: Organisations, Opportunities, Deliveries, Activities and Events, one or more data fields holds a user s ID to identify Owner/Responsible. These data fields can be updated with user ID s or 0 for no owner/responsible. Participates for Events (meetings) For Events there is a special data field: ev_parids (String type, maximum 80 characters long) This field holds a list of user ID s for users attending the Event. The format is ;<ID1>;<ID2>;<ID3>;...; Each user ID is separated by semicolon and the string must begin and end with semicolon. Quotations Quotation lines are stored as a Product entity records. The field prd_oppid is to be the OpportunityId and as such link the quotation line to the Opportunity. Important: When changes are applied to quotation lines, the client must also explicitly update the total revenue and GM values for the Opportunity as appropriate. Products For products in webcrm the field 4_prd_combined contains concatenated values of custom fields according to the webcrm configuration for Custom fields for Products. Important: When changes are applied to product custom fields, the client must also explicitly update 4_prd_combined as appropriate according to the webcrm configuration for Custom fields for Products. Record unique ID number In webcrm the unique record ID number per entity is displayed at the lower left hand side of the screen when editing/viewing a record. The number can be seen next to the R letter. page 11

12 Entity type 9 Users Entity type 9 Users is supported with some limitations: The following methods are supported: - RetriveByQuery - WriteToWebCrm - WriteCollectionToWebCrm - ReadFromWebcrmByDates - ReadFromWebcrmById Fields for password, autcode and loginlog are blocked completely. Fields u_lastlogindate, u_logincount, u_wrongpasswordcount, u_languageid, u_integrationid, u_groupid, u_accessid are read only fields. Write methods do not allow creating new users. page 12

13 Relations (entity type 19) Each relation record has these fields: The maximum length of the text fields are 50 characters The r_type can be one of these four values: 1: person - person 2: organisation - person 3: organisation- organisation 4: Linked organisations (organisation- organisation) For the B2C/Person version of webcrm only type 1 is possible There are 4 id fields in each relation record referring to the unique record id numbers of the relation Relation - Left hand side: r_org1id r_person1id Relation - Right hand side: r_org2id r_person2id If the relation type does not include a person then the person Id number will be = 0. The Created can be used for other purposes than the create date and is displayed in webcrm as Relation date The Code is a number in the range from 1 to 99. The text associated with each code is defined in the webcrm system: Configuration/Drop down lists/relations. It is not possible to retrieve the text values associated with each Code using the API. page 13

14 Web service methods Details of properties and methods can be found here: General methods: Authenticate (dbn Code, username, password) - Verifies webcrm credentials. The authentication is automatically expired in 20 minutes if there is no activity. EndSession () - Terminates current session. The authentication performed with Authenticate method will not be valid any longer. ReturnFieldDescription (entitytype, index(fieldid) ) - Returns meta-data for the specified data field (DatabaseFieldKey, type, optional dropdown values, description, fielssize, index(fieldid), sql-name, item number, sortorder ) ReturnAllFieldDescription () - Returns meta-data for all data fields (DatabaseFieldKey, type, optional dropdown values, description, fielssize, index(fieldid), sql-name, item number, sortorder ) ChangeOrgForOpportunity () - Chenmges the Organisation reference for an opportunity/deliverey and alle releted data for that opportunity/delivery NOTE: These 4 methods ReadFromWebcrmByDatesDirect ReadFromWebcrmByIdDirect WriteToWebcrmDirect WriteCollectionToWebcrmDirect have replaced ReadFromWebcrmByDates ReadFromWebcrmById WriteToWebcrm WriteCollectionToWebcrm The only difference is, that the new methods use the so-called sql-name to identify data fields whereas the old methods used index(fieldid) as field name page 14

15 Write data methods: WriteToWebcrmDirect (entitytype, organisationid, recordid, data) - Updates an existing entity specified by record organisationid and recordid or creates a new if ID are = 0. If entitytype refers to organisations type then organisationid and recordid are to be identical. WriteCollectionToWebcrmDirect ( entitytype, collection) - Updates or creates collection of entities. Notes for write methods: When creating new records care must be taken to make sure that data fields are initialized. For example: Normally data fields such as Organisation type and Organisation status should be initialized. The same usually applies for custom fields of type drop down. When creating a new table row for opportunity (create only) and the update value for opportunity/delivery number = -1 (string) then the API will assign the opportunity/delivery number using auto numbering according to the settings in webcrm. For all data fields of type Memo: If "/A/" is found in the beginning of the updatetext, then the updatetext is inserted at the beginning of any existing text. The "/A/" characters themselves are not saved. If "\A\" is found in the beginning of the updatetext, then the updatetext is appended to the end of any existing text. The "\A\" characters themselves are not saved. If "/X/" is found in the beginning of the updatetext, then the updatetext overwrites any existing text. The "/X/" characters themselves are not saved. /X/ mode is the default mode if none of the above codes are found in the beginning of the updatetext. However, for the Activity and Opportunity/Delivery history fields (log) the "/A/" mode is the default mode if none of the above codes are found in the beginning of the updatetext. page 15

16 Read data methods: ReadFromWebcrmByDatesDirect (entitytype, fromdatetime, todatetime, datemode) - Returns a list of data fields for entities based on date criteria. Records are filtered by dates: >=fromdatetime and <=todatetime datemode = ByCreationDate : The record create date is used as matching criteria datemode = ByUpdateDate : The record update date is used as matching criteria Dates may not be before January 1st 2000 or after December 31st The date interval may not exceed 100 days. A maximum of records are returned. ReadFromWebcrmByIdDirect (entitytype, organisationid, recordid) - Returns the data fields for the entitytype based on the given organisationid and recordid. If entitytype refers to organisations type then organisationid and recordid are to be identical. Records are filtered by Organisation_ID and recordid If recordid = 0 it returns data for all records found If recordid <> 0 then it returns only the specific record If entitytype is Organisation then OrganisationID must be = RecordID OrganisationID must be <> 0. A maximum of records are returned. You can use the ReadFromWebcrmByDates method to get of list of data fields for entities including ID s to retrieve and then optionally read additional records one by one with the ReadFromWebcrmById method. ReturnAllUsers () - Returns list of all users with access level > 4 sorted by user name. It returns UserID, access level (5-99), user Name, initials, loginname. ReturnUserDetails (loginname) This method returns the user details for a specific user identified by login name It returns: user_id Integer, u_accesslevel (integer 0-99), u_languageid Integer (44,45,46,...) u_gmtdifference Integer (-12 to +12) And unformatted string values for: u_name, u_initials, u_ , u_mobile, u_telephone u_territories u_custom1, u_custom2. u_custom15 Territories: Comma separated list of territory numbers. Example:,44,45,358 = 0 indicates all territories = 1 indicates no territories,* last in the list indicates read only access to all territories not included in the list page 16

17 Search data methods: QuickSearch (dbncode, username, password, searchmode, searchvalue, userid, options) - Searches for an Organisation/Person based on the given parameters. This method performs its own separate authentication and session termination and does not require calling Authenticate and EndSession methods. searchmode: 1: Search for tele numbers (searches for telephone, fax, direct and mobile numbers) 2: Search for Organisation name Or Organisation name Division name 3: Search for Person name 4: Search for Person If more than one match is found, only the data for the first match is returned (sorted by person last name, organisation name) UserID: Defines the current user ( = 0 for none) for the list of Meetings, Activities, Opportunities and Deliveries described below Returns the count of matches found and a list of data (blank data is omitted): Person data is omitted if the search result is for Organisation. Person Salutation, Title, Full name, telephone, mobile Organisation name, division name, telephone, full address, alert text List of meetings (events) from today s date and forward for the current organisation with the current user as meeting responsible (Date, time, Description, Contact person name) List of Activities for the organisation with activity status <> completed and with current user as activity responsible (Date, Time, Action, Description, Contact person name) List of Opportunities + Deliveries for the organisation with current user as: Opportunity 1st or Opportunity 2nd responsible or Delivery responsible, and Delivery status <> complete. (Pipeline level, Delivery status, Delivery risk, Description, Number, Value (revenue), Product, Date) page 17

18 Search data methods: SearchOrganisation (searchfieldnumber, searchvalue, postcode, options) - Returns a list of Organisation_ID s (max 10000). The list is sorted by name. Postcode can be blank or contain a postcode to limit the search. searchfieldnumber identifies the data field to be searched for: 1: Organisation name Or Organisation name division name 2: Telephone or fax number (Telephone 2 or fax for B2C version) X: Custom field value. X: 101 to 116 ( o_customn field N=X ) X: Extra custom field value. X: 201 to 208 ( o_ucustomn field N=X ) In webcrm it is possible to create one or more custom field to hold a unique identifier for the Organisation. This may be useful to hold a unique ID used by the records of the system that uses the API to integrate with webcrm. Custom fields can be updated from the API. Please note that the API itself does not validate that custom field values are unique the client side must do this. When using SearchOrganisation and searchfieldnumber = 1 the search uses a special case in-sensitive search algorithm where all spaces and special characters such as /,. - are ignored. AS, A/S, APS, IS, I/S, LTD, INC, GMBH, SA, AB, at the end of the name must be omitted in the search. AS, A/S, IS, I/S, SA, AB, at the beginning of the name must be omitted in the search. SearchPerson (searchfieldnumber, searchvalue, organisationid, options) - Returns a list of Organisation_ID and Person_ID pairs (max 10000). The list is sorted by name. OrganisationID can be zero to search in all organizations or > 0 to limit to a specific organisation. searchfieldnumber identifies the data field to be searched for: 1: Person name 2: Person 3: Direct telephone or Mobile number (Telephone or Mobile for B2C version) X: Custom field value. X : 101 to 116 ( p_customn field N=X ) X: Checkmark field value. X: 201 to 210 ( p_chkmarkn field N=X ) page 18

19 SearchOpportunity (searchfieldnumber, searchvalue, organisationid, options) - Returns a list of Opportunity_ID s (max 10000). The list is sorted by opportunity number and creation date. OrganisationID can be zero to search in all organizations or > 0 to limit to a specific organisation. searchfieldnumber identifies the data field to be searched for: 1: Opportunity number (String value including preceding zeros) 2: Pipeline level ( 0 to 14 ) ( 13 = won, 14 = lost ) X: Custom field value. X : 101 to 116 ( op_customn field N=X ) X: Search field. X : 121 to 122 ( op_search1, op_search2 ) X: Lost field. X : 131 to 133 ( op_lost1, op_lost2, op_lost3, ) SearchDelivery (searchfieldnumber, searchvalue, organisationid, options) - Returns a list of Delivery_ID s (max 10000). The list is sorted by delivery number and creation date. A delivery in webcrm also holds all the data fields from the opportunity that optionally preceded the delivery. OrganisationID can be zero to search in all organizations or > 0 to limit to a specific organisation. searchfieldnumber identifies the data field to be searched for: 1: Delivery number (String value including preceding zeros) 2: Opportunity number (String value including preceding zeros) X: Opp. custom field value X : 101 to 116 ( op_customn field N=X ) X: Del. custom field value X : 201 to 216 ( opc_customn field N=X ) X: Search field. X : 121 to 122 ( op_search1, op_search2 ) X: Lost field. X : 131 to 133 ( op_lost1, op_lost2, op_lost3, ) SearchQuotationID (opportunityid) - Returns a list of ProductId s (max 10000) linked to the Opportunity. The list is sorted by created date-time. SearchQuotationData (opportunityid) - Returns a list of quotation lines (=Product records) (max 10000) linked to the Opportunity. The list is sorted by created date-time and contains all the field values for each Product record. DeleteQuotation (productid, opportunityid) - Deletes one or all quotation lines for a specific Opportunity. If productid = 0 then all quotation lines (= Product records) for the Opportunity are deleted. page 19

20 Notes for search methods: Searches are always case insensitive SearchValue may include % in the beginning or end as wild cards. Examples of search strings: abcd (exact match) abcd% (begins with) %abcd (ends with) %abcd% (contains) Search value may not exceed 50 characters in length. Telephone searches are based only on digits all other characters are removed. All search methods except QuickSearch returns just ID numbers. Search results include only fields that are enabled in the webcrm system Options parameter: For future use. Set value = None page 20

21 Query method RetrieveByQuery() This method enables you to retrieve data the way you can retrieve data using the webcrm system s overview/report generator. The RetrieveByQuery method takes 4 arguments SELECT FROM WHERE ORDER BY It returns up to a maximum of rows. Start by setting up the report in your webcrm system. In the Advanced tab click the SQL forapi button. You will see the 4 arguments for the RetrieveByQuery method: page 21

22 Notes for the RetrieveByQuery method: In case you need more that the 14 fields supported by the reports, you note down the arguments. Then you change the report for the next 14 fields and click the SQL for API button again and add the new SELECT fields to the list you noted down earlier. Date/Time parameters for the WHERE parameter is a real number where the integer part is the number of days since 1900 and the decimal part is the fraction of a day. Note: Convert to time zone GMT+1 (Central Europe). Custom fields of type integers for the WHERE parameter must be represented as a string of length 12 with preceding zeros. For example: Custom fields of type multi-list for the WHERE parameter must be represented as a string where each value for the multi-list is represented by one character. This character is encoded from the associated number (01-99) for the associated multi-list value. if multinr = 59 then mappedcharacter = chr( 214 ) else if multinr < 48 then mappedcharacter =chr( multinr + 48 ) else mappedcharacter = chr( multinr ) end if end if In addition to the API supported entities, the RetrieveByQuery method also permits these tables: punchcard punchentry support supporttime deliverytime page 22

23 Linked data methods: ReadLinkedData (entitytype) - Returns linked data for the specified entitytype DeleteLinkedData (entitytype) - Deletes all linked data for the specified entitytype. Returns the count of deleted records. UpdateLinkedData (entitytype, datalist) - Updates or creates records of linked data for the specified entitytype. Returns the count of created records, updated records, ignored records (id not found) and ignored records (invalid format). In webcrm linked data is used for populating linked drop down lists. If a user picks a value in one drop down list, the options in the linked drop down lists will be updated. Linked data for each entity is a single list of all possible valid combinations of the linked drop down lists. Linked data are also used for item lists (products) for quotation lines. Use entitytype=7 for linked data to be used for item lines. Linked data is read and written by the API as a string in a fixed format. The following is a format for a single linked data record: id~data1~data2~data3~data4~data5~data6~data7~data8~ data9~memo~price~costprice id = 0 means create new row (when writing). When writing Linked data it can have up to a maximum of 12,000 lines (records) for each entity. Each line is separated by line break: Character 10 or character The memo field may contain line break codes = \r\n. No field may contain the character ~ or character 13, 10. Maximum length is 50 characters for data1-9 and 2000 characters for memo. The fields price and costprice are only used for products (entity type = Products). For other entity types these fields must be set = 0. A period (. ) is to be used as a decimal point for price and cost price. If text ~ or line break should be treated as a part of content then wrappers /# and #/ has to be applied. In the other words, ~ should substituted with /#~#/ and line break with /#\r#//#\n#/. page 23

24 Document methods SaveDocument(document, file) Creates and updates a webcrm document. The first parameter is used to describe the document and specify how it is linked in webcrm. The second parameter is to pass file content. It is requried when creating new document. Otherwise it is optional. Maximal allowed size for the uploaded file is 30 MB. ReadDocument(documentId) Returns description data of the webcrm document specified by ID. Document ID can be received as a result of SaveDocument method or by RetrieveByQuery method. Note that the document itself cannot be retrieved. page 24

25 Notes for the webcrm B2C version (the so-called person version) In webcrm the data model is identical for both B2B and B2C versions. However, in the B2C version of webcrm the parent level of data entities appears as Person and there will always be one and only one row of the person table linked to each row of the organisation table. For the B2B version there can be any number of persons (including zero) linked to each organisation. For the B2C version no data entity of type Organisation is visible in webcrm screens. Instead the Organisation data fields are display along with the Person data fields as if it were one record and appearing to be part of the Person record. However, the internal data table and record structure is exactly the same as for the B2B version with separate Organisation and Person records. For the B2C version the Organisation data fields Name and Division name are not used instead a company name can be located in a custom field ( See webcrm: Configuration/ Custom fields ). For the B2C version Organisation records cannot be directly created from the web service methods they will be created automatically by the API when creating a Person. So for the B2C version you must create a Person, and then update the corresponding Organisation fields (if required). To read or modify a Person record use the ReadFromWebcrmById() with a personid as input to obtain the organisationid for the person record. Then use both OrganisationID and PersonID when modifying a person record. page 25

26 Application note: Integrating webcrm with ERP Systems Debtor integration Debtor basic data in ERP (Customer name, address, telephone, www, VAT number, VAT group) is synchronized with Organisations in webcrm. Debtor contact person details can optionally be synchronized with Persons in webcrm. When Debtor basic data is created/updated the data should be synced to webcrm. A feature for initial sync should be available. This will enable to copy all ERP Debtors to Organisations in webcrm. Filter options for example for selecting only active debtors, can be considered. Normally the unique Debtor number is used as key for the sync process. webcrm has custom fields available for unique data fields. When new Organisations in webcrm are created/updated the webcrm system field LastUpdated is updated with a timestamp. This timestamp field can be used by the sync process to search for updated Organisations in webcrm since the last successful sync. Normally you will also filter to sync only Organisations with status = Customer. You can apply the API method RetrieveByQuery for this process. A simple approach is to add a button in ERP Sync webcrm. Clicking this button will execute the sync from webcrm to ERP. You could additionally schedule the process to run automatically every few hours. Order and invoice status Rather than updating webcrm with information detailed such as Debtor order status, previous orders and invoices we instead recommend links (URL) as buttons in webcrm to the ERP system to look up such information on-line in the ERP system (in a read-only web page). We can provide encrypted keys as part of the URL to authenticate each such look up. Contact webcrm to agree on how webcrm shall render such links in the webcrm system. As a part of the above Debtor sync you may consider to include syncing key information such as Credit line/status, total number of orders, alert message etc. webcrm has custom fields for such purpose. page 26

27 Creating quotations and orders from webcrm To create quotations and orders in webcrm we recommend a link (URL) as a button in webcrm to the ERP system open a web page in the ERP system. We can provide encrypted keys as part of the URL to authenticate each such a web page. Contact webcrm to agree on how webcrm shall render such a links in the webcrm system. Alternatively it is possible to sync all the possible order-items (maximum items) to webcrm including VAT codes (see separate documentation for Quotations in webcrm). By doing so it becomes possible to create and edit quotations directly in webcrm. Such quotations can be synced to ERP by the API method RetrieveByQuery for this process. When quotations in webcrm are created/updated the webcrm system field LastUpdated is updated with a timestamp. This timestamp field can be used by the sync process to search for updated quotations/orders in webcrm since the last successful sync. You can consider filter options to only sync quotations when the status in webcrm changes to Order. A simple approach is to add a button in ERP Sync webcrm orders. Clicking this button will execute the sync from webcrm to ERP. You could additionally schedule the process to run automatically every few hours. page 27