How to Use Reference Data and Images

If you have a fixed list of information that you want users to choose from when filling the form, you can import a CSV file to use as reference data. For example a catalogue price file could be imported if your forms regularly need populating with material information.

Simpro Premium and Simpro Digital Forms has an extensive list of integrated fields that can be used for reference data without importing a CSV. Consult the Simpro List of Simpro Premium Reference Data to see if the information you want to reference is available without uploading a CSV. Learn more in Integrate Simpro Digital Forms With Simpro Premium.

Import a CSV if the information you want to reference comes from a system other than Simpro Premium. Alternatively, if a field in Simpro Premium is not available as reference data, you may be able to export CSV files directly from Simpro Premium to import them as reference data in Simpro Digital Forms.

Learn more in How to Export Simpro Premium Data.

To format a Reference Data CSV to prepare it for importing:

1. You can create a Reference Data CSV from scratch or start with a CSV that you have exported from another system.
2. The CSV you are importing must contain 15 or fewer columns. Many of the CSVs available to export from Simpro Premium exceed this quantity. Cut and paste columns to divide your CSVs into multiple smaller files or remove unnecessary columns from your file to meet this requirement.
3. Ensure the CSV you are importing contains a header row. You will need to remember the headings of columns when mapping reference data to fields. It is generally easier to map reference data if the column headings are named the same as your fields on your forms.
4. Insert a blank row directly after the header row separating the data from the header row. If you are using reference data to populate a drop-down field, this will make the drop-down blank by default, rather than selecting the item in the first row by default.
5. A Reference Data CSV can contain rows that include duplicate values. When you map reference data, you can decide if duplicate values are shown or if duplicates are condensed.
   • For example, you might have a price file that includes twenty items which are listed with three product groups, lighting, HVAC, Solar and Data. When mapping a product group to a field you can set the field to only show these three product groups, rather than showing HVAC, Solar and Data twenty times, for each row in the file.
6. If you want fields on a single form to auto-populate with reference data from multiple files each file must contain a common column.
   • For example, if you want to auto-populate fields with information from a CSV file that contains a list of customer assets, when you select the name of a site that is pulled from a separate CSV containing a list of site. Both the site list CSV and the customer asset list CSV must contain a column that contain common information. This column is used to cross reference both files and ensure the correct asset information is auto-populated. This common column could be a site name or site ID column that appears in the site list file for each site, but also appears in the asset list file for each asset.
7. If you intend to Divide reference data among User Groups, include a column that indicates which rows should be assigned to different user groups.
   • For example, if you have your field users divided into user groups based on the geographic zone that they work in, and you are importing a CSV that contains site information, you can include a column that lists the zone for each site, so that only the sites in each field user’s assigned zone are accessible.
8. If your spreadsheet is not a CSV formatted file, Save As CSV (Comma delimited).

To import your reference data:

1. Click Reference Data & Images > ADD REFERENCE DATA.
2. Click NEXT.
3. Enter the Name of the reference data file.
4. Enter a Description to help identify the file.
5. Click Choose file > locate and select the CSV file from your local files and click Open.
6. Select Divide reference data among User Groups to partition some of the data so that different rows are able to be referenced by different groups of users.
   • This is useful if you have a very large data file and different employees are only going to need access to certain rows. For example, if you have a business that works internationally and different groups of technicians work with materials exclusive to their specific country you might want to divide a price file CSV based on which countries the parts are from. Note that you can assign users to multiple user groups. Lean more in How to manage groups.
   • Select the Column which values matches User Groups to select the column which determines which rows are accessible to different user groups.
   • Click Create User Groups? if the user groups listed in the selected column do not already exist in Simpro Digital Forms. This allows you to create new user groups based on the unique values in the selected column. For example, if you have a list of sites with a column for zone (north, south, east, or west), and you have different groups of field users who work exclusively in those zones, you could use this feature to create north, south, east, and west user groups. This would ensure that each group only has access to the relevant sites.
   • Click + to create the new User Groups. You can also click download to export a CSV that contains the specific rows each group has access to, click edit to upload a new CSV for the user group or delete the user group if it is not required.
7. The data that has been successfully imported is displayed. Click Re-Upload data if the correct information has not been uploaded. The data is now available to be mapped to fields on a form. Learn more in Map Reference Data.

Uploaded reference data CSVs and images can be edited, downloaded and deleted as required.

To manage Reference Data and Images:

1. Click on Reference Data & Images.
2. Click a Reference Data CSV. If the reference data is restricted to certain user groups the following options are available:
   • Click to upload a new CSV to update which rows this user group has access to.
   • Click to download a CSV containing the rows that this user group has access to.
   • Click + to add users to this User Group.
   • Click to remove this User Groups access to this file.
3. In the Reference Data section under Action click one of the following options:
   • Click to upload a new CSV to update the reference data in the file. This is useful as it allows your fields that are setup with reference data to reference a new version of the file, without needing to re-map them.

   Not available for Reference Data automatically imported from Simpro Premium.

   • Click to download a CSV containing reference data in the file.
   • Click to delete the reference data file. Note that if you delete an CSV all fields mapped to the file will need to be remapped.

   Not available for Reference Data automatically imported from Simpro Premium.

4. Click Reference Images to add and save images to be used in Static Image Fields for mobile forms.
   • Click Add image to upload and name an image.
   • Click to edit the name or re-upload the image for this file.
   • Click to remove the file from your Reference Image library.
5. To display Reference Images, insert a Static Image Field on a form and select the image from your image library.

Digital Forms has a limit of 10 reference images per account.

Map reference data to fields so that you can determine where the information in the form is getting pulled from. The reference data can be mapped from an imported CSV or directly from Simpro Premium. Once you have mapped a field with reference data, you can choose to auto-populate other fields with reference data based on what was entered in the initial field.

For example, you can map a job number field on a form to your job IDs in Simpro Premium, then map your customer and site name fields, so that when the user filling in the form enters the job number, the customer and site names fields auto-populate with the details from the same job.

Map reference data fields

To map reference data to fields:

1. Go to Forms and edit an existing form.
2. Add a new field that should include reference data or locate an existing field.
3. Access the Field Settings and click Reference Data.
4. In the Reference Data File drop-down select where you want to pull the reference data from.
5. In the Reference Column drop-down select the field from Simpro Premium that you want to pull the data from, or if you are using a CSV select the heading of the column where the data is coming from. Learn more in Integrate Simpro Digital Forms With Simpro Premium.
6. If other fields should auto-populate based on the information entered into this field, do not select a Reference Screen or Reference field. Click Done.
7. If there are other fields that should auto-populate with reference data, based on the information entered in this initial field, continue to Auto-populate reference data fields.

In order to submit forms directly to Simpro Premium so that they are attached to a quote or job, they must include a field named “Quote ID” or “Job ID”.

Map Quote ID or Job ID fields

By default all forms completed in the Simpro Digital Forms mobile app are sent to the Submissions area of Simpro Digital Forms. To send forms to Simpro Premium when submitted, you can add a Quote ID or Job ID reference data field to your forms. This allows the field user to select which quote or job the form should be attached to. Learn more in Map Reference Data.

Forms sent to Simpro Premium appear in the Attachments tab, in the relevant quote or job. The Added By column lists the employee that authorised the connection between Simpro Digital Forms and Simpro Premium. Forms from Simpro Digital Forms cannot be sent to other areas of Simpro Premium, such as customer or site files.

To add a Quote or Job ID reference data field to a form:

1. Go to Forms and edit an existing form.
2. Add a new Single Choice field to any screen.
3. Rename the field to Quote ID or Job ID.
   • Follow this naming convention precisely. Use this capitalisation and spacing exactly as shown.
4. Click in the Job / Quote ID field and expand the Reference Data drop down in the left pane under Field Settings.
5. In the Reference Data File drop-down, select SimproJobs or Simpro Quotes.
6. In the Reference Column select QuoteID or JobID.
7. Click Done.

The naming of the “Quote ID” or “Job ID” field must exactly match the naming convention shown here. It cannot be named Quote Number, Job #, QuoteID or any other variation of this terminology. The capitalisation and space between words is required.

Selecting a valid quote or job number in this field ensures the form is attached to the correct quote or job record in Simpro Premium when the form is submitted.

Note that a Reference Screen and Reference field drop-down can also be selected for this field, to auto-populate other fields when the Quote or Job ID is filled in.

Auto-populate reference data fields

To map fields so that they auto-populate with reference data:

1. Add a new field that should include the auto-populated reference data or locate an existing field that will be auto-populated.
2. Under the Field Settings expand the Reference Data section.
3. In the Reference Data File drop-down select where you want to pull the reference data from.
• This can either be an area of Simpro Premium, such as Simpro Job or Simpro Customers or a Reference data CSV that has been uploaded to Simpro Digital Forms.
• For Reference data CSVs the Reference Data File should be the same for the field triggering information to auto-populate and the fields that should be auto-populated with reference data.
4. In the Reference Column drop-down select the field from Simpro Premium that you want to pull the data from, or if you are using a CSV select the heading of the column where the data is coming from.
5. In the Reference Screen drop-down select the screen where the field triggering the reference data to be auto-populated is located. The auto-populating field can often be on the same screen as the triggering field.
   • For example if you have a job number on a job details screen which you want to trigger a job description field to auto-populate, you would select job details as the Reference Screen.
6. In the Reference Field drop-down select the field that will trigger reference data to be auto-populated onto this field.
• For example if you want a job description field to auto-populate based on the job number field, select the job number field as the Reference Field.
• Note that if the Reference Field comes from a different Reference Data File, or area of Simpro Premium to the field that you want to auto-populate, you will need to add a field that links these two fields using a common Reference Column. For example if you want to trigger a customer name field, to auto-populate when you enter a Job ID, you need to have a Customer ID field, because the Customer ID column is common to both the Simpro Jobs and Simpro Customers Reference Data files. Learn more in Auto-populate reference data from multiple sources.
7. Click Done.

Auto-populate reference data from multiple sources

Auto-populating reference data from multiple sources in an advanced setup. It is recommended to start with Map reference data fields and Auto-populate reference data fields and practise these steps before auto-populating reference data from multiple sources.

Often a form will need to be auto-populated with data from one area of Simpro Premium, such as your customer information, when details from another area of Simpro Premium are selected, such as a Job ID.

Similarly, you may need to auto-populate information from an asset list CSV file, when you select a site name from a site list CSV file.

Whenever data needs to be referenced from multiple CSV files or areas of Simpro Premium, a field that links them together must be added to your form. This field must be mapped to a Reference Column that is common to both areas of Simpro Premium or both Reference Data Files.

For example, if you want a Simpro Customer Name to auto-populate, when a Simpro Job ID is entered, a Customer ID field can be used to create a link because the CustomerID Reference Column exists under both the Simpro Jobs and Simpro Customers Reference Data Files.

The following steps provide an example of how to auto-populate a customer name field when a job number is selected. The same principle applies regardless of which different areas of Simpro you want to pull information from.

To auto-populate reference data from multiple areas of Simpro Premium:

1. Add and name the first field that you want to use to trigger other fields to auto-populate.
   • For example add a Single Choice Field and name the field Job Number.
2. Under the Field Settings expand the Reference Data section.
3. In the Reference Data File drop-down select where you want to pull the reference data from.
   • For example, select Simpro Jobs.
4. In the Reference Column drop-down select the field from Simpro Premium that you want to pull the data from and click Done.
   • For example, select JobID.
5. Add and name the field that will link the field from the first area of Simpro Premium to the second area.
   • It will help to name this field based on the name of the Reference Column that both areas of Simpro Premium have in common.
   • For example, add a Single Choice Field and name the field Customer ID.
6. Under the Field Settings for this linking field expand the Reference Data section.
7. In the Reference Data File drop-down select the same Reference Data File as the first field.
   • For example, select Simpro Jobs.
8. In the Reference Column drop-down select the field from Simpro Premium that is a common link between the first area of Simpro Premium that is mapped to your first field and the second area of Simpro Premium that will be mapped to your next field. Refer the List of Simpro Premium Reference Data to see which fields are common to the different areas of Simpro Premium that can be used to link auto-populating fields together.
   • For example, select CustomerID. CustomerID appears in both the Simpro Jobs and Simpro Customers Reference Data Files.
9. In the Reference Screen drop-down select the screen on your form where the first triggering field is located. The auto-populating field can often be on the same screen as the triggering field.
10. In the Reference Field drop-down select the first field that will trigger reference data to be auto-populated onto this field.
    • For example, select the Job Number field that you named and created.
11. Click Done.
12. Add and name the field from the second area of Simpro Premium.
    • For example add a Single Choice Field > name the field Customer Name.
13. Click in this field to access the Field Settings and expand the Reference Data section.
14. In the Reference Data File select the area of Simpro Premium that this field is being pulled from. This will be a different area to the trigger and linking fields.
    • For example, select Simpro Customers.
15. In the Reference Column drop-down select the field from Simpro Premium that you want to pull the data from.
    • For example, select Customer Name.
16. In the Reference Screen drop-down select the screen on your form where the linking field is located. The auto-populating field can often be on the same screen as the linking or triggering field.
17. In the Reference Field drop-down select the field that links the first field to this one and click Done.
    • For example, select the Customer ID field that you've created and named.
18. You can repeat steps 5-17 to continue creating additional fields that link to other areas of Simpro and auto-populate from the triggering field.
    • For example, you could also create a Site ID linking field and a Site Name field that auto-populates when Job ID is selected.
19. You can replete steps 13-17 to continue creating additional fields that will auto-populate based on the information populated in the linking field.
    • For example, you could create a Customer Address field that also auto-populates with information when the Job ID is selected.
20. If you do not want to display your linking fields you can hide them from the mobile users in the Field Settings > Advanced for the linking field by toggling off Mobile Visible. Learn more in Field settings.

The following steps provide an example of how to auto-populate customer asset IDs when a site address is selected. The same principle applies regardless of what information you are mapping from a reference data csv file.

To auto-populate reference data from multiple reference data CSV files:

1. Add and name the first field that you want to use to trigger other fields to auto-populate.
   • For example add a Single Choice Field > name the field Site Address.
2. Access the Field Settings and click Reference Data.
3. In the Reference Data File drop-down select the CSV file that contains the reference data you want to map this field to.
   • For example, select a Sites CSV file.
4. In the Reference Column drop-down select which column that the data needs to be pulled from and click Done.
   • For example, select a Site Address column in the CSV file.
5. Add and name the field that will link the field from the first CSV to the second CSV.
   • It will help to name this field based on the name of the column that both CSVs contain.
   • For example, add a Single Choice Field > Name the field Site Name. In this example, both the Customer Assets CSV and the Sites CSV contain the site name column.
6. Under the Field Settings for this linking field expand the Reference Data section.
7. In the Reference Data File drop-down select the same Reference Data File as the first field.
   • For example, select the Sites CSV file.
8. In the Reference Column drop-down select the column that is a common link between the first CSV file that is mapped to your first field and the second CSV file that will be mapped to your next field.
   • For example, select Site Name. In this example, the Site Name column appears in both the Sites CSV file and the Customer Assets CSV file.
9. In the Reference Screen drop-down select the screen on your form where the first triggering field is located. The auto-populating field can often be on the same screen as the triggering field.
10. In the Reference Field drop-down select the first field that will trigger reference data to be auto-populated onto this field.
    • For example, select the Site Name field that you named and created.
11. Click Done.
12. Add and name the field from the second reference data CSV file.
    • For example add a Multiple Choice Field and name the field Asset IDs.
13. Click in this field to access the Field Settings and expand the Reference Data section.
14. In the Reference Data File select the reference data CSV file that this information is being pulled from. This will be a different file to the trigger and linking fields.
    • For example, select a customer assets CSV.
15. In the Reference Column drop-down select the column in the reference data CSV file that you want to pull the data from.
    • For example, select an Asset ID column.
16. In the Reference Screen drop-down select the screen on your form where the linking field is located. The auto-populating field can often be on the same screen as the linking or triggering field.
17. In the Reference Field drop-down select the field that links the first field to this one and click Done.
    • For example, select the Site Name field that you've created and named.
18. You can repeat steps 5-17 to continue creating additional fields that link to other CSVs and auto-populate from the triggering field.
    • For example, if your Sites CSV also contained a Plant ID column you could also create a Plant ID field linking field and a Plant Name field that auto-populates when the Site Address is selected.
19. You can replete steps 13-17 to continue creating additional fields that will auto-populate based on the information populated in the linking field.
    • For example, you could create an Asset Type field that also auto-populates with information when Site Address is selected.
20. If you do not want to display your linking fields you can hide them from the mobile users in the Field Settings > Advanced for the linking field by toggling off Mobile Visible. Learn more in Field settings.

It is also possible to auto-populate reference data from an area of Simpro Premium when a field is filled in, that’s mapped to reference data from a CSV file, or auto-populate fields with reference data from a CSV, when a field that’s mapped to data from an area of Simpro Premium. For example, you could auto-populate asset fields with reference data from a CSV, when a Simpro job number is entered.

To achieve this you must ensure that the reference data CSV contains a column that is a common link with the data that is pulled from the relevant area of Simpro Premium. For example, to auto-populate the asset fields when entering a job id, the CSV would need to contain a column that contains the job IDs, job name or another field that is included in the list of Simpro Reference Data for Simpro Jobs.

List of Simpro Premium Reference Data

The following fields can be referenced directly using the integration between Simpro Premium and Simpro Digital Forms. You are not required to upload a reference data CSV to map these fields. Each field is arranged into Reference Data Files that encompass different areas of Simpro Premium. Learn more in Integrate Simpro Digital Forms With Simpro Premium.

Simpro Companies

• Address
• City
• Company ID
• Company Number
• Date Modified
• Email
• Name
• Phone

Some of this data is taken from fields visible under System > Setup > Company in your Simpro Premium build. Some of this data is not visible in Simpro Premium.

Simpro Customers

• Address
• City
• Customer ID (Can be used to link customers with jobs or quotes)
• Date Modified
• Email
• Name
• Phone

This data is taken from fields visible under People > Customers in your Simpro Premium build.

Simpro Employees

• Date Modified
• Email
• Employee ID (Can be used with the Project Manager ID or Salesperson ID to link jobs and quotes with employees)
• Name
• Position

This data is taken from fields visible under People > Employees in your Simpro Premium build.

Simpro Jobs

• Customer ID (Can be used to link customers with jobs or quotes)
• Date Modified
• Description
• Job ID
• Name
• Notes
• Order Number
• Project Manager ID (Can be used with the Employee ID to link jobs with employees)
• Request Number
• Salesperson ID (Can be used with the Employee ID to link jobs with employees)
• Site ID (Can be used to link sites with jobs or quotes)

This data is taken from fields inside jobs in your Simpro Premium build.

Simpro Quotes

• Customer ID (Can be used to link customers with jobs or quotes)
• Date Modified
• Description
• Name
• Notes
• Order Number
• Project Manager ID (Can be used with the Employee ID to link quotes with employees)
• Quote ID
• Request Number
• Salesperson ID (Can be used with the Employee ID to link quotes with employees)
• Site ID (Can be used to link sites with jobs or quotes)

This data is taken from fields inside jobs in your Simpro Premium build.

Simpro Sites

• Address
• City
• Contact Email
• Contact Name
• Contact Phone
• Date Modified
• Name
• Postcode
• Site ID (Can be used to link sites, with jobs or quotes)
• State

This data is taken from fields visible under People > Sites in your Simpro Premium build.