Web Services / Boomi

Introduction

With Web Service APIs, you can configure Planful to import data from an external source. First you need to complete the Web Service Access page located under Maintenance Configuration Tasks to define security access for importing data and set up user notification so that users know when new data is loaded to Planful.

Web Services is one method in which your data added to the Boomi Atmosphere (an on-demand integration service) is loaded to Planful. A web browser is used to build, deploy and manage integrations. No software or hardware is required.

This portion of the document discusses:

• Web Service Access
• Understanding Boomi
• Working with Planful APIs

Web Service Access

Complete the Web Service Access configuration task.

1. Access Web Service Access page under Maintenance > Admin > Configuration Tasks.

2. Click Web Service Access.

3. Click Enable for API.

4. Planful provides default URLs under Web Service URL. These URLs will be needed to connect with the Planful application through a session-state or state-free authentication.

5. From the list of available users, select users and click the arrow to map those you want notified when data is loaded.

Once Web Service Access is configured, you can create a Data Load Rule.

1. Navigate to Maintenance > DLR > Data Load Rules.

2. Click the New Data Load Rule tab.

3. Select Web Services as the Load Type on the New Data Load Rule page.

4. Use an external Data Integration tool (Boomi) to load data to the Planful system.

5. The steps will vary based on the external Data Integration tool used.

UnderstandingBoomi

Boomi Atomsphere is an on-demand integration service that makes it possible for Planful to integrate with a customers' general ledgers or ERP systems. Users can securely build, deploy and manage integrations using only a web browser.

Understanding the Boomi Integration Process

The main component in Boomi is the process. A process represents a business process- or transaction-level interface between two systems. An example of a process might be loading account dimension data to Planful. Processes in Boomi are depicted with a left-to-right series of shapes connected together like a flow chart to illustrate the steps required to transform, route, or manipulate the data from the source to the destination. Processes use connectors to retrieve and send data.

Processes are deployed to the atom which is a dynamic runtime engine. Once processes have been deployed, the atom contains all the components required to execute the integration processes from start to finish including connectors, transformation rules, decision handling, and processing logic.

Understanding the Boomi Interface

The lifecycle of any integration process would start from building it to managing it, and all the steps in between can be performed appropriately via the following menu options: Build, Deploy, Manage, and Account.

Build

Starting with the Build tab, Boomi Atomsphere applies the 'build' concept as a way to organize and control data processing. Integration requires data structuring to enable communication between the different applications. An integration service should allow structured data types to be extracted, manipulated, validated, and forwarded.

In order to integrate applications directly from the Web without coding, Boomi uses a built-in visual interface to create and direct process flows. This where an integration process is built.

Deploy

The Deploy tab allows users to specify on which atom(s) a process will run. A single process may be deployed to multiple atoms and a single atom can contain multiple processes. In the figure below, the Monthly Balances process has been deployed to the Planful atom.

An integration process is not deployed as the main version until all changes and testing have been completed. Once deployed, as shown in the figure below, each deployment is noted as unique version under the 'Deployments' section of the Deploy tab. Changes to the Build tab do not take effect until the new version has been deployed.

Manage

The Manage tab provides a view of process execution results, under Process Reporting. Data can be viewed and errors can be troubleshooted.

Also under the Manage tab, scheduling and the atom status can be viewed.

Finally, to view Account information, select the drop-down arrow next to the account name on the top right and select Setup.

Integration Types Explained

There are many types of Planful-supported integrations. The following documentation provides an overview of the entire integration for the simplest type: data file via SFTP or FTP.

Data File via SFTP

One of the most common integrations is a flat file containing data extracted from the customer's accounting system. The file which must be non-proprietary and delimited, is uploaded to the Planful SFTP site. Customer SFTP site credentials are created and supplied by the Operations Support Team.

The Integration Team reviews the file to ensure the formatting is correct and identifies the fields the customer wants to load into the Planful application.

The data load process is then created in Boomi Atomsphere. A connection is created to retrieve the customer file. In the figure below, the connection is named

HA SFTP Connection. This connection is from Boomi to the SFTP site using the customer's credentials.

Within this connection, an SFTP operation is defined. In the figure below, the data load process will retrieve any file that begins with K2 and then delete the file.

The fields are mapped in Boomi and mapped to the fields defined in the data load rule created in the Planful application. Then, via web services, the data is loaded into Planful.

Data Load

Two methods can be used to load data from Boomi to Planful: a scheduled data load or an On Demand web page. A scheduled data load automatically loads data based on the customer's business rules. For example, some customers want data automatically loaded after business hours each evening. while others want data loaded every few hours during the workday.

The On Demand web page places control of loading data into the customer's hands. Created by the Integration Team upon request, this method allows the customer to load data on demand.

With the On Demand web page, the customer enters Boomi login credentials, and the fiscal year and month they want to load. When Submit is selected, a data load process is started in Boomi.

In either case, an email notification is generated by Planful informing the customer that the data was loaded successfully or not. An example of an email notification for a successful data load is provided in the figure below.

If the data load is unsuccessful, exceptions are listed. In the figure below, an example of an email for an unsuccessful data load lists missing accounts. In order for the data to load successfully, the accounts must be added to the Planful application and the data load must be rerun.

Glossary of Terms

• Application Programming Interface (API) - programming instructions and standards for accessing web-based software applications or web tools.

• Boomi Atom - a lightweight, dynamic runtime engine. Once an integration process have been deployed to the atom, the atom will contain all the components required to execute processes from beginning to end, including connectors, transformation rules, decision handling, and processing logic.

• Boomi Atomsphere - allows for the integration of data directly from the web without installing software or hardware. Users can securely build, deploy and manage integrations using only a web browser. Boomi Atomsphere handles any combinations of software-as-a-service (SaaS) and on-premise application integration.

• Connector - used in Boomi, connectors get data into and send data out of processes. They enable communication with the applications or data sources between which data needs to move, or in other words, the "end points" of the process. If working with a customer who wants to load a file from the SFTP site, the SFTP Connector would be used. To load data from a data load process in Boomi into Planful, a Web Services Connector would be used.

• Web Services - a method of communication between two electronic devices over the web. Allows different applications from different sources to communicate with each other without time-consuming custom coding, and because all communication is in XML, web services are not tied to any one operating system or programming language.

Common Issues

Integration issues experienced by customers comprise three areas: source (data from a file or database), Boomi, or Planful. The following flow chart illustrates the steps required to determine where the issue lies.

Troubleshooting Steps

Verify that the data load process was successful in Boomi.

1. On the top right, click the account name, then select Switch Account.

2. Enter part of the account name and click Search.

3. Select the account name and click OK.

4. Select Manage , then Process Reporting.

   

5. By default, all data load processes executed within the past hour are listed. To choose an alternate time frame, select the drop-down listing and click Apply.

   

6. All data load processes executed during the selected time frame display. Each process has either a green dot which signifies that the process executed successfully or a red dot which signifies that the process executed with errors.

   

7. If there are errors, the issue is escalated to the Integration Team for resolution.

8. If there are no errors, the next step is to log into the customer's Planful application.

9. To verify that the data loaded successfully, select Maintenance > Data Load History.

10. Select the data load rule that was used to load the data. Use the From and To fields to narrow the search and click GO.

11. The data loads for the selected time frame display. There are two statuses: Pass and Fail . Pass indicates that the data load was successful while Fail indicates that the data load contained errors.

12. If the most recent data load status is Fail , select the failed data load and click the Detailed Report option.

13. The detailed data load log report displays.

14. If the most recent data load process is successful, select Maintenance > Load Data to verify that the period and/or year to which the customer is loading data is not locked.

15. If the period and/or year is not locked, select Maintenance > Reports > Process Cube & Dimension to process the cube.

16. If there are no issues, the next step is to verify the data in Boomi. Return to Boomi and select Manage > Process Reporting.

17. Under Executions , select the most recent data load process.

    
    

    Note:

    Default time frame is the Past Hour. If no data load processes display, select Past Week or enter a date range.

18. Click the date/time stamp to display the connections made during the data load process.

19. If the data load process uses a file, select SFTP, Connection HA SFTP Connection, Operation: Get GL File.

    

    Note:

    If the data load process uses a database connection, select the Database Connection: GP Connection, Get Summary Data 2 (or the appropriate operation name) as shown in the figure below.

    

20. Click the cog wheel and select View Document.

    

21. A partial view of the data displays in the document viewer once connected to the atom.

22. Select Download Original Document on the lower right side.

    

23. Click Save when prompted.

24. Open the file in Microsoft® Excel® or Notepad®. This data is pulled from the customer's source, either a file via SFTP or a database. Verify that the data is correct.

25. If there are errors, contact the customer to correct and reload.

26. If there are no errors, escalate to the Integration Team to reload the data.

Working with Planful APIs

Planful provides many Application Programming Interfaces (APIs). These APIS offer a simple, powerful and secured way of importing or exporting data to and from the Planful application.

For information, see the API Library.