Documents: Templates and DocuSign
      Back to home
      1. Solo Help Center
      2. SolarNexus
      3. Documents: Templates and DocuSign

      Document Template Object Reference

      Doc Template Variables include many variables that are objects with sub-properties that can be output. These objects and sub-properties are described here.

      Some of the SolarNexus template variables described in the Available Variables list on the template editor screen are objects that contain sub-properties. For example, the salesperson variable is a User object with properties corresponding to the project sales owner's name, phone, email, etc.

      This article describes each type of SolarNexus template object and the properties it contains.

      To output an object-type variable in a template, use the syntax {{object.property}}. For example, to output the sales owner's full name, write {{salesperson.full_name}}.

      Types of Objects include:
      • Date
      • Milestone
      • User
      • Solution Element
      • Item
      • Finance Option
      • PV Array
      • PV Inverter

      Date

      This type of object is used to report dates and times of events defined in SolarNexus. Events are scheduled milestones or subtasks.

      The properties on a Date object include:

      • start_at, with the following sub-properties:
        • raw
        • full_date
        • short_date
        • day_of_week
        • day_of_month
        • ordinal_day_of_month
        • year
        • time
        • full_date_with_time
      • completed_at (has same set of sub-properties as start_at above) 
      • has_duration
      • duration_hours
      • duration_minutes

      Examples:

      scheduled milestones

      For milestones, use the name of the milestone "before completion" as the object's name. So for example, if your scheduled milestone is "Sales Appointment," you would use "sales_appointment" as the object. If you wanted to provide the scheduled start date and time of the Sales Appointment in a paragraph in your template, that could be:

      <p>{{sales_appointment.start_at.short_date}} at {{sales_appointment.start_at.time}}</p>

       

      scheduled subtasks

      For subtask events defined in a given milestone's definition, you may refer to that predefined subtask using the milestone's name and including that subtask's index (first subtask's index = 0). So let's say you have an milestone called "Install Work" with a scheduled subtask called "Start PV Install" listed second in the defined subtasks (index=1).

      <p>{{install_work.subtask(1).start_at.short_date}} at {{install_work.subtask(1).start_at.time}}</p>

       

      "scheduled" object- This is a special instance of a Date object that refers to the most recently scheduled milestone OR subtask, rather than a named milestone or subtask. When scheduling an event (milestone or subtask) in the SolarNexus UI, the user may check a box to send out a notification email to the customer using a selected Email template. This feature is handy when the job process does not have formal milestone for scheduling a future milestone When used, the scheduled object will fill in the information about the milestone or subtask that the user is scheduling at that time.

      • scheduled.name
      • scheduled.name_before_completion (not available for subtasks)
      • scheduled.name_after_completion (not available for subtasks)
      • scheduled.owner and scheduled.owner_or_salesperson (User objects):
        • scheduled.owner.full_name
        • scheduled.owner.first_name
        • scheduled.owner.last_name
        • scheduled.owner.title
        • scheduled.owner.phone
        • scheduled.owner.email
      • scheduled.start_at (Date object):
        • scheduled.start_at.raw
        • scheduled.start_at.full_date_and_time
        • scheduled.start_at.full_date
        • scheduled.start_at.short_date
        • scheduled.start_at.day_of_week
        • scheduled.start_at.ordinal_day_of_month
        • scheduled.start_at.year
        • scheduled.start_at.time
      • scheduled.has_duration
      • scheduled.duration_hours
      • scheduled.duration_minutes

      The scheduled object may also be used with specific milestones and predefined subtasks by using the milestone name and subtask index. The following shows an example using a milestone named "Schedule and Install PV System" with 2 pre-defined subtasks: a) "schedule install" (index=0), and b) "PV Install-Day 1" (index=1). The email template may use the following for notification of the scheduled start time for the "PV Install-Day 1" event:

      • schedule_and_install_pv_ystem.subtasks(1).start_at.raw
      • schedule_and_install_pv_system.subtasks(1).start_at.full_date_and_time
      • schedule_and_install_pv_system.subtasks(1).start_at.full_date
      • schedule_and_install_pv_system.subtasks(1).start_at.short_date
      • schedule_and_install_pv_system.subtasks(1).start_at.day_of_week
      • schedule_and_install_pv_system.subtasks(1).start_at.ordinal_day_of_month
      • schedule_and_install_pv_system.subtasks(1).start_at.year
      • schedule_and_install_pv_system.subtasks(1).start_at.time

       

      User

      Set of properties for any User type of object. These include project roles (owner_or_salesperson, project_manager, etc), as well as assigned event task owner (e.g. see "scheduled" Date event above). Properties include:

      • full_name, e.g. {{owner_or_salesperson.full_name}}
      • first_name
      • last_name
      • title
      • phone
      • email


      Solution Element (aka "Services")

      The user interface refers to Services, but the associated template variables use the term "solution_elements." Solution_elements is an array of solution_element objects containing all solution elements, regardless of type, ordered by user-specified position. Each solution_element object has:

      • type - The top level categories of elements. Its a predefined enumeration of these values: PV System, Storage System, Efficiency Measure, and General Service
      • subtype - This is known as the "Service Type" in the SolarNexus UI. It is a set of Admin defined values
      • name - This is the user provided name for any "General Element" or "Efficiency Measure" type element. PV and storage element types are auto-named "PV System" and "Storage System"
      • description - the short description of the scope of work for this solution element.
      • items - items is an array of product items in the solution_element, each with:
        • type (REMOVED)
        • category - This is the Company Catalog's product category
        • sub-category - This is the subcategory within the Company Catalog where the product resides. Note that some Catalog categories do note have subcategories.
        • provider - In case of materials/products, this is the manufacturer. But items can also represent services or labor, so provider covers both.
        • model_name - Product model number, or the name of the service/labor item.
        • quantity
        • img_url - outputs the url for the first image associated with the item (i.e. a product in the Company Catalog can have an image uploaded).
      • cost object properties, a solution_element's cost object includes:
        • subtotal
        • adjusted_subtotal
        • preliminary_contract_price
        • unit_price
        • cost_item_groups. Each cost item group object has:
          • sub_total_price
          • name
          • description
          • optional cost_items (if enabled for the group). Each cost item object has:
            • provider
            • model_name
            • variation
            • quantity
            • unit
            • cost
      • plus any other properties specific to the element type
      • EE element-specific values:
        • electric_savings_annual
        • electric_savings_annual_percent
        • non-electric_savings_annual
        • non-electric_savings_annual_percent

      We also provide the following objects that define specific solution elements, or subsets of solution elements:

      • Existing ee_measures object variable becomes a subset of solution_elements of type "Efficiency Measure."
      • general_solution_elements is subset of solution_elements of type "General Service"
      • pv_solution_element object only includes properties of the one and only one PV system element (type = "PV System")
      • storage_solution_element object only includes properties of the one and only one storage system element (type = "Storage System")

      Object name is solution_element. Also have special specific solution_elements: pv_solution_element and storage_solution_element. There is a collection (solution_elements) that you can loop through. And special solution_element collections that are a subset of elements: ee_measures, and general_solution_elements.

       

      Item

      Object is named item, an object within a solution_element. (for item in solution_element.items)

       

      Finance Option

      Object is named fin_opt. An analysis can generate an array of up to 3 finance option objects. There is a collection (fin_opts) that you can loop through.

       

      PV Array

      Used in the pv_arrays array variable.

       

      PV Inverter

      Used in the pv_inverters array variable

       

      Using Objects in Liquid Directives

      Object Indices

      The objects in a collection have an index from 0, 1, 2 (first, second, third position)

      It’s OK to reference an indexed object in a conditional directive {% %}, but not in a simple evaluation {{ }}. For example, You can do this:

      {% assign loan_one.name = fin_opt_loans[0].name %}
      loan 1: {{loan_one.name}}

      But not this:

      loan 1: {{fin_opt_loans[0].name}}

      Due to the way the template is parsed during evaluation, you can’t reference a non-existent array index inside {{ }}, even if that is enclosed within an {% if %} that would prevent it from being evaluated. I think it parses all the expressions in {{ }} prior to evaluating the conditionals, and in the process of parsing an expression involving an array, it tries to access the referenced index, which is where it’s failing.

      Assigning fin_opt_loans[0] to fin_opt_pre allows it to work because it’s ok to reference object properties inside of {{ }} even if that object might not exist. When initially parsing that expression, it doesn’t check if the object exists.