Communications to the Customers

Create and publish customer oriented communications to be displayed on the user portal, the login screen and/or the console.

• Create text based or image based communications (formatting including hyperlinks is supported)
• Quick formatting: title / description / predefined icon
• Communications are active for a predefined time-frame (i.e. they have a predefined start and end date)
• Communications can be delivered to users from selected organizations only

The Wiki syntax (in the text of the communication) creates hyperlinks which point to the console!

iTop 2.7+ (iTop 3.0+ for 1.3.1 version) and a User Portal activated

Use the Standard installation process for this extension.

Since version 1.4.1, it is possible to change the default filtering applied on Communications displayed in Login and Console.
After installation, there is no module parameters visible, you have to copy this one and change it

Configuration

    'itop-communications' => array (
        'display_filter' => array (
            'login' => "SELECT Communication WHERE status != 'closed' AND start_date <= :now",
            'backoffice' => "SELECT Communication WHERE status != 'closed' AND start_date <= :now",
        ),
    )'

• In those OQL you can use the placeholder :now.
• No need to filter based on the allowed portals, this filtering criteria is added behind the scene and cannot be cancelled/removed.
• For changing the Portal filtering this can be done though an extension modifying the Communication class (adding a display_portal_date for eg.) and the Portal brick

itop-design | modules_designs | module_design@itop_portal | bricks

      <brick id="communication" xsi:type="Combodo\iTop\Portal\Brick\CommunicationBrick">
          <oql _delta="redefine"><![CDATA[SELECT Communication WHERE status='ongoing' AND display_portal_date <= NOW() AND end_date >= NOW() ]]></oql>
        </brick>

Users with profile Communication Manager (or Administrator) can create a new Communication and to view the list of Communications. Click on the menu “Communications” under “Service Management”.

The form to create a new communication is the following:

When saving the communication, coherence checks are performed and error or warning messages can be displayed.

Since version 1.4.1

Within the Message part of a Communication, it is possible to use placeholders to display information linked to the current user/contact.

Examples

• $current_contact->org_id_friendlyname$ which is equivalent t $current_user->org_id_friendlyname$
• $current_contact->name$
• $current_contact->org_id->code$
• $current_contact->location_id->address$

Limitations:

• Placeholders can only be used in the message part, not in the title
• Placeholders are not replaced if the Communications are displayed to a User which has no associated Person.
• Placeholders are not replaced if the Communications are displayed in the Login page, because there isn't any identified User yet.
• Placeholders can be used as the last part of a valid URL only

CKEditor does not let you create a link to a placeholder such as

<a ref="$current_contact->org_id->url$">My Link</a>

But it will support, something like pointing to different part of a same website

<a ref="https://my-sharepoint-site.com/$current_contact->org_id->code$">My Link</a>

When a communication is “on going”, it is displayed in the portal, at the top of the home page. The text of the communications are truncated in order to preserve a constant height for the communications area in the home page.

The user can click on a communication to display it in a popup dialog. This is especially useful on small screens (mobile phones) where the communication may be truncated.

If there are several on-going communications at the same time, they are displayed one after the other, using a carousel, automatically sliding to the next communication after 5 seconds. Small bullets are displayed at the bottom of the carousel to allow direct access to the Nth communication. The carousel automatically stops sliding when the user positions the mouse hover it.

When there is no on-going communication, nothing is shown in the home page of the portal.

On every screen of the console,

• A communication banner is displayed, if there is at least one active communication for the current user.
• Each communication once read (or not) can be wrapped, and iTop will remember that this user has read this communication
• The complete communication banner can be wrapped, and will remain as is until a new communication pops-up
• The communication banner will disappear as long as there isn't open communication anymore

Question: Can I modify the way the Communications are displayed on a Portal?
Answer: Yes, with an iTop extension.

Here is the XML of the Portal CommunicationBrick, with the parameters which can be changed:

itop_design / module_designs / module_design@my-itop-portal / bricks

<brick id="communication" xsi:type="Combodo\iTop\Portal\Brick\CommunicationBrick" _delta="define">
   <active>true</active>
   <rank>1</rank>
   <height>15</height>    <!-- integer , size in em -->
   <width>12</width>      <!-- integer , must be between 1 and 12 -->
   <title>Portal:Communications</title>    <!-- string -->
   <oql></oql>            <!-- Query for the displayed communications 
            (if authorized to the current user, see Communication::IsAllowedToUser).
            Leave empty to preserve the default behavior. Use :now instead of NOW(). -->
   <security>             <!-- Order is deny/allow Pseudo OQL traduction : 
            WHERE user_profile NOT IN (:denied_profiles) AND user_profile IN (:allowed_profiles) -->
     <denied_profiles/>   <!-- OQL query. Used only when not empty -->
     <allowed_profiles/>  <!-- OQL query. Used only when not empty -->
   </security>
</brick>

The default query on OQL is

SELECT Communication WHERE status != 'closed' AND start_date <= :now

Question: Can I display Communications on multiple Portals?
Answer: Yes, with an iTop extension.

You will have to customize the Communication class to add a criteria to specifies the Portals on which a particular Communication should be displayed.

itop_design / classes / class@Communication

      <fields>
        <field id="portals" xsi:type="AttributeEnumSet" _delta="define">
          <sql>portals</sql>
          <values>
            <value id="user-portal">user-portal</value>
            <value id="partner-portal">partner-portal</value>
          </values>
          <is_null_allowed>true</is_null_allowed>
          <dependencies/>
          <tracking_level>all</tracking_level>
        </field>
      </fields>

You must also modify the presentation

itop_design / classes / class@Communication

      <presentation>
        <details _delta="must_exists">
          <items>
            <item id="col:col0">
              <items>
                <item id="portals" _delta="define">
                  <rank>70</rank>
                </item>
              </items>
            </item>
          </items>
        </details>
      </presentation>

Then modify the Portals themselves, by changing the scope of Communications displayed in each portal

itop_design / module_designs / module_design@itop-portal / bricks

<brick id="communication" xsi:type="Combodo\iTop\Portal\Brick\CommunicationBrick" _delta="if_exists">
  <oql _delta="define">
    <![CDATA[SELECT Communication WHERE portals MATCHES ('user-portal') 
             AND status = 'ongoing' AND start_date <= :now]]>
  </oql>
</brick>

• On the itop-portal you will add the condition portals MATCHES ('user-portal')
• on the itop-portal-business-partner you will add the condition portals MATCHES ('partner-portal')

Question: Can I display Communications to Users of organizations matching some particular conditions?
Answer: Yes, with an iTop extension.

Can be useful, if you are a Service Provider. You could define “permanent” Communication(s) which would be displayed only if the user's Organization match a particular condition, for example his contract is about to expire and need to be renewed, or its consumption of credit has expired or whatever logic

Check the Tutorial Communications displayed on Condition

Q: Can I order Communications on a different criteria than their start_date?
A: Yes, you can for example add a rank to the Communication class, so most critical ones are displayed first

Here is an example with adding a rank field on the Communication class and forcing the natural order to be based on that rank

itop-design | classes

    <class id="Communication">
      <properties>
        <order>
          <columns>
            <column id="rank" ascending="true" _delta="redefine"/>
          </columns>
        </order>
      </properties>
      <fields>
        <field id="rank" xsi:type="AttributeInteger" _delta="define">
          <sql>rank</sql>
          <default_value>0</default_value>
          <is_null_allowed>false</is_null_allowed>
        </field>
      </fields>
      <presentation>
        <details>
          <items>
            <item id="col:col0">
              <items>
                <item id="fieldset:Communication:when">
                  <items>
                    <item id="rank"  _delta="define">
                      <rank>70</rank>
                    </item>
                  </items>
                </item>
              </items>
            </item>
          </items>
        </details>
      </presentation>
    </class>