Web Import Tool Guide

 ♦ Primary benefits: 

 ♦ Secondary benefits: 

If you are given Web Import Tool access rights:

Import / Export Rights

Data in Beeline Enterprise is stored in a series of data tables arranged in a hierarchy structure to support system functionality and workflows. To ensure that data is populated into the relevant data table, data can only be imported using a Beeline import template. The process starts by downloading the relevant import template. Templates are revised as needed to ensure that Beeline supports current market practices therefore users should ALWAYS download a new template prior to EVERY import to ensure that the template in use is the most current version.  

Once the new/revised data is populated into the template file, the next step is to validate the data by running the file through the validation process. In a perfect world, all files always validate with no errors with the first validation “run”. In the real world, there are several factors that can cause the validation to require multiple “runs”, requiring multiple error adjustments, before a file successfully validates. Templates that include data fields that are replicated throughout Beeline data hierarchies or templates that include multiple “conditional” fields will be the biggest challenge. Every data field has a single “home” location. However, a data field may be replicated in multiple data tables. Each instance of that field must remain in sync with the value of the “home” location. Some data fields are required due to Beeline data rather than client data, but this data needs to be entered as indicated. The validation process is not only to check data in the import file, but also to verify that it is consistent with the data already populated in the system. Patience is a key factor! The Import Tool is ALWAYS right. Items in the error list must ALWAYS be resolved—and resolved to the Import Tool’s satisfaction. The Errors List is not the enemy. It is the guardian at the gate to ensure that all is well before the import portal will be opened.

A “View Details” option allows users to review the validation results and adjust data entries as indicated. If adjustments are made, the file must be re-validated. This process is repeated until all data entries pass the validation process. ALL line items included in any import template data file must successfully validate before the file is ready to import into Beeline Enterprise.

The validation process identifies data that meets format or system specifications required within Beeline Enterprise. Validation does NOT verify that the content information is accurate—it can only verify that the content matches all system requirements as to data entry format requirements and data table hierarchy specifications. Verification that the data is accurate is a task reserved to client-side users because the data is, and always remains, the property of the client.

An Export file can go a long way to simplify the overall validation process since it can “reveal” how data is currently stored in your Beeline Enterprise instance and therefore serve as a model to follow when creating a new import file. Export files are also frequently referred to as “reverse imports”.

Step-by-step instructions for creating an import file, exporting a reverse import, validating the new import file, and importing the validated file are provided below. Check the Import/Export Template List chart located in this article to verify if the import template also allows for reverse imports. For those templates that do not include export rights, follow the instructions provided in the Header row Comment tags for guidance.

Who is authorized to Import, Export, or Validate?

Reach out to your Program Office for any questions as to import, export, and/or validation rights. These actions are permissions assigned to your user role. Please note: THESE PERMISSIONS ARE INDEPENDENT FROM CERTIFICATION LEVEL TRAINING. Completing Certification level training is not a prerequisite or requirement for the granting of import, export, and/or validations rights. The degree to which you are authorized to complete the activities included below depends on which permissions are assigned to you. If your permissions only grant you validation rights, then you will need the assistance of someone in the Program Office who has import rights to complete the import process once you have validated the import file. Permissions must be assigned to your profile to enable you to import, export, or validate files. You cannot impersonate a user to import, export, or validate in the Web Import Tool. Which Program Office staff are granted which rights is determined by your Program Office managers. Assigning the permissions to a user role profile record requires assistance from your Beeline Representative.

Download the template and populate the data fields.

Access to download an import template file is located under the Admin Header Menu or via the Self-Service Data Management selection list located under the Preferences Menu. Both methods are detailed below. System configurations and your user role settings determine which access method is available to you.

• From your home dashboard, click Admin in the Header Menu bar, then click Import. The Import screen displays.

• From your home dashboard, click the gear icon to display the Preferences menu.
• Hover over VMS Settings, then click Data Management in the fly-out panel. The Data Management screen displays.

• Click Web Import in the list of options. The Data Management : Import screen displays.

1. On the Import list screen, click Add New. (Note: The Add New link is only visible to users granted Web Import Tool access rights.) The Import – Status: Creating screen displays.

2. On the Import – Status: Creating screen, expand the Import Type drop-down list and select the import template you need. Once your selection is made, a download link for that import template automatically displays to the right of the Import Type field as shown in the second screenshot below. Notice that the Validate button is now visible as an Action button as well as the template download link next to the Import Type field.

3. Click the template name hyperlink to download the import template.
4. Click Cancel or Return to exit the Import – Status: Creating screen.
5. Use the “Save As” option to rename and save the template as your import file. Please follow any file-naming conventions required by your program. Use a filename that CLEARLY defines the contents of this template file, especially if someone else will be the importer and needs to select the file from the list screen.
6. Follow the format requirements as indicated in the import template’s header row. Simply hover over the header cell in each template column and the requirements display as Comments. Once your data entry into the template is complete, the next step is to validate your data file.

• Optional: Extract a sample file (i.e., reverse import) of your system data to use as a reference aide by following the instructions in the Export section below.
  Please note: Not all import templates include export rights. Check the Import/Export Template List chart located in this article to verify if this option is available for your import template.

Export a “reverse import” to use as a reference aide.

1. Use either the Admin/Import or the Preferences/VMS Settings option explained in the Download section above to navigate to the Import list screen.

2. Click Export. The Export Screen displays.

NOTE: If you do not see the Export option, reach out to your Program Office for assistance. (Export is a separately assigned user role permission.)

3. Expand the Export Type drop-down list and select the export Type to match your intended import. The screen refreshes to display data fields specific to that data template. Notice that Beeline required fields are indicated by an asterisk (*). (The example shown below is based on the Supplier template.)

4. Click Search to the right of each Required field and then make your selections from the pop-up Select Values Screen as to which categories should be included in your export file. Use the checkboxes to select individual items or the checkbox in the header row to select all items.
   TIP: Check the results total at the bottom of the list to make sure you have reviewed all possible items for your selection list.

5. Click OK to save your selections and return to the Export screen.
6. Repeat Steps 4 and 5 until you have made your selections for all Required fields. If you want your export file to include examples of non-Required fields, follow the same process to make your selections. Notice that SupplierCode is not designated as a Required Field. It is required to IMPORT a Supplier record, but not for an export file, although the information would be helpful to include to use as an example.
7. Now click Search for the entire Export file. The screen refreshes to display a results list to match the selections you made.

8. Review the list and click Search Options if you need to make adjustments. Notice that the data has been previously validated—which makes it an excellent resource to consult when filling out your import file.
9. Click Export to download your file in xlsx format.
10. Use standard Excel® practices to open and review your exported file. Not only does the export file show you how data has been entered previously into Beeline data tables; it also provides an example so that your data entries can be consistent and indicates which fields can be left blank without triggering a validation error.

TIP: Export files use a generic filename label. Save or Rename the file using a filename that is more descriptive for your purposes.

Upload and validate your import file.

1. Use either the Admin/Import or the Preferences/VMS Settings option explained in the Download section above to navigate to the Import list screen.
2. On the Import screen, click Add New.

NOTE: The Add New link is only visible to users granted Web Import Tool access rights. You cannot impersonate a user who has these rights, the permissions must be assigned to YOUR profile record.

3. Expand the Import Type drop-down list to select the import “type” that matches your import file.

4. Enter the name of your import file in the Name field. This is now your data-loaded import file you previously downloaded as a template. Follow any file-naming conventions required by your program.
5. Click Select next to the Select File label and use your browse options to locate your import file.

6. Click Upload in the Select Import Attachment pop-up window to import your file.

7. Click Save in the next Select Import Attachment pop-up window to complete the import process.
   
   Notice that this window includes an Attachment hyperlink and a Title field. You can review your file by clicking the hyperlink or you may adjust the text you entered in the previous Name field by entering revised content in this Title field.

8. The screen refreshes to display the Import – Status: Creating screen. Verify that the Import Type selection matches your import file “type”. As noted above, do not leave this field at the “Select Import Type” default setting or your import will not validate properly.
9. Confirm that the Name entry is the filename you want to use for this file. Regardless of the filename you selected during the Select process, it saves your file using the content in the Name or Title field.

10. Click Validate to begin the validation process now. Your file is automatically assigned an Import Number for tracking purposes and added to the display list on the Import screen.
    Optional: Click Save to store your file to validate at a later time. Use this option when importing large files that need to be processed after standard business hours.
11. When you click the Validate button, it triggers the validation process. Your file goes into the validation utility queue and the status of your file updates to “Pending Validation”. A banner message indicates the status of your file and updates when the validation process is complete. You may leave this screen open to monitor the process of your validation or you may click Return to exit and return later. The validation process continues to run in the background.

12. During the validation process, the status changes to one of the following options based on the import results:

• Pending Validation:         File is in queue for validation utility process.
• Validation Failed:             File has errors that need to be corrected.
• Validated:                          File has passed validation with zero errors.
• Importing:                         File import is in process.
• Imported:                          File has been validated and imported.

13. After the validation process is complete, click View Details in the Content column to open your file and review the validation results. Results display as separate line items.

Notice that the View Details screen includes two new columns, Validated and Comments. The Validated column indicates a Yes or No.

• For all No results, review the information in the Comments column to determine what adjustments you need to make before you re-validate the import file.
• For all Yes results, review the Comments information to ensure that the validation result is the EXPECTED result.
  For example, if your intent was to “add” a new record but the validation comment indicates that the record was “updated” or “replaced”, then you need to check the data in Beeline Enterprise to resolve the inconsistency. REMEMBER, data can originate from multiple sources and/or users (for example, manual entry, import file, feed file, utility program, etc.,) within Beeline Enterprise but all client data is stored within a single production environment. You need to ensure that the data you import is compatible with the data already in place or generated from other sources. Validation results for Timesheet imports are explained in the Appendix, “Event-Driven Import Templates” section, since they include “conditions” that are unique to timesheet entry.

14. Use the Record Select pull-down menu to filter which records you want to view. Options include Show All Records, Show Valid Records, or Show Failed Records.

15. If your validation includes failed records, review the content in the Comments column to determine what adjustments need to be made to your original import file. Check the “Beeline CWS Import Error Guide” workbook for additional information related to validation comments and how to resolve them. Each tab in this Excel® workbook is specific to a template. Please be sure to consult the tab that matches your import template. Click to download this guide.
16. If your file passes the validation, it is highly recommended that you review all line items in your import file to ensure that the information you plan to import is accurate. The validation process is data processing that checks for FORMATS and Beeline Enterprise SPECIFICATIONS; it cannot verify that the content entered in the template is accurate information. 
17. When you have finished making adjustments to your template file, click Reset Status to exit the validation screen and return to the Import – Status: Creating screen.
18. Click Clear to remove your prior import file, then use the same select. upload, and validate steps to process your revised (corrected) import file.

19. Repeat this process until ALL line items in your import file pass validation. Note: Depending on the complexity of the template, it is normal to go through multiple validation attempts to achieve ultimate success!

Import the successfully validated file.

Once all line items in an import file have successfully validated, it is ready for import into a Beeline Enterprise environment. We strongly recommend that all validated import files be imported into a client-specific test environment (UAT) for review prior to their import into your production environment. Please reach out to your Beeline COM (Client Operations Manager) for assistance with project test environments. Process steps for importing validated files vary based on the assigned Web Import Tool usage rights granted to client-side users.

• Validate Only* – users with this level of access may validate files but need to reach out to their Program Office to identify who has import rights and can import your validated file.
• Validate with Import Right* – users with this level of access have the ability to import validated files.

*If you are not sure whether you have been assigned validation/import permissions, check with your Program Office. If you are tasked with importing a file created by someone else, work with your Program Office as to visibility rights to the file.

Validate Only - Steps to Import:

1. Use either the Admin/Import or the Preferences/VMS Settings option explained in the Download section of this document to navigate to the Import list screen.

2. On the Import screen, locate the file to be imported in the displayed list or use the Search Options to locate the file.
3. Verify that the file status indicates “validated”.

4. Click View Details in the Content column. The screen refreshes to the Import Results screen.

5. Confirm that the Record Select field is set to “Show All Records” and that all displayed line items indicate “Yes” in the Validated column.
6. Review all line items in your import file to ensure that the information you plan to import is accurate. The validation process verifies the data meets FORMAT and Beeline Enterprise REQUIREMENTS; it cannot verify that the data is accurate information.
7. Notify the designated Importer that the file is validated and ready for import; include the file number.

NOTE: Each Program Office should have at least one user who has import rights.

Validate with Import Rights - Steps to Import:

1. Use either the Admin/Import or the Preferences/VMS Settings option explained in the Download section of this document to navigate to the Import list screen.
2. Complete Steps 2 through 6 as described in the “Validate Only” section above.
3. Review all line items in the import file to ensure that the information you plan to import is accurate. The validation process is data processing that checks for FORMATS and Beeline Enterprise SPECIFICATIONS; it cannot verify that the content entered in the template is accurate information. You will be prompted during the import process to accept responsibility for the data you import—including any fees assessed to “correct” imported data errors.

4. Click Import Records to begin the import process.

5. A pop-up window displays requesting confirmation. Click OK to proceed.

6. A second confirmation pop-up window appears. This window includes a checkbox to indicate that you wish to proceed and that you accept responsibility for the data you are about to import. Click the checkbox and then click Proceed to continue. Note: each import process requires acceptance on BOTH confirmation windows.

7. The screen refreshes back to the Import screen. A status banner indicates that your file is queued for import. The status message updates when the import process is complete. The status of the file updates to: Imported. You may leave this screen open to monitor the process of your import or you may click Return to exit and return later. The import process continues to run in the background.

8. Once completed, import results can be verified by locating any of the imported records using any of the Header Menu bar options (for example, Manage Search or Admin/Security). Locate a record you imported and then scroll down to the lower right corner of the record and you will see information that indicates the user, the date, and the time the record was “Created By” and “Modified By”. It will also indicate that the “Source” was a “Web Import”.

Working with data: other resources and guides

Data Imports: How to Guide

The Data Imports: How to guide lists the data import templates in the order in which they should be imported into Beeline Enterprise. It provides insights into how the data fields relate to a single import template as well as how the various import templates relate to each other. Beeline Enterprise is based on data hierarchy tables, and it is essential to understand these data relationships when working with import templates. The table layout for this guide includes a separate column for Field Name, Comments, Character Limit, and Column. Required Beeline Enterprise fields are identified by an asterisk (*).

Field Names are color-coded as follows:

• Yellow - required Client data
• Green - required Beeline data
• Gray - optional data

Click to download guide.

Web Import Tool: Sample Data Files

Sample data files can be a useful tool for learning how to populate data into an import template file. They are provided for instructional purposes only and should not be used as a substitute import file. ALWAYS use a standard Beeline Enterprise import template downloaded from the Web Import Tool to ensure you have the latest version of a template.

Sample files are populated with generic data based on standard Beeline Enterprise terminology. If your program uses terminology key functionality to customize text to be client-specific, then a reverse import could be the better option to create a sample file.

Standard sample data files can be retrieved here.

Instructions on how to create a reverse import are included in this article.

Standard State and Country Codes

Standard Code Lists for State and Country Codes, US County Codes, and Country/ISO Codes are provided below. Use of codes should be consistent throughout your data tables.

Web Import Tool: Validation Errors

The import tool validation process checks the data in the import file to determine if it meets the data requirements in Beeline Enterprise. Any line item in the file with data that does not match the expected format rules and inclusion requirements will generate an “error”. All errors need to be resolved before the file can be imported. You may need to repeat the validation process several times before you have a file that “passes” without any errors. Our Beeline CWS Import Error Guide lists the most common errors and how to resolve them.

Click to download the Beeline CWS Import Error Guide workbook.

Web Import Tool: Template List including Reverse Import

All templates can be used to import data into Beeline Enterprise; however, not all import templates can be used to create reverse imports (i.e., data exports). Check the list located here to identify which templates can be used for data exports.

Reverse imports can be used for multiple purposes. They can be as an example to follow when entering data for a new Web Import Tool import file. They can be used as the basis to design system feed files and/or API interfaces. They can extract data that needs to be transferred from one system to another.

The advantage of the reverse import is that it eliminates the element of guesswork when creating an import file since the file you create is based on data entries that have already successfully passed through the import validation process.

Web Import Tool: Import Screens and Details

The Beeline Enterprise Import screen is used to track activity and post results once files are processed through the Web Import Tool. A detailed description of the Import Screen layout and functions is available here.

Event-Driven Import Template Fields

Most data fields are strictly informational, and the content entered only needs to be accurate and reflect the correct format requirements to pass the validation rules. However, some data fields are event-driven and also need to reflect the action taken to create the data entered. The Timesheet import template is an event-driven template where you will need to include the status of the timesheet header for the validation process to determine the correct data entry. Details for entering and adjusting these specialized fields is available here.

Web Import Tool: Glossary of Terms

As previously mentioned, import templates are based on standard Beeline Enterprise terminology. If your program uses terminology key functionality the column headers in the import templates will not match the data field labels you see in your Beeline Enterprise production instance. Run a “Terminology Keys and Values” reverse import (Instructions are provided in the “Export a ‘reverse import’...” section of this article.) to use as a guide when using the glossary of terms available here.