Latest update: 07.03.2024

Introduction

The purpose of this document is to provide instructions for the implementation team at Matrix42 customers to implement the Matrix42 Core solution successfully. It outlines the required tasks to get started effectively and includes step-by-step instructions for each topic.

The general training material for administering the Matrix42 Service Management Tool (ESM) can be used as support material in addition to these instructions. Also, the paid digital training service can be useful now and later! 

Training material is available in the Matrix42 Community:

Training material: Administering ESM

Training material: Matrix42 Admin tips

Prerequisites for using this document

Before starting the implementation, please make sure that:

• You have purchased the Matrix42 Core solution
• The delivery kick-off meeting has been held
• The production environment URL and credentials have been delivered to you
• Some of the tasks require access to the Matrix42 environment. For conducting these tasks, access to the environment either with your Microsoft Entra ID credentials or with a local user is required. The access to the environment is sorted out latest in the Solution introduction session.     

List of requirements

• A Microsoft Entra ID instance or local user information for Authentication, authorization, and user information
  • The following information is required for local users: first name, last name, email, username (can be the email address)  
• An M365 Exchange Online instance 
  • Minimum license requirement: M365 E3 license
  • A dedicated user account (mailbox) 
• Access to internet

Implementation tasks and responsibilities

The following table defines the responsibilities related to implementing and starting using the Matrix42 Core solution. 

Technical setup and integrations

This chapter describes the necessary technical setup steps. Some of the instructions can be found through links to other articles. 

Microsoft Entra ID integration

The MS Entra ID integration is used for authentication, authorization, and for fetching user information to the Matrix42 Service Management Tool. Please find the instructions from the link below.  

Setting up OpenID authentication with Entra ID 

Scope of work for the Matrix42-MS Entra ID integration

The scope of work done by Matrix42 or an Matrix42 partner includes the following areas:  

M365 Exchange Online integration

The M365 Exchange Online integration is used for receiving and sending emails to and from the Matrix42 Service Management Tool. Please set up the M365 account and the Entra ID app registration based on the following requirements. 

Requirements

• The user account should have at minimum an M365 E3 license
• The user account must not be a shared mailbox or a service account
• The following information is required: username (email address) and password. The user and password are required even though OAuth 2.0 authentication is used since the authentication is based on the ROPC authentication flow. The mail server is always outlook.office365.com. 
• An Entra ID app registration is required to allow the Matrix42 Service Management Tool (ESM) to communicate with the email server.
• The IMAPS and SMTP protocols should be enabled. The ports 993 and 587 should also be enabled. 
• Multi-factor authentication (MFA) cannot be used. There are two levels of MFA settings: global and mailbox-specific. Please contact your mail server administrator to add necessary exceptions and disable MFA from the mail account used for the email integration.  
• The dedicated mailbox Inbox for the email integration should be empty

Steps

Before starting with the configuration steps below, please log in to M365 Exchange Online by entering the email accounts credentials in your browser. This helps to make sure the credentials work. Note! Please ensure you can access the Inbox without MFA prompts or other dialogs requiring actions from the user.  

Please perform the actions under step 1 and step 2 in the linked instructions. The Matrix42 delivery consultant will take care of Step 3. 

MailTask|ERROR|2022-09-27 11:47:40,387|ajp-nio-0.0.0.0-8009-exec-7|/resources/task/6104880/run root MailTask|Mail could not be imported (Matrix42@customer.fi)
        javax.mail.MessagingException: M3 BAD User is authenticated but not connected.;
         nested exception is:
           com.sun.mail.iap.BadCommandException: M3 BAD User is authenticated but not connected.

MailTask|ERROR|2022-09-27 11:47:40,387|ajp-nio-0.0.0.0-8009-exec-7|/resources/task/6104880/run root MailTask|Mail could not be imported (Matrix42@customer.fi)
        javax.mail.MessagingException: 03 BAD User is authenticated but not connected.;
         nested exception is:
           com.sun.mail.iap.BadCommandException: O3 BAD User is authenticated but not connected.

MailTask|ERROR|2021-11-10 14:11:30,278|ajp-nio-0.0.0.0-8009-exec-4|/resources/task/6104880/run admin.user MailTask|Mail could not be imported (MailTask name)
        javax.mail.AuthenticationFailedException: AUTHENTICATE failed.

Microsoft Teams Integration

Please find the implementation instructions from the link below. Please note that since the Matrix42 Core solution comes with the required templates and listeners, you can start from the step “Add Bot to Microsoft Teams."

In addition to the instructions, you can also find a configuration video and bot commands through the link below. 

Configuration guide: Microsoft Teams Bot

Master data management

Define Teams

Teams, often called support groups, are used to facilitate the efficient and effective handling of incidents and service requests. These groups typically comprise IT professionals with specialized knowledge and expertise in specific areas.

Steps for creating Teams:

1. Navigate to the Agent UI (end-user user interface of ESM) 
2. Create a new list view for the Team template
3. Review the out-of-the-box datacard and determine whether some of them could be used
4. Edit the Team datacards if necessary by opening, editing, and saving the datacard. 
5. Create new Team datacards if necessary
   1. Define a name
   2. Add members 
   3. Define a queue manager
   4. Define a support channel (e.g., an email address for outbound email notifications)
   5. Define the Team email signature
   6. Save the datacard

Define Service levels

Service levels are used to define and communicate performance expectations for handling tickets (including Incidents and Service Requests). They establish specific response and resolution times for different types of incidents or service requests, ensuring consistent and timely support. Service levels are automatically associated with tickets based on Services, which helps support teams prioritize and manage workloads effectively, meet customer expectations, and maintain service quality.

Steps:

1. Navigate to the Agent UI (end-user user interface of ESM). Select the icon (+) in the header bar for creating a new datacard.  
2. Type Service level in the search field
3. Select the Service level from the results in the menu. An empty Service level datacard will now open. 
4. Define a name for the Service level
5. Add a description
6. Define a response time
7. Select applicable business hours for the Service level 
8.  Define resolution target times in hours for each priority. For example, if a Ticket's priority is “1” (e.g., Critical), the response time could be 2 hours. Please note that this is always subject to the agreed service levels. 
9.  Save the datacard. 

If necessary, repeat steps 1…9 to create new Service levels. 

When using a user with the Content admin role, you can view the Service levels from the left-hand side navigation panel (Content Admin → Service level management  → Service levels). You can also create new Service level datacards from the list view by selecting “New”.

Define Services

The service catalog is a centralized repository that provides information about IT services. The catalog, modeled by Service datacards in the Matrix42 Service Management Tool (ESM), provides information and supports IT teams in managing and delivering IT services effectively.  

Steps:

1. Navigate to the Agent UI (end-user user interface of ESM). Select the icon (+) in the header bar for creating a new datacard.  
2. Type Service in the search field
3. Select Service from the results in the menu. An empty Service datacard will now open. 
4. Define a name for the Service
5. Add a description
6. Select an applicable Service level. Define also other service-related information on the service datacard (not required, but recommended). 
7. Save the datacard. 

Define Self-service items for Matrix42 Self-Service 2 

Self-service items are used for publishing items in the self-service portal. The environment comes out of the box with sample items, which can be used as the basis for defining the actual self-service items. In the screenshot below, on the left, you can see self-service items presented in the self-service portal. On the right side, you can see the items in the Matrix42 Service Management Tool (ESM). The self-service items are created and managed in ESM. 

Before creating new self-service items, make sure to check whether changes are needed to the predefined self-service categories. Self-service categories are used to group the Self-service items, and they are also defined in ESM as datacards, similar to the Self-service items. 

Please follow the steps below to add new self-service categories: 

1. Navigate to the Agent UI (end-user user interface of ESM). Select the icon (+) in the header bar for creating a new datacard.  
2. Type Self-service item category in the search field
3. Select Self-service item category from the results in the menu. An empty Self-service item category datacard will now open. 
4. Define a name for the Self-service item category 
5. Save the datacard. 

Please follow the steps below to add new self-service items: 

1. Navigate to the Agent UI (end-user user interface of ESM). Select the icon (+) in the header bar for creating a new datacard.  
2. Type Self-service item in the search field
3. Select Self-service item from the results in the menu. An empty Service datacard will now open. 
4. Define a name for the Self-service item
5. Set the Service type: Service Order
6. Select a Self-Service category
7. Set a price if necessary
8. Define a target delivery time in days
9. Select whether the approval workflow should be applied for orders associated with this item
10. Add a description
11. Upload product images
12.  Add predefined tasks if necessary. This allows a task or a set of tasks to be created for the agent once a service request associated with this item is created through the self-service. 
13. Select the associated Service
14. Save the datacard. 

Repeat these steps for creating more items. 

Modifying existing items and creating new ones through views 

You can modify the existing items by modifying the datacards in ESM (open the datacard, edit the information and save the datacard). 

If you are using a user with the Content admin role, you can view the Self-service categories and items from the left-hand side navigation panel: Content Admin → Self-Service catalog. You can also create new Self-service Items and Self-service categories from these list views. 

 

Configuration changes

Edit Email templates

Email templates are used for simplifying the agents' work. With email templates, agents can send email messages to customers based on predefined messages without having to write the messages over and over again. 

The solution comes with predefined email templates. If necessary, these can be changed by the administrator. The out-of-the-box text content of the default email template used for new emails is written in English. If necessary, the content can be changed. The default configuration is saved with the name “defaultConfiguration.” Modifying this template will modify the default email template. Please use the following configuration guide for editing email templates:  

Configuration guide: Editing email templates

Edit Automatic email notifications

The solution sends automatic emails to ensure the customers and the team members are informed about relevant process steps. E-mail notification datacards define the content of the automatic email notifications. Administrators can change the predefined content if necessary. 

Required changes

Define Sender Addresses for Team Datacards

1. Navigate to the Agent UI (end-user user interface of ESM) 
2. Create a new list view for the Team template.
   1. Alternatively, the Team datacards can be found in the E-mail notification templates view under the Content administration views.
3. Open the relevant Team datacards and click Edit all
4. Set the desired sender address for the Team to the Support channel attribute
5. Save the datacard
6. Repeat the steps above for each relevant Team datacard

Define sender addresses for E-mail notification datacards

1. Navigate to the Agent UI (end-user user interface of ESM) 
2. Create a new list view for the E-mail notification template
   1. Alternatively, the Team datacards can be found under the Content admin role views
3. Set the sender address for Ticket creation.
   1. Find the datacard named "Ticket created” 
   2. Set the desired sender address to the Sender's email address for Ticket creation attribute
4. Set the sender address for the knowledge management process
   1. Find the “KB Article is about to expire in 1 month” datacard
   2. Set the desired sender address to the Sender's email address for KB articles attribute
   3. Save the datacard
   4. Repeat these same sub-steps for the following datacards named:
      1. “KB Article is about to expire in 1 week”
      2. “KB Article is waiting for review”
5. Repeat the steps all the steps above for all datacards with the necessary language versions.

Optional changes 

Change email contents

1. Navigate to the Agent UI (end-user user interface of ESM) 
2. Create a new list view for the E-mail notification template
   1. Alternatively, the Team datacards can be found under the Content admin role views
3. Open the E-mail notification datacard you wish to modify
4. Select Edit all, and modify the following attributes if necessary:
   1. E-mail subject
   2. E-mail header
   3. E-mail body
   4. E-mail footer

Define Ticket routing and assignment rules

Tickets are routed based on self-service items. By defining a team for each Self-Service Item, you can ensure that Tickets are routed to the correct teams. 

1. Navigate to the Agent UI (end-user user interface of ESM) 
2. Create a new list view for the Self-Service items template
   1. Alternatively, the Self-Service item datacards can be found under the Content admin role views
3. Define a team for each self-service item datacard
   1. Find the item for which you want to define a Team, and open the datacard
   2. Select Edit all, and modify the value in the Team attribute 
   3. Save the datacard

Incidents are linked to the “Other IT Issue” Self-Service Item datacard. For defining the routing of incidents, please define a team also for this datacard. 

Define predefined tasks

1. Navigate to the Agent UI (end-user user interface of ESM) 
2. Create a new list view for the Self-Service items template
   1. Alternatively, the Self-Service item datacards can be found under the Content admin role views
3. Define tasks for each self-service item datacard
   1. Find the item for which you want to define tasks, and open the datacard
   2. Select Edit all, and either add or remove predefined tasks 
   3. Save the datacard

User and access management

This chapter includes instructions for managing access to the solution. Access management with both Microsoft Entra ID integration and local users are considered below. 

User and Access Management with Microsoft Entra ID Integration

Access to the applications is managed by the organization membership (in Microsoft Entra ID) and security group membership. The following chapters describe the access management principles for both the Matrix42 Self-Service 2 (ESS2) and the Matrix42 Service Management Tool (ESM). 

Access Management in Matrix42 Self-Service 2

As defined in the application registration phase when configuring the Matrix42-Microsoft Entra ID integration, all accounts in the organizational directory can access the Matrix42 Self-Service 2 portal. The accounts do not need specific security group memberships for accessing Matrix42 Self-Service 2.   

Access management in the Matrix42 Service Management Tool

Access to ESM is managed by security group membership. The following table outlines the default security groups, their purpose, and the relevant platform settings. 

Steps for using the default security groups for access management: 

1. Create two security groups in Microsoft Entra ID: ESMUsers for normal-level users and ESMAdmins for administrators. 

   ESMAdmins role should be used only by certified Matrix42 Administrations

   The ESMAdmins role should be used only by certified Matrix42 Administrations, since the role provides root-level access to ESM. Root-level access implies that the users a) can see all data in the system regardless of underlying user permissions, and b) change the configuration without restrictions.  

    
2.  Assign these groups to the necessary users.

In case you want to use some other groups, please follow the instructions in the next chapter. 

Using custom Microsoft Entra ID security groups for access management

Steps for using custom Microsoft Entra ID security groups for access management: 

1. Create two security groups in Microsoft Entra ID: one for normal-level users and another for administrators.
2.  Assign these groups to the necessary users.
3.  Change the values of the following platform settings to match the custom security groups.
   1. Security group for normal users: servlet.auth.user.ad.group
   2. Security group for admin users: servlet.auth.admin.ad.group
4. Run the provisioning task
   1. Navigate to the Admin UI → IGA →  Select the relevant schedule-based provisioning task → Run task manually. Wait until the provisioning task has been ran before continuing to the next step. 
5. Ensure that the settings are correct by asking a normal-level user and an administrator-level user to log in. 

Steps for making sure users can log in to the application

1. Ensure that you have configured the Microsoft Entra ID integration according to the instructions in the chapter “Microsoft Entra ID integration”. 
2. Ensure that the user information has been fetched to ESM. The users can be found as Person datacards. 
   1. Navigate to the Agent UI (end-user user interface of ESM) 
   2. Create a new list view for the Person template
   3.  Check that person datacards originating from Microsoft Entra ID exists 
      1.  Pick some Person cards and check that the Person datacards include basic information, such as First name, Last name, Email, User Principal Name (UPN), and Entitlements (Microsoft Entra ID-groups). 
3. Ask users to log in
4. Assign licenses to users
5. Assign users to roles in ESM according to the instructions (see button below). The available roles are “Service Desk Agent”, “Content Admin", and “Service Manager”. 

Configuration guide: Assigning roles to users

Creating local users

Please follow the instructions to create local users (link below).  

Instructions: Creating local users

Instructing the end users

It is important to instruct the end-users on how to access and use the solution and application. Here are some considerations for instructing end users:

• The Solution description provides detailed insights into the included processes and use cases. Although these descriptions do not serve as user instructions, they can still be valuable for end users as they offer a deeper understanding of the design and functionality of the processes and use cases within the solution.
• As the Matrix42 Service Management Tool (ESM) is likely a new application for end users, it is advisable for them to acquaint themselves with the fundamental aspects of the user interface. User instructions, conveniently accessible through the top-right corner of the application, offer valuable guidance for end users, making it highly recommended for them to utilize these resources to become familiar with ESM's functionality.