Sidebar

Combodo

iTop Extensions

Communications to the Customers

name:
Communications to the Customers
description:
Communications to the Customers via the portal
version:
1.3.4
release:
2024-08-07
itop-version-min:
3.0.0
code:
itop-communications
state:
stable
diffusion:
iTop Hub
php-version-max:
PHP 8.3

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

For iTop before 2.7.0 use version 1.1.2 or before
For iTop 2.7.x use version 1.2.0 maximum.
For iTop 3.0.x, use version 1.2.0 or above
For iTop 3.1.x, use version 1.3.2 or above

Features

  • 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

Revision history

Date Version Description
2024-08-07 1.3.4 * N°6986 - Symfony 6.4 - Remove deprecated calls - communication
* N°6623 - Read-only attribute, dynamically read-write, entry silently ignored on submission
* N°7322 - Make title mandatory in Communication
2023-07-13 1.3.2 * N°6510 - Remove tests folder from builds
2023-07-05 1.3.1 * N°3475 - Display communication in backoffice and login pages, change class icon
* N°5714 and N°6470 - Add dynamically targeted organizations
* N°6233 - Add fieldsets, tips, change labels
* N°6029 - Add uniqueness rule on Link class
* Add compatibility with iTop 3.1 (Symfony 5.4)
* Updated german translations by Lars Kaltefleiter
2021-12-20 1.2.0 * Add 3.0 compatibility
* Add ES translations
* Fix icons not showing anymore in iTop 3.0.0+
2020-12-03 1.1.2 * Fix extension version inside module file
2020-11-18 1.1.1 * Fix incompatibility with Request Template, for iTop with a portal different than the standard portal
2020-02-03 1.1.0 * Add compatibility with iTop 2.7+
* Add MySQL8 compatibility
* Minimum iTop version set to 2.4.0
2019-09-11 1.0.10 * Update extension description
* Correctly display and hide communications to user with silos
2018-12-19 1.0.9 Update translations
2018-06-27 1.0.7 Add DE translations
2018-06-26 1.0.6 Fix portal tile UI
2016-08-23 1.0.5 Bug fix: the option “cascade to child organizations” was not working
2016-08-08 1.0.3 First released version

Limitations

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

Requirements

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

Installation

Use the Standard installation process for this extension.

Configuration

This extensions has no configuration parameter.

Usage

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”.

"Communications" menu

The menu lists all the “on-going” communications. To see the “closed” communications, open the search form at the top of the page, adjust the search criteria and press the “Search” button.

Creating a new communication

The form to create a new communication is the following:

 New Communication form

Field Meaning
Announcer The organization owning this communication.
Status Automatically computed based on the start and end dates
Start date The date (and time) at which to start showing this communication in the portal
End date The date (and time) at which to stop showing this communication in the portal
Target organizations… How to retrieve the “Target organizations”. If the value is
Only the chosen ones it's all organizations explicitly linked to this communication,
Chosen and descendants its the organizations explicitly linked and their child organizations in cascade,
Organizations from OQL its the organizations returned by the OQL (Chosen organizations are ignored)
OQL query An OQL query which mus return just Organization object, it can use :this→code placeholder, for eg to reference the Anouncer
Displayed on… On which UI this communication will be displayed:
Portals means all portal,
Standard portal means just the out of the box User portal
Login is the Login screen
Console is every screens of the iTop back-office
Icon An optional icon to display next to the communication in the portal. Choose “None” for displaying no icon.
Title An optional plain text title for the communication.
Message The actual body of the communication. Use the formatting toolbar to style the text, to insert images or add hyperlinks.

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

If no “Target Organizations” is selected, everybody will see the communication

Communications in the Portal

 Communications in the portal

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.

 Popup showing a communication

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.

The end users do not need to have access to the announcer organization in order to view the communications in the portal. The system automatically displays the appropriate communications independently of the usual access rights.
To create a “graphic only” communication (for example a graphic banner), use the “description” field to insert a large version of the banner as either a JPEG or PNG image, leave the title blank and select Icon: “None”. The banner image will be displayed using the complete width for the browser, automatically adjusting to browser resizes.

Communications in Console

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

Communications in Login

Questions & Answers

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:

Search in the XML:
Tag Usage Description
<brick id="name" xsi:type="Combodo\iTop\Portal\Brick\CommunicationBrick"> optional Communications to the customer
<active>true</active> optional Toggle brick true/false, defaults to true
<rank>1</rank> optional How to order the brick in the welcome screen, defaults to 1
<height>15</height> optional Height in 'em'
<width>12</width> optional Width, must be between 1 and 12
<title>Portal:Communications</title> mandatory Title, can be a dictionary key
<oql>SELECT Communication WHERE status != 'closed' AND start_date <= :now</oql> optional Query for the displayed communications (if authorized to the current user). Leave empty to preserve the default behavior. Use :now instead of NOW().
<security> optional If present, determines the visibility of this brick. Deny takes precedence.
<allowed_profiles>SELECT URP_Profiles WHERE name = 'Portal power user'</allowed_profiles> optional If defined, then the current user must have at least one profile returned by this OQL query (URP_Profiles)
<denied_profiles>SELECT URP_Profiles WHERE name = 'Portal power user'</denied_profiles> optional If defined, then the current user must NOT have any of the profiles returned by this OQL query (URP_Profiles)
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

Multiple portals

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.

Here I am using an EnumSet type of field, only available since 2.7.1, but you can use another attribute type, to modelize this information
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')

Permanent communication on condition

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

extensions/itop-communications.txt · Last modified: 2024/08/26 15:17 (external edit)
Back to top
Contact us