1 Integration Framework of SAP Business One Introduction to Creating Scenarios for SAP Business One03, 2015 This course introduces the general process and techniques for creating a new scenario package that involves SAP Business One.
2 Objectives At the end of this course, you will be able to:Describe the general process for designing and creating a new integration scenario package Follow the steps to create a simple scenario package that converts an inbound SAP Business One object to a file outbound At the end of this course, you will be able to: Describe the general process for designing and creating a new integration scenario package Follow the steps to create a simple scenario package that converts an inbound SAP Business One object to a file outbound
3 Overall Scenario Design ProcessStep 1: Analyze the Integration Requirement Step 2: Translate the Business Process Model into a Scenario Design Step 3: Define the Scenario Package and Steps Step 4: Write the Data Transformation Statements Step 5: Activate and Test the Scenario Steps Step 6: Transport the Scenario Package to the Production Environment You generally follow a defined process for creating new scenarios involving SAP Business One. The steps in this process are: Analyze the integration requirement from a business and technical perspective Translate the business process model into a scenario design Define the scenario package and steps Write the data transformation statements needed to produce the data in the format for the receiver system Activate and test the scenario package steps in the development environment Transport the package to a production environment Each of these steps is important and this course will cover the steps in more detail, using a sample scenario that converts an SAP Business One object to a flat external file.
4 Step 1: Analyze the Integration RequirementThe first step is the case analysis. The outcome of this step is a business process model.
5 Step 1: Case Analysis The requirement will involve the exchange of data between two systems Before creating the scenario package, analyze and model the business process Based on the model, identify the parts to be implemented in the integration framework – this requires a good knowledge of the functions and capabilities of the integration framework The business process requirement will involve the exchange of data between two systems. You can model the business process using standard design tools. The model should cover the entire business process and include decision points and processing done in third-party or external systems. Then you should identify the parts of the business process to be implemented in the integration framework. In order to do this you need to have a good knowledge of the functions and capabilities of the integration framework, for example, adapter types, atoms, etc. You should not skip this step even if the business process seems straightforward. If you make a mistake in the analysis, you may not discover this until you implement the scenario. Make sure that the customer reviews and accepts the design before you progress to the next step.
6 Step 2: Translate the Model to a Scenario Package DesignThe next step translates the business process model into a design for an integration scenario.
7 Step 2: Scenario Design A scenario package can contain one or more steps. A step models a specific interaction between two systems These interactions can be synchronous or asynchronous, and you can have a mix of synchronous or asynchronous steps Asynchronous example: SAP Business One object transformed to an output file Synchronous example: Web service that adds or updates an SAP Business One object using a call atom. The response is returned back to the Web service A scenario package can contain one or more steps. A step models a specific interaction between two systems. These interactions can be synchronous or asynchronous, and you can have a mix of synchronous or asynchronous steps in the package. For a simple business process with a single interaction, there will be just one step. For a more complex business process with multiple interactions, there can be several steps. In the slide example you can see a single interaction in which a sales order from SAP Business One is transformed to a file. An event from SAP Business One triggers the scenario step. This is an asynchronous scenario step. Another example of an interaction is a Web service that adds or updates a document in SAP Business One. The Web service system is the sender of this scenario step. This is a synchronous scenario step, because after receiving the request and calling SAP business One, the integration framework sends the response back to the Web service system. Within the step process there is an atom that calls SAP Business One. In a scenario package you might have a step for each document type.
8 Step Design Decide how the step will be triggered, which system types communicate with each other, how the integration framework will transform the message, and what other processing will occur, such as calls to external systems In this step example: Inbound Processing Outbound The sales order created in SAP Business One triggers the integration processing The inbound adapter is SAP Business One The processing is a single atom which transforms the retrieved B1 object into the file format The outbound adapter type is a flat file In the design for the step, you decide how the step will be triggered, which system types communicate with each other, how the integration framework will transform the message, and if any other processing will occur, such as calls to external systems. Note that the system types are independent of sender and receiver direction. In the step definition you define the inbound and outbound phases of the interaction and select the relevant adapter types. Note that the sender and receiver systems are not defined within the step. You do not specify the sender and receiver systems until you are ready to deploy the package. You also define the step processing which can include data transformation as well as other atoms for other types of processing such as external calls or . In the example, the sales order is created in the SAP Business One system and this triggers the integration processing. The inbound adapter type is SAP Business One. The processing is just one single atom which transforms the retrieved B1 object into the file format required by the receiver system. The outbound adapter type is a flat file.
9 Step 3: Create the Scenario Package and StepsNow you define the package and steps using the integration framework development environment.
10 BizStore Naming ConventionPath: All scenario components are stored in the BizStore database of the integration framework Scenario packages are identified with the prefix vPac Scenario steps are identified with the prefix vBIU (Business Integration Unit) Example: Scenario Step vBIU.sapB1PO2B1SO Scenario Package vPac.sap.ICPurchasing Before you create the scenario package and steps, you should decide on a naming convention for your scenarios. All the components of scenarios you create are stored in the BizStore database of the integration framework. Scenario packages are stored in the com.sap.b1i.vplatform.scenarios.design area of the BizStore. Within the BizStore the scenario packages are identified with the prefix vPac and the development prefix you entered. The scenario steps are identified with the prefix vBIU (Business Integration Unit). To view the BizStore directly you need to use an external XML editor (not the internal editor of the integration framework). You should develop a naming convention so that your scenario steps are easy to locate. Scenario Step vBIU.sapB1SO2B1PO
11 Scenario Package Creation - ProcessScenario Step Inbound Processing Outbound Create a new scenario Define scenario step and associate to scenario package For each scenario step: Define the Inbound channel and retrieval mode Define the Processing (flow and transformation atoms, and prepare XSLT statements for the output file format Define the Outbound channel The overall sequence for creating a scenario package is: First create the scenario package Then define each scenario step and associate it to the package name For each scenario step: Define the inbound channel by selecting the correct options from the integration framework’s menus. Define the retrieval mode for the incoming message, for example the DI API. Define the Processing. This might require adding flow atoms and data transformation atoms. Prepare the XSLT statements for converting the incoming message to the outbound file format. Define the Outbound channel by selecting the correct options from the integration framework’s menus.
12 Create Scenario PackagePath: Scenarios → Package Design Select the + icon to create a new package Enter a name for the package 2 1 It’s a straightforward task to create a new scenario package from the Scenarios > Package Design tab. Select the + icon to create the package. Enter a name for the package. The name cannot contain spaces or underscores. The prefix will be added to the package name when you press the save button. For information on setting up a prefix, see the companion course “Settings for Development Environment.”
13 Define Scenario Step Select the + icon to create a new stepPath: Scenarios → Step Design Select the + icon to create a new step Select the Package name Enter the step name Proceed to define the Inbound, Processing and Outbound for the step by selecting the buttons 2 3 4 1 To define a step, choose the Scenarios > Step Design tab. Select the + icon to create a new step. Make sure you select the correct package name, then enter a name for the step. After you save the step definition, you can proceed to define the Inbound, Processing and Outbound for the step by selecting the relevant buttons.
14 Step Inbound DefinitionTo define the Inbound for the step, select the Channel button For a B1 to File scenario step, select the Inbound Channel and the Retrieval fields from the dropdown lists, as shown here 1 2 3 The inbound channel definition is built by selecting the Channel and Retrieval buttons in turn. For the B1 to File scenario, select the fields as follows from the dropdown lists in the Inbound Channel window: Inbound type is SAP Business One Process Mode is Asynchronous. Note this is the only choice available. The process mode for an SAP Business One inbound is always asynchronous. Process Trigger is B1 Event. The event is the creation of a sales order which will trigger the step. Identification method is also B1 Event. Identifier is 17. The objectID of a sales order is 17. Then select the Retrieval button to define how the object is retrieved from SAP Business One: Retrieval Adapter is DI API Retrieval Type is Object. Remember to save the changes. Tip: To see a list of SAP Business One objects and field names, go to the Help tab and choose B1 Object Help.
15 Step Outbound DefinitionTo define the Outbound for the step, select the Outbound button in step setup: For a B1 to File Outbound scenario, select the Outbound Channel fields from the dropdown lists, as shown here Select the Details button then select the Outbound File Formatting fields from the dropdown lists, as shown here 2 1 To define the Outbound for the step, select the Outbound button in step setup. For the B1 to File scenario, select the fields as follows from the dropdown lists in the Outbound Channel window: Outbound Channel is Flat File. Outbound Format is file. This is the only choice available. The Error Inbox Resend Mode is automatically selected but you can optionally change this setting. Next, choose the Details button and select the fields as follows from the dropdown lists in the Outbound File Formatting window: Outbound Format is dsv (delimiter separated value file). Mode is write. You can select other modes, such as append. Character Encoding is ISO. DSV Field Delimiter is entered as a comma. You can enter any applicable delimiter character. Remember to save the changes. Note: A Format Control Document is only needed if you choose a txt Outbound Format.
16 Step Processing Processing To define the Processing for the step, select the Processing button in step setup: The BizFlow diagram for the step opens with a default process flow (atom0) This final atom will transforms the input XML message into a file structure for the outbound phase No other atoms are needed for this scenario At runtime, the input message to the atom contains the sales order object When you select the Processing button in the step setup, a BizFlow diagram opens, as shown here. You will see a single atom in the process flow. The default processing for a step is a single transformation atom (atom 0). The purpose of this final atom is to transform the input XML message containing the sales order object data into a file structure for the outbound phase. When the step runs, the input message to this atom contains the sales order object data. For the sample B1 to File conversion scenario, no other atoms are needed. If required, you can add further atoms to the process flow by choosing the arrow at the start of the BizFlow.
17 Step 4: Write the Data Transformation StatementsAfter you have defined the scenario step you write the data transformation statements.
18 Example Message StructureThe XML message that the integration framework processes from one flow atom to the next contains various sections that are transformed along the way Trigger - B1 Event coming from the table SEVT Sender message – object fields The XML message that the integration framework processes from one flow atom to the next contains different sections that are transformed along the way to produce the final message for the outbound phase. In this example: The Payload “T” section contains the B1 event which is the trigger for the processing step. The Payload “S” section contains sender message, in this case the DI API object structure. The Payload “R” sections will contain the receiver message that is handed over to the outbound channel, in this case, flat file fields. This section is not completed until the final transformation atom runs. Receiver message for handover to the outbound channel
19 Data Transformation For the B1 to File scenario, you need to define transformation statements for the final atom In these statements you define the flat file structure for the outbound phase Since the flat file fields are based on the input object, you can view the object by running a test to generate the payload section “S” of the message After you write the transformation statements the final atom will add section “R” to the message XML Message Payload section “S” with inbound object structure Payload sections “R” with flat file fields for the outbound phase For the B1 to File scenario, the final XML message that is handed over to the outbound phase will contain the flat file fields extracted from the sales order object. To accomplish this, you need to define transformation statements that are processed by the final transformation atom. In these statements you define the flat file structure for the outbound phase. Since the flat file fields are based on the input object, the easiest ways to see what the sales order object structure looks like is to run a test! You can run a test even though you have not yet defined the output file. The test will generate the payload section “S” of the message. After you write the transformation statements, the final atom, when it runs, will add section “R” to the message.
20 Step 5: Activate and TestThe next step is to activate and test the scenario steps. For the B1 to File scenario, you will complete the data transformation statements during the testing.
21 Define Inbound System Path: SLD Before activating the scenario, define the systems for the scenario package inbound and outbound phases Example: For the B1 object to file scenario, select an SAP Business One database from the SLD list Use the Test Connection button to test connectivity Before you activate the scenario, define the systems in the SLD for the inbound and outbound phases. For the B1 to file scenario, you would select a system from the list of SAP Business One databases. Note that this database should be configured to match the customer’s database, including any user-defined fields and tables, and master data needed for the scenarios or other configurations needed for the scenario. Be sure to test the connectivity.
22 Define Outbound SystemPath: SLD → Create System In the SLD, define the systems for the scenario package Example: For the B1 object to file scenario: Create a new system based on system type F.AnySystem Predefine the folders and enter file patterns for the FILI and FILO folders on the receiver system Note: If you include the pattern ???? in the file name, the integration framework will increment the value each time, starting from 0000 1 For the B1 to file scenario, a new system is created in the SLD for the outbound phase. This new system, which we name File Out, is based on the system type F.AnySystem. Because the outbound is a file, you need to predefine the FILI and FILO folders that the integration framework will use on the receiver system. In this example we called the folders In and Out. Make sure that the folders are accessible by the integration framework and can be written to. Then enter file patterns for the inbound and outbound folders. The file patterns can contain wildcard characters. If you include question marks in the pattern for the file name, the integration framework will increment the value, starting from 0000, each time it creates an outbound file in the FILO folder. 2 3
23 Activate the Scenario for TestingPath: Scenarios → Setup There are two ways to activate the scenario: Run the setup wizard, or Manually select the sender and receiver systems, then choose Activate You need to activate the package in the integration framework. You can activate the package manually or run the setup wizard. The result is the same. To activate a package manually, select Scenarios > Setup and select the Sender and Receiver systems from the SLD, then choose the Activate button Note: Once you activate the package you cannot change any of the step definitions until you deactivate it again. Run the setup wizard
24 Data Transformation StepsFor this B1 to File example, you still need to write the data transformation statements to convert the object to a flat file: Trigger the step by creating a sales order Open the XML message from the message log. In the payload “S” section you will see the object structure In the BizFlow diagram, open the XSL file for the final atom and add your XSLT statements Rerun the test. When the final atom runs, the XML message payload “R” sections are completed XML Message Payload section “S” with inbound object structure atom0.xsl Payload sections “R” with flat file fields for the outbound phase For this B1 to File example, you still need to write the data transformation statements to convert the object to a flat file. To do this you will test the inbound phase to see the XML message contents: Trigger the step by creating a sales order in SAP Business One Using the message log, open the XML message for the step. This contains the payload “S” section filled with the sales order fields. In the BizFlow diagram, open the XSL file belonging to the final atom and add your transformation statements to define the flat file structure. Rerun the test from the message log. When the final atom runs, the payload “R” sections are completed. Open the XML message again from the message log to see the payload section “R”.
25 Test the Scenario Step and Open the Message LogPath: Monitoring → Message Log After you create a sales order, view the message log display In the log, choose the icon to open the XML message To test the scenario step, create a Sales Order in SAP Business One. This triggers the step. Open up the Message Log by choosing the Monitoring > Message Log tab and refresh the log display. In the log message, choose the relevant icon to open the XML message that the integration framework is processing.
26 View the XML Message from the Message LogIn the Payload Role = “S” section you can see the DI API field names for the sales order object: BOM/BO/Documents contains the header fields BOM/BO/Document_Lines contains the row fields In the message you can see the various payload sections. In the Payload Role = “S” section you can see the list of DI API field names from the sales order object, for example, the DocNum and the CardCode, and so on. You can also see the XML tags that define the object structure, for example: BOM/BO/Documents contains the header fields BOM/BO/Document_Lines contains the row fields Note: to view the message in the message log, you must set the Log Level parameter to “Full message” in the Maintenance → Cfg MsgLog tab. Note: to view the message, set the Log Level parameter to “Full message” in the Maintenance → Cfg MsgLog tab
27 Preparing the XSLT Statements -1The basic XSLT for a flat file is to define a
28 Preparing the XSLT Statements - 2In the
29 XSL File for Atom0 Open the BizFlow diagram by selecting the Processing button in the scenario step definition Double-click the final atom to open the predefined XSL file atom0.xsl The
30 Insert the Transformation StatementsInsert the XSLT statements between the transform template tags Follow the object structure to select the values from the object fields
31 Rerun the Test and Check the MessagePath: Monitoring → Message Log From the message log, retry the message From the Message Log monitoring tab, retry the message by selecting the relevant icon. You have the option to resend the message from the start or restart the process.
32 View the Final XML MessageOpen the XML message again from the message log If the transformation has worked you will see the row and column structure for the selected fields in the Payload Role = “R” section of the message Open the message again using the relevant icon. If the transformation has worked, you will see the row and column structure in the Payload Role = “R” section of the XML message.
33 Outbound File The outbound file is located in the outbound folder defined in the SLD entry for the receiver system Finally, you can see the output file in the folder you defined in the SLD entry for the receiver system.
34 Step 6: Export the Scenario Package to the Production EnvironmentAfter you have fully tested the scenario, you export the scenario package to the production environment.
35 Documentation To include documentation with the scenario package:Path: Tools → Control Center → Maintenance → BizStore Upload To include documentation with the scenario package: Create the document in pdf format with the file name vPac.pdf Save the document to the vPac folder of the scenario in the BizStore Include the document with the final export zip package. To deliver documentation with the scenario package, create a PDF document called vPac.pdf and use the BizStore upload tool load it to the vPAC folder of the scenario in the BizStore. The BizStrore URI is /com.sap.b1i.vplatform.scenarios.design/vPac.
36 Export the Scenario PackagePath: Scenarios → Export To transport the scenario package, create an export file You can include scenario packages, scenario steps, documentation and test messages in the export file To transport the scenario to the customer’s production environment, create an export file. Use the built-in export tool to copy the package as a zip file. You have the option to include the test messages that you used during the debugging. The export creates a zip file.
37 Summary In this course, you learned a basic process for developing a scenario package that involves SAP Business One: Step 1: Analyze the Integration Requirement Step 2: Translate the Business Process Model into a Scenario Design Step 3: Define the Scenario Package and Steps Step 4: Write the Data Transformation Statements Step 5: Activate and Test the Scenario Step 6: Transport the Scenario Package to the Production Environment In this course, you learned a basic process for developing scenario packages involved SAP Business One: Step 1: Analyze the Integration Requirement Step 2: Translate the Business Process Model into a Scenario Design Step 3: Create the Scenario Package and Steps Step 4: Write the Data Transformation Statements Step 5: Activate the Test the Scenario Step 6: Transport the Scenario Package to the Production Environment
38 Thank You! For more information visit SDN at
39