Differences

This shows you the differences between two versions of the page.

--- bw2:databuilder_tool [2021/02/11 15:36]
akoehler
+++ bw2:databuilder_tool [2022/08/02 15:33] (current)
akoehler
@@ Line 11: / Line 11: @@
 ====== Before You Begin ======
-You will need to know, or have examples of , the data structures the API is expecting. This includes element (field names) and child objects within the structure. Keep in mind that names will generally require an exact match, including case.
+You will need to know, or have examples of, the data structures the API is expecting. This includes an element (field names) and child objects within the structure. Keep in mind that names will generally require an exact match, including case.
 =====For SAP Business One Service Layer=====
-An easy way to view the data structures used for SAP Business One is to create a small workflow that executes a GET on the object in question.  The workflow will have two WebService2 steps: a login step and a GET step.  The GET step references the target object (e.g. SalesOrders). The GET step will return the data structure for the object in the "Output String."  This is also an easy way to create a template file for the object in your environment as it will include any user-defined fields as well.
+An easy way to view the data structures used for SAP Business One is to create a small workflow that executes a GET on the object in question.  The workflow will have two WebService2 steps: a login step and a GET step.  The GET step references the target object (e.g., SalesOrders). The GET step will return the data structure for the object in the "Output String."  This is also an easy way to create a template file for the object in your environment as it will include any user-defined fields as well.
 More information dealing with SAP Service Layer can be found **[[bw2:sap_business_one_integration_using_service_layer|here]]**
@@ Line 20: / Line 20: @@
   - Input will generally be from a SQL Reader step.
-  - The example used in this page is for JSON.  The same general process is also used for XML.
+  - The example used on this page is for JSON.  The same general process is also used for XML.
+  - When working with decisions, the Databuilder tool in a branch of a decision will only reference Databuilder tools in that same branch.
 ====== General Process ======
@@ Line 26: / Line 27: @@
   - Create an input (SQL Reader) step for each dataset that will be needed. An example would be order header and order lines.
   - Create a DataBuilder step for each dataset.
-  - Once all DataBuilder steps are created, add the lower-level datasets to the main dataset. The lower-level datasets are referenced by their Object Name. These are listed in the “Field Type” drop-down after they are created.
+  - Once all DataBuilder steps are created, add the lower-level datasets to the main dataset. Their Object Name references the lower-level datasets. These are listed in the “Field Type” drop-down after they are created.
-  - The “CumulativeData” variable from the main DataBuilder step in referenced in the web service step that transmits the information to the API.
+  - The “CumulativeData” variable from the main DataBuilder step is referenced in the web service step that transmits the API's information.
+====Databuilder====
+{{ :bw2:bizweaverdatabuilder1.png |}}
+  - **Tool Name:** This is the name given to the tool. This will be displayed in the design canvas as well as the variable selector
+  - **Description:** A space for notes about the tool.
+  - **DataSource Object:** This is the source of data for the Databuilder.
+    - This is required and is always a SQL/HANA tool.
+      - **Hint** the number of rows you feed into the databuilder from the subsequent SQL step determines the number of sections is output. This is more helpful when dealing with XML over JSON but keeps this in mind while generating JSON or XML the SQL statement and the database for the databuilder step.
+  - **Data Type:** This determines the type of file that is generated.
+  - **Add as an Array:** this will add an array to your JSON or XML.
+    - Arrays will be displayed in the Field Type drop-down
+    - If selected, it will insert the Array into the JSON or XML where it is located in the list.
+  - **Top-Level Element:** This clears the JSON or XML data if it is contained in a loop, so subsequent processes do not build on top of the previous cycle.
+    - This is generally used to update one thing at a time. If the API used can be updated with one large JSON or XML file, this option can be un-selected.
+  - **Create New Object:** The Object name of the JSON or XML structure.
+    - This can be used to create multiple levels of XML or JSON (see example below)
+  - **Preview Box:** A preview of the JSON or XML that is being built.
+  - **Name-Value Pair:**
+    - **Field Name:** The name of the name-value pair
+    - **Field Type:** This can either be String, Numeric, Boolean, or an Array built later in the workflow.
+    - **Value:** Normally a variable from the connected SQL/HANA step. These can also be hard-coded values.
+  - **Add Row or Delete:** {{:bw2:bizweaverdatabuilder2.png|}}  The down arrow will add a row below the current row. The "X" will delete that row.
+======JSON Example======
+Below is an example of how to build a basic JSON File. The data is coming from SAP but this concept applies to any API being used to pass data to.
+{{ :bw2:bizweaverdatabuilder3.png |}}
+  * Start by getting all the data needed and process that through a loop as we only want to process one record at a time in this example.
+    * **Note** Most APIs are case-sensitive.
+  * Once the data is sent into the loop you will limit it down to one record and add link it to the next step which is the data builder step
+    * Note Top-Level Element is selected. In this example, we are adding one record at a time
+{{ :bw2:bizweaverdatabuilder4.png |}}
+<WRAP center round tip 80%>
+In most cases the lower-level sections will need to be marked as an **array**. The “Add as an array” checkbox should be selected. However, always check your API documentation to verify this.  **At the same time**, the "Top-level Element" checkbox should remain cleared.
+</WRAP>
+<WRAP center round important 80%>
+When creating lower-level section that __may__ have more than one entry (i.e. an array), be sure to put the DataBuilder tool within a **Loop**.  As each record is read from the input it is added to the bottom of the array being constructed.  Not using a loop will result in an incorrect data structure.
+</WRAP>
+  * Once the data is mapped add another loop to process all lines. This will be built as an array. The Create New Object is filled in as it is needed to identify the array.
+{{ :bw2:bizweaverdatabuilder5.png |}}
+  * Once the lines data builder step is built you will then return to the header data builder step and it will now appear in the field type dropdown. Select it and it will now add the array to the header data builder step once it processes.
+{{ :bw2:bizweaverdatabuilder6.png |}}
+  * Once the JSON is built it the Cumulative data variable from the Header step can be used and entered into the body section of a Web Service 2 tool to then be sent through the API.
+{{ :bw2:bizweaverdatabuilder7.png |}}
+====Databuilder Variables====
+^Name         ^ Description
+|AddAsArry|True or False if the add as array checkbox is selected|
+|CumulativeData|This is the collection of all data that was built in the databuilder|
+|Data|This is the last run of data that was entered into the databuilder|
+|DataSourceName|This indicates the name of the tool that is being used for the source data for the databuilder|
+|DataType|This indicates the type of data your are building XML or JSON|
+|ObjectName|Is the name of the top level of your JSON or XML|
+|TopLevelElement|True or False if the top level element checkbox is selected|
+| StepMessage|During a failure the reason for failure will be populated here |
+| StepStatus        |True or False|

Wiki

User Tools

Site Tools

Differences

Page Tools