Creating Service Requests from ESS to ESM

In order for Efecte Self-Service to be able to create new or poll new service requests correctly, the following attributes and attribute codes are required to exist and to have a value:

• Efecte efecte_id
• statusAttribute - status
• requestedForEmailAttribute – RequestedFor
• serviceItemExternalIdAttribute – ServiceItem. If the value of this attribute is empty, ESS will use the value from defaultIntegrationServiceItemId defined in the Efecte Service Management connector of ESS.

If any of the above-listed required fields is empty, the service request will not be created.

Detailed rules for processing service requests are as follows:

• WebShopId - if present, an upgrade of an existing service request will be performed
• efecte_id - if WebShopId is empty and there is no request in ESS with the given efecte_id, a new service request will be created. If a request with the given efecte_id exists in the ESS, an update of the existing one will be executed
• RequestedFor - a user with a matching email must exist in the organization information data in ESS. If that is not the case, the service request will not be created.
• OrderedBy - a user with a matching email must exist in the organization information data. If that is not the case, the service request will not be created. If the value of the field is empty, the RequestedFor email will be used instead
• ServiceItem - a service item with the exactly same Item ID has to exist and be valid (checks are also performed against the working copy in Efecte Self Service). If that condition isn't met, the service request is not created in ESS
• ServiceOffering- if set, the service request will be created with the given name. If the attribute is not set, the service offer name will be copied from the service offering found based on ServiceItem in ESS
• ServiceItemName - if set, the service request will be created with that name. If the attribute is not set, the service name will be copied from the service item found based on ServiceItem in ESS
• Price / MonthlySubscription - if set, the service request will be created with the corresponding data. If the attribute is not set, attributes will be copied from the service item found based on ServiceItem
• AdditionalInformation - if the value of the additional information attribute starts with "Description:", the connector will take text after the "Description:" part up to the end of the line. If the add info field doesn't start with the "Description:" prefix, all content of the attribute value will be processed

Receiving Knowledge Base Article Ratings from ESS to ESM

Users can rate knowledge base articles in ESS if the feature is enabled on ESS. In order to enable knowledge base article rating on ESM, the following steps need to be done:

• Add an attribute “Rating” to the Knowledge Base Article template
• Set AverageHandler to the attribute.
• No metadata needed, but if you wish, you can set the ProgressBar maximum value: 1 and Progress Bar mode: value. These settings show the value as a progress bar.
• Datatype: Decimal number. (Setting the handler changes the datatype automatically by the handler)
• Set Visibility: Show in view only
• Save the attribute
• Go to the class the attribute is in
• Confirm that the attribute has a code (should be given automatically)
• Configure the permissions of the attribute
• Make sure that on ESS configuration the rating is mapped to this attribute
• Create views, which use the Rating attribute to show the average ratings of Knowledge Base articles

Publishing Service Announcements from ESM to ESS

Publishing announcements from ESM to ESS is implemented using the following features:

• Listeners, which send announcements from ESM to ESS with SendDataCardXmlToHttpAction
• A listener, which sets the announcement to expire
• An event, which triggers a data card save when the validity of the announcement has expired. The data card save triggers the listener mentioned above.

Enabling Service Announcements in an Existing ESM-ESS Environment

Importing the Configuration Package

A configuration package (efecte-configuration_ESS_ANNOUNCEMENTS.xml), which includes the Service Announcement template and most of the configurations, is available. Also, the files mentioned below are available as separate files. Importing the configuration package automatically sets most of the settings and reduces the work needed to do the steps below. Import the configuration package via the Maintenance view’s Import configurations feature.

The package contains:

• The Service Announcement template.
• Listeners.
• Pre-filled Platform settings which need to be edited after import.
• The message queue task.
• The event for triggering announcement expiration.

If you import the package, you can skip the following parts:

• Import Service Announcement template and the listeners.
• Configure one event on the Self-Service Announcement template.
• Part of the configuration of the MessageQueue task. Scheduling settings need to be set.

After a successful configuration import, you should get the following report:

Templates created: 1
Data card listeners created: 3
Folders created: 0
Roles created: 0
Users created: 0
Reports created: 0
Dashboards created: 0
Schedulable tasks created: 1
Template events created: 1
Permissions created: 0
Platform settings created: 3
Layouts created: 0

You can use the following sections to double-check that all configurations are correct and to fill the parts that need to be configured manually after the configuration import.

Import Service announcement template and the listeners

• Import the Service Announcement Template to your ESM using the template import.
• ESM_Template_ESS_Announcement_2015_4.xml
• Check permissions of the template and select which roles have access to the template.
• Create a folder "Service announcements", in which the template's data cards can be created. Allow creation of Service Announcement data cards to this folder.
• Import these listeners to the Self-Service Announcement template:
  • 1st one sets a helper value last action: 1_presave.set_Last_Action_For_ESS_Announcement.xml
  • 2nd sends the announcement to ESS: 2_postsave.1.POST_ESS_Announcement_To_ESS.xml
  • 3rd deletes the announcement from ESS:  3_postsave.2.DELETE_ESS_Announcement_From_ESS.xml

Insert the ESS API token to ESM platform settings

• If your environment is in cloud, contact servicedesk@efecte.com Efecte Service Desk and they can deliver you the ESS API token, which is needed in ESM-ESS communication.
• If your environment is on-premise, go to ESS global admin and generate API token there.
• Create a new platform setting ‘ess.token’.
• Set the value of this setting by copy-pasting the API token to it.
• It's possible to configure the name of the setting, but in the default listener, the name of the setting is 'ess.token'. If you change the name, update both the platform setting and the listener.

Insert the ESS Tenant settings to your platform settings

• Create a new platform setting ‘ess.tenant’.
• Set your ESS Tenant name as the value of this setting, e.g. mycompany.

Insert the ESS URL to platform settings

• Create a new platform setting 'ess.announcement.url'.
• In on-premise: Set your ESS URL as the value of this setting, e.g.  https://mycompany.testefecte.com:55443/announcement
• In cloud: Set your ESS URL as the value of this setting e.g.   https://mycompany.efectecloud-dev.com/api/ssc/announcement
• The port and the service name /announcement remain the same for all ESS environments.
• It's possible to configure the name of the setting, but in the default listener, the name of the setting is 'ess.announcement.url'. If you change the name, update both the platform setting and the listener.

Enable announcements from ESS

• Set 'Announcements enabled' in ESS tenant admin - Settings

Configure one event on Self-Service Announcement template

Check and configure Schedulable Tasks

• EventTask has to be configured to trigger the event. In most environments this exists and no changes are needed.
• MessageQueueTask has to be configured to clean and reprocess the item in the queue. Running it every 5 minutes is the default setting.
      
  

Check and configure network settings

Make sure the announcement port is accessible and there’s no firewalls etc. blocking connections from ESM to the ESS environment.