Adeptia NetSuite Integration Accelerator User Guide. 343 West Erie, Suite 440 Chicago, IL 60654, USA Phone: (312) x111 Fax: (312)

Transcription

1 Adeptia NetSuite Integration Accelerator User Guide 343 West Erie, Suite 440 Chicago, IL 60654, USA Phone: (312) x111 Fax: (312)

2 Table of Contents 1 INSTALLATION OVERVIEW CONFIGURING NETSUITE INTEGRATION ACCELERATOR NETSUITE.COM ACCOUNT CONFIGURATION ACCELERATOR TEMPLATES, SERVICES AND PROCESS FLOWS TEMPLATES Template Name: T_XYZObject_To_Netsuite_ Template Name: T_XYZObject_From_Netsuite_ SERVICES Web Service Activities XML Schemas Mapping PROCESS FLOWS Name: NSLogin_ EXAMPLE PROCESS FLOWS PA_CUSTOMERADDLIST_TO_NETSUITE_ PA_SEARCHCUSTOMER_FROM_NETSUITE_ ADEPTIA IMPLEMENTATION APPROACH DESIGN, CONFIGURE AND DEPLOY STEPS Design Configure Deploy USING NETSUITE INTEGRATION ACCELERATOR DESIGN PROCESS FLOW CONFIGURE THE SERVICES MODIFY MAPPING ACTIVITY TO HANDLE WEB SERVICE SEARCH RESPONSE DEPLOYING THE PROCESS FLOW Event and Triggers Event Registry APPENDIX A: SYSTEM REQUIREMENTS AND PREREQUISITES SYSTEM REQUIREMENTS PREREQUISITES ADEPTIA NETSUITE Page 2 of 26

3 1 Installation 1.1 Overview Adeptia Netsuite Integration Accelerator is designed to help speed up implementing a solution for connecting Netsuite.com with the internal applications and systems of an organization. It consists of Adeptia Server process flow templates and services that can be easily and quickly configured to create data flows between Netsuite and internal applications and databases. Setting up Adeptia Netsuite Integration Accelerator consists of two steps. 1. Installing the Adeptia Server that includes Netsuite Integration Accelerator Objects 2. Configuring the Netsuite Integration Accelerator This section covers installing Adeptia Netsuite Integration Accelerator. For installing the Adeptia Server, please refer to Adeptia Installation Guide at There is an additional checkbox Install NetSuite Accelerator in Enter Adeptia Server Database Information screen. Select this checkbox to install Netsuite Accelerator. After installing the Adeptia Server with Netsuite accelerator objects, login into Adeptia Server using the following information: - User account: NetSuiteUser - Default password: nsuser123 You will see the Netsuite process flows and services in the repository such as Manage -> Process Flows. Refer to Adeptia Server user manual to learn more about process flows and services. Page 3 of 26

4 2 Configuring Netsuite Integration Accelerator 2.1 Netsuite.com Account Configuration A Netsuite.com user account with integration privileges is required to connect to Netsuite.com through web services. The account should also have the necessary permissions for operations such as to create, update and view objects details based on the integration needs. To configure this user account within Adeptia Server so it can be used at run-time, follow the steps below. 1. Login into Adeptia server as admin. Password for admin user is indigo1. 2. Click on Administer tab and navigate to Setup menu option and Click Application Settings, the Application Settings page is displayed. 3. Click Update System Properties Link, the Update System Properties page is displayed. 4. Page 4 of 26

5 Note: To get the Netsuite Account ID, login into Netsuite with Administrator role and navigate to Setup -> Integration -> Web Services 5. Enter the 'Netsuite LoginID' in 'abpm.solution.netsuite. id' section 6. Enter the 'Netsuite Account ID' in 'abom.solution.netsuite.accountid' section 7. Enter the 'Netsuite Login Password' in 'abpm.solution.netsuite.password' section 8. Enter the 'Netsuite Account Type' in 'abom.solution.netsuite.accounttype' section 9. Click on 'Save' button 10. Click Reload configuration link in the confirmation page Page 5 of 26

6 3 Accelerator Templates, Services and Process Flows 3.1 Templates Adeptia provides process flow templates to make it easy for designing the flows that may be required for customer s integration needs. Most implementations of process flows to either move the data from or to Netsuite.com follows a common pattern that is pre-built into the templates. The template process flows are designed to guide through these patterns and to quickly and easily implement a process flows. The templates explain the process from a high level Template Name: T_XYZObject_To_Netsuite_2012 Customer Internet F I R E W A L L ERP (Account Master) Sales Business The process flow template listed in the process flow manage page with the name T_XYZObject_To_Netsuite_2012 is to help to implement a process flow for moving the data from internal system to Netsuite.com. When a process flow is created from the template, a suggestion for naming the process flow is to replace T_XYZObject with internal system name and the Netsuite.com object Name. For example as in ERP_Customer_To_Netsuite. Page 6 of 26

7 \ Following table lists the activities which are used in this process flow and their description: Activity Label Activity Name Activity Type Activity Purpose Call to NetSuite Login Flow Call Call Call the NSLogin Process flow to log into NetSuite and get Session ID. Fetch Record Data File NS_XYZObject_LeadRequest File Source Reads the Lead CSV file. Read Record Schema Fetch bunch of Records Process incoming bunch of records into XML stream NS_ XYZObject _RecordSchema RecordQueueProducer RecordQueueReceiver Text Schema RecordQueueProducer RecordQueueReceiver RepeaterService RepeaterService RepeaterService Map Add Record Add webservice call Fetch update and error records Error record schema Persist error records NSMap_ XYZObject _AddRecord NS_AddWS NSMap_ XYZObject _FetchUpdateRecords NS_ XYZObject _ErrorSchema NS_ XYZObject _ErrorStatusFT Data Mapping Web Service Consumer Data Mapping Text Schema File Target Schema for parsing the record data from the CSV file. Process the bunch of records from input data Process the incoming records and convert it into XML stream. Generates multiple streams of incoming data to pass it to the subsequent activities Maps the data for Add webservice call. Web service to add leads on Netsuite Mapping Activity to fetch the update and error records from incoming data. Converts error records XML stream to Text data stream Persist error records in a CSV file Page 7 of 26

8 Disable Schema header PutContextVarTag Put-Context-Var Fetch Records one by one RecordQueueProducer1 RecordQueueProducer Disables the File header property for error records CSV file so that only one header is generated in each iteration of the process Fetch the incoming update records one by one Template Name: T_XYZObject_From_Netsuite_2012 Customer Get Messages Internet F I R E W A L L Adepti ERP (Account Master) Sales Business The process flow template listed in the process flow manage page with the name T_XYZObject_From_Netsuite_2012 helps implement a process flow for moving the data from Netsuite.com to internal system. When a process flow is created from the template, a suggestion for naming the process flow is to replace T_XYZObject with internal system name and the Netsuite.com object Name. For example as in ERP_Customer_From_Netsuite. Page 8 of 26

9 Following table lists the activities which are used in this process flow and their description: Activity Label Activity Name Activity Type Activity Purpose Call to NetSuite Login Flow Fetch Search Query File Call NS_ XYZObject _LeadRequest Call File Source Read Record Schema NS_ XYZObject _RecordSchema Text Schema Map Record Data for NetSuite Search Format NetSuite Search Web service Call Map search response NSMap_ XYZObject _RecordSearchAll NS_SearchWS NSMap_ XYZObject _ResponseFromNetsuite Data Mapping Web Service Consumer Data Mapping Call the NSLogin Process flow to log into NetSuite and get Session ID. Reads the source file which contains the search criteria Converts the data from the source file into XML stream. Maps the Record for Search Web service Call. Makes the Search Web service Call to NetSuite Maps the Number of Pages in the Pagination Read Record Schema NS_ XYZObject _RecordSchemaWithHeader Text Schema Convert XML stream to CSV stream. Persist search response NS_ XYZObject _SearchResponseFT File Target Populates the customer's data in target CSV file. Generate searchmore message NS_ XYZObject _GenerateSearchMoreMessage CustomPlugin Generates input to the searchmore webservice call SearchMore Web service Call Map searchmore response NS_SearchMoreWS NSMap_ XYZObject _ResponseFromNetsuite_SearchMore Web Service Consumer Data Mapping Makes SearchMore service Call to NetSuite Data mapping iterates over each of the record of the searchmore response and extract the information of the Page 9 of 26

10 each customer. Read Record Schema NS_ XYZObject _RecordSchemaWithoutHeader Text Schema Convert XML stream to CSV stream. Persist searchmore response NS_ XYZObject _SearchResponseFT File Target Populates the customer's data in target CSV file. NetSuite Logout NS_LogoutWS Web Service Consumer Makes Logout Web service Call to NetSuite so the session will end 3.2 Services Adeptia Netsuite Integration Accelerator has several process flow services pre-built to speed up the implementation process Web Service Activities The NetSuite Integration Accelerator package contains the Web Service consumer activities. The web service activities are intended to be used in process flows that interact with the NetSuite web services. Web Service Operation Type Web Service Name Description login NS_LoginWS_2012 Web service to login into NetSuite logout NS_LogoutWS_2012 Web service to Logout from Netsuite add NS_AddWS_2012 Web service to add leads on Netsuite update NS_UpdateWS_2012 Web service to Update Existing Leads in Netsuite Search NS_SearchWS_2012 Web service to search for set of records based on search criteria XML Schemas The NetSuite Integration Accelerator package contains the XML Schemas that will handle all the web service operations and Record types. The schemas are intended to be used in From or To process flows. Adeptia XML Schema Name NS_Schema_Input_2012 NS_Schema_Output_2012 Description XML schema for input to the web service operation XML schema for web service output Page 10 of 26

11 3.2.3 Mapping The NetSuite Integration Accelerator package contains mapping activities which is used to generate different web service messages as well as handle web service responses. These mapping activities are intended to be used in From or To process flows. Mapping Activity Name PA_SalesOrderAddList_Map_2012 PA_SalesOrderUpdateList_Map_2012 PA_CustomerAddList_Map_2012 PA_OpportunityAddList_Map_2012 PA_OpportunityUpdateList_Map_2012 PA_ContactUpdateList_Map_2012 PA_ContactAddList_Map_2012 PA_CustomerUpdateList_Map_2012 PA_UpdateListResponse_Customer_Map_2012 PA_ContactAddList_Resp_Map_2012 PA_UpdatetListResponse_Opportunity_Map_2012 PA_UpdateListResponse_SalesOrder_Map_2012 PA_UpdateListResponse_Contact_Map_2012 PA_SalesOrderAddList_Resp_Map_2012 PA_OpportunityAddList_Resp_Map_2012 PA_InvoicesSearchMore_Resp_2012 PA_InvoicesSearch_Resp_2012 PA_KitItemsSearch_Resp_2012 PA_AssemblyItemsSearch_Resp_2012 PA_KitItemsMoreSearch_Resp_2012 PA_AssemblyItemsMoreSearch_Resp_2012 PA_SalesOrderSearchMore_Resp_2012 PA_SalesOrderSearch_Resp_2012 PA_OpportunitySearchMore_Resp_2012 Description Generate request to add record in Netsuite for SalesOrder Generate request to update record in Netsuite for SalesOrder Generate request to add record in Netsuite for Customer Generate request to add record in Netsuite for Opportunity Generate request to update record in Netsuite for Opportunity Generate request to update record in Netsuite for Contact Generate request to add record in Netsuite for Contact Generate request to update record in Netsuite for Customer Read response from the updatelist webservice for Customer Read response from the addlist webservice for Contact Read response from the updatelist webservice for Opportunity Read response from the updatelist webservice for SalesOrder Read response from the updatelist webservice for Contact Read response from the addlist webservice for SalesOrder Read response from the addlist webservice for Opportunity Read Invoices Search More Response and Populate database Read Invoices Response and Populate database Read Kit Item Response and Populate database Read Assembly Item Response and Populate database Read KitItem Response and Populate database Read Assembly Item Search More Response and Populate database Read SalesOrder Search More Response and Populate database Read Sales Order Response and Populate database Read Opportunity Response and Populate database Page 11 of 26

12 PA_ServiceItemsSearch_Resp_2012 PA_CashRefundSearch_Resp_2012 PA_CashRefundSearchMore_Resp_2012 PA_CreditMemosSearchMore_Resp_2012 PA_CreditMemosSearch_Resp_2012 PA_OpportunitySearch_Resp_2012 PA_ServiceItemsMoreSearch_Resp_2012 PA_CashSalesSearchMore_Resp_2012 PA_CashSalesSearch_Resp_2012 PA_DiscountItemsMoreSearch_Resp_2012 PA_DiscountItemsSearch_Resp_2012 PA_DeleteRecordsFromDB_Contact_2012 PA_DeleteRecordsFromDB_Opportunity_2012 PA_DeleteRecordsFromDB_SalesOrder_2012 PA_InventoryItemSearchMore_Resp_2012 PA_InventoryItemSearch_Resp_2012 PA_DeleteRecordsFromDB_Customer_2012 PA_CustomerAddList_Resp_Map_2012 PA_CustomerSearchMore_Resp_2012 PA_CustomerSearch_Resp_2012 PA_ContactSearch_Resp_2012 PA_ContactSearchMore_Resp_2012 Read ServiceItem Response and Populate database Read CashRefund Response and Populate database Read CashRefund Search More Response and Populate database Read Credit Memos Search More Response and Populate database Read Credit Memos Response and Populate database Read Opportunity Response and Populate database Read Service Item Search More Response and Populate database Read Cash Sales Search More Response and Populate database Read Cash Sales Response and Populate database Read DiscountItem Search More Response and Populate database Read DiscountItem Response and Populate database Delete added record from the database to add it again with NetSuiteInternalID Delete added record from the database to add it again with NetSuiteInternalID Delete added record from the database to add it again with NetSuiteInternalID Read Inventory Item Search More Response and Populate database Read InventoryItem Response and Populate database Delete added record from the database to add it again with NetSuiteInternalID Read response from the addlist webservice for Customer Read Customer Search More Response and Populate database Read Customer Response and Populate database Read Conatct Response and Populate database Read Conatct Response and Populate database 3.3 Process Flows Name: NSLogin_2012 This process flow is used to connect and login to Netsuite.com and open a session. The login process flow is designed to login into Netsuite portal using the credentials defined in Adeptia Server properties. To know how to define Netsuite login credentials, refer to Nesuite.com Account Configuration section. After login into Netsuite portal, this flow returns a session Id to the parent process flow, which is used by parent process flow for further communication with netsuite. The process flow can be called from other process flows before making a web service call to Netsuite.com. Page 12 of 26

13 The steps (also called services or activities) in this process flow are: Set Cookie in the Calling Flow NS_SetParentCtxCookie Activity Label Activity Name Activity Type Activity Purpose Read NetSuite Reads the Authentication information NS_LoginRequest_2012 Scripted Service Login Info from Server-Configure Properties file. Authentication Web service Web service NS_LoginWS_2012 Login Web service Call to NetSuite. Consumer Call Persist Login Persists the response of login NS_Customer_loginFT_2012 File target response webservice call to a file. Set Login Status Set-Parent- Set Login Status in calling process LoginStatus in Calling Flow Context flow s variable. Set-Parent- Context Set Cookie in the calling process flow s variable. 4 Example Process Flows Two process flows for the Customers record type are implemented based on the template process flows and packaged as part of the NetSuite Integration Accelerator package. 4.1 PA_CustomerAddList_To_Netsuite_2012 Name: PA_CustomerAddList_To_Netsuite_2012 Based on Template: T_XYZObject_To_Netsuite_2012 Description: Push new records from Database to Netsuite This process flow calls a sub process NSLogin_2012 which is used to login into Netsuite portal. After login, now in parent process flow, the advance database source activity PA_DBSource_AddListCustomer_2012 pull data from database source, which contains records to be added to Netsuite. The NS_AddWS_2012 web service activity tries to add all the records into Netsuite. Once the webservice call completes its execution then the response of web-service call received by data mapper called PA_CustomerAddList_Resp_Map_2012. If there would be any error record generated while inserting the data in NetSuite then those erroneous records inserted back into source database with error message. <<Insert Delete Description>> Page 13 of 26

14 Once all the records are processed, NS_LogoutWS_2012 web service activity is executed to log out from Netsuite. 4.2 PA_SearchCustomer_From_NetSuite_2012 Name: PA_SearchCustomer_From_NetSuite_2012 Based on Template: T_XYZObject_From_Netsuite_2012 Usage: Pull Data from Netsuite and Migrate to Database Tables This process flow calls a sub process NSLogin_2012 which is used to login into Netsuite portal. After login, now in parent process flow, the custom plugin activity PA_Customer_GenerateSearchMessage_2012 generate the search message for web-service call called NS_Search_2012, search message can also contains search criteria. The mapping activity PA_CustomerSearch_Resp_2012, takes the response from web-service call and makes it available to adv. database target activity called PA_CustomerDataTarget_2012. The mapping activity also sets the total page count and current page index (after increasing it by 1), in the process flow context. Once the search records are persisted in the target database, the process flow checks whether more data is available. This is done at the decision node using Java Condition. This Java Condition checks if the page index is greater than the page count. If it returns false, it means that more data is available. If more data is available then another web Service consumer activity NS_SearchMoreWS_2012 is used to fetch more data. Before this web service consumer activity, a custom plugin NS_Customer_GenerateSearchMoreMessage_PA_2012 is used to set the page index to be searched. Again the searched records are fetched in XML format which inserted into target database. If there is no more data available, a web service consumer activity NS_LogoutWS is used to logout from Netsuite. The Search Operators used in Customers_From_NetSuite process flow are: Search Value type: String Operators supported: Contains, doesnotcontain, doesnotstartwith, empty, is, isnot, notempty, startswith Search Value type: Long, TextNumber, Double Operators supported: between, empty, equalto, greaterthan, greaterthanorequalto, lessthan, lessthanorequalto, notbetween, notempty, notequalto, notgreaterthan, notgreaterthanorequalto, notlessthan, notlessthanorequalto Search Value type: Date Operators supported: after, before, empty, notafter, notbefore, notempty, noton, notonorafter, notonorbefore, notwithin, on, onorafter, onorbefore, within Search Value type: MultiSelect Operators supported: anyof, noneof Page 14 of 26

15 Search Value type: Time Operators supported: between Search Value type: Period Operators supported: equalto Page 15 of 26

16 5 Adeptia Implementation Approach Adeptia s approach for implementing any solution is the following 3 simple steps: Design, Configure and Deploy. 5.1 Design, Configure and Deploy Steps Design In the Design step the high level process flow is designed in the Process Designer graphically to describe the entire flow. This may be done either by a Business Analyst or an IT Developer by using the Process Designer. The process flow is not functional yet it is just a representation. The Adeptia Netsuite Integration Accelerator provides template process flows so this step can be made even easier. Users may use these templates or the sample process flows by easily modifying them to design the flows that meet their needs Configure In the configure step, the individual steps in the process flow are created. This is done by specifying the rules in the Adeptia services, this creates an instance of the Adeptia service which is called an activity. For example: Services like Database source, Database Schema, Mapping etc. are configured. Then, in the Process Designer these activities are associated with the steps in the process flow designed earlier. Adeptia Netsuite Integration Accelerator provides many pre-built activities for using in the creation of Netsuite integration solutions. Page 16 of 26

17 5.1.3 Deploy In the Deploy step, the process flow that has been designed and configured is activated by attaching it to a trigger that would start the execution of the flow. Various batch and real-time triggers are available. Page 17 of 26

18 6 Using Netsuite Integration Accelerator This section describes the Adeptia approach of Design, Configure and Deploy in implementing Netsuite integration solutions. This section explains how you can create a process flow using the template flows. 6.1 Design Process Flow We will create a process flow to fetch data from Netsuite.com to a database. You need to do the following exercise to create this process flow : Decide which module of netsuite you want to search. For example Opportunity Criteria on basis of which you want to search the module. For example lastmodifieddate Operator. For example within Predefined search value. For example lastbusinessweek For possible values of operators and predefined search value you can refer the Netsuite XSD documentation on To define these values and to generate the required web service request message, you have to modify the custome plugin activity used before 'NS_Search_2012' WebService Call activity to. Similarly to process the search response you need to modify the mapping activity which is used after the 'NS_Search_2012' activity. To know how to edit the mapping activity to process the search response refer to section Modify mapping to handle Web Service Search Response. Now to create the process flow to fetch the records from netsuite.com, which meets the criteria specified above, first you need to design a process flow and then you have to attach the activities with that process flow. In this step a copy of the template process flow is made because we don t want to edit or overwrite the template since we want it to be available for future use. The following steps are performed: 1. Navigate to Manage T_XYZObject_To_Netsuite_ Click Edit 3. Edit the Name field by replacing T_XYZObject with Object Name. For eg. ERP_Contact_To_Netsuite. Also edit the Description field. 4. Click SaveAs 5. Now the process flow can be used as is or can be modified to fit your business needs. Page 18 of 26

19 6.2 Configure the Services Configuring is the second step in completing the process flow. Services are the individual steps of the process flow. After creating the source services, source schema and the mapping objects to suit the business requirements, edit the process flow to attach the activities to the process flow. Most web service target schemas are pre-built as part of the Netsuite accelerator. In many cases only the source activities needs to be created and mapped to the existing target Web Service schemas and attach to the template process flow. For more information about creating and using services, refer to Adeptia Server User Guide. Here is an example of configuring XML Schema using Netsuite XSD. Page 19 of 26

20 6.3 Modify mapping activity to handle Web Service Search Response In this process flow, 'PA_CustomerSearch_Resp_2012' mapping activity is used to map the fields of the output of 'NS_Search_2012' web-service call. Currently fields of Customer entity are mapped with the fields of target schema. You need to modify this mapping activity. First of all you need to load the modified adv. Database schema called 'PA_CustomerSchema_2012' at the target end and then map the fields of Customer entity with the fields of target schema. Screen shot given below shows the existing 'PA_CustomerAddList_Rest_Map_2012' mapping activity. Page 20 of 26

21 Finally, the activities are to be attached to the process flow. This is done in the Process Designer by opening the flow in Edit mode. 1. In the Process Designer, navigate to the Service in the Activities Panel. 2. Select the activity and then drag and drop it on the step in the process flow. 3. Repeat until all the steps in the process flow are filled with an activity. 4. Now the process flow is complete and it is ready for execution. Page 21 of 26

22 6.4 Deploying the Process flow Event and Triggers Adeptia server offers several types of events and triggers such as database, calendar, File, HTTP, JMS, Mail, Timer, Web services to tie to the process flow so they can be completely executed automatically from various sources. Page 22 of 26

23 For e.g. to read the account information from Netsuite.com to synchronize the data with the internal system, the file can be scheduled to run the process flow every day. This creates a Calendar event to run the process flow every day at 6:00 AM. Page 23 of 26

24 Event Registry After the event or trigger is created the event must be registered to automate executing the process flow. The Final step is to activate the event. 1. Page 24 of 26

25 2. Select the event and click on the Activate button. 7 Appendix A: System Requirements and Prerequisites 7.1 System Requirements Hardware Software CPU: Intel Pentium IV 1GHz or newer RAM: 1GB min, 2GB recommended Hard Disk: 2GB Operating System: Windows NT/2000+/XP, UNIX, Linux Database: Embedded DB included. Commercial RDBMS recommended for production environments Java: J2SE v1.5 SDK (Bundled with Adeptia Server) Browser: IE 6.0 Misc.: Adobe Acrobat Reader Client End Applets: JRE Prerequisites One of the following Adeptia products must be installed before installing the Netsuite Integration Accelerator. Adeptia B2BI Server Adeptia BPM Server Adeptia EBIMS Server Adeptia ESB Server Adeptia ETL Server Please ensure that you have upgraded your license to support NetSuite accelerator. For further queries please contact to Adeptia Support (support@adeptia.com) as a part of license pre-requisition. Netsuite Account To integrate with Netsuite.com, an Enterprise Edition, Unlimited Edition, or Developer Edition account is required. Developer Edition account is used for building and testing the integration solution. Enterprise or Unlimited edition account is used for production solution. Page 25 of 26

26 Appendix B: Useful Links 7.3 Adeptia Technical Documentation Software Downloads Technical Support: Netsuite Integration Accelerator Solution Page Netsuite Integration Accelerator Data Sheet Netsuite Integration Demonstration Netsuite Netsuite.com Web Services Developers Guide Page 26 of 26