You must be familiar with the fundamentals of iTop XML design.

For an overview of the Customer Portal customization capabilities, please have a look at the page Customize your Customer Portal

This structure is specific to a portal developped over the itop-portal-base library.

Here are the features built it the itop-portal-base library. You may implement your own brick in a separate module, provided that its name (i.e. xsi:type) does not interfere with the existing bricks.

Since version 3.1.0 of iTop and the closing of a security breach, adding a relationship in the portal between a UserRequest and a Person for example, might be denied to the user also there are valid scopes on classes Person and UserRequest for this user. He can get this type of error message:

Attribute pointing to an object that is either non existing or not readable by the current user: 
  current_object = lnkContactToTicket::-1, attcode = ticket_id, attvalue = xxx, current_user = UserLocal::xx

The underlying reason, is that this relationship is stored in the class lnkContactToTicket which contains two fields of type AttributeExternalKey, one pointing to the Ticket class and the other to the Contact class.

Don't hesitate to activate the Debug log on portal, to get more explanations:

Configuration

'log_level_min' => [\LogChannels::PORTAL => \LogAPI::LEVEL_DEBUG,],

The datamodel for User Portals became editable with iTop 2.3 released in summer 2016

This version came live with iTop 2.4 beta, released in July 2017.

• Filter Brick: extension was included to the core application.
• UserProfileBrick: Profile picture, preferences and password forms can be disabled. Available from PHP 5.5.16

   <brick xsi:type=UserProfileBrick>
      <show_picture_form>true</show_picture_form>
      <show_password_form>false</show_password_form>
      <show_preferences_form>true</show_preferences_form>

• BrowseBrick:
  • “Tree” mode displays a description on top of a name.
  • Default action is the first declared action, an hamburger menu was added proposing all actions
  • New mode “mosaic” convenient on small devices, allowing to display an image associated with the browsed objects.

  <brick xsi:type=BrowseBrick>
     <browse_modes><availables><mode id="mosaic"/></availables></browse_modes>
     <levels><level><image_att>class_field_id</image_att></level></levels>

• Open a form in the same window, in a tab or a pop-up

 <brick xsi:type=BrowseBrick><levels><level><actions><action><opening_target>new</opening_target>... 

 <brick xsi:type=ManageBrick><opening_target>self</opening_target>... 

• ManageBrick displays count on tabs

 <brick xsi:type=ManageBrick><groupings><tabs><show_tab_count>true</show_tab_count>... 

• Create Brick now support abstract class, no specific tag for this

• Dictionary entries now usable in forms.

         <legend>{{'Form:Portal:TicketEdit:Fieldset:General'|dict_s}}</legend> 

• Configurable display mode on forms to change the layout form/properties/display_mode
• Configurable display mode on fields to change the layout

  <div class="form_field" data-field-id="title" data-field-display-mode="cosy"> 

• A LinkedSet attribute can now be open by default at form opening.

  <div class="form_field" data-field-id="contacts_list" data-field-opened="true"> 

• Actions buttons can be added
• Forms can be defined specifically for a particular transition, so you can decide which fields will be prompted, overwriting the console behavior. Check here for more details

Example, display a read only field:

  <div class="form_field" data-field-id="org_id" data-field-flags="read_only"/>

• By default the submit button is now hidden on forms when transitions are proposed. If you want to restore the previous behavior use this tag <always_show_submit> on forms defined in XML.

    <module_design id="itop-portal">
      <forms>
        <form id="ticket-create" _delta="if_exists">
          <properties _delta="define_if_not_exists">
            <always_show_submit _delta="force">true</always_show_submit>
          </properties>
        </form>
      </forms>
    </module_design>

• Configurable opening mode for additional portals
• You can hide a transition to some portal users, for example, support agent could be allowed to assign a ticket in the portal while all others would not. But as soon as you define a lifecycle tag then you must explicitly describe all denied Events (stimuli), this denial is for all profiles unless denied profiles are explicitly listed.

    <module_design id="itop-portal">
      <classes>
        <class id="Ticket">
          <lifecycle _delta="define">
            <stimuli>
              <!-- ev_assigned and ev_resolved will NEVER be available in portal -->
              <stimulus id="ev_assign">
              </stimulus>
              <stimulus id="ev_resolved">
              </stimulus>
              <!-- ev_pending will be available in portal to other profiles than Support Agent -->
              <stimulus id="ev_pending">
                <denied_profiles>
                   <denied_profile id="Support Agent"/> 
                </denied_profiles>
              </stimulus>
            </stimuli>
          </lifecycle>
        </class>
      </classes>
    </module_design>

• ManageBrick: this version provides new display types (pie chart, bar chart and badge) to the Manage Brick.

<brick xsi:type="Combodo\iTop\Portal\Brick\ManageBrick">
   <display_modes>
      <availables>
          <mode id="list"/>
          <mode id="pie-chart"/>
          <mode id="bar-chart"/>
      </availables>
      <default>pie-chart</default>
      <tile>badge</tile>
   </display_modes>

• It also allows to export data to Excel.

  <export><export_default_fields>true</export_default_fields>...

• The exported fields can be specified:

  <export><fields><field id="title"/>....

• The number of groups can be limited:

  <grouping><tabs><limit>5</limit>...

• When the number of groups is limited, the remaining can be aggregated:

  <grouping><tabs><limit>5</limit><show_others>true</show_others>...

• Aggregated Brick_ : a new brick to display in a page tiles from another bricks

• A LinkedSet attribute can display (or not) items that are out of scope.

<div class="form_field" data-field-id="contacts_list" data-field-ignore-scopes="true"/>

• It's now possible to specify a tab description, displayed just below the brick title.
• As usual it can be a dictionary entry like Brick:Portal:OngoingRequest:Tab:OnGoing+ which does not exist and need to be created in parallel.

ManageBrick

  <grouping><tabs><groups><group id="MyTab"><description>enter there your tab description...

• It's now possible to change the default size of a Manage and Browse brick.
• The possible options are 10, 20, 50 and -1 which mean display all objects without pagination. Default is 20, as it was when it was not possible to set it.

<default_list_length>-1</default_list_length>

• It's now possible to navigate in a Browse brick, through n-n relation.
• You could display Documents associated to Application Solutions, Teams and below theirs Members or Customer Contracts, with below the included Services & Service Subcategories.

module-designs / module-design@itop-portal / bricks

<brick id="team-members" xsi:type="Combodo\iTop\Portal\Brick\BrowseBrick" _delta="define">
  <title><default>Teams members</default></title>
  <description>Browse brick navigation using n-n relation.</description>
  <decoration_class><default>fa fa-arrow-circle-o-left fa-2x</default></decoration_class>
  <levels>
    <level id="1">
      <class>Team</class>
      <levels>
        <level id="1">
          <class>Person</class>
          <--! parent_att can be an AttributeLinkedsetIndirect -->
          <--! before only AttributeExternalKey was possible -->
          <parent_att>team_list</parent_att>
          <name_att/>
          <tooltip_att>email</tooltip_att>
          <description_att>function</description_att>
          <title>Class:Person</title>
          <levels/>
          <actions>
            <action id="view" xsi:type="view"><rank>1</rank></action>
          </actions>
        </level>
      </levels>
    </level>
  </levels>
  <browse_modes>
    <availables>
      <mode id="list"/>
      <mode id="tree"/>
    </availables>
    <default>tree</default>
  </browse_modes>
  <default_list_length>-1</default_list_length>
  <data_loading>lazy</data_loading>
</brick>

You can create navigation rules and call them from any form

Close window

  <navigation_rule id="close-form" xsi:type="close"/>

Go to the homepage

  <navigation_rule id="go-to-homepage" xsi:type="go-to-homepage"/>

Open a manage brick

  <navigation_rule id="go-to-resolved-requests" xsi:type="go-to-manage-brick">
    <!-- Mandatory, ID of the ManageBrick to go to -->
    <id>ongoing-tickets-for-portal-user</id>
    <!-- Optional, must be an ID of the available display modes of the brick  -->
    <display_mode>list</display_mode>
    <!-- Optional, must be an ID of the grouping tab of the brick -->
    <grouping_tab>resolved</grouping_tab>
    <!-- Optional, a string to preset as filter in the brick. -->
    <!-- <filter>:this->caller_id_friendlyname</filter> -->
  </navigation_rule>

Open a browse brick

  <navigation_rule id="go-to-services" xsi:type="go-to-browse-brick">
    <!-- Mandatory, ID of the BrowseBrick to go to -->
    <id>services</id>
    <!-- Optional, must be an ID of the available browse modes of the brick -->
    <!-- <browse_mode>tree</browse_mode> -->
    <!-- Optional, a string to preset as filter in the brick. -->
    <!-- <filter>computer</filter> -->
  </navigation_rule>

For Navigating to an AggregateBrick or a CreateBrick, use the below developer's method:

Open a brick, developer method

  <navigation_rule id="go-to-change-overview" xsi:type="go-to-brick">
    <route>
      <id>p_aggregatepage_brick</id>
      <params>
        <param id="sBrickId">change-overview</param>
      </params>
    </route>
  </navigation_rule>
  <navigation_rule id="go-to-new-version" xsi:type="go-to-brick">
    <route>
      <id>p_create_brick</id>
      <params>
        <param id="sBrickId">new-version</param>
      </params>
    </route>
  </navigation_rule>
  <!-- It can be used also for ManageBrick and BrowsBrick: -->
  <navigation_rule id="go-to-ongoing-tickets" xsi:type="go-to-brick">
    <route>
      <id>p_manage_brick_display_as</id>
      <params>
        <param id="sBrickId">ongoing-tickets-for-portal-user</param>
        <param id="sDisplayMode">list</param>
        <param id="sGroupingTab">resolved</param>
      </params>
    </route>
  </navigation_rule>
  <navigation_rule id="go-to-my-extensions" xsi:type="go-to-brick">
    <route>
      <id>p_browse_brick_mode</id>
      <params>
        <param id="sBrickId">my-extensions</param>
        <param id="sBrowseMode">mosaic</param>
      </params>
    </route>
  </navigation_rule>

Open an object

  <navigation_rule id="go-to-object" xsi:type="go-to-object">
    <!-- Mandatory, opens the first result from the OQL. Result may vary ¯\_(ツ)_/¯  but ":this" available! -->
    <oql>SELECT Ticket WHERE id = :this->id</oql>
    <!-- Optional, mode of the object form, either view|edit -->
    <mode>view</mode>
    <!-- Optional, how to open the object form, replace the current form (current), in a modal (modal) or in the page (page) -->
    <opening_target>modal</opening_target>
  </navigation_rule>

Then from any form you can call those navigation rules

module_design@itop-portal / forms

<form id="ticket-apply-stimulus">
  <properties>
    <navigation_rules _delta="define">
      <submit>
        <default>go-to-resolved-requests</default>
      </submit>
      <cancel>
        <default>go-to-homepage</default>
        <modal>close-form</modal>
      </cancel>
    </navigation_rules>
  </properties>
</form>